提交文件
This commit is contained in:
473
.qoder/repowiki/zh/content/后端开发指南/服务层开发/考核服务.md
Normal file
473
.qoder/repowiki/zh/content/后端开发指南/服务层开发/考核服务.md
Normal file
@@ -0,0 +1,473 @@
|
||||
# 考核服务
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
考核服务是医院绩效管理系统的核心模块，负责管理员工的绩效考核流程。该服务实现了完整的考核生命周期管理，包括考核记录的CRUD操作、状态管理和流程控制。系统采用基于平衡计分卡（BSC）的多维度考核体系，支持多种科室类型的差异化考核需求。
|
||||
|
||||
## 项目结构
|
||||
|
||||
考核服务位于后端应用的服务层，采用清晰的分层架构设计：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||||
- [models.py](file://backend/app/models/models.py#L149-L203)
|
||||
- [database.py](file://backend/app/core/database.py#L9-L39)
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
|
||||
- [models.py](file://backend/app/models/models.py#L1-L438)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### AssessmentService 类
|
||||
|
||||
AssessmentService 是考核服务的核心类，提供了完整的考核管理功能：
|
||||
|
||||
#### 主要职责
|
||||
- 考核记录的创建、读取、更新、删除
|
||||
- 考核状态的流转管理
|
||||
- 考核分数的自动计算
|
||||
- 批量考核创建功能
|
||||
|
||||
#### 关键特性
|
||||
- 异步数据库操作支持
|
||||
- 完整的状态机管理
|
||||
- 自动化的分数计算
|
||||
- 权限控制集成
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
|
||||
|
||||
## 架构概览
|
||||
|
||||
考核服务采用经典的三层架构模式，确保了良好的关注点分离：
|
||||
|
||||
```mermaid
|
||||
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响应
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L17-L263)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 数据模型设计
|
||||
|
||||
#### Assessment 模型
|
||||
Assessment 模型代表一条完整的考核记录，包含以下关键字段：
|
||||
|
||||
```mermaid
|
||||
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 : "关联"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L149-L203)
|
||||
- [models.py](file://backend/app/models/models.py#L181-L203)
|
||||
|
||||
#### AssessmentStatus 状态枚举
|
||||
考核状态采用严格的有限状态机设计：
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> DRAFT : 创建
|
||||
DRAFT --> SUBMITTED : 提交
|
||||
SUBMITTED --> REVIEWED : 审核通过
|
||||
SUBMITTED --> REJECTED : 审核驳回
|
||||
REVIEWED --> FINALIZED : 确认
|
||||
REJECTED --> DRAFT : 修改后重新提交
|
||||
FINALIZED --> [*] : 结束
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [models.py](file://backend/app/models/models.py#L45-L52)
|
||||
|
||||
**章节来源**
|
||||
- [models.py](file://backend/app/models/models.py#L149-L203)
|
||||
- [models.py](file://backend/app/models/models.py#L45-L52)
|
||||
|
||||
### 核心业务方法详解
|
||||
|
||||
#### 1. 列表查询方法
|
||||
|
||||
`get_list()` 方法提供了灵活的考核记录查询功能：
|
||||
|
||||
**功能特点：**
|
||||
- 多条件过滤支持（员工ID、科室ID、年度、月份、状态）
|
||||
- 分页查询支持
|
||||
- 性能优化的子查询统计
|
||||
- 关联数据预加载
|
||||
|
||||
**查询逻辑：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始查询]) --> BuildQuery["构建基础查询"]
|
||||
BuildQuery --> CheckFilters{"是否有过滤条件?"}
|
||||
CheckFilters --> |是| ApplyFilters["应用过滤条件"]
|
||||
CheckFilters --> |否| CountQuery["构建统计查询"]
|
||||
ApplyFilters --> CountQuery
|
||||
CountQuery --> Pagination["应用分页"]
|
||||
Pagination --> ExecuteQuery["执行查询"]
|
||||
ExecuteQuery --> ReturnResults["返回结果"]
|
||||
ReturnResults --> End([结束])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L56)
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L18-L56)
|
||||
|
||||
#### 2. 详情获取方法
|
||||
|
||||
`get_by_id()` 方法提供了完整的考核详情查询：
|
||||
|
||||
**功能特点：**
|
||||
- 关联员工信息查询
|
||||
- 考核明细及指标信息加载
|
||||
- 预加载优化减少N+1查询
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
|
||||
|
||||
#### 3. 创建考核方法
|
||||
|
||||
`create()` 方法实现了完整的考核创建流程：
|
||||
|
||||
**核心算法：**
|
||||
1. 计算总分：所有明细得分的简单求和
|
||||
2. 计算加权得分：每个指标得分乘以其权重后的总和
|
||||
3. 创建主记录和明细记录
|
||||
4. 自动设置初始状态为草稿
|
||||
|
||||
**分数计算公式：**
|
||||
- 总分 = Σ(明细得分)
|
||||
- 加权得分 = Σ(明细得分 × 指标权重)
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
|
||||
|
||||
#### 4. 更新考核方法
|
||||
|
||||
`update()` 方法提供了受控的考核更新功能：
|
||||
|
||||
**状态限制：**
|
||||
- 仅允许草稿和被驳回状态的记录进行更新
|
||||
- 更新时会删除旧的考核明细并重新创建
|
||||
|
||||
**更新流程：**
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始更新]) --> LoadAssessment["加载考核记录"]
|
||||
LoadAssessment --> CheckStatus{"状态是否允许更新?"}
|
||||
CheckStatus --> |否| ReturnNull["返回None"]
|
||||
CheckStatus --> |是| DeleteOldDetails["删除旧明细"]
|
||||
DeleteOldDetails --> RecalculateScores["重新计算分数"]
|
||||
RecalculateScores --> UpdateFields["更新其他字段"]
|
||||
UpdateFields --> SaveChanges["保存更改"]
|
||||
SaveChanges --> ReturnAssessment["返回更新后的记录"]
|
||||
ReturnNull --> End([结束])
|
||||
ReturnAssessment --> End
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
|
||||
|
||||
#### 5. 流程控制方法
|
||||
|
||||
##### 提交方法 (`submit`)
|
||||
将草稿状态的考核记录提交到审核流程。
|
||||
|
||||
##### 审核方法 (`review`)
|
||||
管理员或经理对提交的考核进行审核：
|
||||
- 通过：状态转为已审核
|
||||
- 驳回：状态转为被驳回并可添加审核意见
|
||||
|
||||
##### 确认方法 (`finalize`)
|
||||
最终确认已审核的考核记录，状态转为已确认。
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L205)
|
||||
|
||||
#### 6. 批量创建方法
|
||||
|
||||
`batch_create_for_department()` 实现了高效的批量考核创建：
|
||||
|
||||
**功能特点：**
|
||||
- 为指定科室的所有在职员工批量创建考核
|
||||
- 自动检查重复创建
|
||||
- 为每个员工创建相同的考核指标模板
|
||||
|
||||
**使用场景：**
|
||||
- 月末批量创建员工考核
|
||||
- 新指标模板上线时的批量创建
|
||||
- 年度考核周期开始时的批量初始化
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
|
||||
|
||||
### 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 | 管理员/经理 | 批量创建考核 |
|
||||
|
||||
**章节来源**
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L166)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
### 外部依赖
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
|
||||
- [database.py](file://backend/app/core/database.py#L4-L20)
|
||||
|
||||
### 内部依赖关系
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L10-L11)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L14-L15)
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
|
||||
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L17)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 数据库优化策略
|
||||
|
||||
1. **索引优化**
|
||||
- 考核记录按员工ID、年度月份、状态建立复合索引
|
||||
- 考核明细按考核记录ID、指标ID建立索引
|
||||
|
||||
2. **查询优化**
|
||||
- 使用 selectinload 进行关联数据预加载
|
||||
- 子查询统计避免全表扫描
|
||||
|
||||
3. **连接池管理**
|
||||
- 异步连接池配置
|
||||
- 连接超时和重试机制
|
||||
|
||||
### 缓存策略
|
||||
|
||||
- 使用 LRU 缓存存储常用配置
|
||||
- 数据库查询结果缓存（可选）
|
||||
|
||||
### 异步处理
|
||||
|
||||
- 全面采用异步数据库操作
|
||||
- 避免阻塞式I/O操作
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
#### 1. 考核状态错误
|
||||
**问题：** 尝试在不允许的状态下更新或操作考核
|
||||
**解决方案：** 检查当前状态是否符合操作要求
|
||||
|
||||
#### 2. 权限不足
|
||||
**问题：** 审核或确认操作返回403错误
|
||||
**解决方案：** 确认当前用户具有管理员或经理权限
|
||||
|
||||
#### 3. 数据库连接问题
|
||||
**问题：** 数据库操作失败
|
||||
**解决方案：** 检查数据库连接配置和网络连通性
|
||||
|
||||
#### 4. 分页查询异常
|
||||
**问题：** 分页参数无效导致查询错误
|
||||
**解决方案：** 验证页码和每页数量参数范围
|
||||
|
||||
**章节来源**
|
||||
- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
|
||||
- [security.py](file://backend/app/core/security.py#L94-L109)
|
||||
|
||||
## 结论
|
||||
|
||||
考核服务通过精心设计的架构和完善的业务逻辑，为医院绩效管理提供了强大的技术支持。系统的主要优势包括：
|
||||
|
||||
1. **完整的生命周期管理**：从创建到确认的完整流程覆盖
|
||||
2. **灵活的查询能力**：支持多维度、多条件的复杂查询
|
||||
3. **严格的状态控制**：确保业务流程的合规性
|
||||
4. **高效的批量处理**：支持大规模数据的批量操作
|
||||
5. **完善的权限控制**：基于角色的精细化权限管理
|
||||
|
||||
该服务为后续的薪资计算、统计分析等功能奠定了坚实的基础，是整个绩效管理系统的核心支柱。
|
||||
Reference in New Issue
Block a user