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

18 KiB
Raw Blame History

基础数据接口

**本文档引用的文件** - [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/salary.py](file://backend/app/api/v1/salary.py) - [backend/app/services/department_service.py](file://backend/app/services/department_service.py) - [backend/app/services/staff_service.py](file://backend/app/services/staff_service.py) - [backend/app/services/indicator_service.py](file://backend/app/services/indicator_service.py) - [backend/app/services/salary_service.py](file://backend/app/services/salary_service.py) - [backend/app/models/models.py](file://backend/app/models/models.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/app/main.py](file://backend/app/main.py) - [frontend/src/api/department.js](file://frontend/src/api/department.js) - [frontend/src/api/staff.js](file://frontend/src/api/staff.js) - [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js) - [frontend/src/api/salary.js](file://frontend/src/api/salary.js)

目录

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

简介

本文件面向基础数据接口的详细文档，涵盖以下模块：

  • 科室管理：支持树形结构的增删改查、层级关系维护与权限控制
  • 员工管理：支持员工信息的CRUD、按科室检索与状态管理
  • 考核指标管理：支持指标分类、权重设置、计算公式与模板导入
  • 工资相关接口：支持工资记录的CRUD、批量生成与确认、业务规则校验

文档同时说明RESTful设计原则、统一响应格式、分页查询、条件筛选、排序规则、数据导入导出与批量操作的实现思路，以及错误处理策略。

项目结构

后端采用FastAPI + SQLAlchemy 2.0 + 异步数据库访问，遵循分层架构：

  • API层：定义路由与请求参数校验
  • 服务层：封装业务逻辑与数据访问
  • 模型层：定义数据库实体与关系
  • 模式层：定义Pydantic数据结构用于序列化与校验
  • 前端层：通过Axios封装的API调用
graph TB
subgraph "前端"
FE_Dep["department.js"]
FE_Staff["staff.js"]
FE_Ind["indicator.js"]
FE_Sal["salary.js"]
end
subgraph "后端"
API_Dep["departments.py"]
API_Staff["staff.py"]
API_Ind["indicators.py"]
API_Sal["salary.py"]
SVC_Dep["department_service.py"]
SVC_Staff["staff_service.py"]
SVC_Ind["indicator_service.py"]
SVC_Sal["salary_service.py"]
MODELS["models.py"]
SCHEMAS["schemas.py"]
MAIN["main.py"]
end
FE_Dep --> API_Dep
FE_Staff --> API_Staff
FE_Ind --> API_Ind
FE_Sal --> API_Sal
API_Dep --> SVC_Dep
API_Staff --> SVC_Staff
API_Ind --> SVC_Ind
API_Sal --> SVC_Sal
SVC_Dep --> MODELS
SVC_Staff --> MODELS
SVC_Ind --> MODELS
SVC_Sal --> MODELS
API_Dep --> SCHEMAS
API_Staff --> SCHEMAS
API_Ind --> SCHEMAS
API_Sal --> SCHEMAS
MAIN --> API_Dep
MAIN --> API_Staff
MAIN --> API_Ind
MAIN --> API_Sal

图表来源

章节来源

核心组件

  • API路由层：定义RESTful端点，负责参数解析、权限校验与统一响应包装
  • 服务层：封装业务逻辑，处理数据访问、复杂查询与事务控制
  • 模型层：定义实体关系、索引与约束，支撑树形结构与多对多关系
  • 模式层：定义输入输出结构，确保前后端数据一致性与校验

章节来源

架构概览

系统采用分层架构，API层仅负责协议转换与权限控制，服务层承担业务规则，模型层承载数据结构与约束。统一响应格式包含状态码、消息、数据体、分页信息；异常通过全局处理器记录并抛出。

sequenceDiagram
participant Client as "客户端"
participant API as "API路由"
participant Service as "服务层"
participant DB as "数据库"
Client->>API : "HTTP请求"
API->>API : "参数校验/权限检查"
API->>Service : "调用业务逻辑"
Service->>DB : "SQLAlchemy查询/写入"
DB-->>Service : "返回结果"
Service-->>API : "业务结果"
API-->>Client : "统一响应格式"

图表来源

详细组件分析

科室管理接口

  • 功能范围

    • 列表查询：支持按类型、启用状态过滤，分页与排序
    • 树形结构：按层级与排序生成树形结构，便于前端渲染
    • 单条查询：按ID获取详情
    • 新增/更新/删除：新增时自动计算层级，删除前检查是否存在子节点
    • 权限控制：新增、更新、删除需管理员或经理权限

  • 数据模型与关系

    • Department实体支持自引用父-子关系，维护level与sort_order
    • 通过索引优化dept_type与parent_id查询

  • 统一响应与分页

    • 响应包含code、message、data、total、page、page_size
    • 列表默认按sort_order与id排序

  • 错误处理

    • 未找到资源返回404
    • 删除失败（存在子节点）返回400
classDiagram
class Department {
+int id
+string name
+string code
+DeptType dept_type
+int parent_id
+int level
+int sort_order
+bool is_active
+string description
+datetime created_at
+datetime updated_at
+Department parent
+Staff[] staff
}
class DepartmentService {
+get_list(...)
+get_tree(...)
+get_by_id(...)
+get_by_code(...)
+create(...)
+update(...)
+delete(...)
}
DepartmentService --> Department : "读写"

图表来源

章节来源

员工管理接口

  • 功能范围

    • 列表查询：支持按科室、状态、关键词（姓名/工号）过滤，分页与排序
    • 单条查询：按ID获取详情，附加科室名称
    • 新增/更新/删除：新增前检查工号唯一性
    • 科室员工查询：按科室ID获取在职员工列表

  • 数据模型与关系

    • Staff与Department为多对一关系，支持按状态与部门ID高效查询
    • 提供索引优化department_id与status字段

  • 统一响应与分页

    • 响应包含code、message、data、total、page、page_size
    • 列表默认按id倒序

  • 错误处理

    • 未找到资源返回404
classDiagram
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+string title
+string phone
+string email
+float base_salary
+float performance_ratio
+StaffStatus status
+datetime hire_date
+datetime created_at
+datetime updated_at
+Department department
+Assessment[] assessments
+SalaryRecord[] salary_records
}
class StaffService {
+get_list(...)
+get_by_id(...)
+get_by_employee_id(...)
+create(...)
+update(...)
+delete(...)
+get_by_department(...)
}
StaffService --> Staff : "读写"

