提交文件

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,424 @@
+# 绩效考核管理
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js)
+- [docs/api.md](file://docs/api.md)
+- [docs/详细设计.md](file://docs/详细设计.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本模块聚焦于医院绩效系统的“绩效考核管理”，围绕考核流程（草稿→提交→审核→确认→完成）、考核记录与明细处理、批量创建、平衡计分卡（财务、客户、内部流程、学习与成长）应用、状态管理与审批控制、数据统计与报表、以及规则配置与权重计算展开。文档同时提供业务流程图、界面操作说明与API接口规范，帮助开发者与使用者高效理解与使用。
+
+## 项目结构
+后端采用FastAPI + SQLAlchemy异步ORM，前端采用Vue 3 + Element Plus，数据模型、服务层与API路由清晰分离，前端通过封装的API模块调用后端接口。
+
+```mermaid
+graph TB
+subgraph "前端"
+FE_List["Assessments.vue<br/>考核列表视图"]
+FE_Detail["AssessmentDetail.vue<br/>考核详情视图"]
+FE_API_A["assessment.js<br/>考核API封装"]
+FE_API_I["indicator.js<br/>指标API封装"]
+end
+subgraph "后端"
+API["assessments.py<br/>考核API路由"]
+SVC["assessment_service.py<br/>考核服务"]
+MODELS["models.py<br/>数据模型"]
+SCHEMAS["schemas.py<br/>数据模式"]
+IND_API["indicators.py<br/>指标API路由"]
+end
+FE_List --> FE_API_A
+FE_Detail --> FE_API_A
+FE_List --> FE_API_I
+FE_API_A --> API
+FE_API_I --> IND_API
+API --> SVC
+SVC --> MODELS
+SVC --> SCHEMAS
+IND_API --> SVC
+```
+
+图表来源
+- [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#L1-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
+
+章节来源
+- [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)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
+
+## 核心组件
+- 数据模型
+  - Assessment：考核记录，包含周期、总分、加权得分、状态、关联人员与明细。
+  - AssessmentDetail：考核明细，记录每个指标的实际值、得分、佐证材料等。
+  - Indicator：考核指标，包含类型、平衡计分卡维度、权重、最高分、目标值等。
+  - AssessmentStatus：枚举状态（草稿、已提交、已审核、已确认、已驳回）。
+- 服务层
+  - AssessmentService：提供列表查询、详情加载、创建、更新、提交、审核、确认、批量创建等核心能力。
+- API层
+  - 路由提供列表、详情、创建、更新、提交、审核、确认、批量创建等REST接口。
+- 前端
+  - Assessments.vue：列表页，支持筛选、分页、批量创建、状态流转。
+  - AssessmentDetail.vue：详情页，支持草稿态编辑、保存、提交、审核、确认。
+  - assessment.js/indicator.js：前端API封装，统一调用后端接口。
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [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#L14-L263)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
+
+## 架构总览
+后端采用分层架构：API路由负责参数解析与鉴权，服务层封装业务逻辑，模型层映射数据库表结构。前端通过HTTP请求与后端交互，完成考核流程的可视化操作。
+
+```mermaid
+graph TB
+Client["浏览器/移动端"] --> FE["前端Vue应用"]
+FE --> API["FastAPI路由层"]
+API --> Service["服务层"]
+Service --> DB["数据库"]
+Service --> Models["数据模型"]
+Service --> Schemas["数据模式"]
+```
+
+图表来源
+- [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#L1-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+
+## 详细组件分析
+
+### 考核流程管理（草稿→提交→审核→确认→完成）
+- 流程状态
+  - 草稿：可编辑明细与得分。
+  - 已提交：等待审核。
+  - 已审核：等待确认。
+  - 已确认：完成，不可再编辑。
+  - 已驳回：退回草稿，可重新提交。
+- 接口流转
+  - 草稿 → 提交：POST /assessments/{id}/submit
+  - 已提交 → 审核：POST /assessments/{id}/review（批准/驳回）
+  - 已审核 → 确认：POST /assessments/{id}/finalize
+  - 已确认 → 完成：不可逆
+- 前端操作
+  - 列表页仅显示状态与操作按钮，按钮随状态变化。
+  - 详情页支持草稿态编辑与保存，提交后进入审核流程。
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : "提交"
+已提交 --> 已审核 : "审核通过"
+已提交 --> 草稿 : "审核驳回"
+已审核 --> 已确认 : "确认"
+已确认 --> [*]
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L55-L63)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L86-L93)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L45-L51)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L105-L145)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L55-L63)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L86-L93)
+
+### 考核记录管理与明细处理
+- 记录管理
+  - 创建：POST /assessments（携带明细数组）
+  - 更新：PUT /assessments/{id}（仅允许草稿或已驳回状态）
+  - 详情：GET /assessments/{id}（包含明细与指标名称）
+- 明细字段
+  - 指标ID、实际值、得分、佐证材料、备注
+- 加权得分计算
+  - 总分：明细得分求和
+  - 加权得分：∑(明细得分 × 指标权重)
+
+```mermaid
+flowchart TD
+Start(["创建/更新考核"]) --> CalcTotal["计算总分<br/>sum(明细得分)"]
+CalcTotal --> LoadIndicators["加载指标权重"]
+LoadIndicators --> CalcWeighted["计算加权得分<br/>sum(得分×权重)"]
+CalcWeighted --> SaveAssessment["保存考核记录与明细"]
+SaveAssessment --> End(["完成"])
+```
+
+图表来源
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L156)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
+
+章节来源
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L80-L103)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L156)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L194-L271)
+
+### 批量创建功能
+- 触发入口：列表页“批量创建”
+- 参数：科室ID、年度、月份、指标ID列表
+- 逻辑：为该科室当月在职员工逐一创建空明细的考核记录（若不存在）
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant V as "Assessments.vue"
+participant A as "assessment.js"
+participant R as "assessments.py"
+participant S as "assessment_service.py"
+U->>V : "点击批量创建"
+V->>A : "调用批量创建API"
+A->>R : "POST /assessments/batch-create"
+R->>S : "batch_create_for_department()"
+S->>S : "查询在职员工"
+S->>S : "检查是否存在重复"
+S->>S : "创建考核记录+明细"
+S-->>R : "返回创建数量"
+R-->>A : "返回成功响应"
+A-->>V : "提示成功并刷新列表"
+```
+
+图表来源
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L28-L112)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
+
+章节来源
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L28-L112)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L38-L49)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L148-L165)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L207-L262)
+
+### 平衡计分卡维度应用
+- 指标维度
+  - 财务（financial）
+  - 客户（customer）
+  - 内部流程（internal_process）
+  - 学习与成长（learning_growth）
+- 应用方式
+  - 指标表包含bs_dimension字段，用于区分维度
+  - 前端在详情页展示指标类型标签，便于识别维度属性
+- 配置建议
+  - 不同科室类型可选用不同模板或指标组合，体现维度侧重点差异
+
+```mermaid
+classDiagram
+class Indicator {
+bs_dimension
+weight
+max_score
+}
+class AssessmentDetail {
+indicator_id
+actual_value
+score
+}
+Indicator <.. AssessmentDetail : "被引用"
+```
+
+图表来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L181-L202)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L151-L193)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L35)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L38-L42)
+
+### 状态管理与审批控制
+- 状态枚举与流转限制
+  - 草稿/已驳回：可更新
+  - 已提交：仅能审核
+  - 已审核：仅能确认
+  - 已确认：不可再更改
+- 审批接口
+  - 审核：POST /assessments/{id}/review（批准/驳回）
+  - 确认：POST /assessments/{id}/finalize
+
+章节来源
+- [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#L110-L205)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
+
+### 数据统计分析与报表
+- 指标管理API
+  - 获取启用指标：GET /indicators/active
+  - 获取指标列表：GET /indicators
+- 报表与统计
+  - 文档中提供统计接口（如科室统计、趋势分析、分布等），可结合考核数据进行分析
+- 建议
+  - 基于Assessment与AssessmentDetail聚合，生成部门/个人/维度的统计报表
+
+章节来源
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L44-L55)
+- [docs/api.md](file://docs/api.md#L471-L537)
+- [docs/详细设计.md](file://docs/详细设计.md#L155-L163)
+
+### 考核规则配置、权重计算与结果汇总
+- 规则配置
+  - 指标权重：Indicator.weight
+  - 最高分：Indicator.max_score
+  - 计算方法/公式：Indicator.calculation_method
+- 权重计算
+  - 总分：明细得分求和
+  - 加权得分：∑(明细得分 × 指标权重)
+- 结果汇总
+  - 以Assessment为单位汇总，支持按周期、部门、状态等维度统计
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L147)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L178)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L70-L108)
+
+## 依赖关系分析
+
+```mermaid
+graph LR
+AssessAPI["assessments.py"] --> AssessSvc["assessment_service.py"]
+AssessSvc --> Models["models.py"]
+AssessSvc --> Schemas["schemas.py"]
+IndAPI["indicators.py"] --> AssessSvc
+FEAssess["Assessments.vue"] --> FEAssessAPI["assessment.js"]
+FEDetail["AssessmentDetail.vue"] --> FEAssessAPI
+FEAssessAPI --> AssessAPI
+FEInd["indicator.js"] --> IndAPI
+```
+
+图表来源
+- [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#L1-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
+
+章节来源
+- [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#L1-L438)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [backend/app/api/v1/indicators.py](file://backend/app/api/v1/indicators.py#L1-L142)
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [frontend/src/api/assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [frontend/src/api/indicator.js](file://frontend/src/api/indicator.js#L1-L32)
+
+## 性能考虑
+- 查询优化
+  - 列表查询支持按员工、科室、年度、月份、状态过滤，建议在相关列建立索引（如 idx_assessment_staff、idx_assessment_period、idx_assessment_status）。
+- 批量创建
+  - 批量创建时避免重复记录，减少数据库写入压力。
+- 前端渲染
+  - 大列表分页加载，避免一次性渲染过多行。
+- 异步处理
+  - 服务层使用异步会话，适合高并发场景。
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L174-L178)
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L18-L55)
+
+## 故障排查指南
+- 常见问题
+  - 状态不允许：仅允许在草稿或已驳回状态下更新；仅允许在已提交状态下审核；仅允许在已审核状态下确认。
+  - 资源不存在：接口返回404，检查ID或参数。
+  - 参数错误：检查必填字段与范围（如月份1-12、权重>0）。
+- 前端提示
+  - 使用Element Plus的消息组件提示成功/失败。
+- 日志与监控
+  - 后端日志目录：logs/，可定位异常请求与SQL执行情况。
+
+章节来源
+- [backend/app/services/assessment_service.py](file://backend/app/services/assessment_service.py#L110-L205)
+- [backend/app/api/v1/assessments.py](file://backend/app/api/v1/assessments.py#L98-L101)
+- [docs/api.md](file://docs/api.md#L540-L551)
+
+## 结论
+本模块以清晰的流程状态与严格的审批控制为核心，结合平衡计分卡维度与指标权重，实现了从草稿到完成的全流程管理。前后端职责分明，接口规范明确，具备良好的扩展性与可维护性。建议后续完善统计分析与报表模块，并在生产环境增加更完善的日志与监控策略。
+
+## 附录
+
+### 业务流程图（概念）
+```mermaid
+flowchart TD
+A["开始"] --> B["创建/编辑考核<br/>草稿态"]
+B --> C["提交考核"]
+C --> D{"审核通过？"}
+D -- "是" --> E["确认考核"]
+D -- "否" --> F["退回草稿<br/>可重新提交"]
+E --> G["完成"]
+F --> C
+G --> H["结束"]
+```
+
+[此图为概念流程图，不对应具体代码文件]
+
+### 界面操作说明
+- 列表页
+  - 支持按科室、考核周期、状态筛选；分页浏览；批量创建；对草稿/已提交/已审核状态显示相应操作按钮。
+- 详情页
+  - 展示基本信息与明细；草稿态可编辑实际值、得分、佐证材料；支持保存、提交、审核、确认等操作。
+
+章节来源
+- [frontend/src/views/assessment/Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [frontend/src/views/assessment/AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+
+### API接口文档（节选）
+- 获取考核列表：GET /assessments
+- 获取考核详情：GET /assessments/{id}
+- 创建考核：POST /assessments
+- 更新考核：PUT /assessments/{id}
+- 提交考核：POST /assessments/{id}/submit
+- 审核考核：POST /assessments/{id}/review
+- 确认考核：POST /assessments/{id}/finalize
+- 批量创建：POST /assessments/batch-create
+- 获取启用指标：GET /indicators/active
+
+章节来源
+- [docs/api.md](file://docs/api.md#L298-L397)
+- [docs/api.md](file://docs/api.md#L471-L537)