chenqi/hospital_performance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
hospital_performance/.qoder/repowiki/zh/content/后端开发指南/API路由实现/统计报表接口.md
chenqi 44f250f58e 提交文件
2026-02-28 15:16:15 +08:00

18 KiB
Raw Permalink 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) - [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)

目录

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

简介

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

项目结构

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

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

图表来源

章节来源

核心组件

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

章节来源

架构概览

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

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响应

图表来源

详细组件分析

BSC维度分析

  • 功能：按财务、客户、内部流程、学习与成长四个维度统计得分、权重与指标数量，并计算平均分。
  • 查询条件：支持按年度、月份、科室过滤，仅统计已确认的考核记录。
  • 聚合逻辑：按维度分组，计算加权总分、总权重、指标数量与平均分。
  • 输出格式：包含维度详情与统计周期。
flowchart TD
Start(["开始"]) --> BuildConditions["构建查询条件<br/>状态=FINALIZED<br/>可选: 年度/月份/科室"]
BuildConditions --> QueryGroup["按维度分组查询<br/>SUM(得分*权重)/SUM(权重)"]
QueryGroup --> Aggregate["聚合维度统计<br/>得分/权重/指标数/平均分"]
Aggregate --> FormatOutput["格式化输出<br/>包含周期信息"]
FormatOutput --> End(["结束"])

图表来源

章节来源

科室绩效统计

  • 功能：获取各科室的绩效统计，包括员工人数、总分、平均分、最高/最低分、员工列表。
  • 聚合逻辑：按科室汇总，计算平均分并按平均分降序排列。
  • 输出格式：包含科室基本信息与员工明细。
flowchart TD
Start(["开始"]) --> FilterFinalized["过滤已确认考核记录"]
FilterFinalized --> JoinTables["连接科室/员工/考核表"]
JoinTables --> GroupByDept["按科室分组聚合"]
GroupByDept --> CalcStats["计算员工数/总分/最高/最低分"]
CalcStats --> AvgScore["计算平均分"]
AvgScore --> Sort["按平均分降序排序"]
Sort --> Format["格式化输出"]
Format --> End(["结束"])

图表来源

章节来源

趋势分析

  • 功能：按月度统计平均分与加权平均分，支持指定最近N个月或按年份范围查询。
  • 时间处理：跨年处理，确保月份范围正确。
  • 输出格式：包含月份与对应的平均分。
flowchart TD
Start(["开始"]) --> SetPeriod["设置统计周期<br/>默认当前年份"]
SetPeriod --> MonthRange["计算最近N个月范围"]
MonthRange --> CrossYear{"是否跨年？"}
CrossYear --> |是| YearConditions["年份条件: 上一年>=起始月<br/>当年<=当前月"]
CrossYear --> |否| SameYear["年份条件: 当年且起止范围内"]
YearConditions --> QueryAvg["按月分组查询平均分"]
SameYear --> QueryAvg
QueryAvg --> Format["格式化输出"]
Format --> End(["结束"])

图表来源

章节来源

预警数据

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

章节来源

周期统计

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

章节来源

关键指标仪表盘

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

章节来源

收支趋势

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

章节来源

科室绩效排名

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

章节来源

个人绩效统计与对比分析

  • 功能：获取个人绩效排名，支持限制返回数量。
  • 实现：连接员工、科室、考核表，按加权平均分排序并标注排名。
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 : 标注排名序号

图表来源

章节来源

指标完成度

  • 功能：按指标统计平均分、最大/最小分、完成率等。
  • 计算逻辑：完成率=平均分/目标值×100%，上限100%。
  • 输出格式：包含指标基本信息与统计指标。

章节来源

依赖关系分析

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

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

图表来源

章节来源

性能考虑

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

章节来源

故障排除指南

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

章节来源

结论

统计报表接口实现了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
    • 返回：指标平均分、完成率等

章节来源

数据模型关系

erDiagram
DEPARTMENTS ||--o{ STAFF : "拥有"
STAFF ||--o{ ASSESSMENTS : "参与"
INDICATORS ||--o{ ASSESSMENT_DETAILS : "被评估"
ASSESSMENTS ||--o{ ASSESSMENT_DETAILS : "包含"
SALARY_RECORDS ||--|| STAFF : "关联"

图表来源

统计口径说明

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

章节来源

数据质量控制与异常检测

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

章节来源