chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0395f31d24e6601c652dfbe2a6826cf8de2037be
hospital_performance/.qoder/repowiki/zh/content/API接口文档/统计分析接口.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

18 KiB
Raw Blame History

统计分析接口

**本文引用的文件** - [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) - [docs/api.md](file://docs/api.md) - [docs/详细设计文档.md](file://docs/详细设计文档.md) - [backend/init_db.py](file://backend/init_db.py) - [TEST_REPORT.md](file://TEST_REPORT.md) - [frontend/public/test-api.html](file://frontend/public/test-api.html)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向“统计分析与报表接口”的使用者与维护者，系统化梳理后端统计接口、服务层实现、数据模型与前端调用方式，并补充计算逻辑、时间范围选择、聚合方式、同比环比分析、多维交叉分析、数据钻取与筛选、报表导出、缓存策略与性能优化建议，以及移动端适配与响应时间优化思路。文档同时给出接口参数、响应结构与图表数据格式，帮助快速集成与扩展。

项目结构

统计分析相关代码分布在后端 API、服务层、模型与前端调用层，配合通用响应与数据模式定义，形成清晰的分层架构。

graph TB
subgraph "前端"
FE_API["frontend/src/api/stats.js"]
FE_VIEW["frontend/src/views/reports/Reports.vue"]
end
subgraph "后端"
API["backend/app/api/v1/stats.py"]
SVC["backend/app/services/stats_service.py"]
MODELS["backend/app/models/models.py"]
SCHEMAS["backend/app/schemas/schemas.py"]
end
FE_API --> API
FE_VIEW --> FE_API
API --> SVC
SVC --> MODELS
API --> SCHEMAS
SVC --> SCHEMAS

图示来源

章节来源

核心组件

  • 统计 API 路由器：提供 BSC 维度分析、科室绩效统计、趋势分析、周期统计、KPI 仪表盘、收支趋势、科室/员工排名、指标完成度等接口。
  • 统计服务层：封装 SQL 查询与聚合逻辑，负责跨表联结、条件过滤、分组统计与排序。
  • 数据模型：定义 BSC 维度、指标类型、评估状态、部门类型等枚举与实体关系。
  • 前端调用与视图：封装 axios 请求、发起多路并发请求、渲染 ECharts 图表与表格。

章节来源

架构总览

统计接口采用 FastAPI + SQLAlchemy 异步 ORM 的分层设计，前端通过统一的 API 封装进行调用，后端服务层负责复杂聚合与排序，最终以统一响应体返回。

sequenceDiagram
participant FE as "前端报表页面"
participant API as "统计API(stats.py)"
participant SVC as "统计服务(stats_service.py)"
participant DB as "数据库(异步会话)"
FE->>API : GET /stats/department?period_year&period_month
API->>SVC : get_department_stats(...)
SVC->>DB : 执行SQL聚合(按科室分组)
DB-->>SVC : 聚合结果集
SVC-->>API : 汇总后的科室统计列表
API-->>FE : 统一响应体(data : 列表)

图示来源

章节来源

详细组件分析

BSC 维度分析

  • 接口：GET /stats/bsc-dimension
  • 功能：按财务、客户、内部流程、学习与成长四个维度统计得分、权重、指标数量与平均分。
  • 时间范围：支持按年/月过滤；未指定时返回全部。
  • 聚合方式：按维度分组，计算总分=Σ(明细得分×指标权重)，总权重=Σ权重，平均分=总分/总权重。
  • 筛选条件：可按科室过滤。
  • 响应结构：包含维度字典与统计周期字符串。

章节来源

科室绩效统计

  • 接口：GET /stats/department
  • 功能：返回各科室的员工数、总分、平均分、最高/最低分、员工得分列表，并按平均分降序排列。
  • 时间范围：按年/月过滤；未指定则返回全部。
  • 聚合方式：按科室分组，累计加权得分，计算平均分，记录员工明细。
  • 响应结构：数组，元素包含科室信息、统计指标与员工列表。

章节来源

趋势分析（月度）

  • 接口：GET /stats/trend
  • 功能：按最近 N 个月的趋势统计，支持按科室过滤。
  • 时间范围：若未指定年份，默认使用当前年；按最近 N 个月聚合，跨年处理。
  • 聚合方式：按月分组，计算平均总分、平均加权分与记录数。
  • 响应结构：数组，元素包含月份、平均分与计数。

章节来源

周期统计

  • 接口：GET /stats/period
  • 功能：返回指定周期的汇总统计（总科室数、总员工数、平均分），并包含各科室明细。
  • 时间范围：若未指定年/月，默认使用当前年/月。
  • 聚合方式：对当期科室统计结果做二次汇总。
  • 响应结构：包含周期字符串、汇总指标与明细数组。

章节来源

KPI 仪表盘

  • 接口：GET /stats/kpi-gauges
  • 功能：返回关键指标仪表盘数据（床位使用率、药占比、材料占比、患者满意度等）。
  • 时间范围：若未指定年/月，默认使用当前年/月。
  • 注意：当前为演示数据，后续需替换为真实数据库查询。

章节来源

收支趋势

  • 接口：GET /stats/finance-trend
  • 功能：返回最近 N 个月的收入、支出、利润趋势。
  • 时间范围：按最近 N 个月聚合。
  • 注意：当前为演示数据，后续需替换为真实数据库查询。

章节来源

科室绩效排名

  • 接口：GET /stats/department-ranking
  • 功能：返回指定周期内科室的平均分排名前 N。
  • 时间范围：若未指定年/月，默认使用当前年/月。
  • 聚合方式：基于科室统计结果取前 N。
  • 响应结构：数组，元素为科室排名数据。

章节来源

员工绩效排名

  • 接口：GET /stats/ranking
  • 功能：返回指定周期内员工的加权得分排名前 N。
  • 时间范围：必须提供年/月。
  • 聚合方式：按加权得分降序取前 N。
  • 响应结构：数组，元素包含员工信息与排名。

章节来源

指标完成度

  • 接口：GET /stats/completion
  • 功能：返回指标的平均分、最大/最小分、完成率与统计数量。
  • 时间范围：按年/月过滤；可按指标 ID 过滤。
  • 聚合方式：按指标分组，计算平均分与完成率=平均分/目标值×100（上限 100）。
  • 响应结构：包含指标数组。

章节来源

预警数据

  • 接口：GET /stats/alerts
  • 功能：返回预警数据（低分员工、未完成考核科室、异常数据）。
  • 注意：当前为演示数据，后续需替换为真实数据库查询。

章节来源

依赖关系分析

  • API 层依赖服务层，服务层依赖模型层与异步数据库会话。
  • 前端通过封装的 API 模块调用后端接口，视图组件负责并发请求与图表渲染。
  • 统一响应体与 Pydantic 模式用于前后端契约约束。
classDiagram
class StatsAPI {
+get_bsc_dimension_stats()
+get_department_stats()
+get_trend_stats()
+get_period_stats()
+get_kpi_gauges()
+get_finance_trend()
+get_department_ranking()
+get_ranking_stats()
+get_completion_stats()
}
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
}
StatsAPI --> StatsService : "调用"
StatsService --> Models : "查询/聚合"

