提交文件

2026-02-28 15:16:15 +08:00
parent 1a4e50e0a4
commit 44f250f58e
159 changed files with 61268 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/业务逻辑设计/考核流程设计.md
+++ b/.qoder/repowiki/zh/content/业务逻辑设计/考核流程设计.md
@@ -0,0 +1,384 @@
+# 考核流程设计
+
+<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)