提交文件

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,326 @@
+# 考核详情查看
+
+<cite>
+**本文档引用的文件**
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
+- [assessment.js](file://frontend/src/api/assessment.js)
+- [assessments.py](file://backend/app/api/v1/assessments.py)
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [models.py](file://backend/app/models/models.py)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
+- [security.py](file://backend/app/core/security.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+- [详细设计.md](file://docs/详细设计.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本章节面向“考核详情查看”功能，系统性阐述考核记录的详细信息展示、员工与科室信息、考核周期、各项指标得分与总分计算、加权得分计算公式、权重配置与分数等级划分、考核明细展示格式、数据来源与更新机制，并补充权限控制与数据安全保护措施。文档同时提供界面布局示意、数据流图与序列图，帮助前后端开发者与产品人员快速理解与实现。
+
+## 项目结构
+本功能涉及前后端协同：
+- 前端负责详情页面渲染、交互与权限控制提示
+- 后端提供REST API、服务层计算与数据库持久化
+- 数据模型定义了考核记录、明细、指标与状态枚举
+- 安全模块提供认证与授权中间件
+
+```mermaid
+graph TB
+FE["前端<br/>AssessmentDetail.vue"] --> API["后端API<br/>assessments.py"]
+API --> SVC["服务层<br/>assessment_service.py"]
+SVC --> DB["数据库模型<br/>models.py"]
+API --> SEC["安全中间件<br/>security.py"]
+```
+
+图表来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
+- [models.py](file://backend/app/models/models.py#L149-L203)
+- [security.py](file://backend/app/core/security.py#L55-L110)
+
+章节来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [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#L1-L438)
+- [security.py](file://backend/app/core/security.py#L1-L110)
+
+## 核心组件
+- 前端详情视图：展示基本信息、考核明细、状态标签与操作按钮，支持草稿态编辑与保存、提交、审核、确认等流程操作。
+- 后端API：提供获取详情、更新、提交、审核、确认等接口，并在权限控制下限制操作范围。
+- 服务层：负责业务逻辑，包括加权得分计算、状态流转、批量创建等。
+- 数据模型：定义考核记录、明细、指标、状态与类型枚举，以及外键关系。
+- 安全模块：提供JWT解析、当前用户获取、管理员/经理权限校验。
+
+章节来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L98-L218)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L145)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L205)
+- [models.py](file://backend/app/models/models.py#L45-L61)
+- [security.py](file://backend/app/core/security.py#L85-L110)
+
+## 架构总览
+详情查看流程由前端发起请求，后端API接收并调用服务层，服务层读取数据库模型并返回数据，前端渲染详情卡片与明细表格，支持在草稿态编辑与提交审核。
+
+```mermaid
+sequenceDiagram
+participant U as "用户"
+participant FE as "前端详情页面"
+participant API as "后端API"
+participant SVC as "服务层"
+participant DB as "数据库模型"
+U->>FE : 打开考核详情
+FE->>API : GET /assessments/{id}
+API->>SVC : get_by_id(assessment_id)
+SVC->>DB : 查询Assessment+Staff+Details+Indicator
+DB-->>SVC : 返回实体
+SVC-->>API : AssessmentResponse
+API-->>FE : JSON数据
+FE->>FE : 渲染基本信息与明细
+FE->>API : 草稿态保存/提交/审核/确认
+API->>SVC : update/submit/review/finalize
+SVC->>DB : 更新状态与分数
+DB-->>SVC : 提交事务
+SVC-->>API : 成功
+API-->>FE : 返回结果
+```
+
+图表来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L150-L217)
+- [assessment.js](file://frontend/src/api/assessment.js#L9-L36)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L145)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L205)
+- [models.py](file://backend/app/models/models.py#L149-L203)
+
+## 详细组件分析
+
+### 前端详情视图（AssessmentDetail.vue）
+- 基本信息卡片：显示员工姓名、科室、考核周期与加权总分，状态以标签形式展示。
+- 考核明细表格：展示指标名称、类型、权重、最高分、实际值、得分、佐证材料；草稿态支持输入编辑，其他状态只读并按得分分级显示颜色。
+- 操作按钮：根据状态显示保存、提交、审核通过/驳回、确认等按钮，点击后调用对应API。
+
+```mermaid
+flowchart TD
+Start(["进入详情页面"]) --> Load["加载考核详情"]
+Load --> Render["渲染基本信息与明细"]
+Render --> EditCheck{"是否草稿态？"}
+EditCheck --> |是| Edit["可编辑输入实际值/得分/佐证材料"]
+EditCheck --> |否| View["只读显示"]
+Edit --> Save["保存草稿"]
+Edit --> Submit["提交审核"]
+View --> Review["审核通过/驳回"]
+View --> Finalize["确认考核"]
+Save --> Reload["重新加载数据"]
+Submit --> Reload
+Review --> Reload
+Finalize --> Reload
+Reload --> End(["完成"])
+```
+
+图表来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L150-L217)
+
+章节来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+
+### 后端API与服务层（assessments.py、assessment_service.py）
+- 获取详情：API层调用服务层按ID查询，返回带员工与科室名称、明细含指标名称的结构化数据。
+- 加权得分计算：服务层在创建/更新时，遍历明细，按指标权重累加计算 weighted_score。
+- 状态流转：提交、审核、确认分别更新状态与时间戳，仅允许在合法状态下变更。
+- 批量创建：为指定科室批量生成考核记录与明细，避免重复。
+
+```mermaid
+classDiagram
+class Assessment {
+int id
+int staff_id
+int period_year
+int period_month
+string period_type
+float total_score
+float weighted_score
+string 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 Indicator {
+int id
+string name
+string code
+string indicator_type
+float weight
+float max_score
+}
+Assessment "1" o-- "*" AssessmentDetail : "明细"
+AssessmentDetail "1" --> "1" Indicator : "指标"
+```
+
+图表来源
+- [models.py](file://backend/app/models/models.py#L149-L203)
+
+章节来源
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L77)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L70-L156)
+- [models.py](file://backend/app/models/models.py#L149-L203)
+
+### 数据模型与字段说明
+- 考核记录表（assessments）：包含员工ID、考核周期、总分、加权得分、状态、时间戳与备注。
+- 考核明细表（assessment_details）：包含指标ID、实际值、得分、佐证材料与备注。
+- 指标表（indicators）：包含指标名称、编码、类型、权重、最高分、目标值等。
+- 状态枚举：草稿、已提交、已审核、已确认、已驳回。
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L45-L61)
+- [models.py](file://backend/app/models/models.py#L149-L203)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L87-L131)
+
+### 权限控制与数据安全
+- 当前用户获取：通过JWT令牌解析当前用户，校验激活状态。
+- 管理员/经理权限：审核与确认接口要求管理员或经理角色。
+- 列表与详情：详情接口对当前用户可见性进行校验，防止越权访问。
+
+章节来源
+- [security.py](file://backend/app/core/security.py#L55-L110)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
+
+## 依赖关系分析
+- 前端依赖后端API，通过HTTP请求获取数据并提交操作。
+- 后端API依赖服务层，服务层依赖SQLAlchemy ORM与数据库模型。
+- 安全中间件贯穿API层，确保敏感操作受控。
+
+```mermaid
+graph LR
+FE["前端"] --> API["后端API"]
+API --> SVC["服务层"]
+SVC --> MODELS["数据模型"]
+API --> SEC["安全中间件"]
+```
+
+图表来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L102-L102)
+- [assessment.js](file://frontend/src/api/assessment.js#L9-L36)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L145)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L58-L68)
+- [models.py](file://backend/app/models/models.py#L149-L203)
+- [security.py](file://backend/app/core/security.py#L55-L110)
+
+章节来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [assessment.js](file://frontend/src/api/assessment.js#L1-L50)
+- [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#L1-L438)
+- [security.py](file://backend/app/core/security.py#L1-L110)
+
+## 性能考虑
+- 查询优化：详情查询使用selectinload预加载关联对象，减少N+1查询。
+- 分页与过滤：列表接口支持按科室、周期、状态分页查询，避免一次性加载过多数据。
+- 缓存策略：可在高频读取场景引入Redis缓存，降低数据库压力。
+- 前端渲染：明细表格按需渲染，草稿态编辑采用双向绑定，减少不必要的重绘。
+
+章节来源
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L28-L55)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L20-L52)
+
+## 故障排查指南
+- 404未找到：详情接口若返回不存在，检查assessment_id是否正确。
+- 状态不允许：更新、提交、审核、确认仅在特定状态允许，检查当前状态与流程。
+- 权限不足：审核与确认接口需要管理员或经理权限，检查用户角色。
+- 数据异常：加权得分异常时，检查指标权重与明细得分是否匹配。
+
+章节来源
+- [assessments.py](file://backend/app/api/v1/assessments.py#L63-L64)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
+- [security.py](file://backend/app/core/security.py#L94-L109)
+
+## 结论
+“考核详情查看”功能通过前后端协作，实现了从数据到界面的完整闭环：前端负责展示与交互，后端负责数据与流程控制，服务层承担计算与状态管理，安全模块提供权限保障。加权得分计算清晰、权重配置灵活、状态流转可控，满足医院绩效管理的精细化需求。
+
+## 附录
+
+### 考核详情展示格式
+- 基本信息
+  - 姓名、科室、考核周期、加权总分
+- 考核明细
+  - 指标名称、指标类型、权重、最高分、实际值、得分、佐证材料
+- 状态标签与操作按钮
+  - 草稿态：保存、提交
+  - 已提交：审核通过、驳回
+  - 已审核：确认
+  - 已确认：不可编辑
+
+章节来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L18-L93)
+
+### 加权得分计算公式与权重配置
+- 加权得分（weighted_score）= Σ(指标得分 × 指标权重)
+- 权重来源于指标表（indicators.weight），创建/更新时由服务层遍历明细累加计算
+- 最高分（max_score）用于前端输入校验与显示
+
+章节来源
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L76-L84)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L140-L146)
+- [models.py](file://backend/app/models/models.py#L126-L127)
+
+### 分数等级划分
+- 优秀：≥90分
+- 良好：80-89分
+- 一般：60-79分
+- 较差：<60分
+
+章节来源
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L139-L144)
+
+### 数据来源与更新机制
+- 数据来源：指标库（indicators）、考核记录（assessments）、明细（assessment_details）
+- 更新机制：草稿态可编辑并保存；提交后进入审核流程；审核通过进入确认；最终确认后不可再编辑
+
+章节来源
+- [models.py](file://backend/app/models/models.py#L149-L203)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L158-L205)
+
+### 权限控制与数据安全
+- 认证：JWT令牌解析与当前用户校验
+- 授权：管理员/经理角色才能审核与确认
+- 可见性：详情接口对当前用户可见性进行校验
+
+章节来源
+- [security.py](file://backend/app/core/security.py#L55-L110)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L118-L145)
+
+### 相关接口与数据模型对照
+- 获取详情：GET /assessments/{id}
+- 更新详情：PUT /assessments/{id}
+- 提交：POST /assessments/{id}/submit
+- 审核：POST /assessments/{id}/review
+- 确认：POST /assessments/{id}/finalize
+- 批量创建：POST /assessments/batch-create
+
+章节来源
+- [assessment.js](file://frontend/src/api/assessment.js#L9-L49)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L55-L165)