图示来源

章节来源

性能考虑

  • 查询优化
    • 使用分组与聚合函数减少往返，避免在 Python 层重复计算。
    • 对常用过滤条件建立索引（如评估状态、周期、科室等）。
  • 并发与缓存
    • 前端并发请求多个统计接口，减少等待时间。
    • 对热点报表（如周期统计）可引入 Redis 缓存，设置合理 TTL。
  • 分页与限制
    • 排名类接口限制返回数量（如 limit），避免大结果集。
  • 前端渲染
    • 图表仅在数据就绪后初始化，避免重复渲染。
  • 响应时间优化建议
    • 后端：开启连接池、使用异步 ORM、避免 N+1 查询。
    • 前端：懒加载图表、骨架屏、分页加载。

[本节为通用性能指导，不直接分析具体文件]

故障排查指南

  • 常见问题
    • 参数缺失：确保提供年/月参数或允许默认使用当前年/月。
    • 数据为空：确认数据库中存在对应周期的评估数据。
    • 权限问题：确保携带有效 JWT Token。
  • 快速定位
    • 使用内置测试页面与后端日志定位接口状态与错误信息。
    • 前端 Network 标签查看失败请求详情。
  • 建议步骤
    • 清除浏览器缓存与本地存储，硬刷新页面。
    • 重启后端与前端服务，确认端口占用与代理配置。

章节来源

结论

统计分析接口围绕“BSC 维度、科室/员工绩效、趋势与排名、指标完成度”等核心主题，提供了清晰的分层实现与统一响应格式。结合前端并发请求与 ECharts 图表渲染，能够满足日常报表与移动端展示需求。后续可在真实数据接入、缓存策略与性能优化方面持续改进。

