Files

2026-02-28 15:16:15 +08:00

20 KiB

Raw Blame History

API接口文档

**本文档引用的文件** - [backend/app/main.py](file://backend/app/main.py) - [backend/app/core/security.py](file://backend/app/core/security.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/performance_plans.py](file://backend/app/api/v1/performance_plans.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/finance.py](file://backend/app/api/v1/finance.py) - [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py) - [backend/app/api/v1/menus.py](file://backend/app/api/v1/menus.py) - [backend/app/api/v1/templates.py](file://backend/app/api/v1/templates.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py) - [backend/app/models/models.py](file://backend/app/models/models.py)

简介

本文件为医院绩效管理系统API接口的完整文档。系统采用FastAPI + SQLAlchemy 2.0架构，支持异步IO操作，提供RESTful API接口，涵盖认证授权、基础数据管理、绩效考核、工资核算、财务统计、系统管理等核心功能模块。

系统采用JWT令牌认证机制，支持管理员(admin)、经理(manager)、普通员工(staff)三种角色权限控制，确保数据安全和业务流程的规范性。

项目结构

后端采用模块化架构设计，主要目录结构如下：

graph TB
subgraph "后端应用结构"
A["app/"] --> B["api/v1/"]
A --> C["core/"]
A --> D["models/"]
A --> E["services/"]
A --> F["schemas/"]
B --> B1["认证接口(auth.py)"]
B --> B2["基础数据(departments.py, staff.py, indicators.py)"]
B --> B3["考核管理(performance_plans.py, assessments.py)"]
B --> B4["工资核算(salary.py)"]
B --> B5["财务核算(finance.py)"]
B --> B6["统计分析(stats.py)"]
B --> B7["系统管理(menus.py, templates.py)"]
C --> C1["安全配置(security.py)"]
C --> C2["数据库配置(database.py)"]
C --> C3["配置管理(config.py)"]
D --> D1["数据模型(models.py)"]
F --> F1["数据模式(schemas.py)"]
end

图表来源

章节来源

backend/app/main.py

核心组件

认证与安全机制

系统采用JWT令牌进行身份认证，支持多种权限级别：

用户认证: OAuth2密码模式，支持用户名密码登录
权限控制:
- 普通用户: 仅能查看和基本操作
- 经理用户: 可进行数据维护和审批操作
- 管理员: 拥有系统完全管理权限
密码安全: 使用bcrypt进行密码哈希存储

数据模型架构

系统采用SQLAlchemy ORM映射，核心实体包括：

基础实体: 科室、员工、指标
业务实体: 考核记录、工资记录、绩效计划
系统实体: 用户、菜单、指标模板

章节来源

架构概览

graph TB
subgraph "客户端层"
Web[Web前端]
Mobile[移动端]
API[第三方系统]
end
subgraph "API网关层"
FastAPI[FastAPI应用]
CORS[CORS中间件]
Router[路由分发]
end
subgraph "业务逻辑层"
Auth[认证模块]
Services[业务服务层]
Security[安全控制]
end
subgraph "数据访问层"
DB[(PostgreSQL数据库)]
ORM[SQLAlchemy ORM]
end
subgraph "配置层"
Config[应用配置]
Logging[日志配置]
end
Web --> FastAPI
Mobile --> FastAPI
API --> FastAPI
FastAPI --> CORS
FastAPI --> Router
FastAPI --> Auth
FastAPI --> Services
FastAPI --> Security
Services --> ORM
ORM --> DB
FastAPI --> Config
Auth --> Config
Security --> Config
Logging --> Config

图表来源

详细组件分析

认证接口模块

用户登录

HTTP方法: POST
URL模式: /api/v1/auth/login
请求参数:
- username: 字符串，最小长度3，最大长度50
- password: 字符串，最小长度6，最大长度100

响应格式:

{
  "access_token": "字符串",
  "token_type": "bearer"
}

错误码: 401(用户名或密码错误)，403(账户已禁用)

用户注册

HTTP方法: POST
URL模式: /api/v1/auth/register
请求参数:
- username: 字符串，唯一性约束
- password: 字符串，密码哈希处理
- staff_id: 整数，关联员工信息
- role: 字符串，角色类型

响应格式:

{
  "code": 200,
  "message": "注册成功",
  "data": {"id": 1}
}

获取当前用户信息

HTTP方法: GET
URL模式: /api/v1/auth/me
权限要求: 需要有效JWT令牌
响应格式: 用户基本信息

章节来源

基础数据接口模块

科室管理接口

获取科室列表

HTTP方法: GET
URL模式: /api/v1/departments
查询参数:
- dept_type: 科室类型过滤
- is_active: 是否启用过滤
- page/page_size: 分页参数
响应格式: 分页响应，包含科室列表和统计信息

创建科室

HTTP方法: POST
URL模式: /api/v1/departments
权限要求: 管理员或经理权限
请求验证: 科室编码唯一性检查

更新科室

HTTP方法: PUT
URL模式: /api/v1/departments/{dept_id}

删除科室

HTTP方法: DELETE
URL模式: /api/v1/departments/{dept_id}
权限要求: 管理员或经理权限
业务规则: 无法删除存在子科室的科室

员工管理接口

获取员工列表

HTTP方法: GET
URL模式: /api/v1/staff
查询参数:
- department_id: 科室ID过滤
- status: 员工状态过滤
- keyword: 搜索关键词
响应格式: 包含科室名称的员工列表

创建员工

HTTP方法: POST
URL模式: /api/v1/staff
权限要求: 管理员或经理权限
请求验证: 工号唯一性检查

获取科室员工

HTTP方法: GET
URL模式: /api/v1/staff/department/{department_id}

指标管理接口

获取指标列表

HTTP方法: GET
URL模式: /api/v1/indicators
查询参数:
- indicator_type: 指标类型
- bs_dimension: 平衡计分卡维度
- is_active: 是否启用

创建指标

HTTP方法: POST
URL模式: /api/v1/indicators
权限要求: 管理员或经理权限
请求验证: 指标编码唯一性检查

指标模板管理

HTTP方法: GET
URL模式: /api/v1/indicators/templates/list
业务功能: 获取可用的指标模板列表

章节来源

考核管理接口模块

绩效计划管理

获取计划列表

HTTP方法: GET
URL模式: /api/v1/plans
查询参数:
- plan_level: 计划层级
- plan_year: 计划年度
- department_id: 科室ID
- status: 状态过滤

创建绩效计划

HTTP方法: POST
URL模式: /api/v1/plans
请求参数: 计划基本信息和KPI关联

提交计划

HTTP方法: POST
URL模式: /api/v1/plans/{plan_id}/submit

审批计划

HTTP方法: POST
URL模式: /api/v1/plans/{plan_id}/approve
权限要求: 管理员或经理权限

激活计划

HTTP方法: POST
URL模式: /api/v1/plans/{plan_id}/activate
权限要求: 管理员或经理权限

绩效考核管理

获取考核列表

HTTP方法: GET
URL模式: /api/v1/assessments
查询参数:
- staff_id: 员工ID
- department_id: 科室ID
- period_year: 年度
- period_month: 月份
- status: 状态

创建考核记录

HTTP方法: POST
URL模式: /api/v1/assessments

批量创建考核

HTTP方法: POST
URL模式: /api/v1/assessments/batch-create
权限要求: 管理员或经理权限

审核考核

HTTP方法: POST
URL模式: /api/v1/assessments/{assessment_id}/review
权限要求: 管理员或经理权限

章节来源

工资核算接口模块

工资记录管理

获取工资记录列表

HTTP方法: GET
URL模式: /api/v1/salary
查询参数:
- staff_id: 员工ID
- department_id: 科室ID
- period_year: 年度
- period_month: 月份
- status: 状态

创建工资记录

HTTP方法: POST
URL模式: /api/v1/salary
权限要求: 管理员或经理权限

根据考核生成工资

HTTP方法: POST
URL模式: /api/v1/salary/generate
权限要求: 管理员或经理权限

批量生成工资

HTTP方法: POST
URL模式: /api/v1/salary/batch-generate
权限要求: 管理员或经理权限

确认工资

HTTP方法: POST
URL模式: /api/v1/salary/{record_id}/confirm
权限要求: 管理员或经理权限

章节来源

backend/app/api/v1/salary.py

财务核算接口模块

财务数据查询

获取科室收入

HTTP方法: GET
URL模式: /api/v1/finance/revenue

获取科室支出

HTTP方法: GET
URL模式: /api/v1/finance/expense

获取收支结余

HTTP方法: GET
URL模式: /api/v1/finance/balance

按类别统计收入/支出

HTTP方法: GET
URL模式: /api/v1/finance/revenue/by-category
URL模式: /api/v1/finance/expense/by-category

获取财务汇总

HTTP方法: GET
URL模式: /api/v1/finance/summary

财务记录管理

创建财务记录

HTTP方法: POST
URL模式: /api/v1/finance
权限要求: 管理员或经理权限
请求验证: 类别有效性检查

更新财务记录

HTTP方法: PUT
URL模式: /api/v1/finance/{record_id}
权限要求: 管理员或经理权限

删除财务记录

HTTP方法: DELETE
URL模式: /api/v1/finance/{record_id}
权限要求: 管理员或经理权限

章节来源

backend/app/api/v1/finance.py

统计分析接口模块

绩效统计分析

BSC维度分析

HTTP方法: GET
URL模式: /api/v1/stats/bsc-dimension

科室绩效统计

HTTP方法: GET
URL模式: /api/v1/stats/department

趋势分析

HTTP方法: GET
URL模式: /api/v1/stats/trend
查询参数: months(最近几个月)

周期统计

HTTP方法: GET
URL模式: /api/v1/stats/period

关键指标仪表盘

HTTP方法: GET
URL模式: /api/v1/stats/kpi-gauges

排名统计

科室绩效排名

HTTP方法: GET
URL模式: /api/v1/stats/department-ranking

绩效排名

HTTP方法: GET
URL模式: /api/v1/stats/ranking

指标完成度

HTTP方法: GET
URL模式: /api/v1/stats/completion

章节来源

backend/app/api/v1/stats.py

系统管理接口模块

菜单管理

获取菜单树

HTTP方法: GET
URL模式: /api/v1/menus/tree
查询参数: visible_only(是否只返回可见菜单)

获取菜单列表

HTTP方法: GET
URL模式: /api/v1/menus

创建菜单

HTTP方法: POST
URL模式: /api/v1/menus
权限要求: 管理员或经理权限

更新菜单

HTTP方法: PUT
URL模式: /api/v1/menus/{menu_id}
权限要求: 管理员或经理权限

删除菜单

HTTP方法: DELETE
URL模式: /api/v1/menus/{menu_id}
权限要求: 管理员或经理权限

初始化默认菜单

HTTP方法: POST
URL模式: /api/v1/menus/init
权限要求: 管理员权限

指标模板管理

获取模板列表

HTTP方法: GET
URL模式: /api/v1/templates

获取模板类型列表

HTTP方法: GET
URL模式: /api/v1/templates/types

获取BSC维度列表

HTTP方法: GET
URL模式: /api/v1/templates/dimensions

创建模板

HTTP方法: POST
URL模式: /api/v1/templates
权限要求: 管理员或经理权限

添加模板指标

HTTP方法: POST
URL模式: /api/v1/templates/{template_id}/indicators
权限要求: 管理员或经理权限

批量添加模板指标

HTTP方法: POST
URL模式: /api/v1/templates/{template_id}/indicators/batch
权限要求: 管理员或经理权限

章节来源

依赖关系分析

graph TB
subgraph "API层"
AuthAPI[认证API]
BasicAPI[基础数据API]
AssessmentAPI[考核API]
SalaryAPI[工资API]
FinanceAPI[财务API]
StatsAPI[统计API]
MenuAPI[菜单API]
TemplateAPI[模板API]
end
subgraph "服务层"
AuthService[认证服务]
DeptService[科室服务]
StaffService[员工服务]
IndService[指标服务]
PlanService[计划服务]
AssessService[考核服务]
SalaryService[工资服务]
FinanceService[财务服务]
StatsService[统计服务]
MenuService[菜单服务]
TemplateService[模板服务]
end
subgraph "数据层"
UserModel[用户模型]
DeptModel[科室模型]
StaffModel[员工模型]
IndModel[指标模型]
PlanModel[计划模型]
AssessModel[考核模型]
SalaryModel[工资模型]
FinanceModel[财务模型]
MenuModel[菜单模型]
TemplateModel[模板模型]
end
AuthAPI --> AuthService
BasicAPI --> DeptService
BasicAPI --> StaffService
BasicAPI --> IndService
AssessmentAPI --> PlanService
AssessmentAPI --> AssessService
SalaryAPI --> SalaryService
FinanceAPI --> FinanceService
StatsAPI --> StatsService
MenuAPI --> MenuService
TemplateAPI --> TemplateService
AuthService --> UserModel
DeptService --> DeptModel
StaffService --> StaffModel
IndService --> IndModel
PlanService --> PlanModel
AssessService --> AssessModel
SalaryService --> SalaryModel
FinanceService --> FinanceModel
MenuService --> MenuModel
TemplateService --> TemplateModel

图表来源

章节来源

性能考虑

数据库优化策略

索引优化
- 关键查询字段建立复合索引
- 时间范围查询优化
- 多条件过滤查询优化
查询优化
- 分页查询避免全表扫描
- 连接查询优化
- 子查询优化
缓存策略
- 配置热点数据缓存
- 结果集缓存
- 查询结果缓存

异步处理

系统采用异步IO架构，支持高并发请求处理：

异步数据库操作: SQLAlchemy 2.0异步支持
异步文件处理: 日志和配置文件异步读取
异步任务队列: 后台任务处理

安全考虑

认证安全
- JWT令牌过期时间控制
- 密码哈希存储
- 会话管理
授权控制
- 基于角色的访问控制(RBAC)
- 请求权限验证
- 数据访问权限控制
输入验证
- 参数类型验证
- 长度和范围验证
- 格式验证

故障排除指南

常见错误码

错误码	描述	可能原因
400	请求参数错误	参数类型不正确或缺失
401	未授权	JWT令牌无效或过期
403	禁止访问	权限不足或账户被禁用
404	资源不存在	请求的资源不存在
422	数据验证错误	业务规则验证失败
500	服务器内部错误	服务器异常

调试步骤

检查认证状态
- 验证JWT令牌有效性
- 检查用户权限级别
- 确认账户状态正常
验证请求参数
- 检查必填参数
- 验证参数格式
- 确认参数范围
查看系统日志
- 应用程序日志
- 数据库查询日志
- 错误日志分析
测试API端点
- 使用Swagger UI测试
- 编写单元测试
- 集成测试验证

章节来源

backend/app/main.py

结论

本API接口文档涵盖了医院绩效管理系统的核心功能模块，提供了完整的RESTful API规范。系统采用现代化的技术栈，具备良好的扩展性和安全性。通过清晰的权限控制和数据验证机制，确保了系统的稳定运行。

建议在实际部署时：

配置适当的环境变量和数据库连接
设置合理的JWT令牌过期时间
实施监控和日志记录
定期备份数据库
进行安全审计和渗透测试

附录

API版本管理

系统采用URL前缀版本控制：

版本前缀: /api/v1
开放API文档: /api/v1/docs
Redoc文档: /api/v1/redoc

速率限制

系统支持多种速率限制策略：

基于IP的请求频率限制
基于用户的API调用限制
针对敏感操作的额外限制

请求响应示例

成功响应格式

{
  "code": 200,
  "message": "success",
  "data": {},
  "total": 0,
  "page": 1,
  "page_size": 20
}

错误响应格式

{
  "code": 400,
  "message": "错误描述",
  "data": null
}

参数验证规则

字符串类型: 最小长度、最大长度、字符集验证
数值类型: 最小值、最大值、精度验证
日期时间: 格式验证、范围验证
枚举类型: 值域验证
复合类型: 结构验证、嵌套验证

20 KiB Raw Blame History Unescape Escape

API接口文档

目录

简介

项目结构

核心组件

认证与安全机制

数据模型架构

架构概览

详细组件分析

认证接口模块

用户登录

用户注册

获取当前用户信息

基础数据接口模块

科室管理接口

获取科室列表

创建科室

更新科室

删除科室

员工管理接口

获取员工列表

创建员工

获取科室员工

指标管理接口

获取指标列表

创建指标

指标模板管理

考核管理接口模块

绩效计划管理

获取计划列表

创建绩效计划

提交计划

审批计划

激活计划

绩效考核管理

获取考核列表

创建考核记录

批量创建考核

审核考核

工资核算接口模块

工资记录管理

获取工资记录列表

创建工资记录

根据考核生成工资

批量生成工资

确认工资

财务核算接口模块

财务数据查询

获取科室收入

获取科室支出

获取收支结余

按类别统计收入/支出

获取财务汇总

财务记录管理

创建财务记录

更新财务记录

删除财务记录

统计分析接口模块

绩效统计分析

BSC维度分析

科室绩效统计

趋势分析

周期统计

关键指标仪表盘

排名统计

科室绩效排名

绩效排名

指标完成度

系统管理接口模块

菜单管理

获取菜单树

获取菜单列表

创建菜单

更新菜单

删除菜单

初始化默认菜单

指标模板管理

获取模板列表

获取模板类型列表

20 KiB

Raw Blame History