hospital_performance/.qoder/repowiki/zh/content/业务逻辑设计/考核流程设计.md

考核流程设计

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

目录

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

引言

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

项目结构

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

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
• frontend/src/api/assessment.js
• backend/app/api/v1/assessments.py
• backend/app/services/assessment_service.py
• backend/app/schemas/schemas.py
• backend/app/core/security.py
• backend/app/models/models.py

章节来源

• backend/app/api/v1/assessments.py
• backend/app/services/assessment_service.py
• backend/app/models/models.py
• backend/app/schemas/schemas.py
• backend/app/core/security.py
• frontend/src/views/assessment/Assessments.vue
• frontend/src/api/assessment.js

核心组件

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

章节来源

• backend/app/models/models.py
• backend/app/services/assessment_service.py
• backend/app/api/v1/assessments.py
• backend/app/schemas/schemas.py
• backend/app/core/security.py

架构总览

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

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
• backend/app/api/v1/assessments.py
• backend/app/core/security.py
• backend/app/services/assessment_service.py

详细组件分析

考核状态与业务规则

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

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

图表来源

• backend/app/models/models.py
• backend/app/services/assessment_service.py
• backend/app/api/v1/assessments.py

章节来源

• backend/app/models/models.py
• backend/app/services/assessment_service.py
• backend/app/api/v1/assessments.py

考核创建与更新流程

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

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

图表来源

• backend/app/services/assessment_service.py

章节来源

• backend/app/services/assessment_service.py

考核提交、审核与确认流程

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

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
• backend/app/services/assessment_service.py

章节来源

• backend/app/api/v1/assessments.py
• backend/app/services/assessment_service.py

批量创建考核流程与并发处理

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

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

章节来源

• backend/app/services/assessment_service.py

权限控制与安全策略

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

章节来源

• backend/app/core/security.py
• backend/app/api/v1/assessments.py

数据验证与事务管理

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

章节来源

• backend/app/services/assessment_service.py
• frontend/src/views/assessment/Assessments.vue

前后端交互与扩展点

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

章节来源

• frontend/src/views/assessment/Assessments.vue
• frontend/src/api/assessment.js
• docs/详细设计.md

依赖关系分析

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

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
• frontend/src/api/assessment.js
• backend/app/api/v1/assessments.py
• backend/app/core/security.py
• backend/app/services/assessment_service.py
• backend/app/models/models.py

章节来源

• backend/app/models/models.py
• backend/app/services/assessment_service.py
• backend/app/api/v1/assessments.py

性能考虑

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

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

故障排除指南

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

章节来源

• backend/app/api/v1/assessments.py
• backend/app/services/assessment_service.py

结论

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

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

附录

数据模型与索引映射

• 考核记录表：staff_id、period_year+period_month、status等索引。
• 考核明细表：assessment_id、indicator_id索引。
• 员工表：department_id、status索引。
• 指标表：indicator_type权重约束。

章节来源

• backend/app/models/models.py
• backend/alembic/versions/001_initial.py

数据库迁移与扩展

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

章节来源

• backend/alembic/versions/001_initial.py
• backend/alembic/versions/002_template.py