# 考核流程设计

<cite>
**本文档引用的文件**
- [backend/app/models/models.py](file://backend/app/models/models.py)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
- [backend/app/core/security.py](file://backend/app/core/security.py)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
- [docs/详细设计.md](file://docs/详细设计.md)
</cite>

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

## 引言
本文件面向医院绩效系统的“考核流程设计”，围绕考核状态流转机制（草稿→提交→审核→确认）进行系统化说明，涵盖业务规则、权限控制、数据验证、流程实现、批量创建与并发处理、异常处理与事务管理策略，以及流程控制的扩展点与自定义配置选项。文档同时提供前后端交互与数据库结构映射，帮助开发者与运维人员快速理解与实施。

## 项目结构
后端采用FastAPI + SQLAlchemy异步ORM，按领域模块划分：API路由、服务层、数据模型、Schema定义、安全认证与配置。前端采用Vue 3 + Element Plus，提供考核列表、状态操作与批量创建能力。

```mermaid
graph TB
subgraph "前端"
FE_List["Assessments.vue<br/>考核列表与操作"]
FE_API["assessment.js<br/>HTTP客户端封装"]
end
subgraph "后端"
API["assessments.py<br/>API路由"]
SVC["assessment_service.py<br/>服务层"]
SCHEMA["schemas.py<br/>数据模式"]
SEC["security.py<br/>权限与认证"]
MODEL["models.py<br/>数据模型"]
DB[("数据库")]
end
FE_List --> FE_API
FE_API --> API
API --> SVC
SVC --> MODEL
SVC --> SCHEMA
API --> SEC
SVC --> DB
MODEL --> DB
```

**图表来源**
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L200)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L200)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)

## 核心组件
- 数据模型层：定义考核记录、明细、员工、科室、指标等实体及其关系与索引。
- 服务层：封装业务逻辑，包括创建、更新、提交、审核、确认、批量创建等。
- API层：暴露REST接口，绑定权限装饰器，返回标准化响应。
- Schema层：定义请求/响应数据结构与枚举类型，确保前后端契约一致。
- 安全层：基于JWT的认证与授权，区分普通员工、管理员与经理权限。
- 前端视图与API封装：提供考核列表、状态操作按钮与批量创建弹窗。

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L17-L166)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)

