# 统计报表接口

<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)
- [backend/app/main.py](file://backend/app/main.py)
- [backend/app/core/config.py](file://backend/app/core/config.py)
- [backend/app/core/database.py](file://backend/app/core/database.py)
- [backend/app/api/__init__.py](file://backend/app/api/__init__.py)
- [docs/详细设计.md](file://docs/详细设计.md)
</cite>

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

## 简介
本文件详细说明医院绩效管理系统的统计报表接口，涵盖BSC维度分析、绩效统计、趋势分析、预警数据、周期统计、关键指标仪表盘、收支趋势、科室绩效排名、个人绩效统计与对比分析等功能。文档重点阐述多维度数据聚合、图表数据生成、报表格式化、实时数据更新、缓存策略、性能优化、统计数据准确性保证、数据源管理与ETL流程、自定义报表、数据导出与可视化集成、统计口径说明、数据质量控制与异常检测机制。

## 项目结构
后端采用FastAPI + SQLAlchemy 2.0 + PostgreSQL + 异步IO架构，统计报表接口位于API路由层，业务逻辑封装在服务层，数据模型定义在ORM层，配置与数据库连接在核心模块中。

```mermaid
graph TB
subgraph "表现层"
Frontend[前端应用]
end
subgraph "应用层"
API_Router[API路由层<br/>stats.py]
Main_App[主应用入口<br/>main.py]
end
subgraph "服务层"
Stats_Service[统计服务层<br/>stats_service.py]
end
subgraph "数据层"
Models[数据模型<br/>models.py]
Schemas[数据模式<br/>schemas.py]
Database[数据库连接<br/>database.py]
Config[系统配置<br/>config.py]
end
Frontend --> API_Router
API_Router --> Stats_Service
Stats_Service --> Models
Stats_Service --> Database
API_Router --> Main_App
Main_App --> Config
Database --> Config
```

**图表来源**
- [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-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)

**章节来源**
- [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-L438)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L1-L743)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)

## 核心组件
- API路由层：提供REST接口，负责请求参数解析、鉴权与响应包装。
- 服务层：实现统计逻辑，包括BSC维度分析、科室/个人绩效统计、趋势分析、指标完成度等。
- 数据模型层：定义科室、员工、指标、考核、明细、工资等实体及其关系。
- 数据模式层：定义Pydantic模型用于序列化/反序列化与API响应。
- 核心模块：配置系统参数、数据库连接与中间件。

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L14-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#L62-L231)
- [backend/app/schemas/schemas.py](file://backend/app/schemas/schemas.py#L347-L375)
- [backend/app/core/config.py](file://backend/app/core/config.py#L9-L47)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)

## 架构概览
统计报表接口遵循分层架构，API路由层仅负责输入输出与鉴权，服务层封装复杂查询与聚合逻辑，数据模型层提供ORM映射，核心模块提供配置与数据库连接。

```mermaid
sequenceDiagram
participant Client as "客户端"
participant API as "统计API路由<br/>stats.py"
participant Service as "统计服务<br/>stats_service.py"
participant DB as "数据库引擎<br/>database.py"
participant Model as "数据模型<br/>models.py"
Client->>API : GET /api/v1/stats/bsc-dimension
API->>Service : get_bsc_dimension_stats(...)
Service->>DB : 异步SQL查询
DB->>Model : ORM映射
Model-->>DB : 查询结果
DB-->>Service : 结果集
Service-->>API : 聚合后的统计结果
API-->>Client : JSON响应
```

**图表来源**
- [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)
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L39)
- [backend/app/models/models.py](file://backend/app/models/models.py#L117-L197)

## 详细组件分析

### BSC维度分析
- 功能：按财务、客户、内部流程、学习与成长四个维度统计得分、权重与指标数量，并计算平均分。
- 查询条件：支持按年度、月份、科室过滤，仅统计已确认的考核记录。
- 聚合逻辑：按维度分组，计算加权总分、总权重、指标数量与平均分。
- 输出格式：包含维度详情与统计周期。

```mermaid
flowchart TD
Start(["开始"]) --> BuildConditions["构建查询条件<br/>状态=FINALIZED<br/>可选: 年度/月份/科室"]
BuildConditions --> QueryGroup["按维度分组查询<br/>SUM(得分*权重)/SUM(权重)"]
QueryGroup --> Aggregate["聚合维度统计<br/>得分/权重/指标数/平均分"]
Aggregate --> FormatOutput["格式化输出<br/>包含周期信息"]
FormatOutput --> End(["结束"])
```

**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L19-L72)

**章节来源**
- [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)

### 科室绩效统计
- 功能：获取各科室的绩效统计，包括员工人数、总分、平均分、最高/最低分、员工列表。
- 聚合逻辑：按科室汇总，计算平均分并按平均分降序排列。
- 输出格式：包含科室基本信息与员工明细。

```mermaid
flowchart TD
Start(["开始"]) --> FilterFinalized["过滤已确认考核记录"]
FilterFinalized --> JoinTables["连接科室/员工/考核表"]
JoinTables --> GroupByDept["按科室分组聚合"]
GroupByDept --> CalcStats["计算员工数/总分/最高/最低分"]
CalcStats --> AvgScore["计算平均分"]
AvgScore --> Sort["按平均分降序排序"]
Sort --> Format["格式化输出"]
Format --> End(["结束"])
```

**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)

**章节来源**
- [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#L74-L146)

### 趋势分析
- 功能：按月度统计平均分与加权平均分，支持指定最近N个月或按年份范围查询。
- 时间处理：跨年处理，确保月份范围正确。
- 输出格式：包含月份与对应的平均分。

```mermaid
flowchart TD
Start(["开始"]) --> SetPeriod["设置统计周期<br/>默认当前年份"]
SetPeriod --> MonthRange["计算最近N个月范围"]
MonthRange --> CrossYear{"是否跨年？"}
CrossYear --> |是| YearConditions["年份条件: 上一年>=起始月<br/>当年<=当前月"]
CrossYear --> |否| SameYear["年份条件: 当年且起止范围内"]
YearConditions --> QueryAvg["按月分组查询平均分"]
SameYear --> QueryAvg
QueryAvg --> Format["格式化输出"]
Format --> End(["结束"])
```

**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L148-L199)

**章节来源**
- [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#L148-L199)

### 预警数据
- 功能：预留接口，用于返回低分员工、未完成考核科室、异常数据等预警信息。
- 当前实现：返回模拟数据，后续可扩展为从数据库查询实际预警数据。

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L73-L90)

### 周期统计
- 功能：按年月统计全院的科室数量、员工总数、平均分等汇总信息。
- 计算逻辑：对科室统计结果进行汇总计算。
- 输出格式：包含周期、总数、平均分与明细列表。

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L93-L125)

### 关键指标仪表盘
- 功能：返回关键指标的仪表盘数据，如床位使用率、药占比、材料占比、患者满意度等。
- 当前实现：返回模拟数据，后续可扩展为从数据库查询实际指标。

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L128-L153)

### 收支趋势
- 功能：按月统计收入、支出、利润趋势。
- 当前实现：返回模拟数据，后续可扩展为从财务系统查询实际数据。

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L156-L183)

