14 KiB
14 KiB
考核相关字段
**本文引用的文件** - [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) - [assessment_service.py](file://backend/app/services/assessment_service.py) - [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue) - [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue) - [assessment.js](file://frontend/src/api/assessment.js) - [stats.py](file://backend/app/api/v1/stats.py) - [database.md](file://docs/数据库设计.md) - [详细设计文档.md](file://docs/详细设计文档.md)目录
简介
本文件聚焦于“考核相关字段”的数据字典与业务规则，覆盖以下对象：
- 考核记录表（Assessment）
- 考核明细表（AssessmentDetail）
- 考核状态枚举（AssessmentStatus）
- 考核周期、状态流转、评分计算、完整性校验与一致性保障机制
- 考核结果计算与统计分析相关字段说明
目标是帮助开发者与业务人员快速理解字段含义、取值范围、约束条件、状态转换与计算逻辑，并提供排障建议与最佳实践。
项目结构
后端采用分层架构：API 控制器 → 服务层 → ORM 模型；前端通过 API 与后端交互，展示与操作考核流程。
graph TB
FE["前端视图<br/>Assessments.vue / AssessmentDetail.vue"] --> API["FastAPI 路由<br/>assessments.py"]
API --> SVC["服务层<br/>assessment_service.py"]
SVC --> DB["SQLAlchemy 模型<br/>models.py"]
DB --> SQL["数据库表<br/>assessments / assessment_details"]
API --> STATS["统计接口<br/>stats.py"]
图表来源
章节来源
核心组件
- Assessment（考核记录表）
- 关键字段：period_year、period_month、period_type、total_score、weighted_score、status、assessor_id、reviewer_id、submit_time、review_time、remark
- 业务规则：按月度周期生成记录；总分与加权得分由明细计算；状态驱动流程推进
- AssessmentDetail（考核明细表）
- 关键字段：assessment_id、indicator_id、actual_value、score、evidence、remark
- 业务规则：每个指标一条明细；得分与佐证材料可编辑（草稿态）
- AssessmentStatus（考核状态枚举）
- 草稿（draft）、已提交（submitted）、已审核（reviewed）、已确认（finalized）、已驳回（rejected）
章节来源
架构总览
考核流程由前端触发，经 API 路由进入服务层，持久化到数据库模型，最终支持统计分析。
sequenceDiagram
participant FE as "前端"
participant API as "API 路由"
participant SVC as "服务层"
participant DB as "模型/数据库"
FE->>API : "提交/审核/确认"
API->>SVC : "调用对应方法"
SVC->>DB : "读取/更新 Assessment/Details"
DB-->>SVC : "返回实体"
SVC-->>API : "返回处理结果"
API-->>FE : "返回响应"
图表来源
详细组件分析
Assessment（考核记录表）数据字典
-
字段定义与约束
- id：主键，自增整数
- staff_id：外键指向员工，必填
- period_year：整数，必填，年份范围约束见后端校验
- period_month：整数，必填，1-12
- period_type：字符串，默认 monthly
- total_score：数值，总分，创建时由明细得分求和
- weighted_score：数值，加权得分，按指标权重加权求和
- status：状态枚举，默认 draft
- assessor_id：外键，考核人
- reviewer_id：外键，审核人
- submit_time：提交时间
- review_time：审核时间
- remark：备注
- created_at/updated_at：时间戳
-
业务规则
- 考核周期：以年/月为单位，period_type 默认 monthly
- 总分与加权得分：由明细聚合计算
- 状态流转：草稿 → 已提交 → 已审核 → 已确认；或草稿 → 已驳回
- 时间字段：提交/审核时写入对应时间
-
约束与索引
- 索引：staff_id、period_year+period_month、status
- 约束：状态枚举值限定
章节来源
AssessmentDetail（考核明细表）数据字典
-
字段定义与约束
- id：主键，自增整数
- assessment_id：外键，必填
- indicator_id：外键，必填
- actual_value：实际值，可选
- score：数值，得分，创建默认 0
- evidence：佐证材料，可选
- remark：备注
- created_at/updated_at：时间戳
-
业务规则
- 每个指标一条明细
- 草稿态允许编辑得分与佐证材料
- 服务层在创建/更新时重新计算总分与加权得分
-
约束与索引
- 索引：assessment_id、indicator_id
章节来源
AssessmentStatus（考核状态枚举）数据字典
-
枚举值
- draft：草稿
- submitted：已提交
- reviewed：已审核
- finalized：已确认
- rejected：已驳回
-
状态转换规则
- 草稿 → 已提交（提交）
- 已提交 → 已审核 或 已驳回（审核）
- 已审核 → 已确认（确认）
- 草稿/已驳回 → 可更新（更新时仅允许草稿或已驳回）
章节来源
考核周期与状态流转
- 考核周期
- 默认周期类型为 monthly
- 不同指标模板可配置周期（如年度、季度），但记录层面以年/月为单位
- 状态流转
- 提交：将状态从草稿改为已提交并记录提交时间
- 审核：将状态从已提交改为已审核或已驳回，并记录审核时间
- 确认：将状态从已审核改为已确认
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交"
已提交 --> 已审核 : "审核通过"
已提交 --> 已驳回 : "审核驳回"
已审核 --> 已确认 : "确认"
已确认 --> [*]
已驳回 --> 草稿 : "重新编辑"
图表来源
章节来源
评分计算与字段约束
- 总分计算
- 总分 = 明细得分之和
- 加权得分计算
- 加权得分 = Σ(明细得分 × 指标权重)
- 权重来自指标表（指标权重 > 0）
- 字段约束
- 指标权重必须大于 0（数据库 CheckConstraint）
- 年度/月份范围在 Pydantic 层面有限制
- 得分字段有最小值 0 的约束
flowchart TD
Start(["创建/更新考核"]) --> LoadDetails["加载明细与指标"]
LoadDetails --> SumScore["总分 = Σ 明细.score"]
LoadDetails --> WeightCalc["加权得分 = Σ 明细.score × 指标.weight"]
SumScore --> SaveAssessment["保存 Assessment"]
WeightCalc --> SaveAssessment
SaveAssessment --> End(["完成"])
图表来源
章节来源
完整性检查与一致性保障
- 前端约束
- 草稿态允许编辑得分与佐证材料，得分上限为指标最大分值
- 状态按钮随状态变化显示
- 后端约束
- 状态流转严格限制（仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认）
- 批量创建时按年/月/员工去重，避免重复记录
- 指标权重 > 0 的数据库约束
- 统计一致性
- 统计接口基于当前周期与部门维度聚合，确保跨部门/跨周期对比一致
章节来源
考核结果计算与统计分析
- 计算字段
- total_score：总分
- weighted_score：加权得分
- 统计接口
- 科室绩效统计、周期统计、趋势分析、排名等
- 前端展示平均分、总人数、奖金汇总等
章节来源
依赖关系分析
- 模型层
- Assessment ←→ AssessmentDetail（一对多）
- Assessment ←→ Staff（多对一）
- AssessmentDetail ←→ Indicator（多对一）
- 服务层
- 服务层负责状态流转、计算与批量创建
- API 层
- 提供 CRUD、提交、审核、确认、批量创建等接口
- 前端
- 视图根据状态动态渲染按钮与输入框
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
}
class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
}
class Staff
class Indicator
Assessment "1" o-- "*" AssessmentDetail : "明细"
Assessment "many" --> "1" Staff : "员工"
AssessmentDetail "many" --> "1" Indicator : "指标"
图表来源
章节来源
性能考量
- 查询性能
- 为 staff_id、period_year+period_month、status 建立索引，有利于筛选与排序
- 写入性能
- 批量创建时按部门与周期预检，避免重复记录
- 计算性能
- 总分与加权得分在服务层一次性计算，减少多次往返
- 建议
- 对高频查询增加复合索引
- 对大表进行分区或归档策略（如历史周期）
章节来源
故障排查指南
- 常见问题
- 状态不可变更：仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认
- 无法提交/审核/确认：检查当前状态是否符合预期
- 批量创建重复：系统按 staff_id+period_year+period_month 去重
- 指标权重异常：数据库约束要求权重 > 0
- 前端定位
- 查看状态标签与按钮可用性
- 校验得分上限与佐证材料输入
- 后端定位
- 检查服务层状态判断与时间字段写入
- 核对明细聚合逻辑与指标权重
章节来源
结论
本数据字典明确了考核记录与明细的核心字段、状态流转、评分计算与约束条件，并结合前后端实现展示了完整的业务闭环。遵循上述规则可确保数据一致性与流程可控性，同时为后续扩展（如维度得分、模板周期等）提供清晰边界。
附录
- API 路由与前端交互
- 列表/详情/创建/更新/提交/审核/确认/批量创建
- 前端通过 assessment.js 发起请求，Assessments.vue 与 AssessmentDetail.vue 控制 UI 行为
章节来源