提交文件

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,332 @@
+# 考核数据分析
+
+<cite>
+**本文档引用的文件**
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py)
+- [backend/app/models/models.py](file://backend/app/models/models.py)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue)
+- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py)
+- [docs/详细设计文档.md](file://docs/详细设计文档.md)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向医院绩效系统的“考核数据分析”功能，系统性阐述基于考核数据的统计分析能力，涵盖按科室、按人员、按时间段的绩效统计；BSC四个维度的分析方法、趋势分析与排名统计；数据聚合算法、图表展示与报表生成机制；以及分析指标、计算公式与可视化方案，并给出数据准确性保证与性能优化策略。
+
+## 项目结构
+后端采用 FastAPI + SQLAlchemy 异步 ORM 架构，前端使用 Vue3 + Element Plus + ECharts。统计分析功能由 API 层、服务层与数据模型层协同完成，前端通过统一的统计接口进行数据拉取与可视化渲染。
+
+```mermaid
+graph TB
+FE["前端视图<br/>Reports.vue / Dashboard.vue"] --> API["FastAPI 统计接口<br/>stats.py"]
+API --> SVC["统计服务层<br/>stats_service.py"]
+SVC --> DB["数据库模型<br/>models.py"]
+DB --> SQL["SQLAlchemy 异步查询"]
+FE --> FE_API["前端统计接口封装<br/>stats.js"]
+```
+
+图表来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+
+## 核心组件
+- 统计 API：提供 BSC 维度分析、科室统计、趋势分析、排名、指标完成度等接口。
+- 统计服务：封装 SQL 聚合逻辑，负责按条件过滤、分组统计与排序。
+- 数据模型：定义 Assessment、AssessmentDetail、Indicator、Department、Staff 等实体及其关系。
+- 前端视图：集成 ECharts 进行图表渲染，提供周期选择、联动查询与可视化展示。
+- 指标模板：内置多种科室类型的 BSC 指标模板，支撑不同维度权重与评分方法。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L203)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L112-L309)
+- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L24-L186)
+
+## 架构总览
+统计分析采用“接口-服务-模型-数据库”的分层架构，前端通过统一接口获取数据并渲染图表，后端通过异步查询与聚合函数实现高性能统计。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端视图"
+participant API as "统计接口(stats.py)"
+participant SVC as "统计服务(stats_service.py)"
+participant DB as "数据库模型(models.py)"
+FE->>API : GET /stats/bsc-dimension
+API->>SVC : get_bsc_dimension_stats(...)
+SVC->>DB : 异步查询 + 聚合(group_by)
+DB-->>SVC : 维度统计结果
+SVC-->>API : 维度得分/权重/指标数
+API-->>FE : JSON 响应
+FE->>API : GET /stats/department
+API->>SVC : get_department_stats(...)
+SVC->>DB : 异步查询 + 汇总(group_by)
+DB-->>SVC : 科室统计结果
+SVC-->>API : 排序后的科室列表
+API-->>FE : JSON 响应
+```
+
+图表来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L125)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L146)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+
+## 详细组件分析
+
+### BSC 维度分析
+- 功能概述：按财务、客户、内部流程、学习成长四个维度统计得分、权重与指标数量，并计算平均得分。
+- 数据来源：Assessment、AssessmentDetail、Indicator、Staff。
+- 过滤条件：支持按年度、月份与科室过滤；仅统计已确认状态的考核记录。
+- 聚合逻辑：按维度 group_by，计算维度总分（指标得分×权重求和）、总权重、指标数量，并推导平均得分。
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> BuildCond["构建查询条件<br/>状态=FINALIZED + 年/月/科室过滤"]
+BuildCond --> Query["SQL 聚合查询<br/>按维度分组"]
+Query --> Group["按维度汇总<br/>总分/权重/指标数"]
+Group --> CalcAvg["计算平均得分=总分/权重"]
+CalcAvg --> Return["返回维度统计结果"]
+```
+
+图表来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L33)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+
+### 科室绩效统计
+- 功能概述：按科室汇总员工得分，计算科室平均分、最高分、最低分、员工列表，并按平均分降序排序。
+- 数据来源：Assessment、Staff、Department。
+- 聚合逻辑：先按科室分组统计员工数与总分，再计算平均分，最后按平均分排序。
+
+```mermaid
+flowchart TD
+S(["开始"]) --> Filter["过滤已确认考核记录<br/>按年/月过滤"]
+Filter --> Join["连接 Staff/Department"]
+Join --> GroupByDept["按科室分组统计<br/>员工数/总分/员工列表"]
+GroupByDept --> ComputeAvg["计算平均分=总分/员工数"]
+ComputeAvg --> Sort["按平均分降序排序"]
+Sort --> Output["输出科室统计列表"]
+```
+
+图表来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L110)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L36-L49)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)
+
+### 趋势分析（月度）
+- 功能概述：按月统计平均得分与加权得分，支持跨年份的最近 N 个月趋势。
+- 数据来源：Assessment。
+- 聚合逻辑：按月分组，计算平均分与样本数，按月升序排列。
+
+```mermaid
+flowchart TD
+TStart(["开始"]) --> YearFilter["按年/月过滤<br/>或使用当前年份"]
+YearFilter --> MonthRange["计算起止月份<br/>支持跨年"]
+MonthRange --> GroupMonth["按月分组统计<br/>平均分/样本数"]
+GroupMonth --> Order["按月升序排列"]
+Order --> TOut["返回月度趋势数据"]
+```
+
+图表来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L148-L199)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L52-L70)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L148-L199)
+
+### 绩效排名（科室/员工）
+- 员工排名：按加权得分降序取前 N 名，附带排名序号。
+- 科室排名：基于科室平均分降序取前 N 名。
+- 数据来源：Assessment、Staff、Department。
+
+```mermaid
+sequenceDiagram
+participant FE as "前端"
+participant API as "统计接口"
+participant SVC as "统计服务"
+participant DB as "数据库"
+FE->>API : GET /stats/ranking?limit=N
+API->>SVC : get_ranking_stats(...)
+SVC->>DB : 查询已确认考核记录并排序
+DB-->>SVC : 员工排名结果
+SVC-->>API : 带排名序号的列表
+API-->>FE : JSON 响应
+```
+
+图表来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L186-L207)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L210-L224)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)
+
+### 指标完成度统计
+- 功能概述：按指标统计平均分、最大/最小分、完成率（平均分/目标值×100），并限制完成率上限为 100%。
+- 数据来源：AssessmentDetail、Indicator。
+- 聚合逻辑：按指标分组统计，计算完成率并返回指标列表。
+
+```mermaid
+flowchart TD
+CStart(["开始"]) --> CFilter["过滤已确认考核记录<br/>可按年/月/指标过滤"]
+CFilter --> CGroup["按指标分组统计<br/>平均分/最大分/最小分/样本数"]
+CGroup --> CRate["计算完成率=平均分/目标值×100<br/>上限100%"]
+CRate --> COut["返回指标完成度列表"]
+```
+
+图表来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L227-L241)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
+
+### 前端可视化与报表生成
+- 报表视图 Reports.vue：周期统计概览、科室对比柱状图、绩效分布饼图、科室统计表格、员工排名表格。
+- 仪表盘 Dashboard.vue：趋势折线、科室排名条形图、财务趋势、KPI 仪表盘、预警数据。
+- ECharts 渲染：支持响应式布局与动态刷新，图表联动查询。
+
+```mermaid
+graph TB
+subgraph "前端视图"
+R["Reports.vue<br/>周期统计/科室对比/排名"]
+D["Dashboard.vue<br/>趋势/KPI/预警"]
+end
+subgraph "接口封装"
+FA["stats.js<br/>getDepartmentStats/getTrendData/..."]
+end
+R --> FA
+D --> FA
+```
+
+图表来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L112-L309)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+
+章节来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+
+## 依赖关系分析
+- 统计接口依赖统计服务，统计服务依赖数据模型与 SQLAlchemy 异步查询。
+- 前端视图依赖接口封装，接口封装依赖后端统计接口。
+- 指标模板提供维度权重与评分方法，支撑 BSC 维度分析与指标完成度计算。
+
+```mermaid
+graph LR
+API["stats.py"] --> SVC["stats_service.py"]
+SVC --> MODELS["models.py"]
+FE_VIEWS["Reports.vue / Dashboard.vue"] --> FE_API["stats.js"]
+FE_API --> API
+MODELS --> INIT_TPL["init_templates.py"]
+```
+
+图表来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L1-L242)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L1-L438)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L225-L819)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L1-L276)
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L203)
+- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L24-L186)
+
+## 性能考虑
+- 异步查询：使用 SQLAlchemy 异步引擎与会话，减少阻塞，提升并发处理能力。
+- 索引优化：模型中为常用查询字段建立索引（如 staff/dept/status/period），降低查询成本。
+- 聚合优化：在服务层使用 SQL 聚合函数（sum/count/avg/group_by）一次性完成统计，避免多次往返。
+- 分页与限制：前端接口支持分页与数量限制，避免一次性传输大量数据。
+- 缓存策略：对于静态模板与权重配置可在应用启动时缓存，减少重复读取。
+- 数据分区：历史数据可按年/月分区存储，便于趋势分析与归档清理。
+
+## 故障排除指南
+- 接口返回空数据
+  - 检查过滤条件（年/月/科室）是否正确，确认存在已确认状态的考核记录。
+  - 确认前端传参格式与范围（如月份 1-12）。
+- 统计结果异常
+  - 核对指标权重与目标值是否配置正确，确保完成率计算逻辑生效。
+  - 检查是否存在一票否决指标导致得分异常。
+- 图表渲染问题
+  - 确认 ECharts 初始化与容器尺寸，监听窗口 resize 事件。
+  - 检查数据结构与键名一致性（如 avg_score、total_bonus）。
+
+章节来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L173-L295)
+
+## 结论
+本系统围绕 BSC 四维度与 KPI 指标，提供了完整的统计分析能力：按科室与人员的绩效统计、趋势分析与排名、指标完成度与可视化展示。通过异步查询与聚合优化，保障了性能与准确性；通过前端 ECharts 的丰富图表，提升了数据洞察力。建议后续进一步完善预警机制与报表导出功能，持续优化数据质量与用户体验。
+
+## 附录
+
+### 分析指标与计算公式
+- BSC 维度得分
+  - 维度总分 = Σ(指标得分 × 指标权重)
+  - 维度平均分 = 维度总分 / 维度总权重
+- 科室平均分
+  - 科室平均分 = 科室总分 / 科室员工数
+- 指标完成度
+  - 完成率 = min(平均分 / 目标值 × 100%, 100%)
+
+章节来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L246-L299)
+- [docs/详细设计文档.md](file://docs/详细设计文档.md#L312-L401)
+
+### 可视化展示方案
+- 科室对比柱状图：X 轴科室名称，Y 轴平均得分与右侧奖金折线。
+- 绩效分布饼图：按等级划分（优秀/良好/合格/不合格）。
+- 趋势折线图：月度平均得分与样本数。
+- KPI 仪表盘：床位使用率、药占比、材料占比、患者满意度等关键指标。
+
+章节来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L183-L295)
+- [frontend/src/views/Dashboard.vue](file://frontend/src/views/Dashboard.vue#L741-L807)
+
+### 数据准确性保证
+- 状态约束：仅统计已确认状态的考核记录，避免草稿/审核阶段数据干扰。
+- 权重与目标值校验：模板初始化时写入权重与目标值，确保计算一致性。
+- 一票否决：对严重质量与安全指标设置否决标记，确保结果真实可靠。
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L149-L203)
+- [backend/app/scripts/init_templates.py](file://backend/app/scripts/init_templates.py#L24-L78)