13 KiB
13 KiB
考核服务
**本文档引用的文件** - [assessment_service.py](file://backend/app/services/assessment_service.py) - [models.py](file://backend/app/models/models.py) - [schemas.py](file://backend/app/schemas/schemas.py) - [assessments.py](file://backend/app/api/v1/assessments.py) - [database.py](file://backend/app/core/database.py) - [security.py](file://backend/app/core/security.py) - [config.py](file://backend/app/core/config.py) - [main.py](file://backend/app/main.py)目录
简介
考核服务是医院绩效管理系统的核心模块，负责管理员工的绩效考核流程。该服务实现了完整的考核生命周期管理，包括考核记录的CRUD操作、状态管理和流程控制。系统采用基于平衡计分卡（BSC）的多维度考核体系，支持多种科室类型的差异化考核需求。
项目结构
考核服务位于后端应用的服务层，采用清晰的分层架构设计：
graph TB
subgraph "API层"
A[API路由]
B[认证中间件]
end
subgraph "服务层"
C[AssessmentService]
D[其他服务]
end
subgraph "数据层"
E[模型定义]
F[数据库]
end
subgraph "配置层"
G[数据库配置]
H[安全配置]
I[应用配置]
end
A --> C
B --> A
C --> E
E --> F
G --> F
H --> A
I --> A
图表来源
章节来源
核心组件
AssessmentService 类
AssessmentService 是考核服务的核心类，提供了完整的考核管理功能：
主要职责
- 考核记录的创建、读取、更新、删除
- 考核状态的流转管理
- 考核分数的自动计算
- 批量考核创建功能
关键特性
- 异步数据库操作支持
- 完整的状态机管理
- 自动化的分数计算
- 权限控制集成
章节来源
架构概览
考核服务采用经典的三层架构模式，确保了良好的关注点分离：
sequenceDiagram
participant Client as 客户端
participant API as API路由
participant Service as AssessmentService
participant DB as 数据库
participant Model as 数据模型
Client->>API : HTTP请求
API->>Service : 调用服务方法
Service->>DB : 执行数据库操作
DB->>Model : 映射数据模型
Model-->>DB : 返回实体对象
DB-->>Service : 返回查询结果
Service-->>API : 返回业务结果
API-->>Client : HTTP响应
图表来源
详细组件分析
数据模型设计
Assessment 模型
Assessment 模型代表一条完整的考核记录，包含以下关键字段：
classDiagram
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+AssessmentStatus status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
+datetime created_at
+datetime updated_at
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+datetime created_at
+datetime updated_at
}
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
}
class Indicator {
+int id
+string name
+string code
+IndicatorType indicator_type
+BSCDimension bs_dimension
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+string applicable_dept_types
+bool is_veto
+bool is_active
}
Assessment "1" -- "many" AssessmentDetail : "包含"
Assessment "1" -- "1" Staff : "关联"
AssessmentDetail "1" -- "1" Indicator : "关联"
图表来源
AssessmentStatus 状态枚举
考核状态采用严格的有限状态机设计：
stateDiagram-v2
[*] --> DRAFT : 创建
DRAFT --> SUBMITTED : 提交
SUBMITTED --> REVIEWED : 审核通过
SUBMITTED --> REJECTED : 审核驳回
REVIEWED --> FINALIZED : 确认
REJECTED --> DRAFT : 修改后重新提交
FINALIZED --> [*] : 结束
图表来源
章节来源
核心业务方法详解
1. 列表查询方法
get_list() 方法提供了灵活的考核记录查询功能：
功能特点：
- 多条件过滤支持（员工ID、科室ID、年度、月份、状态）
- 分页查询支持
- 性能优化的子查询统计
- 关联数据预加载
查询逻辑：
flowchart TD
Start([开始查询]) --> BuildQuery["构建基础查询"]
BuildQuery --> CheckFilters{"是否有过滤条件?"}
CheckFilters --> |是| ApplyFilters["应用过滤条件"]
CheckFilters --> |否| CountQuery["构建统计查询"]
ApplyFilters --> CountQuery
CountQuery --> Pagination["应用分页"]
Pagination --> ExecuteQuery["执行查询"]
ExecuteQuery --> ReturnResults["返回结果"]
ReturnResults --> End([结束])
图表来源
章节来源
2. 详情获取方法
get_by_id() 方法提供了完整的考核详情查询：
功能特点：
- 关联员工信息查询
- 考核明细及指标信息加载
- 预加载优化减少N+1查询
章节来源
3. 创建考核方法
create() 方法实现了完整的考核创建流程：
核心算法：
- 计算总分：所有明细得分的简单求和
- 计算加权得分：每个指标得分乘以其权重后的总和
- 创建主记录和明细记录
- 自动设置初始状态为草稿
分数计算公式：
- 总分 = Σ(明细得分)
- 加权得分 = Σ(明细得分 × 指标权重)
章节来源
4. 更新考核方法
update() 方法提供了受控的考核更新功能：
状态限制：
- 仅允许草稿和被驳回状态的记录进行更新
- 更新时会删除旧的考核明细并重新创建
更新流程：
flowchart TD
Start([开始更新]) --> LoadAssessment["加载考核记录"]
LoadAssessment --> CheckStatus{"状态是否允许更新?"}
CheckStatus --> |否| ReturnNull["返回None"]
CheckStatus --> |是| DeleteOldDetails["删除旧明细"]
DeleteOldDetails --> RecalculateScores["重新计算分数"]
RecalculateScores --> UpdateFields["更新其他字段"]
UpdateFields --> SaveChanges["保存更改"]
SaveChanges --> ReturnAssessment["返回更新后的记录"]
ReturnNull --> End([结束])
ReturnAssessment --> End
图表来源
章节来源
5. 流程控制方法
提交方法 (submit)
将草稿状态的考核记录提交到审核流程。
审核方法 (review)
管理员或经理对提交的考核进行审核：
- 通过：状态转为已审核
- 驳回：状态转为被驳回并可添加审核意见
确认方法 (finalize)
最终确认已审核的考核记录，状态转为已确认。
章节来源
6. 批量创建方法
batch_create_for_department() 实现了高效的批量考核创建：
功能特点：
- 为指定科室的所有在职员工批量创建考核
- 自动检查重复创建
- 为每个员工创建相同的考核指标模板
使用场景：
- 月末批量创建员工考核
- 新指标模板上线时的批量创建
- 年度考核周期开始时的批量初始化
章节来源
API 接口设计
RESTful API 规范
| 接口 | 方法 | 权限 | 功能描述 |
|---|---|---|---|
/assessments |
GET | 任意用户 | 获取考核列表 |
/assessments |
POST | 普通用户 | 创建考核记录 |
/assessments/{id} |
GET | 任意用户 | 获取考核详情 |
/assessments/{id} |
PUT | 普通用户 | 更新考核记录 |
/assessments/{id}/submit |
POST | 普通用户 | 提交考核 |
/assessments/{id}/review |
POST | 管理员/经理 | 审核考核 |
/assessments/{id}/finalize |
POST | 管理员/经理 | 确认考核 |
/assessments/batch-create |
POST | 管理员/经理 | 批量创建考核 |
章节来源
依赖关系分析
外部依赖
graph LR
subgraph "核心依赖"
A[SQLAlchemy 2.0]
B[FastAPI]
C[Pydantic]
D[PostgreSQL]
end
subgraph "服务层"
E[AssessmentService]
F[其他业务服务]
end
subgraph "数据层"
G[模型定义]
H[数据库连接]
end
E --> A
E --> G
F --> A
G --> H
H --> D
B --> C
图表来源
内部依赖关系
graph TD
A[AssessmentService] --> B[Assessment 模型]
A --> C[AssessmentDetail 模型]
A --> D[Staff 模型]
A --> E[Indicator 模型]
A --> F[AssessmentStatus 枚举]
A --> G[数据库会话]
H[API路由] --> A
I[安全模块] --> H
J[配置模块] --> H
K[数据库配置] --> G
图表来源
章节来源
性能考虑
数据库优化策略
-
索引优化
- 考核记录按员工ID、年度月份、状态建立复合索引
- 考核明细按考核记录ID、指标ID建立索引
-
查询优化
- 使用 selectinload 进行关联数据预加载
- 子查询统计避免全表扫描
-
连接池管理
- 异步连接池配置
- 连接超时和重试机制
缓存策略
- 使用 LRU 缓存存储常用配置
- 数据库查询结果缓存（可选）
异步处理
- 全面采用异步数据库操作
- 避免阻塞式I/O操作
故障排除指南
常见问题及解决方案
1. 考核状态错误
问题： 尝试在不允许的状态下更新或操作考核 解决方案： 检查当前状态是否符合操作要求
2. 权限不足
问题： 审核或确认操作返回403错误 解决方案： 确认当前用户具有管理员或经理权限
3. 数据库连接问题
问题： 数据库操作失败 解决方案： 检查数据库连接配置和网络连通性
4. 分页查询异常
问题： 分页参数无效导致查询错误 解决方案： 验证页码和每页数量参数范围
章节来源
结论
考核服务通过精心设计的架构和完善的业务逻辑，为医院绩效管理提供了强大的技术支持。系统的主要优势包括：
- 完整的生命周期管理：从创建到确认的完整流程覆盖
- 灵活的查询能力：支持多维度、多条件的复杂查询
- 严格的状态控制：确保业务流程的合规性
- 高效的批量处理：支持大规模数据的批量操作
- 完善的权限控制：基于角色的精细化权限管理
该服务为后续的薪资计算、统计分析等功能奠定了坚实的基础，是整个绩效管理系统的核心支柱。