chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hospital_performance/.qoder/repowiki/zh/content/后端开发指南/API路由实现/API路由实现.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

21 KiB
Raw Permalink Blame History

API路由实现

**本文档引用的文件** - [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)

目录

  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调用示例
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

图表来源

章节来源

核心组件

  • 应用实例与中间件
    • 使用FastAPI构造应用，配置标题、版本、描述与OpenAPI文档路径
    • 注册CORS中间件，允许跨域请求
    • 注册API路由器，统一前缀为配置中的API_PREFIX
    • 定义健康检查端点
    • 注册全局异常处理器，记录日志并抛出异常
  • 配置管理
    • 通过Settings类集中管理应用名、版本、数据库连接、JWT密钥、CORS白名单、分页参数等
    • 使用lru_cache缓存配置实例
  • 安全认证
    • 基于JWT的OAuth2密码流，支持密码哈希、令牌签发与解析
    • 提供当前用户、激活用户、管理员、经理权限校验依赖
  • Schema定义
    • 统一响应模型ResponseBase与分页模型PaginatedResponse
    • 定义枚举类型（科室类型、员工状态、考核状态、指标类型、财务类型等）
    • 为各模块定义输入输出模型，确保请求验证与响应格式标准化

章节来源

架构概览

系统采用分层架构：路由层（FastAPI装饰器与依赖注入）、服务层（业务逻辑封装）、数据层（SQLAlchemy异步ORM）。路由层负责参数解析、权限校验与响应包装；服务层负责领域逻辑；数据层负责持久化。

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

图表来源

详细组件分析

认证模块（auth）

  • 路由装饰器使用
    • 使用APIRouter装饰器定义路由前缀与标签
    • 使用Depends注入数据库会话与安全依赖
  • 路径与查询参数
    • 登录接口使用OAuth2PasswordRequestForm自动解析表单参数
    • 注册接口接收JSON体参数UserCreate
  • 请求验证与响应模型
    • 使用Pydantic模型进行请求体验证
    • 响应模型Token与UserResponse
  • 错误处理
    • 用户名或密码错误返回401
    • 账户禁用返回403
    • 用户名重复返回400
  • 安全控制
    • 密码使用bcrypt哈希存储
    • JWT令牌包含过期时间，默认8小时
    • 当前用户依赖get_current_active_user保证用户激活状态
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令牌访问受保护资源

图表来源

章节来源

基础数据模块（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
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(["返回响应"])

图表来源

章节来源

考核模块（assessments）

  • 功能特性
    • 支持创建、更新、提交、审核、确认考核记录
    • 支持批量创建考核
    • 明细包含指标ID、实际值、得分、佐证材料与备注
  • 路由装饰器与权限
    • 多数操作使用get_current_active_user
    • 审核与确认使用get_current_manager_user
  • 查询参数
    • 支持按员工、科室、年度、月份、状态筛选
  • 流程控制
    • 提交、审核、确认按状态机流转，非法状态返回400
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交"
已提交 --> 已审核 : "审核通过"
已提交 --> 已驳回 : "审核驳回"
已审核 --> 已确认 : "确认"
已确认 --> [*]
已驳回 --> [*]

图表来源

章节来源

工资模块（salary）

  • 功能特性
    • 支持创建、更新、确认工资记录
    • 支持根据考核生成工资、批量生成与批量确认
  • 路由装饰器与权限
    • 生成与确认使用get_current_manager_user
  • 查询参数
    • 支持按员工、科室、年度、月份、状态筛选
  • 业务逻辑
    • 生成工资时需存在已确认的考核记录且无重复工资记录
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}}

图表来源

章节来源

统计模块（stats）

  • 功能特性
    • BSC维度分析、科室绩效统计、趋势分析、周期统计、仪表盘指标、预警数据、排名、指标完成度
  • 查询参数
    • 年度、月份、科室ID、返回数量等
  • 数据处理
    • 对查询结果进行聚合计算（如平均分、总数等）
flowchart TD
Q["接收查询参数<br/>department_id/year/month/limit"] --> Calc["调用统计服务"]
Calc --> Agg["聚合计算<br/>平均分/总数/排名"]
Agg --> Resp["构建响应<br/>统一结构"]
Resp --> Done["返回数据"]

图表来源

章节来源

财务模块（finance）

  • 功能特性
    • 收入、支出、收支结余查询，按类别统计，财务汇总，类别枚举获取
    • 支持创建、更新、删除财务记录
  • 路由装饰器与权限
    • 创建、更新、删除使用get_current_manager_user
  • 类别校验
    • 根据财务类型（收入/支出）校验类别是否有效
