# 开发环境搭建

<cite>
**本文档引用的文件**
- [backend/.env.example](file://backend/.env.example)
- [backend/requirements.txt](file://backend/requirements.txt)
- [backend/alembic.ini](file://backend/alembic.ini)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/init_db.py](file://backend/init_db.py)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py)
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py)
- [backend/create_plan_tables.py](file://backend/create_plan_tables.py)
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py)
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py)
- [backend/test_api.py](file://backend/test_api.py)
- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本指南面向医院绩效系统后端开发团队，提供从零搭建开发环境的完整流程。内容涵盖Python环境要求、虚拟环境创建与依赖安装、环境变量与数据库配置、API配置参数、本地开发服务器启动与热重载、数据库初始化与迁移脚本执行、测试数据准备、IDE配置建议以及常见问题排查。

## 项目结构
后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库连接的现代Python架构，主要目录与职责如下：
- app：核心业务逻辑，包含API路由、核心配置、数据库连接、服务层、模型与工具
- alembic：数据库迁移脚本与配置
- tests：测试用例（当前为空或未启用）
- scripts：初始化脚本与工具脚本
- 根目录：环境变量、依赖清单、迁移配置与数据库文件

```mermaid
graph TB
subgraph "后端根目录"
ENV[".env 环境变量"]
REQ["requirements.txt 依赖"]
ALEMBICINI["alembic.ini 迁移配置"]
DBFILE["hospital_performance.db SQLite 文件"]
end
subgraph "应用核心(app)"
MAIN["app/main.py 应用入口"]
CONFIG["app/core/config.py 配置"]
DB["app/core/database.py 数据库连接"]
MODELS["app/models/* 模型定义"]
SERVICES["app/services/* 服务层"]
APIS["app/api/v1/* API路由"]
SCRIPTS["app/scripts/* 初始化脚本"]
end
subgraph "迁移(alembic)"
ALEMBICENV["alembic/env.py 环境配置"]
VERSIONS["alembic/versions/* 迁移版本"]
end
ENV --> CONFIG
REQ --> MAIN
ALEMBICINI --> ALEMBICENV
CONFIG --> DB
DB --> MODELS
MAIN --> APIS
SCRIPTS --> MODELS
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)

## 核心组件
- 应用入口与路由注册：负责创建FastAPI实例、配置CORS、注册路由前缀、健康检查与全局异常处理
- 配置模块：集中管理应用名称、版本、调试模式、API前缀、数据库连接、JWT密钥与算法、跨域来源、分页参数等
- 数据库连接：基于SQLAlchemy 2.0异步引擎与会话工厂，支持调试模式下的SQL回显
- 迁移配置：Alembic配置文件，指定迁移脚本位置、路径前缀与SQLAlchemy URL

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L15-L77)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/alembic.ini](file://backend/alembic.ini#L3-L7)

## 架构概览
后端采用分层架构，核心交互流程如下：

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Uvicorn as "Uvicorn 服务器"
participant FastAPI as "FastAPI 应用"
participant Router as "API 路由"
participant Service as "业务服务"
participant DB as "数据库"
Dev->>Uvicorn : 启动开发服务器(热重载)
Uvicorn->>FastAPI : 加载应用实例
FastAPI->>Router : 注册路由前缀 /api/v1
Dev->>FastAPI : 请求 /api/v1/health
FastAPI->>Router : 转发健康检查
Router->>FastAPI : 返回健康状态
FastAPI-->>Dev : 200 OK
Dev->>FastAPI : 认证请求
FastAPI->>Service : 调用认证服务
Service->>DB : 查询用户信息
DB-->>Service : 用户数据
Service-->>FastAPI : 认证结果
FastAPI-->>Dev : 返回访问令牌
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L54-L56)
- [backend/app/main.py](file://backend/app/main.py#L83-L91)

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L19-L51)

## 详细组件分析

### Python环境与依赖安装
- Python版本：推荐使用Python 3.10及以上版本
- 虚拟环境：建议使用venv创建隔离环境
- 依赖安装：通过requirements.txt安装所有后端依赖
- 开发服务器：使用uvicorn标准变体运行FastAPI应用

```mermaid
flowchart TD
Start(["开始"]) --> CreateEnv["创建虚拟环境"]
CreateEnv --> ActivateEnv["激活虚拟环境"]
ActivateEnv --> InstallDeps["安装依赖 requirements.txt"]
InstallDeps --> VerifyDeps{"依赖安装完成？"}
VerifyDeps --> |是| SetupEnv["配置环境变量 .env"]
VerifyDeps --> |否| FixDeps["检查并修复依赖问题"]
FixDeps --> InstallDeps
SetupEnv --> Ready["开发环境就绪"]
Ready --> End(["结束"])
```

**图表来源**
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)

**章节来源**
- [backend/requirements.txt](file://backend/requirements.txt#L1-L17)

### 环境变量与数据库配置
- 环境变量文件：.env.example提供了数据库URL、JWT密钥与调试开关的示例
- 数据库连接：默认使用PostgreSQL异步驱动，可通过DATABASE_URL覆盖
- Alembic配置：迁移脚本默认指向SQLite文件，便于本地开发与测试
- 配置优先级：应用配置从.env读取，同时支持运行时覆盖

```mermaid
flowchart TD
EnvFile[".env.example 示例"] --> LoadEnv["加载环境变量"]
LoadEnv --> ConfigClass["Settings 类解析"]
ConfigClass --> DBURL["DATABASE_URL"]
ConfigClass --> JWT["JWT 密钥/算法"]
ConfigClass --> Debug["DEBUG 调试模式"]
DBURL --> Engine["异步引擎创建"]
Engine --> Session["会话工厂"]
Session --> App["应用使用"]
```

**图表来源**
- [backend/.env.example](file://backend/.env.example#L3-L10)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)

**章节来源**
- [backend/.env.example](file://backend/.env.example#L1-L11)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L46)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)

### API配置参数
- 应用名称与版本：用于OpenAPI文档展示
- API前缀：统一为/api/v1，便于版本管理
- CORS来源：允许前端开发服务器跨域访问
- 分页参数：默认每页条数与最大限制
- 异常处理：HTTP异常、请求验证异常与全局异常的统一处理

**章节来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L12-L33)
- [backend/app/main.py](file://backend/app/main.py#L19-L77)

### 本地开发服务器启动与热重载
- 启动命令：直接运行app/main.py，使用uvicorn标准变体
- 热重载：reload=True启用自动重启
- 主机与端口：默认监听0.0.0.0:8000
- 日志级别：info级别输出运行日志

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Python as "Python 解释器"
participant Uvicorn as "Uvicorn"
participant App as "FastAPI 应用"
Dev->>Python : python app/main.py
Python->>Uvicorn : 启动服务器(主机=0.0.0.0, 端口=8000, 热重载)
Uvicorn->>App : 加载应用实例
App-->>Uvicorn : 应用就绪
Uvicorn-->>Dev : 服务器启动完成
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L83-L91)

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L83-L91)

### 数据库初始化与迁移脚本
- 初始表创建：init_db.py与app/core/init_db.py分别提供不同初始化策略
- 菜单与计划表：create_menu_tables.py与create_plan_tables.py按需创建专用表
- 指标模板：init_indicator_templates.py批量导入平衡计分卡指标模板
- 迁移字段：migrate_indicators.py为现有指标表添加BS维度等新字段
- Alembic迁移：alembic.ini配置迁移脚本位置与SQLAlchemy URL

```mermaid
flowchart TD
InitStart["开始初始化"] --> CheckTables["检查表是否存在"]
CheckTables --> |不存在| CreateTable["创建基础表"]
CheckTables --> |存在| SkipInit["跳过初始化"]
CreateTable --> InsertData["插入测试/示例数据"]
InsertData --> InitComplete["初始化完成"]
SkipInit --> InitComplete
```

**图表来源**
- [backend/init_db.py](file://backend/init_db.py#L11-L25)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L103-L110)

**章节来源**
- [backend/init_db.py](file://backend/init_db.py#L1-L83)
- [backend/app/core/init_db.py](file://backend/app/core/init_db.py#L1-L115)
- [backend/create_menu_tables.py](file://backend/create_menu_tables.py#L1-L27)
- [backend/create_plan_tables.py](file://backend/create_plan_tables.py#L1-L20)
- [backend/init_indicator_templates.py](file://backend/init_indicator_templates.py#L1-L375)
- [backend/migrate_indicators.py](file://backend/migrate_indicators.py#L1-L46)
- [backend/alembic.ini](file://backend/alembic.ini#L1-L44)

### 测试数据准备与API验证
- 登录测试：使用test_api.py模拟登录与获取模板数据
- 默认账户：admin/admin123用于快速验证接口
- 接口验证：通过健康检查与模板查询确认服务可用性

**章节来源**
- [backend/test_api.py](file://backend/test_api.py#L1-L33)

### IDE配置与代码规范
- Python版本：建议使用Python 3.10+
- 虚拟环境：使用venv创建独立环境
- 依赖管理：通过requirements.txt安装
- 代码格式化：建议使用Black或autopep8
- Linting：使用flake8或ruff
- IDE插件：启用Python语言服务器与格式化工具

## 依赖关系分析
后端依赖关系清晰，核心模块间耦合度低，便于维护与扩展：

```mermaid
graph LR
FastAPI["FastAPI 应用"] --> Config["配置模块"]
FastAPI --> Router["API 路由"]
Config --> DB["数据库连接"]
DB --> Models["ORM 模型"]
Router --> Services["业务服务"]
Services --> DB
Scripts["初始化脚本"] --> DB
Alembic["Alembic 迁移"] --> DB
```

**图表来源**
- [backend/app/main.py](file://backend/app/main.py#L10-L12)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)

## 性能考虑
- 异步数据库：使用SQLAlchemy异步引擎提升并发性能
- 连接池：通过配置数据库连接池大小与溢出数量控制资源使用
- 调试模式：仅在开发环境开启DEBUG，生产环境关闭以减少日志开销
- CORS范围：限制允许的来源与方法，避免不必要的跨域请求

## 故障排除指南
- 数据库连接失败
  - 检查DATABASE_URL格式与凭据
  - 确认PostgreSQL服务运行状态
  - 如需SQLite，请调整Alembic配置与应用配置
- 端口被占用
  - 修改app/main.py中的端口或停止占用进程
- 热重载无效
  - 确认reload=True且文件保存
  - 检查虚拟环境中uvicorn安装
- 权限错误
  - 使用虚拟环境并确保pip安装权限
- Alembic迁移问题
  - 检查alembic.ini中的SQLAlchemy URL
  - 清理历史迁移并重新生成版本

**章节来源**
- [backend/app/main.py](file://backend/app/main.py#L83-L91)
- [backend/alembic.ini](file://backend/alembic.ini#L7-L7)

## 结论
通过本指南，您可以快速搭建医院绩效系统后端开发环境。建议严格遵循环境变量配置、数据库初始化与迁移脚本执行流程，并在开发过程中充分利用热重载与日志功能。遇到问题时，可依据故障排除指南逐项排查。

## 附录
- 快速检查清单
  - Python 3.10+ 已安装
  - 虚拟环境已创建并激活
  - requirements.txt 依赖安装完成
  - .env 环境变量配置正确
  - 数据库服务运行正常
  - 应用健康检查返回200
  - 初始化脚本执行成功