## 架构总览
系统采用分层架构：前端负责交互与调用，后端API路由接收请求，服务层执行业务规则，数据模型映射到数据库，安全中间件进行权限校验。状态流转由服务层严格控制，API层仅暴露受控的端点。

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "API路由"
participant SEC as "安全中间件"
participant SVC as "服务层"
participant DB as "数据库"
FE->>API : "提交/审核/确认请求"
API->>SEC : "校验JWT与角色"
SEC-->>API : "通过/拒绝"
API->>SVC : "调用业务方法"
SVC->>DB : "读写数据"
DB-->>SVC : "返回结果"
SVC-->>API : "业务结果"
API-->>FE : "标准化响应"
```

**图表来源**
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [backend/app/core/security.py](file://backend/app/core/security.py#L85-L110)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)

## 详细组件分析

### 考核状态与业务规则
- 状态枚举：草稿(draft)、已提交(submitted)、已审核(reviewed)、已确认(finalized)、已驳回(rejected)。
- 状态流转：
  - 草稿 → 已提交：仅草稿或已驳回状态允许提交。
  - 已提交 → 已审核/已驳回：审核人根据审批结果切换状态。
  - 已审核 → 已确认：仅已审核状态允许确认。
- 权限控制：
  - 提交：当前活跃用户即可。
  - 审核/确认：管理员或经理角色。
- 数据验证：
  - 提交前：校验状态必须为草稿。
  - 审核：校验状态必须为已提交。
  - 确认：校验状态必须为已审核。
  - 更新：仅允许草稿或已驳回状态修改明细与备注。

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

**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)

### 考核创建与更新流程
- 创建：
  - 计算总分与加权得分（加权=Σ(指标得分×指标权重)）。
  - 写入主表与明细表，刷新实体。
- 更新：
  - 仅草稿或已驳回状态允许更新。
  - 删除旧明细，重建新明细并重新计算总分与加权得分。
  - 可选更新备注。

```mermaid
flowchart TD
Start(["进入创建/更新"]) --> CheckStatus["检查状态是否允许"]
CheckStatus --> |不允许| Error["返回错误"]
CheckStatus --> |允许| BuildDetails["构建明细列表"]
BuildDetails --> CalcScore["计算总分与加权得分"]
CalcScore --> Persist["持久化主表与明细"]
Persist --> Refresh["刷新实体"]
Refresh --> Done(["完成"])
Error --> Done
```

**图表来源**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L156)

**章节来源**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L71-L156)

### 考核提交、审核与确认流程
- 提交：
  - 校验状态为草稿，设置提交时间，状态变更为已提交。
- 审核：
  - 校验状态为已提交，记录审核人与时间；通过则变更为已审核，否则变更为已驳回。
- 确认：
  - 校验状态为已审核，状态变更为已确认。

```mermaid
sequenceDiagram
participant U as "用户"
participant API as "API"
participant SVC as "服务层"
participant DB as "数据库"
U->>API : "POST /assessments/{id}/submit"
API->>SVC : "submit(id)"
SVC->>DB : "读取并校验状态"
DB-->>SVC : "返回记录"
SVC->>DB : "更新状态=已提交, 写入提交时间"
DB-->>SVC : "提交成功"
SVC-->>API : "返回结果"
API-->>U : "提交成功"
U->>API : "POST /assessments/{id}/review?approved={bool}&remark={text}"
API->>SVC : "review(id, reviewer_id, approved, remark)"
SVC->>DB : "读取并校验状态"
DB-->>SVC : "返回记录"
SVC->>DB : "更新状态=已审核/已驳回, 写入审核人与时间"
DB-->>SVC : "审核完成"
SVC-->>API : "返回结果"
API-->>U : "审核通过/已驳回"
U->>API : "POST /assessments/{id}/finalize"
API->>SVC : "finalize(id)"
SVC->>DB : "读取并校验状态"
DB-->>SVC : "返回记录"
SVC->>DB : "更新状态=已确认"
DB-->>SVC : "确认完成"
SVC-->>API : "返回结果"
API-->>U : "确认成功"
```

**图表来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)

**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)

### 批量创建考核流程与并发处理
- 批量创建：
  - 获取指定科室当月在职员工列表。
  - 检查是否存在同周期重复记录，避免重复创建。
  - 为每位员工创建空明细（默认得分0），并持久化。
- 并发处理：
  - 使用数据库事务保证创建完整性。
  - 建议在高并发场景下增加唯一性约束与去重检查，避免重复创建。
  - 可引入队列或批处理策略，分批创建以降低锁竞争。

```mermaid
flowchart TD
S(["开始批量创建"]) --> FetchStaff["查询在职员工"]
FetchStaff --> Loop{"遍历员工"}
Loop --> |存在| Skip["跳过已存在记录"]
Loop --> |不存在| CreateAssess["创建考核记录(0分)"]
CreateAssess --> CreateDetails["为每个指标创建明细(0分)"]
CreateDetails --> Next["下一个员工"]
Skip --> Next
Next --> |完成| Flush["批量刷新持久化"]
Flush --> E(["结束"])
```

**图表来源**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L208-L262)

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

### 权限控制与安全策略
- 当前用户：从JWT载荷解析用户ID，查询用户信息并校验是否激活。
- 管理员：要求角色为admin。
- 经理/管理员：要求角色为admin或manager。
- API端点：
  - 提交/更新：当前活跃用户。
  - 审核/确认：管理员或经理。
- 建议扩展：支持“谁可以审核/确认”配置化，结合用户与角色、科室层级、指标类型等策略。

**章节来源**
- [backend/app/core/security.py](file://backend/app/core/security.py#L55-L110)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)

### 数据验证与事务管理
- 数据验证：
  - 状态前置校验：提交/审核/确认均严格校验当前状态。
  - 更新校验：仅允许草稿或已驳回状态修改明细。
  - 前端校验：列表页根据状态显示对应操作按钮。
- 事务管理：
  - 服务层使用flush/refresh保证一致性。
  - 建议在关键流程（批量创建、跨表更新）使用显式事务包裹，失败回滚。

**章节来源**
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L111-L205)
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L55-L64)

### 前后端交互与扩展点
- 前端：
  - 列表页支持按科室、周期、状态筛选，分页加载。
  - 操作按钮按状态动态显示（提交、审核、确认）。
  - 批量创建弹窗支持选择科室、周期与指标集合。
- 扩展点：
  - 自定义评分方法：在指标模板与方案中扩展评分参数。
  - 流程定制：支持按科室类型/岗位类型配置不同的审批链路。
  - 结果应用：扩展到绩效工资、晋升、评优等联动模块。

**章节来源**
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L200)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [docs/详细设计.md](file://docs/详细设计.md#L57-L121)

## 依赖关系分析
- API层依赖安全中间件与服务层。
- 服务层依赖数据模型与Schema。
- 数据模型依赖数据库引擎与索引。
- 前端依赖API封装与Element Plus组件库。

```mermaid
graph LR
FE["Assessments.vue"] --> APIJS["assessment.js"]
APIJS --> API["assessments.py"]
API --> SEC["security.py"]
API --> SVC["assessment_service.py"]
SVC --> MODEL["models.py"]
SVC --> SCHEMA["schemas.py"]
MODEL --> DB[("数据库")]
```

**图表来源**
- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L200)
- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
- [backend/app/core/security.py](file://backend/app/core/security.py#L1-L110)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L1-L263)
- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)

## 性能考虑
- 查询优化：
  - 为常用过滤字段（员工ID、周期、状态）建立索引。
  - 使用selectinload减少N+1查询。
- 写入优化：
  - 批量插入明细，减少往返次数。
  - flush/refresh时机合理控制，避免过度刷新。
- 并发与锁：
  - 批量创建时注意唯一性检查与去重，避免重复写入。
  - 高并发场景建议引入队列或分批策略。

[本节为通用指导，无需特定文件引用]

## 故障排除指南
- 常见问题：
  - 状态不允许：检查当前状态是否满足提交/审核/确认前置条件。
  - 权限不足：确认当前用户角色是否为管理员或经理。
  - 重复创建：批量创建时检查同周期是否已存在记录。
- 排查步骤：
  - 查看API响应码与消息。
  - 核对服务层状态校验逻辑。
  - 检查数据库索引与唯一约束。
- 建议：
  - 增加更详细的错误码与国际化提示。
  - 在服务层捕获异常并记录上下文日志。

**章节来源**
- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)

## 结论
本设计以清晰的状态机为核心，结合严格的权限控制与数据验证，实现了从创建到确认的完整考核流程。服务层承担业务规则，API层提供受控接口，前端提供直观的操作体验。通过索引优化、事务管理与并发控制，系统具备良好的可扩展性与稳定性。后续可在流程定制、评分方法与结果应用等方面进一步增强。

[本节为总结，无需特定文件引用]

## 附录

### 数据模型与索引映射
- 考核记录表：staff_id、period_year+period_month、status等索引。
- 考核明细表：assessment_id、indicator_id索引。
- 员工表：department_id、status索引。
- 指标表：indicator_type权重约束。

**章节来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L131)

### 数据库迁移与扩展
- 初始版本：创建科室、员工、指标、考核、明细、工资、用户等核心表。
- 模板扩展：新增指标模板与模板指标关联表，并向指标表补充BSC维度等字段。

**章节来源**
- [backend/alembic/versions/001_initial.py](file://backend/alembic/versions/001_initial.py#L21-L183)
- [backend/alembic/versions/002_template.py](file://backend/alembic/versions/002_template.py#L21-L96)