提交文件

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,470 @@
+# 考核明细模型
+
+<cite>
+**本文档引用的文件**
+- [models.py](file://backend/app/models/models.py)
+- [assessment_service.py](file://backend/app/services/assessment_service.py)
+- [assessments.py](file://backend/app/api/v1/assessments.py)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue)
+- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue)
+- [assessment.js](file://frontend/src/api/assessment.js)
+- [schemas.py](file://backend/app/schemas/schemas.py)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概览](#架构概览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+
+考核明细模型是医院绩效考核管理系统的核心数据结构，负责记录每个考核周期内员工各项指标的具体表现和得分情况。该模型实现了完整的考核数据管理功能，包括实际值记录、得分计算、佐证材料管理和多对一关系约束。
+
+本系统采用现代化的技术栈，后端基于FastAPI和SQLAlchemy 2.0异步ORM，前端使用Vue 3 Composition API和Element Plus组件库，实现了完整的绩效考核流程管理。
+
+## 项目结构
+
+系统采用分层架构设计，主要包含以下层次：
+
+```mermaid
+graph TB
+subgraph "前端层"
+FE1[Assessments.vue<br/>考核列表页面]
+FE2[AssessmentDetail.vue<br/>考核详情页面]
+FE3[assessment.js<br/>API请求封装]
+end
+subgraph "后端层"
+BE1[assessments.py<br/>API路由]
+BE2[assessment_service.py<br/>业务服务层]
+BE3[schemas.py<br/>数据模式定义]
+end
+subgraph "数据层"
+DB1[models.py<br/>数据模型]
+DB2[001_initial.py<br/>数据库迁移]
+end
+FE1 --> FE3
+FE2 --> FE3
+FE3 --> BE1
+BE1 --> BE2
+BE2 --> BE3
+BE3 --> DB1
+DB1 --> DB2
+```
+
+**图表来源**
+- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [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#L181-L203)
+
+**章节来源**
+- [Assessments.vue](file://frontend/src/views/assessment/Assessments.vue#L1-L311)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L1-L257)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+
+## 核心组件
+
+### AssessmentDetail模型设计
+
+AssessmentDetail模型是考核明细的核心数据结构，具有以下关键特性：
+
+**数据字段设计**：
+- `assessment_id`: 考核记录ID（外键关联）
+- `indicator_id`: 指标ID（外键关联）
+- `actual_value`: 实际值（数值型，支持小数）
+- `score`: 得分（数值型，默认0）
+- `evidence`: 佐证材料（文本型）
+- `remark`: 备注（文本型）
+
+**关系映射**：
+- 与Assessment模型建立多对一关系
+- 与Indicator模型建立多对一关系
+- 支持级联删除和级联刷新
+
+**索引优化**：
+- 为assessment_id和indicator_id建立复合索引
+- 提升查询性能和数据完整性
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L181-L203)
+- [001_initial.py](file://backend/alembic/versions/001_initial.py#L114-L132)
+
+### 考核流程集成
+
+系统实现了完整的考核流程，AssessmentDetail模型在整个流程中发挥关键作用：
+
+```mermaid
+sequenceDiagram
+participant User as 用户
+participant Frontend as 前端界面
+participant API as API接口
+participant Service as 服务层
+participant DB as 数据库
+User->>Frontend : 输入实际值和得分
+Frontend->>API : 提交更新请求
+API->>Service : 调用更新方法
+Service->>DB : 更新AssessmentDetail记录
+DB-->>Service : 返回更新结果
+Service->>DB : 计算总分和加权得分
+DB-->>Service : 返回计算结果
+Service-->>API : 返回更新后的考核记录
+API-->>Frontend : 显示更新结果
+Frontend-->>User : 展示最新的考核明细
+```
+
+**图表来源**
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
+
+**章节来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L160-L175)
+
+## 架构概览
+
+系统采用MVC架构模式，AssessmentDetail模型位于数据访问层，向上提供业务服务，向下连接数据库存储。
+
+```mermaid
+graph TB
+subgraph "表现层"
+UI1[Assessments.vue<br/>列表展示]
+UI2[AssessmentDetail.vue<br/>详情编辑]
+end
+subgraph "控制器层"
+API1[assessments.py<br/>路由处理]
+API2[authentication<br/>权限控制]
+end
+subgraph "业务逻辑层"
+SVC1[AssessmentService<br/>考核业务处理]
+SVC2[IndicatorService<br/>指标业务处理]
+end
+subgraph "数据访问层"
+MODEL1[Assessment模型]
+MODEL2[AssessmentDetail模型]
+MODEL3[Indicator模型]
+MODEL4[Staff模型]
+end
+subgraph "数据存储"
+DB1[PostgreSQL数据库]
+DB2[SQLAlchemy ORM]
+end
+UI1 --> API1
+UI2 --> API1
+API1 --> SVC1
+API1 --> SVC2
+SVC1 --> MODEL1
+SVC1 --> MODEL2
+SVC2 --> MODEL3
+MODEL1 --> DB2
+MODEL2 --> DB2
+MODEL3 --> DB2
+MODEL4 --> DB2
+DB2 --> DB1
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L149-L203)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L14-L263)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L166)
+
+## 详细组件分析
+
+### AssessmentDetail模型类图
+
+```mermaid
+classDiagram
+class AssessmentDetail {
+int id
+int assessment_id
+int indicator_id
+float actual_value
+float score
+string evidence
+string remark
+datetime created_at
+datetime updated_at
+assessment Assessment
+indicator Indicator
+}
+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
+datetime created_at
+datetime updated_at
+details AssessmentDetail[]
+}
+class Indicator {
+int id
+string name
+string code
+string indicator_type
+float weight
+float max_score
+float target_value
+string target_unit
+string calculation_method
+string assessment_method
+string deduction_standard
+string data_source
+bool is_veto
+bool is_active
+details AssessmentDetail[]
+}
+AssessmentDetail --> Assessment : "多对一"
+AssessmentDetail --> Indicator : "多对一"
+Assessment "1" --> "*" AssessmentDetail : "一对多"
+Indicator "1" --> "*" AssessmentDetail : "一对多"
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L149-L203)
+
+### 数据完整性约束
+
+系统通过多种机制确保数据完整性：
+
+**数据库层面约束**：
+- 主键约束：确保每条明细记录的唯一性
+- 外键约束：维护Assessment和Indicator的引用完整性
+- 检查约束：限制权重值必须大于0
+- 索引优化：提升查询性能
+
+**业务层面约束**：
+- 状态机控制：严格的流程状态转换
+- 权限控制：不同角色的操作权限
+- 数据验证：输入数据的格式和范围检查
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L144-L146)
+- [models.py](file://backend/app/models/models.py#L199-L202)
+
+### 得分计算算法
+
+系统实现了灵活的得分计算机制：
+
+```mermaid
+flowchart TD
+Start([开始计算]) --> LoadDetails["加载考核明细"]
+LoadDetails --> CalcTotal["计算总分<br/>sum(score)"]
+CalcTotal --> CalcWeighted["计算加权得分<br/>sum(score × indicator.weight)"]
+CalcWeighted --> ValidateRange["验证分数范围<br/>0 ≤ score ≤ max_score"]
+ValidateRange --> CheckVeto{"检查一票否决"}
+CheckVeto --> |是| ApplyVeto["应用一票否决规则"]
+CheckVeto --> |否| CheckExceptions["检查异常值"]
+CheckVeto --> UpdateAssessment["更新考核记录"]
+ApplyVeto --> UpdateAssessment
+CheckExceptions --> UpdateAssessment
+UpdateAssessment --> End([计算完成])
+```
+
+**图表来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L74-L84)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L129-L149)
+
+**章节来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L71-L108)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L111-L156)
+
+### 佐证材料管理
+
+系统提供了完整的佐证材料管理功能：
+
+**存储机制**：
+- 佐证材料以文本形式存储
+- 支持URL链接和文件路径
+- 可扩展为文件上传功能
+
+**使用场景**：
+- 质量指标的证明材料
+- 数量指标的数据支撑
+- 效率指标的计算依据
+- 服务指标的客户反馈
+
+**章节来源**
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L71-L82)
+- [models.py](file://backend/app/models/models.py#L190-L190)
+
+### 时间戳跟踪机制
+
+系统实现了全面的时间戳跟踪：
+
+**创建时间**：记录AssessmentDetail的创建时刻
+**更新时间**：自动更新记录的修改时间
+**流程时间**：记录考核流程各阶段的时间戳
+
+```mermaid
+stateDiagram-v2
+[*] --> 草稿
+草稿 --> 已提交 : 提交审核
+已提交 --> 已审核 : 审核通过
+已提交 --> 已驳回 : 审核驳回
+已审核 --> 已确认 : 确认考核
+已确认 --> [*]
+state 已提交 {
+[*] --> 提交时间记录
+}
+state 已审核 {
+[*] --> 审核时间记录
+}
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L163-L164)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L170)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L163-L167)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L159-L192)
+
+## 依赖关系分析
+
+系统各组件之间的依赖关系如下：
+
+```mermaid
+graph LR
+subgraph "外部依赖"
+A[FastAPI]
+B[SQLAlchemy 2.0]
+C[PostgreSQL]
+D[Vue 3]
+E[Element Plus]
+end
+subgraph "内部模块"
+F[models.py]
+G[assessment_service.py]
+H[assessments.py]
+I[schemas.py]
+J[AssessmentDetail.vue]
+K[Assessments.vue]
+end
+A --> H
+H --> G
+G --> F
+F --> C
+B --> F
+D --> J
+D --> K
+E --> J
+E --> K
+J --> I
+K --> I
+```
+
+**图表来源**
+- [models.py](file://backend/app/models/models.py#L1-L13)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
+- [assessments.py](file://backend/app/api/v1/assessments.py#L1-L16)
+
+**章节来源**
+- [models.py](file://backend/app/models/models.py#L1-L13)
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L1-L12)
+
+## 性能考虑
+
+### 查询优化策略
+
+**索引设计**：
+- 为assessment_id和indicator_id建立复合索引
+- 为常用查询条件建立单独索引
+- 使用覆盖索引减少查询开销
+
+**查询优化**：
+- 使用selectinload进行关联查询
+- 避免N+1查询问题
+- 实施分页查询机制
+
+### 缓存策略
+
+**数据缓存**：
+- 指标配置信息缓存
+- 员工基本信息缓存
+- 科室层级结构缓存
+
+**查询结果缓存**：
+- 统计报表结果缓存
+- 常用查询结果缓存
+- 配置信息缓存
+
+## 故障排除指南
+
+### 常见问题及解决方案
+
+**数据同步问题**：
+- 确保Assessment和AssessmentDetail的事务一致性
+- 检查外键约束是否正确设置
+- 验证数据类型和精度匹配
+
+**性能问题**：
+- 分析慢查询日志
+- 检查索引使用情况
+- 优化复杂查询语句
+
+**权限问题**：
+- 验证用户角色和权限
+- 检查API访问控制
+- 确认数据访问范围
+
+**章节来源**
+- [assessment_service.py](file://backend/app/services/assessment_service.py#L117-L118)
+- [models.py](file://backend/app/models/models.py#L199-L202)
+
+## 结论
+
+考核明细模型作为医院绩效考核管理系统的核心组件，实现了完整的数据管理功能。通过合理的数据结构设计、严格的数据完整性约束和高效的性能优化策略，系统能够满足医院复杂的绩效考核需求。
+
+该模型不仅支持基本的考核数据记录，还提供了灵活的扩展能力，可以适应不同科室和岗位的考核要求。同时，系统的权限控制和审计功能确保了数据的安全性和可追溯性。
+
+## 附录
+
+### 数据录入示例
+
+**单个明细录入**：
+1. 选择考核周期（年、月）
+2. 选择员工和指标
+3. 录入实际值和得分
+4. 添加佐证材料
+5. 保存并提交审核
+
+**批量处理方法**：
+1. 通过批量创建功能生成默认明细
+2. 批量导入实际值数据
+3. 统一审核和确认流程
+4. 生成批量统计报告
+
+### 数据质量保证措施
+
+**数据验证规则**：
+- 分数范围验证（0-max_score）
+- 权重有效性检查
+- 指标类型匹配验证
+- 时间范围合理性检查
+
+**异常值处理**：
+- 设置合理的阈值范围
+- 异常值标记和提醒
+- 自动化异常检测机制
+- 人工复核流程
+
+**章节来源**
+- [schemas.py](file://backend/app/schemas/schemas.py#L196-L218)
+- [AssessmentDetail.vue](file://frontend/src/views/assessment/AssessmentDetail.vue#L47-L68)