图表来源

章节来源

考核指标管理接口

  • 功能范围

    • 列表查询：支持按指标类型、BSC维度、启用状态过滤，分页与排序
    • 启用指标查询：获取全部启用的指标
    • 单条查询：按ID获取详情
    • 新增/更新/删除：新增前检查指标编码唯一性
    • 模板管理：提供模板列表与导入能力，支持覆盖策略

  • 数据模型与关系

    • Indicator实体包含指标类型、BSC维度、权重、最高分值、目标值与单位、计算方法、适用科室类型等
    • 提供索引优化indicator_type字段与权重约束

  • 统一响应与分页

    • 响应包含code、message、data、total、page、page_size
    • 列表默认按indicator_type与id排序

  • 模板导入流程

    • 按模板dept_type批量导入指标，支持覆盖已有指标
flowchart TD
Start(["开始导入"]) --> LoadTemplate["加载模板数据"]
LoadTemplate --> Iterate["遍历指标项"]
Iterate --> Exists{"指标已存在？"}
Exists --> |是且覆盖| Update["更新现有指标"]
Exists --> |是不覆盖| Skip["跳过该指标"]
Exists --> |否| Create["创建新指标"]
Update --> Next["下一个指标"]
Skip --> Next
Create --> Next
Next --> Done(["完成导入"])

图表来源

章节来源

