# 报表分析接口核验与接入说明

> 核验基准：用户于 2026-09-02 提供的 default_OpenAPI.json，OpenAPI 3.1.0，MEDISIGN 患者电子签 API v1。
>
> 页面实现：src/views/management/reports/index.vue；API 封装：src/api/management/reports.ts。

## 1. 结论

最新接口文档已经提供完整的签署报表资源。本轮已将报表页从“读取全部签署任务后前端聚合”切换为服务端报表接口：

- 概览指标、签署趋势和科室分布由 overview 返回；
- 明细由 tasks 服务端分页返回；
- 院区、科室和模板分类由 options 返回；
- 导出改为服务端异步任务，完成后下载文件；
- 打开 `VITE_MOCK_REPORTS` 时仍保留原有 Mock 演示数据；该开关缺省关闭，报表默认走服务端报表接口。

## 2. 接入矩阵

| 页面功能       | HTTP 接口                                                | 接入状态 | 前端使用方式                                                                                                  |
| -------------- | -------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| 筛选字典       | GET /api/v1/reports/signing/options                      | 已接入   | 使用当前操作者有权访问的院区、科室和模板分类；科室随院区筛选联动                                              |
| 概览指标       | GET /api/v1/reports/signing/overview                     | 已接入   | 使用 initiatedCount、signedCount、onTimeRate、averageSignDurationSeconds                                      |
| 签署趋势       | GET /api/v1/reports/signing/overview                     | 已接入   | 使用 trend[].date/label/signedCount，不再用 createdAt 代替 signedAt                                           |
| 科室分布       | GET /api/v1/reports/signing/overview                     | 已接入   | 使用 departments[].departmentName/signedCount                                                                 |
| 明细列表       | GET /api/v1/reports/signing/tasks                        | 已接入   | 使用 records/page/size/total/pages，翻页和每页条数均请求服务端                                                |
| 明细状态和时间 | GET /api/v1/reports/signing/tasks                        | 已接入   | 映射全部 CREATED/WAITING_SIGN/SIGNED/EXPIRED/VOIDED/GENERATING/FAILED，展示脱敏患者、发起时间、完成时间和耗时 |
| 创建导出任务   | POST /api/v1/reports/signing/export-jobs                 | 已接入   | 复用当前筛选条件，默认请求 CSV，不传分页参数以导出全部匹配结果                                                |
| 导出状态       | GET /api/v1/reports/signing/export-jobs/{jobId}          | 已接入   | 轮询 PENDING/RUNNING，处理 SUCCEEDED/FAILED/EXPIRED                                                           |
| 下载导出文件   | GET /api/v1/reports/signing/export-jobs/{jobId}/download | 已接入   | 以 Blob 下载服务端生成文件                                                                                    |
| 明细查看       | 工作台签署任务路由                                       | 已保留   | 点击行跳转工作台，由工作台查询任务详情和签署文件                                                              |

所有真实请求都通过 src/utils/request.ts 的单例发送，路径使用 /v1/...，由默认 /api 前缀形成 /api/v1/...，鉴权沿用 X-Token。

## 3. 参数和统计口径

页面固定传 timezone=Asia/Shanghai，日期区间按左闭右开 [from,to) 转成带 +08:00 的 UTC ISO 时间：

- 7d、14d、month 和自定义日期都生成明确的起止时间；
- overview 同时传 createdFrom/To、signedFrom/To、expiredFrom/To，让发起、签署完成和超时统计使用各自业务时间；
- tasks 和导出只传 createdFrom/To，保证待签署任务不会因缺少 signedAt 或 expiredAt 被时间条件排除；
- 院区、科室、模板分类、签署方式和关键词分别映射为 campusId、departmentId、templateCategory、signMethod、keyword；
- tasks 使用 page、size、timeDimension=CREATED、sort=createdAt、direction=desc。

后端返回的 onTimeRate 按契约是 0-1 小数，前端展示为百分比；无样本的 onTimeRate 和无可靠样本的平均耗时保持为 —。真实签署耗时优先使用 signDurationSeconds，不会用固定演示数字代替。

## 4. 状态和脱敏映射

| 后端状态              | 页面状态 |
| --------------------- | -------- |
| CREATED、WAITING_SIGN | 待签署   |
| GENERATING            | 签署中   |
| SIGNED                | 已签署   |
| EXPIRED               | 已超时   |
| VOIDED                | 已作废   |
| FAILED                | 处理失败 |

明细使用 patientNameMasked 和 patientDisplayId，不补查或展示身份证号、完整手机号、完整病历或签名原图。模板、院区和科室直接使用报表 DTO 返回的快照字段，不再通过当前可见模板列表猜测历史分类。

## 5. 联调时需要确认的事项

接口已经按文档接入，但页面能否显示真实数据仍取决于后端环境：

- 六个报表路径都已部署在 /api/v1，并允许当前角色访问；
- 成功响应使用统一包装，code=0 或 "0"，业务数据位于 data；
- options、overview 和 tasks 的对象查询参数按 OpenAPI 默认 form/explode 方式接收为平铺参数；
- overview 的 trend 按 signedAt、超时按 expiredAt，并返回包含零值日期的趋势；
- tasks 的权限过滤在分页前执行，total/pages 与 records 一致，排序稳定；
- 导出任务创建、状态查询和下载都重新校验权限，文件有效期和过期错误符合契约；
- 真实环境的 Network 请求需确认 401/403/400 能被网关和统一响应正确返回。

当前页面的导出按钮只暴露 CSV；API DTO 已支持 CSV/XLSX，若产品需要 XLSX，可在筛选栏增加格式选择而无需新增接口。