提交文件
This commit is contained in:
504
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/考核记录模型.md
Normal file
504
.qoder/repowiki/zh/content/数据模型详解/核心数据模型/考核记录模型.md
Normal file
@@ -0,0 +1,504 @@
|
||||
# 考核记录模型
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
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["草稿状态<br/>DRAFT"]
|
||||
Draft --> Submit["提交状态<br/>SUBMITTED"]
|
||||
Submit --> Review["审核状态<br/>REVIEWED"]
|
||||
Submit --> Reject["驳回状态<br/>REJECTED"]
|
||||
Review --> Finalize["确认状态<br/>FINALIZED"]
|
||||
Reject --> Draft2["返回草稿<br/>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风格的完整接口集合
|
||||
|
||||
该模型为医院绩效管理系统的稳定运行奠定了坚实的数据基础，能够有效支撑复杂的绩效考核业务需求。
|
||||
Reference in New Issue
Block a user