Files

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

22 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/templates.py](file://backend/app/api/v1/templates.py) - [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.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/template_service.py](file://backend/app/services/template_service.py) - [backend/app/models/models.py](file://backend/app/models/models.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/template.js](file://frontend/src/api/template.js)

简介

本文件为医院绩效管理系统的"基础数据管理接口"提供全面的API文档，覆盖以下四大模块：

科室管理：支持科室的增删改查、树形结构查询、层级计算与父子关系维护
员工管理：支持员工的增删改查、按科室筛选、状态管理与关联查询
考核指标管理：支持指标的增删改查、启用状态管理、模板导入与批量操作
指标模板管理：支持模板的增删改查、模板类型与BSC维度枚举、模板指标的增删改查与批量添加

文档详细说明每个模块的接口规范、数据验证规则、关联关系处理、级联操作、分页查询、搜索过滤、排序功能、数据导入导出与批量操作的使用方法。

项目结构

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

API层：定义路由与请求/响应处理
服务层：封装业务逻辑与数据访问
模型层：定义数据库表结构与关系
模式层：定义Pydantic数据模式与枚举类型
前端层：通过统一请求封装调用后端接口

graph TB
subgraph "前端"
FE_API["前端API封装<br/>department.js / staff.js / indicator.js / template.js"]
end
subgraph "后端"
MAIN["FastAPI应用<br/>app/main.py"]
API_DEPT["科室API<br/>api/v1/departments.py"]
API_STAFF["员工API<br/>api/v1/staff.py"]
API_INDICATOR["指标API<br/>api/v1/indicators.py"]
API_TEMPLATE["模板API<br/>api/v1/templates.py"]
SVC_DEPT["科室服务<br/>services/department_service.py"]
SVC_STAFF["员工服务<br/>services/staff_service.py"]
SVC_INDICATOR["指标服务<br/>services/indicator_service.py"]
SVC_TEMPLATE["模板服务<br/>services/template_service.py"]
MODELS["数据模型<br/>models/models.py"]
SCHEMAS["数据模式<br/>schemas/schemas.py"]
end
FE_API --> MAIN
MAIN --> API_DEPT
MAIN --> API_STAFF
MAIN --> API_INDICATOR
MAIN --> API_TEMPLATE
API_DEPT --> SVC_DEPT
API_STAFF --> SVC_STAFF
API_INDICATOR --> SVC_INDICATOR
API_TEMPLATE --> SVC_TEMPLATE
SVC_DEPT --> MODELS
SVC_STAFF --> MODELS
SVC_INDICATOR --> MODELS
SVC_TEMPLATE --> MODELS
API_DEPT --> SCHEMAS
API_STAFF --> SCHEMAS
API_INDICATOR --> SCHEMAS
API_TEMPLATE --> SCHEMAS

图表来源

章节来源

backend/app/main.py

核心组件

数据模型与枚举
- 科室类型：包含临床、医技、护理、行政、后勤等类型
- 员工状态：在职、休假、离职、退休
- 指标类型：质量、数量、效率、服务、成本
- 平衡计分卡维度：财务、客户、内部流程、学习与成长
- 考核状态：草稿、已提交、已审核、已确认、已驳回
数据模式
- 基础模式：定义字段约束、长度限制、取值范围
- 创建/更新模式：用于请求体校验
- 响应模式：用于序列化输出，包含额外字段如部门名称、指标名称等
服务层方法
- 列表查询：支持分页、过滤条件、排序
- 详情查询：支持关联加载
- 创建/更新/删除：包含唯一性校验与级联检查
- 树形结构：手动构建树避免懒加载问题

章节来源

架构概览

后端采用分层架构，API层负责路由与权限控制，服务层封装业务逻辑，模型层定义数据库结构，模式层定义数据校验与序列化。前端通过统一的请求封装调用后端接口。

sequenceDiagram
participant FE as "前端"
participant API as "API路由"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : 发起HTTP请求
API->>SVC : 调用业务方法
SVC->>DB : 执行SQL查询/更新
DB-->>SVC : 返回结果
SVC-->>API : 返回业务结果
API-->>FE : 返回标准化响应

图表来源

详细组件分析

科室管理接口

接口列表
- GET /departments：获取科室列表（支持类型过滤、启用状态过滤、分页）
- GET /departments/tree：获取科室树形结构（支持类型过滤）
- GET /departments/{dept_id}：获取科室详情
- POST /departments：创建科室（需管理员或经理权限）
- PUT /departments/{dept_id}：更新科室（需管理员或经理权限）
- DELETE /departments/{dept_id}：删除科室（需管理员或经理权限，存在子科室时拒绝删除）
数据验证规则
- 编码唯一性：创建前检查编码是否已存在
- 层级计算：根据父级科室自动计算层级
- 权限控制：创建、更新、删除接口要求管理员或经理角色
关联关系与级联
- 科室与员工：一对多关系，删除前检查是否存在子科室
- 树形结构：手动构建避免懒加载问题
分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：类型、启用状态
- 排序：按排序字段与ID排序
响应结构
- 列表接口返回分页响应对象，包含总数、当前页、每页数量与数据数组
- 详情接口返回单个实体对象

sequenceDiagram
participant Client as "客户端"
participant API as "departments.py"
participant Service as "DepartmentService"
participant DB as "数据库"
Client->>API : GET /departments?dept_type=&is_active=&page=&page_size=
API->>Service : get_list(dept_type, is_active, page, page_size)
Service->>DB : 查询科室列表
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应
Client->>API : POST /departments
API->>Service : create(dept_data)
Service->>DB : 插入新科室
DB-->>Service : 返回新记录
Service-->>API : 返回创建结果
API-->>Client : 返回成功响应

图表来源

章节来源

员工管理接口

接口列表
- GET /staff：获取员工列表（支持科室ID、状态、关键词搜索、分页）
- GET /staff/{staff_id}：获取员工详情（包含部门名称）
- POST /staff：创建员工（需管理员或经理权限）
- PUT /staff/{staff_id}：更新员工（需管理员或经理权限）
- DELETE /staff/{staff_id}：删除员工（需管理员或经理权限）
- GET /staff/department/{department_id}：获取指定科室所有员工
数据验证规则
- 工号唯一性：创建前检查工号是否已存在
- 状态枚举：仅允许预定义状态
- 权限控制：创建、更新、删除接口要求管理员或经理角色
关联关系与级联
- 员工与科室：多对一关系，查询时加载部门信息
- 状态过滤：默认仅显示在职员工
分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：科室ID、状态
- 搜索：姓名或工号模糊匹配
- 排序：按ID倒序
响应结构
- 列表接口返回分页响应对象，数据数组中包含部门名称字段
- 详情接口返回单个实体对象，包含部门名称字段

sequenceDiagram
participant Client as "客户端"
participant API as "staff.py"
participant Service as "StaffService"
participant DB as "数据库"
Client->>API : GET /staff?department_id=&status=&keyword=&page=&page_size=
API->>Service : get_list(department_id, status, keyword, page, page_size)
Service->>DB : 查询员工列表含部门信息
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应含部门名称
Client->>API : POST /staff
API->>Service : create(staff_data)
Service->>DB : 插入新员工
DB-->>Service : 返回新记录
Service-->>API : 返回创建结果
API-->>Client : 返回成功响应

图表来源

章节来源

考核指标管理接口

接口列表
- GET /indicators：获取指标列表（支持类型、BSC维度、启用状态、分页）
- GET /indicators/active：获取所有启用的指标
- GET /indicators/{indicator_id}：获取指标详情
- POST /indicators：创建指标（需管理员或经理权限）
- PUT /indicators/{indicator_id}：更新指标（需管理员或经理权限）
- DELETE /indicators/{indicator_id}：删除指标（需管理员或经理权限）
- GET /indicators/templates/list：获取指标模板列表
- POST /indicators/templates/import：导入指标模板（支持覆盖选项）
数据验证规则
- 编码唯一性：创建前检查编码是否已存在
- 权重范围：权重必须在合理范围内
- 启用状态：支持启用/禁用切换
- 权限控制：创建、更新、删除、模板导入接口要求管理员或经理角色
关联关系与级联
- 指标与考核明细：一对多关系，删除前需确保无关联明细
- 模板导入：支持覆盖现有指标或跳过
分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：类型、BSC维度、启用状态
- 排序：按类型与ID排序
响应结构
- 列表接口返回分页响应对象
- 详情接口返回单个实体对象
- 模板导入接口返回导入数量统计

sequenceDiagram
participant Client as "客户端"
participant API as "indicators.py"
participant Service as "IndicatorService"
participant DB as "数据库"
Client->>API : GET /indicators?indicator_type=&bs_dimension=&is_active=&page=&page_size=
API->>Service : get_list(...)
Service->>DB : 查询指标列表
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应
Client->>API : POST /indicators/templates/import?overwrite=false
API->>Service : import_template(template_data, overwrite)
Service->>DB : 批量插入或更新指标
DB-->>Service : 返回插入数量
Service-->>API : 返回导入统计
API-->>Client : 返回成功响应含创建数量

图表来源

章节来源

指标模板管理接口

接口列表
- GET /templates：获取模板列表（支持类型、启用状态、分页）
- GET /templates/types：获取模板类型列表
- GET /templates/dimensions：获取BSC维度列表
- GET /templates/{template_id}：获取模板详情（包含模板指标详情）
- POST /templates：创建模板（需管理员或经理权限）
- PUT /templates/{template_id}：更新模板（需管理员或经理权限）
- DELETE /templates/{template_id}：删除模板（需管理员或经理权限）
- GET /templates/{template_id}/indicators：获取模板指标列表
- POST /templates/{template_id}/indicators：添加模板指标（需管理员或经理权限）
- PUT /templates/{template_id}/indicators/{indicator_id}：更新模板指标（需管理员或经理权限）
- DELETE /templates/{template_id}/indicators/{indicator_id}：移除模板指标（需管理员或经理权限）
- POST /templates/{template_id}/indicators/batch：批量添加模板指标（需管理员或经理权限）
数据验证规则
- 模板编码唯一性：创建前检查编码是否已存在
- 权重范围：权重必须在合理范围内
- 排序字段：支持自定义排序，未提供时按最大排序+1
- 权限控制：所有模板相关接口要求管理员或经理角色
关联关系与级联
- 模板与模板指标：一对多关系，支持增删改查与批量添加
- 模板指标与指标：多对一关系，查询时加载指标详细信息
分页、搜索与排序
- 分页：页码与每页数量参数，支持最小1、最大100
- 过滤：类型、启用状态
- 排序：按类型与ID排序
响应结构
- 列表接口返回分页响应对象，包含指标数量统计
- 详情接口返回模板对象与指标详情数组
- 批量添加接口返回添加数量统计

sequenceDiagram
participant Client as "客户端"
participant API as "templates.py"
participant Service as "TemplateService"
participant DB as "数据库"
Client->>API : GET /templates?template_type=&is_active=&page=&page_size=
API->>Service : get_list(...)
Service->>DB : 查询模板列表含指标数量
DB-->>Service : 返回结果集
Service-->>API : 返回列表与总数
API-->>Client : 返回分页响应含指标数量
Client->>API : POST /templates/{template_id}/indicators/batch
API->>Service : batch_add_template_indicators(template_id, indicators_data)
Service->>DB : 批量插入模板指标
DB-->>Service : 返回插入结果
Service-->>API : 返回批量统计
API-->>Client : 返回成功响应含添加数量

图表来源

章节来源

依赖分析

模块耦合
- API层仅依赖服务层，不直接操作数据库
- 服务层依赖模型层进行数据库操作
- 模式层为API与服务层提供数据校验与序列化
外部依赖
- FastAPI：Web框架与路由装饰器
- SQLAlchemy 2.0：异步ORM与查询构建
- Pydantic：数据模式与验证
权限控制
- 部分接口要求管理员或经理角色
- 使用依赖注入获取当前用户并进行权限校验

graph TB
API["API层<br/>departments.py / staff.py / indicators.py / templates.py"]
SVC["服务层<br/>department_service.py / staff_service.py / indicator_service.py / template_service.py"]
MODELS["模型层<br/>models.py"]
SCHEMAS["模式层<br/>schemas.py"]
API --> SVC
SVC --> MODELS
API --> SCHEMAS
SVC --> SCHEMAS

图表来源

章节来源

性能考虑

分页与索引
- 列表查询均支持分页，避免一次性返回大量数据
- 数据库表建立了必要的索引以提升查询性能
关联查询
- 使用selectinload优化N+1查询问题
- 树形结构查询手动构建，避免懒加载导致的性能问题
数据验证
- Pydantic模式在请求进入业务层前完成数据验证
- 唯一性检查在创建前执行，减少无效写入
异步处理
- 使用异步数据库连接，提升并发处理能力

故障排除指南

常见错误与处理
- 404错误：资源不存在（科室、员工、指标、模板）
- 400错误：删除失败（存在子资源或状态不允许）
- 400错误：创建失败（编码已存在）
- 权限不足：需要管理员或经理角色
日志与异常
- 全局异常处理器记录异常信息
- HTTP异常与验证异常分别处理
前端调用参考
- 前端通过统一的API封装调用后端接口
- 支持分页参数传递与响应解析

章节来源

结论

本API文档全面覆盖了基础数据管理的四大模块，提供了详细的接口规范、数据验证规则、关联关系处理、分页查询、搜索过滤、排序功能以及批量操作的使用方法。通过清晰的分层架构与严格的权限控制，系统能够稳定地支撑医院绩效管理的各项业务需求。建议在生产环境中结合前端封装进行集成测试，确保接口调用的正确性与性能表现。

22 KiB Raw Blame History Unescape Escape

基础数据接口

目录

简介

项目结构

核心组件

架构概览

详细组件分析

科室管理接口

员工管理接口

考核指标管理接口

指标模板管理接口

依赖分析

性能考虑

故障排除指南

结论

22 KiB

Raw Blame History