### 科室绩效排名
- 功能：按平均分对科室进行排名，支持限制返回数量。
- 实现：基于科室统计结果进行排序与截取。

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L186-L207)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L74-L146)

### 个人绩效统计与对比分析
- 功能：获取个人绩效排名，支持限制返回数量。
- 实现：连接员工、科室、考核表，按加权平均分排序并标注排名。

```mermaid
sequenceDiagram
participant API as "统计API"
participant Service as "统计服务"
participant DB as "数据库"
participant Model as "模型"
API->>Service : get_ranking_stats(year, month, limit)
Service->>DB : 查询已确认考核记录
DB->>Model : 连接员工/科室/考核表
Model-->>DB : 查询结果
DB-->>Service : 排序后的结果集
Service-->>API : 格式化排名数据
API-->>API : 标注排名序号
```

**图表来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L201-L244)

**章节来源**
- [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#L201-L244)

### 指标完成度
- 功能：按指标统计平均分、最大/最小分、完成率等。
- 计算逻辑：完成率=平均分/目标值×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#L246-L299)

## 依赖关系分析
统计报表接口的依赖关系清晰，API路由层依赖服务层，服务层依赖数据模型与数据库连接，整体耦合度低、内聚性强。

```mermaid
graph TB
StatsAPI["统计API路由<br/>stats.py"] --> StatsService["统计服务<br/>stats_service.py"]
StatsService --> Models["数据模型<br/>models.py"]
StatsService --> Database["数据库连接<br/>database.py"]
StatsAPI --> MainApp["主应用<br/>main.py"]
MainApp --> Config["配置<br/>config.py"]
Database --> Config
```

**图表来源**
- [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-L438)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

**章节来源**
- [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-L438)
- [backend/app/core/database.py](file://backend/app/core/database.py#L1-L39)
- [backend/app/main.py](file://backend/app/main.py#L1-L92)
- [backend/app/core/config.py](file://backend/app/core/config.py#L1-L47)

## 性能考虑
- 异步数据库连接：使用SQLAlchemy异步引擎与会话工厂，减少阻塞，提升并发能力。
- 查询优化：合理使用索引（如考核记录的状态、年月、员工ID等），避免N+1查询。
- 分页与限制：接口支持分页与返回数量限制，防止大数据量查询导致性能问题。
- 缓存策略：当前接口未实现缓存，建议对高频查询（如趋势分析、排名）引入Redis缓存，设置合理的TTL。
- 数据库连接池：配置合适的连接池大小与溢出数量，避免连接争用。
- 前端渲染：图表数据建议采用分页或分批加载，避免一次性传输大量数据。

**章节来源**
- [backend/app/core/database.py](file://backend/app/core/database.py#L9-L21)
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L22)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L75-L90)

## 故障排除指南
- 数据库连接失败：检查DATABASE_URL配置与数据库服务状态。
- 查询超时：优化查询条件，增加索引，减少不必要的JOIN。
- 权限错误：确认用户角色与接口权限，确保鉴权中间件正常工作。
- 响应格式异常：检查服务层返回的数据结构与API路由的响应包装。
- 预警与仪表盘：当前返回模拟数据，需实现真实数据查询逻辑。

**章节来源**
- [backend/app/core/config.py](file://backend/app/core/config.py#L18-L26)
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L73-L90)
- [backend/app/main.py](file://backend/app/main.py#L58-L75)

## 结论
统计报表接口实现了BSC维度分析、绩效统计、趋势分析、排名与指标完成度等核心功能，具备良好的扩展性与可维护性。建议后续完善预警与仪表盘的真实数据查询、引入缓存策略、优化查询性能，并补充数据质量控制与异常检测机制，以满足生产环境的稳定性与准确性要求。

## 附录

### API接口定义
- BSC维度分析：GET /api/v1/stats/bsc-dimension
  - 参数：department_id（可选）、period_year、period_month
  - 返回：维度得分、权重、指标数量与平均分
- 科室绩效统计：GET /api/v1/stats/department
  - 参数：period_year、period_month
  - 返回：各科室统计与员工明细
- 趋势分析：GET /api/v1/stats/trend
  - 参数：department_id（可选）、period_year（可选）、months（1-24，默认6）
  - 返回：月度平均分趋势
- 预警数据：GET /api/v1/stats/alerts
  - 参数：limit（1-100，默认10）
  - 返回：低分员工、未完成考核科室、异常数据
- 周期统计：GET /api/v1/stats/period
  - 参数：period_year（可选）、period_month（可选）
  - 返回：周期汇总与明细
- 关键指标仪表盘：GET /api/v1/stats/kpi-gauges
  - 参数：period_year（可选）、period_month（可选）
  - 返回：床位使用率、药占比、材料占比、患者满意度
- 收支趋势：GET /api/v1/stats/finance-trend
  - 参数：months（1-24，默认6）
  - 返回：月度收入、支出、利润
- 科室绩效排名：GET /api/v1/stats/department-ranking
  - 参数：period_year（可选）、period_month（可选）、limit（1-100，默认10）
  - 返回：前N名科室
- 个人绩效统计：GET /api/v1/stats/ranking
  - 参数：period_year、period_month、limit
  - 返回：个人绩效排名
- 指标完成度：GET /api/v1/stats/completion
  - 参数：indicator_id（可选）、period_year、period_month
  - 返回：指标平均分、完成率等

**章节来源**
- [backend/app/api/v1/stats.py](file://backend/app/api/v1/stats.py#L17-L241)

### 数据模型关系
```mermaid
erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "参与"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被评估"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
SALARY_RECORDS ||--|| STAFF : "关联"
```

**图表来源**
- [backend/app/models/models.py](file://backend/app/models/models.py#L62-L231)

### 统计口径说明
- 加权平均分：按指标权重计算的平均分，体现权重影响。
- 完成率：平均分与目标值的比值，上限100%。
- 排名：按加权平均分降序排列，相同分数按规则处理并列。

**章节来源**
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L62-L67)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L284-L296)

### 数据质量控制与异常检测
- 数据完整性：仅统计状态为已确认的考核记录，确保数据有效性。
- 异常值处理：在服务层对空值与边界值进行处理，避免异常影响统计结果。
- ETL流程：建议在系统外部实现ETL，从HIS、财务、院感等系统抽取数据，清洗后入库，统计接口从数据库读取。

**章节来源**
- [docs/详细设计.md](file://docs/详细设计.md#L96-L109)
- [backend/app/services/stats_service.py](file://backend/app/services/stats_service.py#L36-L43)