[本节为总结性内容，不直接分析具体文件]

附录

接口清单与参数说明

  • BSC 维度分析
    • 方法：GET
    • 路径：/stats/bsc-dimension
    • 查询参数：department_id（可选）、period_year、period_month
    • 响应：包含维度字典与周期字符串
  • 科室绩效统计
    • 方法：GET
    • 路径：/stats/department
    • 查询参数：period_year、period_month
    • 响应：科室统计数组
  • 趋势分析
    • 方法：GET
    • 路径：/stats/trend
    • 查询参数：department_id（可选）、period_year（可选）、months（默认 6，范围 1-24）
    • 响应：按月聚合的趋势数组
  • 周期统计
    • 方法：GET
    • 路径：/stats/period
    • 查询参数：period_year（可选）、period_month（可选）
    • 响应：周期汇总与明细数组
  • KPI 仪表盘
    • 方法：GET
    • 路径：/stats/kpi-gauges
    • 查询参数：period_year（可选）、period_month（可选）
    • 响应：关键指标仪表盘数据
  • 收支趋势
    • 方法：GET
    • 路径：/stats/finance-trend
    • 查询参数：months（默认 6，范围 1-24）
    • 响应：收入/支出/利润趋势数组
  • 科室绩效排名
    • 方法：GET
    • 路径：/stats/department-ranking
    • 查询参数：period_year（可选）、period_month（可选）、limit（默认 10，范围 1-100）
    • 响应：科室排名数组
  • 员工绩效排名
    • 方法：GET
    • 路径：/stats/ranking
    • 查询参数：period_year、period_month、limit（默认 10，范围 1-100）
    • 响应：员工排名数组
  • 指标完成度
    • 方法：GET
    • 路径：/stats/completion
    • 查询参数：indicator_id（可选）、period_year、period_month
    • 响应：指标完成度数组
  • 预警数据
    • 方法：GET
    • 路径：/stats/alerts
    • 查询参数：limit（默认 10，范围 1-100）
    • 响应：预警数据对象

章节来源

响应数据结构与图表数据格式

  • 统一响应体
    • 字段：code、message、data（根据接口不同而异）
  • 科室统计
    • 字段：department_id、department_name、staff_count、avg_score、total_bonus、staff_list
  • 趋势数据
    • 字段：month、avg_score、avg_weighted_score、count
  • KPI 仪表盘
    • 字段：bed_usage_rate、drug_ratio、material_ratio、satisfaction_rate
  • 收支趋势
    • 字段：period、income、expense、profit
  • 排名数据
    • 字段：department 或 staff 的基本信息、score、weighted_score、rank
  • 指标完成度
    • 字段：indicator_id、indicator_name、indicator_code、target_value、max_score、avg_score、completion_rate、count

章节来源

计算逻辑与时间范围选择

  • BSC 维度分析
    • 总分=Σ(明细得分×指标权重)，总权重=Σ权重，平均分=总分/总权重
  • 科室统计
    • 平均分=总加权分/员工数；最高/最低分在员工列表中比较得出
  • 趋势分析
    • 若未指定年份，默认使用当前年；按最近 N 个月聚合，跨年处理
  • 指标完成度
    • 完成率=平均分/目标值×100，上限 100
  • 同比环比分析
    • 可通过前端按月序列与后端趋势接口实现同比（同月去年）与环比（相邻月份）对比

章节来源

多维度交叉分析、数据钻取与筛选

  • 多维度：BSC 维度、科室类型、指标类型、评估状态等
  • 数据钻取：从周期统计到科室明细，再到员工明细
  • 筛选条件：按年/月、科室、指标 ID、状态等
  • 前端实现：报表页面通过日期选择器与并发请求实现钻取与筛选

章节来源

报表导出与移动端适配

  • 报表导出：建议在前端将 ECharts 图表导出为 PNG/SVG，或将表格数据导出为 Excel/CSV
  • 移动端适配：图表容器自适应窗口大小，表格采用紧凑布局与分页加载
  • 响应时间优化：后端异步查询、前端懒加载与骨架屏、缓存热点数据

章节来源

数据模型与枚举参考

  • BSC 维度：financial、customer、internal_process、learning_growth
  • 指标类型：quality、quantity、efficiency、service、cost
  • 评估状态：draft、submitted、reviewed、finalized、rejected
  • 科室类型：多种类型枚举，覆盖临床、医技、行政、护理、后勤等

章节来源