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/assessments.py](file://backend/app/api/v1/assessments.py) - [backend/app/services/assessment_service.py](file://backend/app/services/assessment_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/api/v1/templates.py](file://backend/app/api/v1/templates.py) - [backend/app/services/template_service.py](file://backend/app/services/template_service.py) - [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py) - [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py) - [backend/app/core/security.py](file://backend/app/core/security.py) - [backend/app/main.py](file://backend/app/main.py) - [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js) - [docs/api.md](file://docs/api.md) - [docs/详细设计.md](file://docs/详细设计.md)

目录

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

简介

本文件详细说明医院绩效管理系统的考核管理接口，涵盖考核流程管理、考核记录和考核明细的API实现。文档重点解释考核状态流转机制、审批流程和权限控制，同时文档化考核模板的使用、指标计算和得分汇总。系统支持批量考核操作、历史记录查询和统计分析接口，详细介绍考核详情的数据结构、评分规则和权重计算。此外，文档还包含考核进度跟踪、提醒机制和报表生成功能，提供完整的考核生命周期管理、数据一致性保证和并发控制策略。

项目结构

后端采用FastAPI + SQLAlchemy 2.0架构，采用分层设计模式：

graph TB
subgraph "表现层"
Frontend[前端Vue.js应用]
end
subgraph "应用层"
API[API路由层]
Services[业务服务层]
end
subgraph "数据层"
Models[ORM模型层]
Database[(PostgreSQL数据库)]
end
Frontend --> API
API --> Services
Services --> Models
Models --> Database

图表来源

系统采用模块化设计，主要模块包括：

  • 认证模块：JWT令牌管理和权限控制
  • 考核管理模块：考核流程、状态管理和审批
  • 指标模板模块：模板管理和指标配置
  • 统计分析模块：报表和数据分析
  • 数据模型模块：核心业务实体和关系

章节来源

核心组件

考核状态管理

系统实现了完整的考核状态流转机制，支持四种状态：

  • 草稿 (draft)：初始状态，允许修改
  • 已提交 (submitted)：等待审核
  • 已审核 (reviewed)：审核通过，等待确认
  • 已确认 (finalized)：最终状态，不可修改
  • 已驳回 (rejected)：审核不通过
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交考核"
已提交 --> 已审核 : "审核通过"
已提交 --> 已驳回 : "审核驳回"
已审核 --> 已确认 : "确认考核"
已确认 --> [*]
已驳回 --> 草稿 : "重新修改"

图表来源

权限控制系统

系统采用基于角色的权限控制（RBAC）：

graph LR
subgraph "用户角色"
Staff[普通员工]
Manager[科室经理]
Admin[系统管理员]
end
subgraph "权限级别"
Read[只读权限]
Write[写入权限]
Approve[审批权限]
Manage[管理权限]
end
Staff --> Read
Manager --> Write
Manager --> Approve
Admin --> Manage

图表来源

章节来源

架构概览

系统采用经典的三层架构模式，确保关注点分离和代码可维护性：

graph TB
subgraph "API层"
AssessmentsAPI[考核API]
TemplatesAPI[模板API]
StatsAPI[统计API]
end
subgraph "服务层"
AssessmentService[考核服务]
TemplateService[模板服务]
StatsService[统计服务]
end
subgraph "数据层"
AssessmentModel[考核模型]
DetailModel[明细模型]
IndicatorModel[指标模型]
DepartmentModel[科室模型]
end
AssessmentsAPI --> AssessmentService
TemplatesAPI --> TemplateService
StatsAPI --> StatsService
AssessmentService --> AssessmentModel
AssessmentService --> DetailModel
AssessmentService --> IndicatorModel
TemplateService --> AssessmentModel
TemplateService --> DetailModel
TemplateService --> IndicatorModel
StatsService --> AssessmentModel
StatsService --> DetailModel
StatsService --> IndicatorModel
StatsService --> DepartmentModel

图表来源

详细组件分析

考核管理API

考核列表查询

支持多条件过滤和分页查询：

查询参数 类型 描述 示例
staff_id int 员工ID 1001
department_id int 科室ID 501
period_year int 年度 2024
period_month int 月份 1
status string 状态 "submitted"
page int 页码 1
page_size int 每页数量 20

考核详情查询

返回完整的考核信息，包括员工和科室名称以及指标名称：

sequenceDiagram
participant Client as "客户端"
participant API as "考核API"
participant Service as "考核服务"
participant DB as "数据库"
Client->>API : GET /assessments/{id}
API->>Service : get_by_id(assessment_id)
Service->>DB : 查询考核记录
DB-->>Service : 考核详情
Service->>DB : 查询明细和指标
DB-->>Service : 明细数据
Service-->>API : 完整考核信息
API-->>Client : 考核详情响应

图表来源

考核状态流转

flowchart TD
Start([开始]) --> Draft[草稿状态]
Draft --> Submit{提交考核?}
Submit --> |是| Submitted[已提交]
Submit --> |否| Draft
Submitted --> Review{审核结果}
Review --> |通过| Reviewed[已审核]
Review --> |驳回| Rejected[已驳回]
Reviewed --> Finalize{确认考核?}
Finalize --> |是| Finalized[已确认]
Finalize --> |否| Reviewed
Rejected --> Edit[修改后重新提交]
Edit --> Draft
Finalized --> End([结束])

图表来源

章节来源

指标模板管理

模板类型体系

系统支持多种科室类型的指标模板：

模板类型 适用科室 描述
general 通用模板 适用于所有科室的基础指标
surgical 手术临床科室 适用于手术科室的特殊指标
nonsurgical_ward 非手术有病房科室 适用于内科、儿科等有病房科室
nonsurgical_noward 非手术无病房科室 适用于门诊科室
medical_tech 医技科室 适用于检验、影像等医技科室
nursing 护理单元 适用于护理部门
admin 行政科室 适用于行政部门
logistics 后勤科室 适用于后勤保障部门

模板指标关联

erDiagram
INDICATOR_TEMPLATE ||--o{ TEMPLATE_INDICATOR : "包含"
TEMPLATE_INDICATOR }o--|| INDICATOR : "关联"
INDICATOR_TEMPLATE {
int id PK
string template_name
string template_code
string template_type
text dimension_weights
string assessment_cycle
boolean is_active
}
TEMPLATE_INDICATOR {
int id PK
int template_id FK
int indicator_id FK
string category
float target_value
string target_unit
float weight
string scoring_method
text scoring_params
int sort_order
text remark
}
INDICATOR {
int id PK
string name
string code
string indicator_type
string bs_dimension
float weight
float max_score
float target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
text applicable_dept_types
boolean is_veto
boolean is_active
}

图表来源

章节来源

统计分析接口

BSC维度分析

系统支持平衡计分卡四个维度的统计分析：

维度 描述 权重范围
financial 财务管理 30%-40%
customer 顾客服务 25%-35%
internal_process 内部流程 20%-30%
learning_growth 学习与成长 5%-15%

绩效排名统计

sequenceDiagram
participant Client as "客户端"
participant StatsAPI as "统计API"
participant StatsService as "统计服务"
participant DB as "数据库"
Client->>StatsAPI : GET /stats/ranking
StatsAPI->>StatsService : get_ranking_stats(year, month, limit)
StatsService->>DB : 查询最终状态的考核记录
DB-->>StatsService : 排名数据
StatsService->>DB : 关联员工和科室信息
DB-->>StatsService : 员工详情
StatsService-->>StatsAPI : 排名结果
StatsAPI-->>Client : 排名列表

图表来源

章节来源

数据模型设计

核心实体关系

erDiagram
ASSESSMENT {
int id PK
int staff_id FK
int period_year
int period_month
string period_type
float total_score
float weighted_score
string status
int assessor_id FK
int reviewer_id FK
datetime submit_time
datetime review_time
text remark
datetime created_at
datetime updated_at
}
ASSESSMENT_DETAIL {
int id PK
int assessment_id FK
int indicator_id FK
float actual_value
float score
text evidence
text remark
datetime created_at
datetime updated_at
}
INDICATOR {
int id PK
string name
string code
string indicator_type
string bs_dimension
float weight
float max_score
float target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
text applicable_dept_types
boolean is_veto
boolean is_active
}
STAFF {
int id PK
string employee_id
string name
int department_id FK
string position
string title
string phone
string email
float base_salary
float performance_ratio
string status
datetime hire_date
datetime created_at
datetime updated_at
}
DEPARTMENT {
int id PK
string name
string code
string dept_type
int parent_id FK
int level
int sort_order
boolean is_active
text description
datetime created_at
datetime updated_at
}
ASSESSMENT ||--o{ ASSESSMENT_DETAIL : "包含"
ASSESSMENT }o--|| STAFF : "属于"
STAFF }o--|| DEPARTMENT : "隶属于"
ASSESSMENT_DETAIL }o--|| INDICATOR : "对应"

