# 数据分析报表 **本文引用的文件** - [后端统计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) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心组件](#核心组件) 4. [架构总览](#架构总览) 5. [详细组件分析](#详细组件分析) 6. [依赖关系分析](#依赖关系分析) 7. [性能考虑](#性能考虑) 8. [故障排查指南](#故障排查指南) 9. [结论](#结论) 10. [附录](#附录) ## 简介 本文件面向“医院绩效系统”的数据分析报表模块，系统化阐述BSC维度分析、科室绩效统计、趋势分析、绩效排名、指标完成度等核心功能。文档覆盖数据聚合算法、图表展示组件、报表生成机制、多维度统计分析、数据可视化与导出能力，并解释数据更新机制、缓存策略与性能优化方案。同时提供分析指标定义、计算方法与展示样式说明，帮助开发者与运维人员快速理解并扩展系统能力。 ## 项目结构 报表模块由后端FastAPI接口、SQLAlchemy异步ORM服务层、前端Vue组件与ECharts图表构成，遵循前后端分离与职责清晰的设计原则。 ```mermaid graph TB subgraph "前端" FE_Report["Reports.vue
报表页面"] FE_API["stats.js
API封装"] end subgraph "后端" BE_Router["API路由器
__init__.py"] BE_StatsAPI["统计API
stats.py"] BE_Service["统计服务
stats_service.py"] BE_Models["数据模型
models.py"] BE_DB["数据库连接
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["构建过滤条件
状态=FINALIZED
可选: 年/月/科室"] 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)