Files

2026-02-28 15:16:15 +08:00

13 KiB

Raw Blame History

考核记录模型

**本文档引用的文件** - [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)

简介

考核记录模型是医院绩效管理系统的核心数据结构，负责管理员工的绩效考核过程。该模型实现了完整的多级审批流程，支持草稿→提交→审核→确认→驳回的状态流转，并提供了灵活的考核周期管理和数据一致性保证机制。

项目结构

后端采用典型的三层架构设计，主要包含以下层次：

graph TB
subgraph "表现层"
API[API路由层]
Frontend[前端接口]
end
subgraph "业务逻辑层"
Service[服务层]
Schema[数据模式层]
end
subgraph "数据访问层"
Model[模型层]
DB[(数据库)]
end
Frontend --> API
API --> Service
Service --> Model
Model --> DB

图表来源

章节来源

核心组件

考核状态枚举

考核状态枚举定义了完整的审批流程状态：

stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : 提交考核
已提交 --> 已审核 : 审核通过
已提交 --> 已驳回 : 审核驳回
已审核 --> 已确认 : 确认完成
已确认 --> [*]
已驳回 --> 草稿 : 修改后重新提交

图表来源

models.py

主要数据模型

系统包含四个核心数据模型，形成了完整的考核数据结构：

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

章节来源

models.py

架构概览

系统采用RESTful API设计，实现了完整的CRUD操作和业务流程控制：

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 : 返回提交成功

图表来源

详细组件分析

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	备注	可选

关系映射

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

状态流转机制

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

计算逻辑实现

总分计算

总分计算逻辑简单直接，将所有考核明细的得分相加：

# 总分 = Σ(明细得分)
total_score = sum(d.score for d in assessment_data.details)

加权得分计算

加权得分考虑了指标权重的影响：

# 加权得分 = Σ(明细得分 × 指标权重)
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

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

数据一致性保证

级联删除机制

Assessment模型使用了级联删除策略，确保当主记录被删除时，相关的明细记录也会自动清理：

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

依赖关系分析

模块间依赖

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

图表来源

数据流依赖

flowchart TD
Request[HTTP请求] --> Validation[数据验证]
Validation --> ServiceCall[服务调用]
ServiceCall --> DBQuery[数据库查询]
DBQuery --> BusinessLogic[业务逻辑处理]
BusinessLogic --> DBUpdate[数据库更新]
DBUpdate --> Response[响应生成]
Response --> Client[客户端]
Validation --> |Schema验证| ServiceCall
BusinessLogic --> |状态检查| DBUpdate

图表来源

章节来源

性能考虑

查询优化

索引策略: 为常用查询字段建立索引，包括员工ID、考核周期、状态等
延迟加载: 使用selectinload优化N+1查询问题
分页处理: 支持大数据集的分页查询

缓存策略

虽然当前实现没有内置缓存，但可以考虑：

考核状态的热点数据缓存
指标权重的静态数据缓存
员工基本信息的短期缓存

批量操作

系统支持批量创建考核记录，适用于月末批量处理场景：

# 批量创建逻辑
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错误原因: 当前用户权限不足 解决方案: 确保用户具有管理员或经理权限

数据重复

问题: 批量创建时出现重复记录原因: 同一员工在同一考核周期已存在记录 解决方案: 系统会自动跳过已存在的记录

异常处理机制

系统采用统一的异常处理模式：

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

章节来源

assessments.py

结论

考核记录模型设计合理，实现了以下关键特性：

完整的审批流程: 支持多级审批的完整生命周期管理
灵活的数据模型: 支持多种考核周期和指标类型
强一致性的数据结构: 通过外键约束和级联删除保证数据完整性
良好的扩展性: 模块化设计便于功能扩展和维护
完善的API接口: 提供RESTful风格的完整接口集合

该模型为医院绩效管理系统的稳定运行奠定了坚实的数据基础，能够有效支撑复杂的绩效考核业务需求。

13 KiB Raw Blame History Unescape Escape

考核记录模型

目录

简介

项目结构

核心组件

考核状态枚举

主要数据模型

架构概览

详细组件分析

Assessment模型详解

字段设计

关系映射

状态流转机制

计算逻辑实现

总分计算

加权得分计算

API接口设计

数据一致性保证

级联删除机制

索引优化

依赖关系分析

模块间依赖

数据流依赖

性能考虑

查询优化

缓存策略

批量操作

故障排除指南

常见问题及解决方案

状态流转错误

权限不足

数据重复

异常处理机制

结论

13 KiB

Raw Blame History