# 考核数据分析
**本文档引用的文件**
- [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)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向医院绩效系统的“考核数据分析”功能，系统性阐述基于考核数据的统计分析能力，涵盖按科室、按人员、按时间段的绩效统计；BSC四个维度的分析方法、趋势分析与排名统计；数据聚合算法、图表展示与报表生成机制；以及分析指标、计算公式与可视化方案，并给出数据准确性保证与性能优化策略。
## 项目结构
后端采用 FastAPI + SQLAlchemy 异步 ORM 架构，前端使用 Vue3 + Element Plus + ECharts。统计分析功能由 API 层、服务层与数据模型层协同完成，前端通过统一的统计接口进行数据拉取与可视化渲染。
```mermaid
graph TB
FE["前端视图
Reports.vue / Dashboard.vue"] --> API["FastAPI 统计接口
stats.py"]
API --> SVC["统计服务层
stats_service.py"]
SVC --> DB["数据库模型
models.py"]
DB --> SQL["SQLAlchemy 异步查询"]
FE --> FE_API["前端统计接口封装
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["构建查询条件
状态=FINALIZED + 年/月/科室过滤"]
BuildCond --> Query["SQL 聚合查询
按维度分组"]
Query --> Group["按维度汇总
总分/权重/指标数"]
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["过滤已确认考核记录
按年/月过滤"]
Filter --> Join["连接 Staff/Department"]
Join --> GroupByDept["按科室分组统计
员工数/总分/员工列表"]
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["按年/月过滤
或使用当前年份"]
YearFilter --> MonthRange["计算起止月份
支持跨年"]
MonthRange --> GroupMonth["按月分组统计
平均分/样本数"]
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["过滤已确认考核记录
可按年/月/指标过滤"]
CFilter --> CGroup["按指标分组统计
平均分/最大分/最小分/样本数"]
CGroup --> CRate["计算完成率=平均分/目标值×100
上限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
周期统计/科室对比/排名"]
D["Dashboard.vue
趋势/KPI/预警"]
end
subgraph "接口封装"
FA["stats.js
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)