提交文件

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,396 @@
+# 后端开发指南
+
+<cite>
+**本文档引用的文件**
+- [main.py](file://backend/app/main.py)
+- [config.py](file://backend/app/core/config.py)
+- [database.py](file://backend/app/core/database.py)
+- [security.py](file://backend/app/core/security.py)
+- [logging_config.py](file://backend/app/core/logging_config.py)
+- [__init__.py](file://backend/app/api/v1/__init__.py)
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [staff_service.py](file://backend/app/services/staff_service.py)
+- [auth.py](file://backend/app/api/v1/auth.py)
+- [staff.py](file://backend/app/api/v1/staff.py)
+- [init_db.py](file://backend/init_db.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向后端开发者，系统讲解医院绩效管理系统的FastAPI后端开发实践，涵盖：
+- FastAPI框架使用与路由组织
+- 数据模型设计与业务实体映射
+- 服务层架构、依赖注入与异步编程
+- API路由配置、错误处理与日志规范
+- 业务服务开发、数据验证与安全控制
+- 数据库连接管理、事务处理与性能优化
+- 单元测试与集成测试设计、代码质量保证
+
+## 项目结构
+后端采用分层架构：入口应用层、核心配置与基础设施层、数据模型与Schema层、服务层、API路由层。整体结构清晰，职责分离明确。
+
+```mermaid
+graph TB
+subgraph "应用入口"
+MAIN["main.py"]
+end
+subgraph "核心配置与基础设施"
+CFG["config.py"]
+DB["database.py"]
+SEC["security.py"]
+LOG["logging_config.py"]
+end
+subgraph "数据与接口定义"
+MODELS["models.py"]
+SCHEMAS["schemas.py"]
+end
+subgraph "服务层"
+SVC_ASSESS["assessment_service.py"]
+SVC_STAFF["staff_service.py"]
+end
+subgraph "API路由"
+API_V1["api/v1/__init__.py"]
+AUTH["api/v1/auth.py"]
+STAFF["api/v1/staff.py"]
+end
+MAIN --> API_V1
+API_V1 --> AUTH
+API_V1 --> STAFF
+AUTH --> SEC
+STAFF --> SVC_STAFF
+SVC_STAFF --> MODELS
+SVC_ASSESS --> MODELS
+SEC --> DB
+DB --> MODELS
+MODELS --> SCHEMAS
+```
+
+**图表来源**
+- [main.py](file://backend/app/main.py#L15-L77)
+- [config.py](file://backend/app/core/config.py#L9-L46)
+- [database.py](file://backend/app/core/database.py#L9-L38)
+- [security.py](file://backend/app/core/security.py#L18-L110)
+- [logging_config.py](file://backend/app/core/logging_config.py#L26-L64)
+- [models.py](file://backend/app/models/models.py#L62-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [__init__.py](file://backend/app/api/v1/__init__.py#L4-L16)
+- [auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L15-L77)
+- [__init__.py](file://backend/app/api/v1/__init__.py#L4-L16)
+
+## 核心组件
+- 应用实例与中间件：创建FastAPI实例、CORS跨域、健康检查端点、全局异常处理器。
+- 配置中心：应用名、版本、API前缀、数据库连接池、JWT密钥与过期时间、CORS白名单、分页参数等。
+- 数据库层：异步SQLAlchemy引擎、会话工厂、模型基类、依赖注入式会话获取与自动事务提交/回滚。
+- 安全模块：OAuth2密码流、密码哈希与校验、JWT签发与解析、当前用户解析与权限校验（管理员/经理/激活用户）。
+- 日志模块：控制台与文件（按日滚动）双通道，错误级别单独文件，统一格式化输出。
+- 数据模型与Schema：涵盖科室、员工、指标、考核、明细、工资、用户、计划、菜单、模板等实体与枚举。
+- 服务层：封装业务逻辑，如员工管理、考核流程（草稿/提交/审核/确认）、批量创建等。
+- API路由：认证、员工管理等模块化路由，统一返回结构与权限控制。
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L19-L76)
+- [config.py](file://backend/app/core/config.py#L9-L46)
+- [database.py](file://backend/app/core/database.py#L9-L38)
+- [security.py](file://backend/app/core/security.py#L20-L110)
+- [logging_config.py](file://backend/app/core/logging_config.py#L26-L64)
+- [models.py](file://backend/app/models/models.py#L62-L438)
+- [schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+
+## 架构总览
+系统采用“路由层-服务层-数据层”的三层架构，配合依赖注入与异步IO，确保高并发下的稳定与性能。
+
+```mermaid
+graph TB
+CLIENT["客户端"] --> ROUTER["API路由层<br/>auth.py / staff.py"]
+ROUTER --> DEP_DB["依赖注入: get_db()"]
+ROUTER --> DEP_SEC["依赖注入: 当前用户/权限"]
+ROUTER --> SVC["服务层<br/>staff_service.py / assessment_service.py"]
+SVC --> MODEL["数据模型层<br/>models.py"]
+MODEL --> DB["数据库引擎<br/>database.py"]
+ROUTER --> LOG["日志记录<br/>logging_config.py"]
+ROUTER --> CFG["配置中心<br/>config.py"]
+```
+
+**图表来源**
+- [auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [database.py](file://backend/app/core/database.py#L28-L38)
+- [logging_config.py](file://backend/app/core/logging_config.py#L26-L64)
+- [config.py](file://backend/app/core/config.py#L9-L46)
+
+## 详细组件分析
+
+### FastAPI应用与路由组织
+- 应用创建：设置标题、版本、OpenAPI文档路径、CORS策略、健康检查端点。
+- 异常处理：HTTP异常、请求验证异常、全局异常，均记录日志并抛出。
+- 路由注册：v1路由聚合器统一include各模块路由。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant App as "FastAPI应用"
+participant Router as "API路由"
+participant Service as "服务层"
+participant DB as "数据库"
+Client->>App : 请求 /api/v1/staff
+App->>Router : 分发到 staff.py
+Router->>Service : 调用 StaffService
+Service->>DB : 查询/写入
+DB-->>Service : 返回结果
+Service-->>Router : 业务结果
+Router-->>Client : 统一响应结构
+```
+
+**图表来源**
+- [main.py](file://backend/app/main.py#L50-L56)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L16-L49)
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L19-L76)
+- [__init__.py](file://backend/app/api/v1/__init__.py#L4-L16)
+
+### 数据模型设计与业务实体
+- 实体覆盖：科室、员工、指标、考核、明细、工资、用户、计划、菜单、模板等。
+- 枚举类型：科室类型、平衡计分卡维度、员工状态、考核状态、指标类型、计划层级/状态、菜单类型、模板类型等。
+- 约束与索引：权重正数约束、多字段索引、唯一组合索引等，提升查询效率与数据一致性。
+- 关系映射：一对多/多对多、外键约束、级联删除等，确保业务完整性。
+
+```mermaid
+erDiagram
+DEPARTMENTS ||--o{ STAFF : "拥有"
+STAFF ||--o{ ASSESSMENTS : "被考核"
+STAFF ||--o{ SALARY_RECORDS : "薪资记录"
+INDICATORS ||--o{ ASSESSMENT_DETAILS : "被用于"
+ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
+PERFORMANCE_PLANS ||--o{ PLAN_KPI_RELATIONS : "关联指标"
+INDICATORS ||--o{ PLAN_KPI_RELATIONS : "被关联"
+USERS ||--o{ ASSESSMENTS : "审核/复核"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L62-L438)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L62-L438)
+
+### Schema与数据验证
+- Pydantic模型：统一定义请求/响应结构，内置字段长度、范围、枚举校验。
+- 通用响应：统一code/message结构；分页响应包含总数、页码、页大小。
+- 类型安全：枚举类型与数据库枚举保持一致，避免非法值进入数据库。
+
+**章节来源**
+- [schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+
+### 服务层架构与依赖注入
+- 服务类：以静态方法封装业务逻辑，便于测试与复用。
+- 依赖注入：通过AsyncSession注入数据库会话；通过Depends注入当前用户与权限。
+- 异步编程：所有数据库操作使用异步IO，提高并发吞吐。
+
+```mermaid
+classDiagram
+class StaffService {
+get_list(db, department_id, status, keyword, page, page_size)
+get_by_id(db, staff_id)
+get_by_employee_id(db, employee_id)
+create(db, staff_data)
+update(db, staff_id, staff_data)
+delete(db, staff_id)
+get_by_department(db, department_id)
+}
+class AssessmentService {
+get_list(db, staff_id, department_id, period_year, period_month, status, page, page_size)
+get_by_id(db, assessment_id)
+create(db, assessment_data, assessor_id)
+update(db, assessment_id, assessment_data)
+submit(db, assessment_id)
+review(db, assessment_id, reviewer_id, approved, remark)
+finalize(db, assessment_id)
+batch_create_for_department(db, department_id, period_year, period_month, indicators)
+}
+class Assessment {
+total_score
+weighted_score
+status
+}
+StaffService --> Assessment : "关联"
+AssessmentService --> Assessment : "管理"
+```
+
+**图表来源**
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+
+**章节来源**
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+
+### 安全与认证
+- OAuth2密码模式：tokenUrl指向登录接口。
+- 密码处理：bcrypt哈希与校验。
+- JWT：签发含过期时间，解析校验失败则拒绝。
+- 权限控制：当前用户、激活用户、管理员、经理权限装饰器。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Auth as "认证路由"
+participant DB as "数据库"
+participant Sec as "安全模块"
+Client->>Auth : POST /api/v1/auth/login
+Auth->>DB : 查询用户
+DB-->>Auth : 用户对象
+Auth->>Sec : 校验密码
+Sec-->>Auth : 校验结果
+Auth->>Sec : 生成JWT
+Sec-->>Auth : access_token
+Auth-->>Client : Token
+```
+
+**图表来源**
+- [auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [security.py](file://backend/app/core/security.py#L24-L52)
+
+**章节来源**
+- [auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [security.py](file://backend/app/core/security.py#L20-L110)
+
+### 数据库连接管理与事务
+- 异步引擎：基于asyncpg驱动，支持连接池配置。
+- 会话工厂：AsyncSession，expire_on_commit=False减少刷新开销。
+- 依赖注入：get_db提供上下文生命周期的会话，自动commit/rollback/关闭。
+- 事务语义：异常时回滚，finally确保关闭，避免资源泄漏。
+
+```mermaid
+flowchart TD
+Start(["获取会话"]) --> Exec["执行数据库操作"]
+Exec --> Success{"是否异常?"}
+Success --> |否| Commit["提交事务"]
+Success --> |是| Rollback["回滚事务"]
+Commit --> Close["关闭会话"]
+Rollback --> Close
+Close --> End(["结束"])
+```
+
+**图表来源**
+- [database.py](file://backend/app/core/database.py#L28-L38)
+
+**章节来源**
+- [database.py](file://backend/app/core/database.py#L9-L38)
+
+### API路由配置与统一响应
+- 路由前缀：/api/v1，统一文档路径。
+- 权限装饰器：仅管理员/经理可创建/更新/删除敏感资源。
+- 统一响应：code/message/data/分页字段，便于前端处理。
+
+**章节来源**
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+- [schemas.py](file://backend/app/schemas/schemas.py#L49-L60)
+
+### 错误处理与日志记录
+- 异常处理：HTTP异常、请求验证异常、全局异常，均记录日志并向上抛出。
+- 日志策略：控制台INFO级别、文件DEBUG级别、错误单独ERROR文件，按日滚动。
+- 日志获取：统一logger与子logger getChild，便于模块化追踪。
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L58-L74)
+- [logging_config.py](file://backend/app/core/logging_config.py#L26-L64)
+
+## 依赖关系分析
+- 路由层依赖服务层与安全模块；服务层依赖数据模型与数据库会话；安全模块依赖配置与数据库；日志模块独立但被路由层使用。
+- 低耦合高内聚：每个模块职责单一，通过依赖注入解耦。
+
+```mermaid
+graph LR
+AUTH["auth.py"] --> SEC["security.py"]
+AUTH --> SVC_STAFF["staff_service.py"]
+STAFF["staff.py"] --> SVC_STAFF
+SVC_STAFF --> MODELS["models.py"]
+SVC_ASSESS["assessment_service.py"] --> MODELS
+SEC --> DB["database.py"]
+DB --> MODELS
+MAIN["main.py"] --> API_V1["api/v1/__init__.py"]
+API_V1 --> AUTH
+API_V1 --> STAFF
+MAIN --> LOG["logging_config.py"]
+MAIN --> CFG["config.py"]
+```
+
+**图表来源**
+- [auth.py](file://backend/app/api/v1/auth.py#L17-L74)
+- [staff.py](file://backend/app/api/v1/staff.py#L20-L124)
+- [staff_service.py](file://backend/app/services/staff_service.py#L13-L112)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [security.py](file://backend/app/core/security.py#L18-L110)
+- [database.py](file://backend/app/core/database.py#L9-L38)
+- [models.py](file://backend/app/models/models.py#L62-L438)
+- [main.py](file://backend/app/main.py#L19-L76)
+- [__init__.py](file://backend/app/api/v1/__init__.py#L4-L16)
+- [logging_config.py](file://backend/app/core/logging_config.py#L26-L64)
+- [config.py](file://backend/app/core/config.py#L9-L46)
+
+**章节来源**
+- [main.py](file://backend/app/main.py#L19-L76)
+- [__init__.py](file://backend/app/api/v1/__init__.py#L4-L16)
+
+## 性能考虑
+- 异步IO：使用SQLAlchemy 2.0异步引擎与AsyncSession，提升并发能力。
+- 连接池：通过配置项设置池大小与溢出，平衡内存与并发。
+- 查询优化：合理使用selectinload预加载关联，避免N+1问题；为高频查询字段添加索引。
+- 缓存策略：可结合Redis缓存热点数据（如字典、模板），降低数据库压力。
+- 分页与限制：默认分页大小与最大分页限制，防止大查询导致阻塞。
+- 日志级别：生产环境建议调整日志级别，减少磁盘IO与CPU消耗。
+
+[本节为通用指导，无需列出具体文件来源]
+
+## 故障排除指南
+- 登录失败：检查用户名是否存在、密码是否正确、账户是否激活。
+- 权限不足：确认当前用户角色（admin/manager/staff），以及是否处于激活状态。
+- 数据库连接异常：检查DATABASE_URL、连接池配置、PostgreSQL服务状态。
+- 事务未提交：确认服务层调用await db.flush()/commit()，异常时自动回滚。
+- 日志排查：查看应用日志与错误日志，定位异常堆栈与请求上下文。
+
+**章节来源**
+- [auth.py](file://backend/app/api/v1/auth.py#L22-L37)
+- [security.py](file://backend/app/core/security.py#L55-L109)
+- [database.py](file://backend/app/core/database.py#L28-L38)
+- [logging_config.py](file://backend/app/core/logging_config.py#L26-L64)
+
+## 结论
+本指南梳理了医院绩效系统后端的架构与实现要点，强调了FastAPI的异步特性、依赖注入、安全认证与日志体系。通过清晰的分层与严格的Schema验证，系统具备良好的扩展性与可维护性。建议在后续迭代中完善单元测试与集成测试，持续优化查询与缓存策略，确保系统在高并发场景下的稳定性与性能。
+
+[本节为总结性内容，无需列出具体文件来源]
+
+## 附录
+
+### 开发与运行指引
+- 初始化数据库：运行数据库初始化脚本，创建表并插入测试数据。
+- 启动应用：使用uvicorn启动FastAPI应用，默认监听0.0.0.0:8000。
+- 访问文档：/api/v1/docs 或 /api/v1/redoc。
+
+**章节来源**
+- [init_db.py](file://backend/init_db.py#L11-L79)
+- [main.py](file://backend/app/main.py#L83-L91)