图表来源

章节来源

依赖关系分析

模块依赖图

graph TB
subgraph "外部依赖"
FastAPI[FastAPI框架]
SQLAlchemy[SQLAlchemy ORM]
Postgres[PostgreSQL数据库]
JWT[jwt库]
Bcrypt[bcrypt加密]
end
subgraph "核心模块"
Security[安全模块]
Database[数据库模块]
Logging[日志模块]
end
subgraph "业务模块"
AssessmentAPI[考核API]
AssessmentService[考核服务]
TemplateAPI[模板API]
TemplateService[模板服务]
StatsAPI[统计API]
StatsService[统计服务]
end
FastAPI --> AssessmentAPI
FastAPI --> TemplateAPI
FastAPI --> StatsAPI
AssessmentAPI --> AssessmentService
TemplateAPI --> TemplateService
StatsAPI --> StatsService
AssessmentService --> Database
TemplateService --> Database
StatsService --> Database
AssessmentAPI --> Security
TemplateAPI --> Security
StatsAPI --> Security
Security --> JWT
Security --> Bcrypt
Database --> Postgres

图表来源

数据一致性保证

系统通过以下机制确保数据一致性：

  1. 事务管理：所有数据库操作都在事务中执行
  2. 外键约束：使用SQLAlchemy外键约束保证引用完整性
  3. 状态验证：在状态转换前验证当前状态
  4. 并发控制：使用数据库锁防止并发修改冲突

