# 考核相关字段

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

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件聚焦于“考核相关字段”的数据字典与业务规则，覆盖以下对象：
- 考核记录表（Assessment）
- 考核明细表（AssessmentDetail）
- 考核状态枚举（AssessmentStatus）
- 考核周期、状态流转、评分计算、完整性校验与一致性保障机制
- 考核结果计算与统计分析相关字段说明

目标是帮助开发者与业务人员快速理解字段含义、取值范围、约束条件、状态转换与计算逻辑，并提供排障建议与最佳实践。

## 项目结构
后端采用分层架构：API 控制器 → 服务层 → ORM 模型；前端通过 API 与后端交互，展示与操作考核流程。

```mermaid
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"]
```

图表来源
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L149-L202)
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)

章节来源
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [models.py](file://backend/app/models/models.py#L149-L202)
- [stats.py](file://backend/app/api/v1/stats.py#L1-L242)

## 核心组件
- 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）

章节来源
- [models.py](file://backend/app/models/models.py#L149-L202)
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)

## 架构总览
考核流程由前端触发，经 API 路由进入服务层，持久化到数据库模型，最终支持统计分析。

```mermaid
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 : "返回响应"
```

图表来源
- [assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L227-L255)

## 详细组件分析

### 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
  - 约束：状态枚举值限定

章节来源
- [models.py](file://backend/app/models/models.py#L149-L178)
- [schemas.py](file://backend/app/schemas/schemas.py#L220-L257)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [database.md](file://docs/数据库设计.md#L159-L177)

### AssessmentDetail（考核明细表）数据字典
- 字段定义与约束
  - id：主键，自增整数
  - assessment_id：外键，必填
  - indicator_id：外键，必填
  - actual_value：实际值，可选
  - score：数值，得分，创建默认 0
  - evidence：佐证材料，可选
  - remark：备注
  - created_at/updated_at：时间戳

- 业务规则
  - 每个指标一条明细
  - 草稿态允许编辑得分与佐证材料
  - 服务层在创建/更新时重新计算总分与加权得分

- 约束与索引
  - 索引：assessment_id、indicator_id

章节来源
- [models.py](file://backend/app/models/models.py#L181-L202)
- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)

### AssessmentStatus（考核状态枚举）数据字典
- 枚举值
  - draft：草稿
  - submitted：已提交
  - reviewed：已审核
  - finalized：已确认
  - rejected：已驳回

- 状态转换规则
  - 草稿 → 已提交（提交）
  - 已提交 → 已审核 或 已驳回（审核）
  - 已审核 → 已确认（确认）
  - 草稿/已驳回 → 可更新（更新时仅允许草稿或已驳回）

章节来源
- [models.py](file://backend/app/models/models.py#L45-L52)
- [schemas.py](file://backend/app/schemas/schemas.py#L31-L36)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)

### 考核周期与状态流转
- 考核周期
  - 默认周期类型为 monthly
  - 不同指标模板可配置周期（如年度、季度），但记录层面以年/月为单位
- 状态流转
  - 提交：将状态从草稿改为已提交并记录提交时间
  - 审核：将状态从已提交改为已审核或已驳回，并记录审核时间
  - 确认：将状态从已审核改为已确认

```mermaid
stateDiagram-v2
[*] --> 草稿
草稿 --> 已提交 : "提交"
已提交 --> 已审核 : "审核通过"
已提交 --> 已驳回 : "审核驳回"
已审核 --> 已确认 : "确认"
已确认 --> [*]
已驳回 --> 草稿 : "重新编辑"
```

图表来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)

章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)

### 评分计算与字段约束
- 总分计算
  - 总分 = 明细得分之和
- 加权得分计算
  - 加权得分 = Σ(明细得分 × 指标权重)
  - 权重来自指标表（指标权重 > 0）
- 字段约束
  - 指标权重必须大于 0（数据库 CheckConstraint）
  - 年度/月份范围在 Pydantic 层面有限制
  - 得分字段有最小值 0 的约束

```mermaid
flowchart TD
Start(["创建/更新考核"]) --> LoadDetails["加载明细与指标"]
LoadDetails --> SumScore["总分 = Σ 明细.score"]
LoadDetails --> WeightCalc["加权得分 = Σ 明细.score × 指标.weight"]
SumScore --> SaveAssessment["保存 Assessment"]
WeightCalc --> SaveAssessment
SaveAssessment --> End(["完成"])
```

图表来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [models.py](file://backend/app/models/models.py#L149-L178)

章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
- [models.py](file://backend/app/models/models.py#L149-L178)

### 完整性检查与一致性保障
- 前端约束
  - 草稿态允许编辑得分与佐证材料，得分上限为指标最大分值
  - 状态按钮随状态变化显示
- 后端约束
  - 状态流转严格限制（仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认）
  - 批量创建时按年/月/员工去重，避免重复记录
  - 指标权重 > 0 的数据库约束
- 统计一致性
  - 统计接口基于当前周期与部门维度聚合，确保跨部门/跨周期对比一致

章节来源
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L57-L96)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)
- [models.py](file://backend/app/models/models.py#L144-L146)

### 考核结果计算与统计分析
- 计算字段
  - total_score：总分
  - weighted_score：加权得分
- 统计接口
  - 科室绩效统计、周期统计、趋势分析、排名等
  - 前端展示平均分、总人数、奖金汇总等

章节来源
- [stats.py](file://backend/app/api/v1/stats.py#L36-L242)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L31-L74)

## 依赖关系分析
- 模型层
  - Assessment ←→ AssessmentDetail（一对多）
  - Assessment ←→ Staff（多对一）
  - AssessmentDetail ←→ Indicator（多对一）
- 服务层
  - 服务层负责状态流转、计算与批量创建
- API 层
  - 提供 CRUD、提交、审核、确认、批量创建等接口
- 前端
  - 视图根据状态动态渲染按钮与输入框

```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
}
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 : "指标"
```

图表来源
- [models.py](file://backend/app/models/models.py#L149-L202)

章节来源
- [models.py](file://backend/app/models/models.py#L149-L202)

## 性能考量
- 查询性能
  - 为 staff_id、period_year+period_month、status 建立索引，有利于筛选与排序
- 写入性能
  - 批量创建时按部门与周期预检，避免重复记录
- 计算性能
  - 总分与加权得分在服务层一次性计算，减少多次往返
- 建议
  - 对高频查询增加复合索引
  - 对大表进行分区或归档策略（如历史周期）

章节来源
- [models.py](file://backend/app/models/models.py#L174-L178)
- [assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)

## 故障排查指南
- 常见问题
  - 状态不可变更：仅草稿/已驳回可更新；仅已提交可审核；仅已审核可确认
  - 无法提交/审核/确认：检查当前状态是否符合预期
  - 批量创建重复：系统按 staff_id+period_year+period_month 去重
  - 指标权重异常：数据库约束要求权重 > 0
- 前端定位
  - 查看状态标签与按钮可用性
  - 校验得分上限与佐证材料输入
- 后端定位
  - 检查服务层状态判断与时间字段写入
  - 核对明细聚合逻辑与指标权重

章节来源
- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L57-L63)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L57-L96)

## 结论
本数据字典明确了考核记录与明细的核心字段、状态流转、评分计算与约束条件，并结合前后端实现展示了完整的业务闭环。遵循上述规则可确保数据一致性与流程可控性，同时为后续扩展（如维度得分、模板周期等）提供清晰边界。

## 附录
- API 路由与前端交互
  - 列表/详情/创建/更新/提交/审核/确认/批量创建
  - 前端通过 assessment.js 发起请求，Assessments.vue 与 AssessmentDetail.vue 控制 UI 行为

章节来源
- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L96)