提交文件

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/后端开发指南/API路由实现/API路由实现.md
+++ b/.qoder/repowiki/zh/content/后端开发指南/API路由实现/API路由实现.md
@@ -0,0 +1,534 @@
+# API路由实现
+
+<cite>
+**本文档引用的文件**
+- [backend/app/main.py](file://backend/app/main.py)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py)
+- [backend/app/core/config.py](file://backend/app/core/config.py)
+- [backend/app/core/security.py](file://backend/app/core/security.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南面向医院绩效系统后端API路由实现，系统采用FastAPI框架，提供RESTful风格的接口，涵盖认证、基础数据、考核、工资、统计、计划、菜单、模板、财务等模块。文档重点说明路由装饰器使用、路径参数与查询参数处理、请求验证、响应模型定义、错误处理机制、CORS配置、中间件使用、安全控制、API版本管理、文档生成与测试方法，并给出性能优化、限流策略与监控集成建议。
+
+## 项目结构
+后端采用分层与功能模块化组织：
+- 应用入口与配置：main.py负责应用实例创建、CORS配置、路由注册、异常处理与健康检查
+- API版本：api/v1目录统一管理v1版本的所有路由模块
+- 核心模块：core目录包含配置、数据库连接、安全认证等基础设施
+- 数据模型与Schema：models与schemas定义数据库实体与API输入输出模型
+- 业务服务：services目录封装各模块业务逻辑
+- 前端对接：frontend目录提供前端界面与API调用示例
+
+```mermaid
+graph TB
+A["应用入口<br/>backend/app/main.py"] --> B["API路由器<br/>backend/app/api/v1/__init__.py"]
+B --> C["认证模块<br/>backend/app/api/v1/auth.py"]
+B --> D["基础数据模块<br/>departments/staff/indicators"]
+B --> E["考核模块<br/>backend/app/api/v1/assessments.py"]
+B --> F["工资模块<br/>backend/app/api/v1/salary.py"]
+B --> G["统计模块<br/>backend/app/api/v1/stats.py"]
+B --> H["财务模块<br/>backend/app/api/v1/finance.py"]
+B --> I["计划模块<br/>backend/app/api/v1/performance_plans.py"]
+B --> J["菜单模块<br/>backend/app/api/v1/menus.py"]
+K["配置模块<br/>backend/app/core/config.py"] --> A
+L["安全模块<br/>backend/app/core/security.py"] --> A
+M["Schema定义<br/>backend/app/schemas/schemas.py"] --> C
+M --> D
+M --> E
+M --> F
+M --> G
+M --> H
+M --> I
+M --> J
+```
+
+**图表来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L15-L77)
+- [backend/app/api/v1/__init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
+
+## 核心组件
+- 应用实例与中间件
+  - 使用FastAPI构造应用，配置标题、版本、描述与OpenAPI文档路径
+  - 注册CORS中间件，允许跨域请求
+  - 注册API路由器，统一前缀为配置中的API_PREFIX
+  - 定义健康检查端点
+  - 注册全局异常处理器，记录日志并抛出异常
+- 配置管理
+  - 通过Settings类集中管理应用名、版本、数据库连接、JWT密钥、CORS白名单、分页参数等
+  - 使用lru_cache缓存配置实例
+- 安全认证
+  - 基于JWT的OAuth2密码流，支持密码哈希、令牌签发与解析
+  - 提供当前用户、激活用户、管理员、经理权限校验依赖
+- Schema定义
+  - 统一响应模型ResponseBase与分页模型PaginatedResponse
+  - 定义枚举类型（科室类型、员工状态、考核状态、指标类型、财务类型等）
+  - 为各模块定义输入输出模型，确保请求验证与响应格式标准化
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L19-L77)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L21-L110)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L49-L743)
+
+## 架构概览
+系统采用分层架构：路由层（FastAPI装饰器与依赖注入）、服务层（业务逻辑封装）、数据层（SQLAlchemy异步ORM）。路由层负责参数解析、权限校验与响应包装；服务层负责领域逻辑；数据层负责持久化。
+
+```mermaid
+graph TB
+subgraph "路由层"
+R1["认证路由<br/>auth.py"]
+R2["基础数据路由<br/>departments/staff/indicators.py"]
+R3["考核路由<br/>assessments.py"]
+R4["工资路由<br/>salary.py"]
+R5["统计路由<br/>stats.py"]
+R6["财务路由<br/>finance.py"]
+R7["计划路由<br/>performance_plans.py"]
+R8["菜单路由<br/>menus.py"]
+end
+subgraph "服务层"
+S1["认证服务"]
+S2["部门服务"]
+S3["员工服务"]
+S4["指标服务"]
+S5["考核服务"]
+S6["工资服务"]
+S7["统计服务"]
+S8["财务服务"]
+S9["计划服务"]
+S10["菜单服务"]
+end
+subgraph "数据层"
+D1["数据库会话<br/>AsyncSession"]
+D2["模型定义<br/>models/*.py"]
+end
+R1 --> S1 --> D1
+R2 --> S2 --> D1
+R3 --> S5 --> D1
+R4 --> S6 --> D1
+R5 --> S7 --> D1
+R6 --> S8 --> D1
+R7 --> S9 --> D1
+R8 --> S10 --> D1
+```
+
+**图表来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L14-L74)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L14-L242)
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L18-L217)
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L18-L310)
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L14-L164)
+
+## 详细组件分析
+
+### 认证模块（auth）
+- 路由装饰器使用
+  - 使用APIRouter装饰器定义路由前缀与标签
+  - 使用Depends注入数据库会话与安全依赖
+- 路径与查询参数
+  - 登录接口使用OAuth2PasswordRequestForm自动解析表单参数
+  - 注册接口接收JSON体参数UserCreate
+- 请求验证与响应模型
+  - 使用Pydantic模型进行请求体验证
+  - 响应模型Token与UserResponse
+- 错误处理
+  - 用户名或密码错误返回401
+  - 账户禁用返回403
+  - 用户名重复返回400
+- 安全控制
+  - 密码使用bcrypt哈希存储
+  - JWT令牌包含过期时间，默认8小时
+  - 当前用户依赖get_current_active_user保证用户激活状态
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Auth as "认证路由"
+participant Security as "安全模块"
+participant DB as "数据库"
+Client->>Auth : POST /api/v1/auth/login
+Auth->>DB : 查询用户
+DB-->>Auth : 用户对象
+Auth->>Security : 验证密码
+Security-->>Auth : 验证结果
+Auth->>Security : 创建访问令牌
+Security-->>Auth : 令牌
+Auth-->>Client : {access_token, token_type}
+Note over Client,Security : 登录成功后使用Bearer令牌访问受保护资源
+```
+
+**图表来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L17-L37)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L43)
+
+**章节来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L14-L74)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L21-L110)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L315-L345)
+
+### 基础数据模块（departments, staff, indicators）
+- 路由装饰器与依赖
+  - 使用Depends(get_current_active_user)确保用户登录
+  - 部门、员工、指标管理使用get_current_manager_user限制为管理员或经理
+- 查询参数处理
+  - 列表接口统一支持dept_type/status/is_active/keyword/page/page_size等查询参数
+  - 树形结构接口支持dept_type过滤
+- 响应模型
+  - 使用DepartmentResponse、StaffResponse、IndicatorResponse等模型
+  - 列表接口返回统一的分页响应结构
+- 错误处理
+  - 资源不存在返回404
+  - 编码重复返回400
+  - 删除失败返回400
+
+```mermaid
+flowchart TD
+Start(["请求进入"]) --> Parse["解析查询参数<br/>dept_type/status/is_active/keyword/page/page_size"]
+Parse --> Filter["服务层查询<br/>按条件过滤"]
+Filter --> BuildResp["构建响应模型<br/>DepartmentResponse/StaffResponse/IndicatorResponse"]
+BuildResp --> PageWrap["分页包装<br/>统一响应结构"]
+PageWrap --> End(["返回响应"])
+```
+
+**图表来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L20-L40)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L20-L49)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L20-L41)
+
+**章节来源**
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L17-L108)
+- [backend/app/api/v1/staff.py](file://backend/app/api/v1/staff.py#L17-L124)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L17-L142)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L64-L192)
+
+### 考核模块（assessments）
+- 功能特性
+  - 支持创建、更新、提交、审核、确认考核记录
+  - 支持批量创建考核
+  - 明细包含指标ID、实际值、得分、佐证材料与备注
+- 路由装饰器与权限
+  - 多数操作使用get_current_active_user
+  - 审核与确认使用get_current_manager_user
+- 查询参数
+  - 支持按员工、科室、年度、月份、状态筛选
+- 流程控制
+  - 提交、审核、确认按状态机流转，非法状态返回400
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : "提交"
+已提交 --> 已审核 : "审核通过"
+已提交 --> 已驳回 : "审核驳回"
+已审核 --> 已确认 : "确认"
+已确认 --> [*]
+已驳回 --> [*]
+```
+
+**图表来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L31-L37)
+
+**章节来源**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L270)
+
+### 工资模块（salary）
+- 功能特性
+  - 支持创建、更新、确认工资记录
+  - 支持根据考核生成工资、批量生成与批量确认
+- 路由装饰器与权限
+  - 生成与确认使用get_current_manager_user
+- 查询参数
+  - 支持按员工、科室、年度、月份、状态筛选
+- 业务逻辑
+  - 生成工资时需存在已确认的考核记录且无重复工资记录
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Salary as "工资路由"
+participant Service as "工资服务"
+participant DB as "数据库"
+Client->>Salary : POST /api/v1/salary/generate
+Salary->>Service : generate_from_assessment(staff_id, year, month)
+Service->>DB : 查询已确认考核
+DB-->>Service : 考核记录
+Service->>DB : 创建工资记录
+DB-->>Service : 工资记录
+Service-->>Salary : 工资记录
+Salary-->>Client : {code, message, data{id}}
+```
+
+**图表来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L96-L110)
+- [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py)
+
+**章节来源**
+- [backend/app/api/v1/salary.py](file://backend/app/api/v1/salary.py#L17-L156)
+
+### 统计模块（stats）
+- 功能特性
+  - BSC维度分析、科室绩效统计、趋势分析、周期统计、仪表盘指标、预警数据、排名、指标完成度
+- 查询参数
+  - 年度、月份、科室ID、返回数量等
+- 数据处理
+  - 对查询结果进行聚合计算（如平均分、总数等）
+
+```mermaid
+flowchart TD
+Q["接收查询参数<br/>department_id/year/month/limit"] --> Calc["调用统计服务"]
+Calc --> Agg["聚合计算<br/>平均分/总数/排名"]
+Agg --> Resp["构建响应<br/>统一结构"]
+Resp --> Done["返回数据"]
+```
+
+**图表来源**
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L125)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
+
+**章节来源**
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L14-L242)
+
+### 财务模块（finance）
+- 功能特性
+  - 收入、支出、收支结余查询，按类别统计，财务汇总，类别枚举获取
+  - 支持创建、更新、删除财务记录
+- 路由装饰器与权限
+  - 创建、更新、删除使用get_current_manager_user
+- 类别校验
+  - 根据财务类型（收入/支出）校验类别是否有效
+
+```mermaid
+flowchart TD
+Start(["创建财务记录"]) --> Type["判断财务类型"]
+Type --> Rev{"收入?"}
+Rev --> |是| CheckRev["校验收入类别"]
+Rev --> |否| CheckExp["校验支出类别"]
+CheckRev --> Valid{"类别有效?"}
+CheckExp --> Valid
+Valid --> |否| Err["返回400"]
+Valid --> |是| Create["创建记录"]
+Create --> Done["返回成功"]
+```
+
+**图表来源**
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L157-L187)
+
+**章节来源**
+- [backend/app/api/v1/finance.py](file://backend/app/api/v1/finance.py#L18-L217)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L376-L460)
+
+### 计划模块（performance_plans）
+- 功能特性
+  - 绩效计划的CRUD、提交、审批、激活、树形结构、统计信息、指标关联管理
+- 路由装饰器与权限
+  - 多数操作使用get_current_active_user
+  - 审批与激活使用get_current_manager_user
+- 数据结构
+  - 计划与指标关联模型支持权重、评分方法、目标值等
+
+```mermaid
+classDiagram
+class PerformancePlan {
+int id
+string plan_name
+string plan_code
+string plan_level
+int plan_year
+int plan_month
+string status
+int department_id
+int staff_id
+string description
+datetime created_at
+datetime updated_at
+}
+class PlanKpiRelation {
+int id
+int plan_id
+int indicator_id
+float target_value
+string target_unit
+float weight
+string scoring_method
+string scoring_params
+string remark
+}
+PerformancePlan "1" o-- "0..*" PlanKpiRelation : "包含"
+```
+
+**图表来源**
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L519-L570)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L481-L570)
+
+**章节来源**
+- [backend/app/api/v1/performance_plans.py](file://backend/app/api/v1/performance_plans.py#L18-L310)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L461-L580)
+
+### 菜单模块（menus）
+- 功能特性
+  - 菜单树形结构、列表、详情、创建、更新、删除、初始化默认菜单
+- 路由装饰器与权限
+  - 创建、更新、删除、初始化使用get_current_manager_user
+- 树形结构
+  - 支持仅返回可见菜单
+
+**章节来源**
+- [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py#L14-L164)
+
+## 依赖关系分析
+- 路由到服务
+  - 各路由模块通过Depends注入数据库会话，调用对应服务层方法
+  - 服务层封装业务逻辑，避免路由层直接操作数据库
+- 服务到模型
+  - 服务层使用SQLAlchemy异步会话执行查询与事务
+  - 模型定义在models目录，Schema在schemas目录，二者分离职责
+- 安全依赖链
+  - get_current_user -> decode_token -> 数据库查询用户
+  - get_current_active_user -> 检查用户激活状态
+  - get_current_admin_user / get_current_manager_user -> 检查角色
+
+```mermaid
+graph LR
+Route["路由模块"] --> Service["服务模块"]
+Service --> Model["模型定义"]
+Route --> Security["安全依赖"]
+Security --> DB["数据库会话"]
+```
+
+**图表来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L55-L82)
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+**章节来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
+
+## 性能考虑
+- 连接池配置
+  - 数据库连接池大小与溢出配置在配置模块中集中管理，建议根据并发与硬件资源调整
+- 异步IO
+  - 使用SQLAlchemy 2.0异步会话，提升高并发下的吞吐能力
+- 分页与查询优化
+  - 列表接口统一分页参数，避免一次性加载大量数据
+  - 查询参数尽量使用索引字段（如部门ID、状态等）
+- 缓存策略
+  - 配置模块使用LRU缓存缓存Settings实例，减少重复解析环境变量
+- 响应模型序列化
+  - 使用Pydantic模型的model_validate/model_dump，减少手动转换开销
+
+[本节为通用性能指导，不涉及具体文件分析]
+
+## 故障排除指南
+- 认证相关
+  - 401未授权：检查Bearer令牌是否正确传递与未过期
+  - 403禁止访问：检查用户角色与权限依赖
+- 资源不存在
+  - 404：确认ID是否存在，路径参数是否正确
+- 参数验证错误
+  - 422：检查请求体字段类型与长度约束
+- 数据冲突
+  - 400：如用户名重复、编码重复、删除失败等，根据提示修正
+
+**章节来源**
+- [backend/app/api/v1/auth.py](file://backend/app/api/v1/auth.py#L30-L37)
+- [backend/app/api/v1/departments.py](file://backend/app/api/v1/departments.py#L74-L77)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L100-L102)
+
+## 结论
+本系统通过清晰的模块划分、严格的请求验证与响应模型、完善的权限控制与异常处理，实现了稳定可靠的API路由层。结合异步数据库与分页策略，具备良好的扩展性与性能表现。建议在生产环境中进一步完善限流、监控与日志策略，确保系统在高并发场景下的稳定性。
+
+## 附录
+
+### RESTful设计原则
+- 资源命名：使用名词复数形式（如/departments、/staff、/indicators）
+- 路径参数：唯一标识资源（如/{dept_id}）
+- 查询参数：过滤与分页（如?page&page_size）
+- 状态码：遵循HTTP语义（200、201、400、401、403、404、422、500）
+- 响应格式：统一使用包含code、message、data的结构
+
+### HTTP状态码使用
+- 200：成功获取或更新
+- 201：成功创建
+- 400：客户端参数错误或业务逻辑错误
+- 401：未认证
+- 403：权限不足
+- 404：资源不存在
+- 422：请求体验证失败
+- 500：服务器内部错误
+
+### API版本管理
+- 版本前缀：/api/v1
+- 文档路径：/api/v1/docs、/api/v1/redoc、/api/v1/openapi.json
+- 配置集中：settings.API_PREFIX统一管理
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L19-L39)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L16-L16)
+
+### 文档生成与测试
+- 文档生成：FastAPI自动生成OpenAPI规范与交互式文档
+- 测试方法：建议使用pytest与HTTP客户端对各模块进行单元测试与集成测试
+
+[本节为通用指导，不涉及具体文件分析]
+
+### CORS配置与中间件
+- CORS中间件：允许跨域请求，支持凭证、通配符方法与头
+- 中间件注册：在应用创建时添加至FastAPI实例
+
+**章节来源**
+- [backend/app/main.py](file://backend/app/main.py#L41-L48)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L28-L29)
+
+### 安全控制
+- JWT令牌：使用SECRET_KEY与ALGORITHM签名，ACCESS_TOKEN_EXPIRE_MINUTES控制有效期
+- 密码哈希：bcrypt确保密码安全存储
+- 权限依赖：多级权限校验，确保敏感操作仅管理员或经理可执行
+
+**章节来源**
+- [backend/app/core/security.py](file://backend/app/core/security.py#L24-L110)
+- [backend/app/core/config.py](file://backend/app/core/config.py#L23-L26)
+
+### 性能优化与限流策略
+- 连接池：合理配置pool_size与max_overflow
+- 异步查询：利用异步会话减少阻塞
+- 缓存：对热点配置与查询结果进行缓存
+- 限流：建议引入速率限制中间件（如基于IP或令牌的限流）
+- 监控：集成APM工具（如Prometheus + Grafana）监控QPS、延迟与错误率
+
+[本节为通用指导，不涉及具体文件分析]