工资核算管理接口

  • 功能范围

    • 列表查询：支持按员工、科室、年度、月份、状态过滤，分页与排序
    • 单条查询：按ID获取详情，附加员工与科室名称
    • 新增/更新：创建时计算总工资，更新时重新计算总工资
    • 生成工资：根据已确认的考核记录生成工资记录
    • 批量生成：按科室批量生成工资记录
    • 确认工资：单条与批量确认，状态变更

  • 业务规则

    • 工资 = 基本工资 + 绩效奖金 + 补贴 - 扣款
    • 绩效奖金 = 固定基数 × (绩效得分/100) × 员工绩效系数
    • 仅允许对“待确认”状态进行更新与确认

  • 统一响应与分页

    • 响应包含code、message、data、total、page、page_size
    • 列表默认按年度、月份、id倒序

  • 批量操作

    • 批量生成与批量确认均支持按科室过滤
sequenceDiagram
participant Client as "客户端"
participant API as "salary.py"
participant Service as "salary_service.py"
participant DB as "数据库"
Client->>API : "POST /salary/generate?staff_id=&period_year=&period_month="
API->>Service : "generate_from_assessment(...)"
Service->>DB : "查询员工与已确认考核记录"
DB-->>Service : "返回员工与考核记录"
Service->>Service : "计算绩效奖金与总工资"
Service->>DB : "插入工资记录"
DB-->>Service : "返回新记录"
Service-->>API : "返回记录ID"
API-->>Client : "统一响应"

图表来源

章节来源

依赖分析

  • API层依赖服务层与安全中间件，统一响应包装
  • 服务层依赖模型层进行数据持久化
  • 模式层为API与服务层提供数据契约
  • 前端通过Axios封装的API与后端交互
graph LR
FE_Dep["frontend/src/api/department.js"] --> API_Dep["backend/app/api/v1/departments.py"]
FE_Staff["frontend/src/api/staff.js"] --> API_Staff["backend/app/api/v1/staff.py"]
FE_Ind["frontend/src/api/indicator.js"] --> API_Ind["backend/app/api/v1/indicators.py"]
FE_Sal["frontend/src/api/salary.js"] --> API_Sal["backend/app/api/v1/salary.py"]
API_Dep --> SVC_Dep["backend/app/services/department_service.py"]
API_Staff --> SVC_Staff["backend/app/services/staff_service.py"]
API_Ind --> SVC_Ind["backend/app/services/indicator_service.py"]
API_Sal --> SVC_Sal["backend/app/services/salary_service.py"]
SVC_Dep --> MODELS["backend/app/models/models.py"]
SVC_Staff --> MODELS
SVC_Ind --> MODELS
SVC_Sal --> MODELS
API_Dep --> SCHEMAS["backend/app/schemas/schemas.py"]
API_Staff --> SCHEMAS
API_Ind --> SCHEMAS
API_Sal --> SCHEMAS

图表来源

性能考虑

  • 查询优化
    • 使用索引：科室类型、父节点ID、员工部门ID、状态、指标类型、考核记录周期、工资记录周期等
    • 分页查询：限制每页最大数量，避免一次性返回大量数据
    • 关联预加载：使用selectinload减少N+1查询
  • 事务与并发
    • 服务层方法内部保持事务一致性，避免脏读与丢失更新
  • 缓存与异步
    • 当前实现为同步处理，如需高并发场景可引入缓存与异步任务队列

故障排除指南

  • 常见错误
    • 404：资源不存在（科室、员工、指标、工资记录）
    • 400：业务规则不满足（删除存在子节点的科室、重复编码、状态不允许更新/确认）
  • 日志与异常
    • 全局异常处理器记录HTTP异常与验证异常，便于定位问题
  • 排查步骤
    • 检查请求参数与权限头
    • 查看服务层日志与数据库事务状态
    • 确认业务规则（如状态机、唯一性约束）

章节来源

结论

本系统通过清晰的分层架构与统一的数据契约，实现了基础数据管理的核心能力。科室管理支持树形结构与层级维护，员工管理提供灵活的查询与状态管理，指标管理具备模板导入与权重配置能力，工资管理覆盖从生成到确认的完整流程。建议后续在高并发场景引入缓存与异步处理，并持续完善数据校验与审计日志。