# 统计分析接口

<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)