flowchart TD
Start(["创建财务记录"]) --> Type["判断财务类型"]
Type --> Rev{"收入?"}
Rev --> |是| CheckRev["校验收入类别"]
Rev --> |否| CheckExp["校验支出类别"]
CheckRev --> Valid{"类别有效?"}
CheckExp --> Valid
Valid --> |否| Err["返回400"]
Valid --> |是| Create["创建记录"]
Create --> Done["返回成功"]

图表来源

章节来源

计划模块（performance_plans）

  • 功能特性
    • 绩效计划的CRUD、提交、审批、激活、树形结构、统计信息、指标关联管理
  • 路由装饰器与权限
    • 多数操作使用get_current_active_user
    • 审批与激活使用get_current_manager_user
  • 数据结构
    • 计划与指标关联模型支持权重、评分方法、目标值等
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 : "包含"

图表来源

章节来源

菜单模块（menus）

  • 功能特性
    • 菜单树形结构、列表、详情、创建、更新、删除、初始化默认菜单
  • 路由装饰器与权限
    • 创建、更新、删除、初始化使用get_current_manager_user
  • 树形结构
    • 支持仅返回可见菜单

章节来源

依赖关系分析

  • 路由到服务
    • 各路由模块通过Depends注入数据库会话，调用对应服务层方法
    • 服务层封装业务逻辑，避免路由层直接操作数据库
  • 服务到模型
    • 服务层使用SQLAlchemy异步会话执行查询与事务
    • 模型定义在models目录，Schema在schemas目录，二者分离职责
  • 安全依赖链
    • get_current_user -> decode_token -> 数据库查询用户
    • get_current_active_user -> 检查用户激活状态
    • get_current_admin_user / get_current_manager_user -> 检查角色
graph LR
Route["路由模块"] --> Service["服务模块"]
Service --> Model["模型定义"]
Route --> Security["安全依赖"]
Security --> DB["数据库会话"]

图表来源

章节来源

性能考虑

  • 连接池配置
    • 数据库连接池大小与溢出配置在配置模块中集中管理，建议根据并发与硬件资源调整
  • 异步IO
    • 使用SQLAlchemy 2.0异步会话，提升高并发下的吞吐能力
  • 分页与查询优化
    • 列表接口统一分页参数，避免一次性加载大量数据
    • 查询参数尽量使用索引字段（如部门ID、状态等）
  • 缓存策略
    • 配置模块使用LRU缓存缓存Settings实例，减少重复解析环境变量
  • 响应模型序列化
    • 使用Pydantic模型的model_validate/model_dump，减少手动转换开销

[本节为通用性能指导，不涉及具体文件分析]

故障排除指南

  • 认证相关
    • 401未授权：检查Bearer令牌是否正确传递与未过期
    • 403禁止访问：检查用户角色与权限依赖
  • 资源不存在
    • 404：确认ID是否存在，路径参数是否正确
  • 参数验证错误
    • 422：检查请求体字段类型与长度约束
  • 数据冲突
    • 400：如用户名重复、编码重复、删除失败等，根据提示修正

章节来源

结论

本系统通过清晰的模块划分、严格的请求验证与响应模型、完善的权限控制与异常处理，实现了稳定可靠的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统一管理

章节来源

文档生成与测试

  • 文档生成：FastAPI自动生成OpenAPI规范与交互式文档
  • 测试方法：建议使用pytest与HTTP客户端对各模块进行单元测试与集成测试

[本节为通用指导，不涉及具体文件分析]

CORS配置与中间件

  • CORS中间件：允许跨域请求，支持凭证、通配符方法与头
  • 中间件注册：在应用创建时添加至FastAPI实例

章节来源

安全控制

  • JWT令牌：使用SECRET_KEY与ALGORITHM签名，ACCESS_TOKEN_EXPIRE_MINUTES控制有效期
  • 密码哈希：bcrypt确保密码安全存储
  • 权限依赖：多级权限校验，确保敏感操作仅管理员或经理可执行

章节来源

性能优化与限流策略

  • 连接池：合理配置pool_size与max_overflow
  • 异步查询：利用异步会话减少阻塞
  • 缓存：对热点配置与查询结果进行缓存
  • 限流：建议引入速率限制中间件（如基于IP或令牌的限流）
  • 监控：集成APM工具（如Prometheus + Grafana）监控QPS、延迟与错误率

[本节为通用指导，不涉及具体文件分析]