章节来源

性能考虑

查询优化策略

  1. 索引优化：为常用查询字段建立索引

    • 考核记录：staff_id, period_year, period_month, status
    • 明细记录：assessment_id, indicator_id
    • 员工信息：department_id, status

  2. 分页查询：默认每页20条记录，最大100条

  3. 批量操作：支持批量创建和查询

  4. 缓存策略：对于静态数据使用缓存

并发控制

系统采用以下并发控制策略：

flowchart TD
Request[请求到达] --> CheckLock{检查锁}
CheckLock --> |无锁| AcquireLock[获取锁]
CheckLock --> |有锁| Wait[等待锁释放]
AcquireLock --> Process[处理业务逻辑]
Process --> ReleaseLock[释放锁]
Wait --> CheckLock
ReleaseLock --> Response[返回响应]

图表来源

故障排除指南

常见错误处理

错误类型 HTTP状态码 描述 处理建议
未授权 401 JWT令牌无效或过期 重新登录获取新令牌
权限不足 403 用户权限不够 检查用户角色和权限
资源不存在 404 请求的资源不存在 确认ID是否正确
参数错误 400 请求参数不合法 检查请求格式和参数类型
数据验证失败 422 数据不符合验证规则 修正数据格式和范围

日志记录

系统提供完整的日志记录机制：

graph LR
subgraph "日志级别"
Info[信息日志]
Warning[警告日志]
Error[错误日志]
Debug[调试日志]
end
subgraph "日志内容"
Request[请求信息]
Response[响应信息]
ErrorDetail[错误详情]
Performance[性能数据]
end
Info --> Request
Warning --> ErrorDetail
Error --> ErrorDetail
Debug --> Performance

图表来源

章节来源

结论

本考核管理接口提供了完整的医院绩效管理系统解决方案，具有以下特点：

  1. 完整的生命周期管理：从草稿到最终确认的全流程管理
  2. 灵活的权限控制：基于角色的精细化权限管理
  3. 强大的统计分析：多维度的报表和分析功能
  4. 可靠的并发控制：确保数据一致性和系统稳定性
  5. 良好的扩展性：模块化设计便于功能扩展和维护

系统采用现代化的技术栈和设计模式，能够满足医院绩效管理的复杂需求，为提升医疗质量和效率提供有力支撑。

附录

API接口规范

考核管理接口

方法 路径 权限要求 功能描述
GET /assessments 普通员工 获取考核列表
GET /assessments/{id} 普通员工 获取考核详情
POST /assessments 普通员工 创建考核记录
PUT /assessments/{id} 普通员工 更新考核记录
POST /assessments/{id}/submit 普通员工 提交考核
POST /assessments/{id}/review 科室经理 审核考核
POST /assessments/{id}/finalize 科室经理 确认考核
POST /assessments/batch-create 科室经理 批量创建考核

统计分析接口

方法 路径 权限要求 功能描述
GET /stats/bsc-dimension 普通员工 BSC维度分析
GET /stats/department 普通员工 科室绩效统计
GET /stats/trend 普通员工 趋势分析
GET /stats/ranking 普通员工 绩效排名
GET /stats/completion 普通员工 指标完成度

章节来源