# 考核记录模型
**本文档引用的文件**
- [models.py](file://backend/app/models/models.py)
- [assessment_service.py](file://backend/app/services/assessment_service.py)
- [assessments.py](file://backend/app/api/v1/assessments.py)
- [schemas.py](file://backend/app/schemas/schemas.py)
- [001_initial.py](file://backend/alembic/versions/001_initial.py)
- [assessment.js](file://frontend/src/api/assessment.js)
- [database.md](file://docs/database.md)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概览](#架构概览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
## 简介
考核记录模型是医院绩效管理系统的核心数据结构，负责管理员工的绩效考核过程。该模型实现了完整的多级审批流程，支持草稿→提交→审核→确认→驳回的状态流转，并提供了灵活的考核周期管理和数据一致性保证机制。
## 项目结构
后端采用典型的三层架构设计，主要包含以下层次：
```mermaid
graph TB
subgraph "表现层"
API[API路由层]
Frontend[前端接口]
end
subgraph "业务逻辑层"
Service[服务层]
Schema[数据模式层]
end
subgraph "数据访问层"
Model[模型层]
DB[(数据库)]
end
Frontend --> API
API --> Service
Service --> Model
Model --> DB
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L178)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 核心组件
### 考核状态枚举
考核状态枚举定义了完整的审批流程状态：
```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : 提交考核
已提交 --> 已审核 : 审核通过
已提交 --> 已驳回 : 审核驳回
已审核 --> 已确认 : 确认完成
已确认 --> [*]
已驳回 --> 草稿 : 修改后重新提交
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L45-L51)
### 主要数据模型
系统包含四个核心数据模型，形成了完整的考核数据结构：
```mermaid
erDiagram
ASSESSMENTS {
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_DETAILS {
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
}
STAFF {
int id PK
int employee_id UK
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
}
INDICATORS {
int id PK
string name
string code UK
string indicator_type
float weight
float max_score
float target_value
string target_unit
text calculation_method
text assessment_method
text deduction_standard
string data_source
string applicable_dept_types
boolean is_veto
boolean is_active
datetime created_at
datetime updated_at
}
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : contains
STAFF ||--o{ ASSESSMENTS : evaluates
INDICATORS ||--o{ ASSESSMENT_DETAILS : measures
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
**章节来源**
- [models.py](file://backend/app/models/models.py#L149-L203)
## 架构概览
系统采用RESTful API设计，实现了完整的CRUD操作和业务流程控制：
```mermaid
sequenceDiagram
participant Client as 客户端
participant API as API层
participant Service as 服务层
participant DB as 数据库
Client->>API : 创建考核请求
API->>Service : create_assessment()
Service->>DB : 插入Assessment记录
Service->>DB : 插入AssessmentDetail记录
DB-->>Service : 返回新记录ID
Service-->>API : 返回创建结果
API-->>Client : 返回创建成功
Client->>API : 提交考核请求
API->>Service : submit_assessment()
Service->>DB : 更新状态为SUBMITTED
DB-->>Service : 确认更新
Service-->>API : 返回提交结果
API-->>Client : 返回提交成功
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L80-L115)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
## 详细组件分析
### Assessment模型详解
Assessment模型是整个考核系统的核心，包含了完整的考核信息和审批状态：
#### 字段设计
| 字段名 | 类型 | 描述 | 约束 |
|--------|------|------|------|
| id | Integer | 主键ID | 自增 |
| staff_id | Integer | 员工ID | 外键，必填 |
| period_year | Integer | 考核年度 | 必填，范围2020-2100 |
| period_month | Integer | 考核月份 | 必填，范围1-12 |
| period_type | String | 考核周期类型 | 默认monthly |
| total_score | Float | 总分 | 默认0 |
| weighted_score | Float | 加权得分 | 默认0 |
| status | Enum | 考核状态 | 默认DRAFT |
| assessor_id | Integer | 考核人ID | 外键，可选 |
| reviewer_id | Integer | 审核人ID | 外键，可选 |
| submit_time | DateTime | 提交时间 | 可选 |
| review_time | DateTime | 审核时间 | 可选 |
| remark | Text | 备注 | 可选 |
#### 关系映射
```mermaid
classDiagram
class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+float total_score
+float weighted_score
+AssessmentStatus status
+int assessor_id
+int reviewer_id
+datetime submit_time
+datetime review_time
+string remark
+staff : Staff
+assessor : Staff
+reviewer : Staff
+details : AssessmentDetail[]
}
class Staff {
+int id
+string employee_id
+string name
+int department_id
+string position
+assessments : Assessment[]
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+assessment : Assessment
+indicator : Indicator
}
Assessment --> Staff : belongs_to
Assessment --> Staff : evaluated_by
Assessment --> Staff : reviewed_by
Assessment --> AssessmentDetail : has_many
AssessmentDetail --> Indicator : measures
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L149-L173)
#### 状态流转机制
```mermaid
flowchart TD
Start([开始]) --> Draft["草稿状态
DRAFT"]
Draft --> Submit["提交状态
SUBMITTED"]
Submit --> Review["审核状态
REVIEWED"]
Submit --> Reject["驳回状态
REJECTED"]
Review --> Finalize["确认状态
FINALIZED"]
Reject --> Draft2["返回草稿
DRAFT"]
Finalize --> End([结束])
Draft2 --> Submit
style Draft fill:#e1f5fe
style Submit fill:#f3e5f5
style Review fill:#e8f5e8
style Reject fill:#ffebee
style Finalize fill:#fff3e0
```
**图表来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L205)
### 计算逻辑实现
#### 总分计算
总分计算逻辑简单直接，将所有考核明细的得分相加：
```python
# 总分 = Σ(明细得分)
total_score = sum(d.score for d in assessment_data.details)
```
#### 加权得分计算
加权得分考虑了指标权重的影响：
```python
# 加权得分 = Σ(明细得分 × 指标权重)
weighted_score = 0.0
for detail in assessment_data.details:
indicator = await db.execute(
select(Indicator).where(Indicator.id == detail.indicator_id)
)
ind = indicator.scalar_one_or_none()
if ind:
weighted_score += detail.score * float(ind.weight)
```
**章节来源**
- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
### API接口设计
系统提供了完整的RESTful 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 | 批量创建考核 | 管理员/经理 |
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
### 数据一致性保证
#### 级联删除机制
Assessment模型使用了级联删除策略，确保当主记录被删除时，相关的明细记录也会自动清理：
```python
details: Mapped[List["AssessmentDetail"]] = relationship(
"AssessmentDetail",
back_populates="assessment",
cascade="all, delete-orphan"
)
```
#### 索引优化
数据库层面建立了多个索引以提升查询性能：
- `idx_assessment_staff`: 员工ID索引
- `idx_assessment_period`: 年度+月份复合索引
- `idx_assessment_status`: 状态索引
**章节来源**
- [models.py](file://backend/app/models/models.py#L174-L178)
## 依赖关系分析
### 模块间依赖
```mermaid
graph LR
subgraph "外部依赖"
SQLAlchemy[SQLAlchemy ORM]
FastAPI[FastAPI框架]
Pydantic[Pydantic验证]
end
subgraph "内部模块"
Models[数据模型]
Services[业务服务]
API[API路由]
Schemas[数据模式]
end
SQLAlchemy --> Models
FastAPI --> API
Pydantic --> Schemas
API --> Services
Services --> Models
API --> Schemas
Services --> Schemas
```
**图表来源**
- [models.py](file://backend/app/models/models.py#L1-L13)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L11)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L15)
### 数据流依赖
```mermaid
flowchart TD
Request[HTTP请求] --> Validation[数据验证]
Validation --> ServiceCall[服务调用]
ServiceCall --> DBQuery[数据库查询]
DBQuery --> BusinessLogic[业务逻辑处理]
BusinessLogic --> DBUpdate[数据库更新]
DBUpdate --> Response[响应生成]
Response --> Client[客户端]
Validation --> |Schema验证| ServiceCall
BusinessLogic --> |状态检查| DBUpdate
```
**图表来源**
- [schemas.py](file://backend/app/schemas/schemas.py#L220-L237)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
**章节来源**
- [models.py](file://backend/app/models/models.py#L1-L438)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
## 性能考虑
### 查询优化
1. **索引策略**: 为常用查询字段建立索引，包括员工ID、考核周期、状态等
2. **延迟加载**: 使用selectinload优化N+1查询问题
3. **分页处理**: 支持大数据集的分页查询
### 缓存策略
虽然当前实现没有内置缓存，但可以考虑：
- 考核状态的热点数据缓存
- 指标权重的静态数据缓存
- 员工基本信息的短期缓存
### 批量操作
系统支持批量创建考核记录，适用于月末批量处理场景：
```python
# 批量创建逻辑
for staff in staff_list:
assessment = Assessment(staff_id=staff.id, ...)
db.add(assessment)
# 为每个指标创建明细
for indicator_id in indicators:
detail = AssessmentDetail(indicator_id=indicator_id, ...)
db.add(detail)
```
## 故障排除指南
### 常见问题及解决方案
#### 状态流转错误
**问题**: 无法从草稿状态提交
**原因**: 考核记录状态不是DRAFT
**解决方案**: 检查当前状态是否为DRAFT
#### 权限不足
**问题**: 审核或确认接口返回400错误
**原因**: 当前用户权限不足
**解决方案**: 确保用户具有管理员或经理权限
#### 数据重复
**问题**: 批量创建时出现重复记录
**原因**: 同一员工在同一考核周期已存在记录
**解决方案**: 系统会自动跳过已存在的记录
### 异常处理机制
系统采用统一的异常处理模式：
```mermaid
flowchart TD
Try[业务操作] --> Success{操作成功?}
Success --> |是| ReturnOK[返回成功响应]
Success --> |否| CheckError{检查错误类型}
CheckError --> |业务错误| Return400[返回400错误]
CheckError --> |权限错误| Return403[返回403错误]
CheckError --> |数据库错误| Return500[返回500错误]
CheckError --> |其他错误| ReturnError[返回通用错误]
Return400 --> Catch[异常捕获]
Return403 --> Catch
Return500 --> Catch
ReturnError --> Catch
Catch --> Log[记录日志]
Log --> ReturnError
```
**图表来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L132)
**章节来源**
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L132)
## 结论
考核记录模型设计合理，实现了以下关键特性：
1. **完整的审批流程**: 支持多级审批的完整生命周期管理
2. **灵活的数据模型**: 支持多种考核周期和指标类型
3. **强一致性的数据结构**: 通过外键约束和级联删除保证数据完整性
4. **良好的扩展性**: 模块化设计便于功能扩展和维护
5. **完善的API接口**: 提供RESTful风格的完整接口集合
该模型为医院绩效管理系统的稳定运行奠定了坚实的数据基础，能够有效支撑复杂的绩效考核业务需求。