提交文件

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/API接口文档/统计分析接口.md
+++ b/.qoder/repowiki/zh/content/API接口文档/统计分析接口.md
@@ -0,0 +1,423 @@
+# 统计分析接口
+
+<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)
+- [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)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向“统计分析与报表接口”的使用者与维护者，系统化梳理后端统计接口、服务层实现、数据模型与前端调用方式，并补充计算逻辑、时间范围选择、聚合方式、同比环比分析、多维交叉分析、数据钻取与筛选、报表导出、缓存策略与性能优化建议，以及移动端适配与响应时间优化思路。文档同时给出接口参数、响应结构与图表数据格式，帮助快速集成与扩展。
+
+## 项目结构
+统计分析相关代码分布在后端 API、服务层、模型与前端调用层，配合通用响应与数据模式定义，形成清晰的分层架构。
+
+```mermaid
+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
+```
+
+图示来源
+- [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-L200)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [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)
+
+章节来源
+- [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-L200)
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
+- [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)
+
+## 核心组件
+- 统计 API 路由器：提供 BSC 维度分析、科室绩效统计、趋势分析、周期统计、KPI 仪表盘、收支趋势、科室/员工排名、指标完成度等接口。
+- 统计服务层：封装 SQL 查询与聚合逻辑，负责跨表联结、条件过滤、分组统计与排序。
+- 数据模型：定义 BSC 维度、指标类型、评估状态、部门类型等枚举与实体关系。
+- 前端调用与视图：封装 axios 请求、发起多路并发请求、渲染 ECharts 图表与表格。
+
+章节来源
+- [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#L29-L61)
+- [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#L112-L308)
+
+## 架构总览
+统计接口采用 FastAPI + SQLAlchemy 异步 ORM 的分层设计，前端通过统一的 API 封装进行调用，后端服务层负责复杂聚合与排序，最终以统一响应体返回。
+
+```mermaid
+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 : 列表)
+```
+
+图示来源
+- [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#L75-L146)
+
+章节来源
+- [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)
+
+## 详细组件分析
+
+### BSC 维度分析
+- 接口：GET /stats/bsc-dimension
+- 功能：按财务、客户、内部流程、学习与成长四个维度统计得分、权重、指标数量与平均分。
+- 时间范围：支持按年/月过滤；未指定时返回全部。
+- 聚合方式：按维度分组，计算总分=Σ(明细得分×指标权重)，总权重=Σ权重，平均分=总分/总权重。
+- 筛选条件：可按科室过滤。
+- 响应结构：包含维度字典与统计周期字符串。
+
+章节来源
+- [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)
+
+### 科室绩效统计
+- 接口：GET /stats/department
+- 功能：返回各科室的员工数、总分、平均分、最高/最低分、员工得分列表，并按平均分降序排列。
+- 时间范围：按年/月过滤；未指定则返回全部。
+- 聚合方式：按科室分组，累计加权得分，计算平均分，记录员工明细。
+- 响应结构：数组，元素包含科室信息、统计指标与员工列表。
+
+章节来源
+- [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#L75-L146)
+
+### 趋势分析（月度）
+- 接口：GET /stats/trend
+- 功能：按最近 N 个月的趋势统计，支持按科室过滤。
+- 时间范围：若未指定年份，默认使用当前年；按最近 N 个月聚合，跨年处理。
+- 聚合方式：按月分组，计算平均总分、平均加权分与记录数。
+- 响应结构：数组，元素包含月份、平均分与计数。
+
+章节来源
+- [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#L149-L199)
+
+### 周期统计
+- 接口：GET /stats/period
+- 功能：返回指定周期的汇总统计（总科室数、总员工数、平均分），并包含各科室明细。
+- 时间范围：若未指定年/月，默认使用当前年/月。
+- 聚合方式：对当期科室统计结果做二次汇总。
+- 响应结构：包含周期字符串、汇总指标与明细数组。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L93-L125)
+
+### KPI 仪表盘
+- 接口：GET /stats/kpi-gauges
+- 功能：返回关键指标仪表盘数据（床位使用率、药占比、材料占比、患者满意度等）。
+- 时间范围：若未指定年/月，默认使用当前年/月。
+- 注意：当前为演示数据，后续需替换为真实数据库查询。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L128-L153)
+
+### 收支趋势
+- 接口：GET /stats/finance-trend
+- 功能：返回最近 N 个月的收入、支出、利润趋势。
+- 时间范围：按最近 N 个月聚合。
+- 注意：当前为演示数据，后续需替换为真实数据库查询。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L156-L183)
+
+### 科室绩效排名
+- 接口：GET /stats/department-ranking
+- 功能：返回指定周期内科室的平均分排名前 N。
+- 时间范围：若未指定年/月，默认使用当前年/月。
+- 聚合方式：基于科室统计结果取前 N。
+- 响应结构：数组，元素为科室排名数据。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L186-L207)
+
+### 员工绩效排名
+- 接口：GET /stats/ranking
+- 功能：返回指定周期内员工的加权得分排名前 N。
+- 时间范围：必须提供年/月。
+- 聚合方式：按加权得分降序取前 N。
+- 响应结构：数组，元素包含员工信息与排名。
+
+章节来源
+- [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#L202-L244)
+
+### 指标完成度
+- 接口：GET /stats/completion
+- 功能：返回指标的平均分、最大/最小分、完成率与统计数量。
+- 时间范围：按年/月过滤；可按指标 ID 过滤。
+- 聚合方式：按指标分组，计算平均分与完成率=平均分/目标值×100（上限 100）。
+- 响应结构：包含指标数组。
+
+章节来源
+- [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#L247-L299)
+
+### 预警数据
+- 接口：GET /stats/alerts
+- 功能：返回预警数据（低分员工、未完成考核科室、异常数据）。
+- 注意：当前为演示数据，后续需替换为真实数据库查询。
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L73-L90)
+
+## 依赖关系分析
+- API 层依赖服务层，服务层依赖模型层与异步数据库会话。
+- 前端通过封装的 API 模块调用后端接口，视图组件负责并发请求与图表渲染。
+- 统一响应体与 Pydantic 模式用于前后端契约约束。
+
+```mermaid
+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 : "查询/聚合"
+```
+
+图示来源
+- [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#L117-L200)
+
+章节来源
+- [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-L200)
+
+## 性能考虑
+- 查询优化
+  - 使用分组与聚合函数减少往返，避免在 Python 层重复计算。
+  - 对常用过滤条件建立索引（如评估状态、周期、科室等）。
+- 并发与缓存
+  - 前端并发请求多个统计接口，减少等待时间。
+  - 对热点报表（如周期统计）可引入 Redis 缓存，设置合理 TTL。
+- 分页与限制
+  - 排名类接口限制返回数量（如 limit），避免大结果集。
+- 前端渲染
+  - 图表仅在数据就绪后初始化，避免重复渲染。
+- 响应时间优化建议
+  - 后端：开启连接池、使用异步 ORM、避免 N+1 查询。
+  - 前端：懒加载图表、骨架屏、分页加载。
+
+[本节为通用性能指导，不直接分析具体文件]
+
+## 故障排查指南
+- 常见问题
+  - 参数缺失：确保提供年/月参数或允许默认使用当前年/月。
+  - 数据为空：确认数据库中存在对应周期的评估数据。
+  - 权限问题：确保携带有效 JWT Token。
+- 快速定位
+  - 使用内置测试页面与后端日志定位接口状态与错误信息。
+  - 前端 Network 标签查看失败请求详情。
+- 建议步骤
+  - 清除浏览器缓存与本地存储，硬刷新页面。
+  - 重启后端与前端服务，确认端口占用与代理配置。
+
+章节来源
+- [frontend/public/test-api.html](file://frontend/public/test-api.html#L113-L129)
+- [TEST_REPORT.md](file://TEST_REPORT.md#L62-L95)
+
+## 结论
+统计分析接口围绕“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）
+  - 响应：预警数据对象
+
+章节来源
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L241)
+- [docs/api.md](file://docs/api.md#L471-L538)
+
+### 响应数据结构与图表数据格式
+- 统一响应体
+  - 字段：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
+
+章节来源
+- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L347-L375)
+- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L128-L183)
+
+### 计算逻辑与时间范围选择
+- BSC 维度分析
+  - 总分=Σ(明细得分×指标权重)，总权重=Σ权重，平均分=总分/总权重
+- 科室统计
+  - 平均分=总加权分/员工数；最高/最低分在员工列表中比较得出
+- 趋势分析
+  - 若未指定年份，默认使用当前年；按最近 N 个月聚合，跨年处理
+- 指标完成度
+  - 完成率=平均分/目标值×100，上限 100
+- 同比环比分析
+  - 可通过前端按月序列与后端趋势接口实现同比（同月去年）与环比（相邻月份）对比
+
+章节来源
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L75-L146)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L149-L199)
+- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L247-L299)
+
+### 多维度交叉分析、数据钻取与筛选
+- 多维度：BSC 维度、科室类型、指标类型、评估状态等
+- 数据钻取：从周期统计到科室明细，再到员工明细
+- 筛选条件：按年/月、科室、指标 ID、状态等
+- 前端实现：报表页面通过日期选择器与并发请求实现钻取与筛选
+
+章节来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L1-L367)
+- [frontend/src/api/stats.js](file://frontend/src/api/stats.js#L1-L43)
+
+### 报表导出与移动端适配
+- 报表导出：建议在前端将 ECharts 图表导出为 PNG/SVG，或将表格数据导出为 Excel/CSV
+- 移动端适配：图表容器自适应窗口大小，表格采用紧凑布局与分页加载
+- 响应时间优化：后端异步查询、前端懒加载与骨架屏、缓存热点数据
+
+章节来源
+- [frontend/src/views/reports/Reports.vue](file://frontend/src/views/reports/Reports.vue#L173-L295)
+
+### 数据模型与枚举参考
+- BSC 维度：financial、customer、internal_process、learning_growth
+- 指标类型：quality、quantity、efficiency、service、cost
+- 评估状态：draft、submitted、reviewed、finalized、rejected
+- 科室类型：多种类型枚举，覆盖临床、医技、行政、护理、后勤等
+
+章节来源
+- [backend/app/models/models.py](file://backend/app/models/models.py#L29-L61)
+- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L146)
+- [docs/详细设计文档.md](file://docs/详细设计文档.md#L85-L120)