提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/后端开发指南/开发环境搭建.md
+++ b/.qoder/repowiki/zh/content/后端开发指南/开发环境搭建.md
@@ -0,0 +1,330 @@
+# 开发环境搭建
+
+<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
+  - 初始化脚本执行成功