yelan
fc22d22f85
用 VITE_MOCK_* 系列环境变量替换全局 VITE_USE_MOCK，各模块独立控制演示数据 启用，并新增 src/utils/mock-flags.ts 统一解析缺省值。文档库关闭演示库时 如实提示接口待接入，避免静默沿用本地数据或覆盖已保存内容。
72 lines
6.0 KiB
Markdown
72 lines
6.0 KiB
Markdown
# 报表分析接口核验与接入说明
|
||
|
||
> 核验基准：用户于 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，可在筛选栏增加格式选择而无需新增接口。
|