提交文件
This commit is contained in:
387
.qoder/repowiki/zh/content/核心功能模块/数据分析报表.md
Normal file
387
.qoder/repowiki/zh/content/核心功能模块/数据分析报表.md
Normal file
@@ -0,0 +1,387 @@
|
||||
# 数据分析报表
|
||||
|
||||
<cite>
|
||||
**本文引用的文件**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py)
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue)
|
||||
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js)
|
||||
- [数据模型 models.py](file://backend/app/models/models.py)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py)
|
||||
- [API路由器 __init__.py](file://backend/app/api/v1/__init__.py)
|
||||
- [数据库设计文档 database.md](file://docs/database.md)
|
||||
- [初始化指标模板 init_templates.py](file://backend/app/scripts/init_templates.py)
|
||||
- [初始化指标模板脚本 init_indicator_templates.py](file://backend/init_indicator_templates.py)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构总览](#架构总览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排查指南](#故障排查指南)
|
||||
9. [结论](#结论)
|
||||
10. [附录](#附录)
|
||||
|
||||
## 简介
|
||||
本文件面向“医院绩效系统”的数据分析报表模块，系统化阐述BSC维度分析、科室绩效统计、趋势分析、绩效排名、指标完成度等核心功能。文档覆盖数据聚合算法、图表展示组件、报表生成机制、多维度统计分析、数据可视化与导出能力，并解释数据更新机制、缓存策略与性能优化方案。同时提供分析指标定义、计算方法与展示样式说明，帮助开发者与运维人员快速理解并扩展系统能力。
|
||||
|
||||
## 项目结构
|
||||
报表模块由后端FastAPI接口、SQLAlchemy异步ORM服务层、前端Vue组件与ECharts图表构成，遵循前后端分离与职责清晰的设计原则。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "前端"
|
||||
FE_Report["Reports.vue<br/>报表页面"]
|
||||
FE_API["stats.js<br/>API封装"]
|
||||
end
|
||||
subgraph "后端"
|
||||
BE_Router["API路由器<br/>__init__.py"]
|
||||
BE_StatsAPI["统计API<br/>stats.py"]
|
||||
BE_Service["统计服务<br/>stats_service.py"]
|
||||
BE_Models["数据模型<br/>models.py"]
|
||||
BE_DB["数据库连接<br/>database.py"]
|
||||
end
|
||||
FE_Report --> FE_API
|
||||
FE_API --> BE_Router
|
||||
BE_Router --> BE_StatsAPI
|
||||
BE_StatsAPI --> BE_Service
|
||||
BE_Service --> BE_Models
|
||||
BE_Service --> BE_DB
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [API路由器 __init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
|
||||
- [数据模型 models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
|
||||
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
|
||||
|
||||
**章节来源**
|
||||
- [API路由器 __init__.py](file://backend/app/api/v1/__init__.py#L1-L17)
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
|
||||
- [数据模型 models.py](file://backend/app/models/models.py#L1-L438)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
|
||||
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
|
||||
|
||||
## 核心组件
|
||||
- 统计API接口：提供BSC维度分析、科室绩效统计、趋势分析、绩效排名、指标完成度、周期统计、关键指标仪表盘、收支趋势等接口。
|
||||
- 统计服务层：封装复杂聚合逻辑，负责SQL查询、分组统计、跨表联接与结果组装。
|
||||
- 数据模型：定义科室、员工、指标、考核、明细、工资等实体及其关系。
|
||||
- 前端报表页面：集成ECharts图表，支持多视图联动与交互式筛选。
|
||||
- 数据库连接：异步SQLAlchemy引擎与会话管理，确保并发安全与事务一致性。
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L17-L242)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L16-L300)
|
||||
- [数据模型 models.py](file://backend/app/models/models.py#L62-L231)
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
|
||||
|
||||
## 架构总览
|
||||
后端采用FastAPI + SQLAlchemy异步ORM，前端使用Vue + ECharts，通过REST接口进行数据交互。统计服务层对多表进行联接与聚合，输出标准化数据结构供前端渲染。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant FE as "前端报表页面"
|
||||
participant API as "统计API(stats.py)"
|
||||
participant SVC as "统计服务(stats_service.py)"
|
||||
participant DB as "数据库连接(database.py)"
|
||||
FE->>API : GET /stats/department?year&month
|
||||
API->>SVC : get_department_stats(db, year, month)
|
||||
SVC->>DB : 异步SQL查询(联接 : departments/staff/assessments)
|
||||
DB-->>SVC : 聚合结果集
|
||||
SVC-->>API : 标准化科室统计列表
|
||||
API-->>FE : JSON响应(data : 列表)
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L36-L49)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L28-L39)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### BSC维度分析
|
||||
- 功能说明：按财务、客户、内部流程、学习成长四个维度统计得分、权重、指标数量与平均分。
|
||||
- 数据聚合算法：
|
||||
- 过滤条件：仅统计最终确认状态的考核记录；可按年、月、科室过滤。
|
||||
- 聚合逻辑：按维度分组，计算加权总分与总权重，得到平均分。
|
||||
- 展示样式：返回维度字典与统计周期字符串，前端可直接映射到图表或表格。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start(["开始"]) --> BuildCond["构建过滤条件<br/>状态=FINALIZED<br/>可选: 年/月/科室"]
|
||||
BuildCond --> JoinTables["联接: 指标→明细→考核"]
|
||||
JoinTables --> GroupByDim["按BSC维度分组"]
|
||||
GroupByDim --> CalcAvg["计算: 加权总分/总权重"]
|
||||
CalcAvg --> Output["输出: 维度统计+周期"]
|
||||
Output --> End(["结束"])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [统计服务 get_bsc_dimension_stats](file://backend/app/services/stats_service.py#L19-L72)
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L17-L33)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
|
||||
|
||||
### 科室绩效统计
|
||||
- 功能说明：按科室汇总员工得分，计算平均分、最大/最小分、员工列表，并按平均分降序排列。
|
||||
- 数据聚合算法：
|
||||
- 聚合字段：科室ID、名称、类型、员工数、总分、平均分、最大/最小分、员工明细。
|
||||
- 排序规则：按平均分降序。
|
||||
- 展示样式：前端表格展示科室统计，支持奖金列（若存在）。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
S(["开始"]) --> Filter["过滤: FINALIZED+年+月"]
|
||||
Filter --> Join["联接: 科室→员工→考核"]
|
||||
Join --> Group["按科室分组聚合"]
|
||||
Group --> Compute["计算: 员工数/总分/平均分/最值"]
|
||||
Compute --> Sort["按平均分降序"]
|
||||
Sort --> Out(["输出: 科室统计列表"])
|
||||
Out --> E(["结束"])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [统计服务 get_department_stats](file://backend/app/services/stats_service.py#L75-L146)
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L36-L49)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
|
||||
|
||||
### 趋势分析（月度）
|
||||
- 功能说明：按月统计平均分与加权平均分，支持指定最近N个月与按科室过滤。
|
||||
- 数据聚合算法：
|
||||
- 时间范围：若指定年份，计算最近months个月（跨年处理）。
|
||||
- 聚合字段：月份、平均分、加权平均分、记录数。
|
||||
- 展示样式：折线/柱状组合图，双轴显示平均分与奖金（若存在）。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
TStart(["开始"]) --> TFilter["过滤: FINALIZED+年/月范围"]
|
||||
TFilter --> TJoin["联接: 员工→考核"]
|
||||
TJoin --> TGroup["按月分组聚合"]
|
||||
TGroup --> TAgg["计算: 平均分/加权平均分/数量"]
|
||||
TAgg --> TSort["按月升序"]
|
||||
TSort --> TOut(["输出: 月度趋势列表"])
|
||||
TOut --> TE(["结束"])
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [统计服务 get_trend_stats](file://backend/app/services/stats_service.py#L149-L199)
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L52-L70)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
|
||||
|
||||
### 绩效排名
|
||||
- 功能说明：提供员工与科室的绩效排名，支持限制返回条数。
|
||||
- 数据聚合算法：
|
||||
- 员工排名：按加权得分降序取前N名。
|
||||
- 科室排名：先按科室汇总平均分，再整体降序取前N名。
|
||||
- 展示样式：表格排名，突出前三名。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant API as "统计API"
|
||||
participant SVC as "统计服务"
|
||||
participant DB as "数据库"
|
||||
API->>SVC : get_ranking_stats(year, month, limit)
|
||||
SVC->>DB : 查询最终确认的考核记录
|
||||
DB-->>SVC : 结果集(员工ID/姓名/部门/得分)
|
||||
SVC-->>API : 排名列表(含排名序号)
|
||||
API-->>API : 返回JSON
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L210-L224)
|
||||
- [统计服务 get_ranking_stats](file://backend/app/services/stats_service.py#L202-L244)
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L186-L207)
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L210-L224)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L202-L244)
|
||||
|
||||
### 指标完成度
|
||||
- 功能说明：按指标统计平均分、最大/最小分、完成率与样本数。
|
||||
- 数据聚合算法：
|
||||
- 过滤条件：最终确认状态；可按年、月、指标过滤。
|
||||
- 计算完成率：平均分/目标值×100%，上限100%。
|
||||
- 展示样式：指标列表卡片，完成率进度条或数值。
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L227-L241)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
|
||||
|
||||
### 周期统计与关键指标仪表盘
|
||||
- 周期统计：汇总当期总科室数、总员工数、平均分等。
|
||||
- 关键指标仪表盘：床位使用率、药占比、材料占比、患者满意度等（演示数据）。
|
||||
- 展示样式：概览卡片与仪表盘组件。
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L93-L125)
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L128-L153)
|
||||
|
||||
### 收支趋势
|
||||
- 功能说明：按月统计收入、支出、利润趋势。
|
||||
- 展示样式：折线图，支持选择最近6/12个月。
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L156-L183)
|
||||
|
||||
### 前端报表页面与图表
|
||||
- 页面组件：筛选器、统计概览卡片、科室对比图、绩效分布饼图、科室统计表、员工排名表。
|
||||
- 图表实现：ECharts初始化、窗口自适应、双轴图表、饼图标签与强调。
|
||||
- 数据加载：并行请求多个接口，统一更新图表。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant View as "Reports.vue"
|
||||
participant API as "stats.js"
|
||||
participant BE as "后端统计API"
|
||||
View->>View : 选择统计周期(年-月)
|
||||
View->>API : 并行调用 : 周期统计/科室统计/员工排名
|
||||
API->>BE : GET /stats/period
|
||||
API->>BE : GET /stats/department
|
||||
API->>BE : GET /stats/ranking
|
||||
BE-->>API : JSON响应
|
||||
API-->>View : 数据对象
|
||||
View->>View : 更新ECharts图表
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L134-L171)
|
||||
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
|
||||
|
||||
**章节来源**
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
|
||||
- [前端统计API封装 stats.js](file://frontend/src/api/stats.js#L1-L43)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class StatsAPI {
|
||||
+get_bsc_dimension_stats()
|
||||
+get_department_stats()
|
||||
+get_trend_stats()
|
||||
+get_ranking_stats()
|
||||
+get_completion_stats()
|
||||
+get_period_stats()
|
||||
+get_kpi_gauges()
|
||||
+get_finance_trend()
|
||||
+get_department_ranking()
|
||||
}
|
||||
class StatsService {
|
||||
+get_bsc_dimension_stats()
|
||||
+get_department_stats()
|
||||
+get_trend_stats()
|
||||
+get_ranking_stats()
|
||||
+get_completion_stats()
|
||||
}
|
||||
class Models {
|
||||
+Assessment
|
||||
+AssessmentDetail
|
||||
+Indicator
|
||||
+Department
|
||||
+Staff
|
||||
+BSCDimension
|
||||
+AssessmentStatus
|
||||
}
|
||||
class Database {
|
||||
+AsyncEngine
|
||||
+AsyncSession
|
||||
}
|
||||
StatsAPI --> StatsService : "调用"
|
||||
StatsService --> Models : "查询/联接"
|
||||
StatsService --> Database : "使用会话"
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
|
||||
- [数据模型 models.py](file://backend/app/models/models.py#L117-L178)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
|
||||
|
||||
**章节来源**
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L1-L242)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
|
||||
- [数据模型 models.py](file://backend/app/models/models.py#L117-L178)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L1-L39)
|
||||
|
||||
## 性能考虑
|
||||
- 异步ORM：使用SQLAlchemy异步引擎与会话，提升并发吞吐与响应速度。
|
||||
- 索引优化：模型中已为常用查询字段建立索引（如考核记录的年月、状态、员工ID等），建议结合实际查询模式评估是否需要复合索引。
|
||||
- 聚合优化：统计服务对大表联接与分组聚合，建议：
|
||||
- 限定查询时间范围（如最近6/12个月）。
|
||||
- 对高频查询增加物化视图或缓存中间结果。
|
||||
- 使用LIMIT限制排名条数，避免超大数据集排序。
|
||||
- 前端优化：ECharts实例复用与窗口resize监听，减少重绘开销；图表数据按需更新，避免全量刷新。
|
||||
- 缓存策略：可引入Redis缓存热点报表（如当月周期统计、Top N排名），设置合理TTL与失效策略，降低数据库压力。
|
||||
- 数据更新机制：建议在考核状态变更时触发增量更新任务，或定时任务批量刷新报表缓存。
|
||||
|
||||
[本节为通用性能指导，不直接分析具体文件]
|
||||
|
||||
## 故障排查指南
|
||||
- 接口返回空数据或异常：
|
||||
- 检查过滤条件（年、月、科室）是否正确传入。
|
||||
- 确认考核状态为最终确认（FINALIZED）。
|
||||
- 图表不显示或空白：
|
||||
- 检查ECharts实例初始化与容器尺寸。
|
||||
- 确认数据格式与字段名一致（如avg_score、total_bonus）。
|
||||
- 数据库连接问题：
|
||||
- 查看异步会话生命周期与异常回滚逻辑。
|
||||
- 检查数据库URL与连接池配置。
|
||||
- 指标模板缺失：
|
||||
- 确认初始化脚本已执行，模板与指标数据完整。
|
||||
|
||||
**章节来源**
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L1-L300)
|
||||
- [数据库连接 database.py](file://backend/app/core/database.py#L28-L39)
|
||||
- [前端报表页面 Reports.vue](file://frontend/src/views/reports/Reports.vue#L173-L181)
|
||||
|
||||
## 结论
|
||||
本模块以清晰的分层架构实现了BSC维度分析、科室统计、趋势与排名等核心报表功能。通过异步ORM与ECharts的结合，既保证了性能也提供了良好的用户体验。建议后续完善缓存与物化视图、扩展更多关键指标仪表盘与导出能力，并持续优化索引与查询计划以应对更大规模数据。
|
||||
|
||||
[本节为总结性内容，不直接分析具体文件]
|
||||
|
||||
## 附录
|
||||
|
||||
### 分析指标定义与计算方法
|
||||
- BSC维度得分：按指标权重加权求和，再除以总权重得到平均分。
|
||||
- 科室平均分：科室内员工加权得分的算术平均。
|
||||
- 趋势数据：按月分组的平均分与加权平均分。
|
||||
- 指标完成率：平均分/目标值×100%，上限100%。
|
||||
- 关键指标（演示）：床位使用率、药占比、材料占比、患者满意度。
|
||||
|
||||
**章节来源**
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L20-L72)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
|
||||
- [统计服务 stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
|
||||
- [后端统计API stats.py](file://backend/app/api/v1/stats.py#L128-L153)
|
||||
|
||||
### 数据模型与索引
|
||||
- 关键实体：Department、Staff、Assessment、AssessmentDetail、Indicator、SalaryRecord。
|
||||
- 索引位置：考核记录、员工、指标、科室等表均有相应索引，加速查询与排序。
|
||||
|
||||
**章节来源**
|
||||
- [数据模型 models.py](file://backend/app/models/models.py#L62-L231)
|
||||
- [数据库设计文档 database.md](file://docs/database.md#L1-L95)
|
||||
|
||||
### 指标模板与BSC维度
|
||||
- 模板类型：通用模板与按科室类型的模板（如手术、非手术、医技、护理、行政等）。
|
||||
- 维度权重：模板可配置财务、客户、内部流程、学习成长维度权重。
|
||||
|
||||
**章节来源**
|
||||
- [初始化指标模板 init_templates.py](file://backend/app/scripts/init_templates.py#L81-L102)
|
||||
- [初始化指标模板脚本 init_indicator_templates.py](file://backend/init_indicator_templates.py#L234-L266)
|
||||
Reference in New Issue
Block a user