5.3 KiB
5.3 KiB
报表分析后端联调与验收说明
事实基准：用户于 2026-09-02 提供的 default_OpenAPI.json，OpenAPI 3.1.0，MEDISIGN 患者电子签 API v1。
本文记录当前契约的前端接入要求和联调检查项，不再把已经存在的报表接口标记为“建议新增”。
1. 当前契约与页面使用
| 接口 | 页面用途 | 状态 |
|---|---|---|
| GET /api/v1/reports/signing/options | 权限范围内的院区、科室、模板分类字典 | 前端已接入 |
| GET /api/v1/reports/signing/overview | 指标、签署趋势、科室分布 | 前端已接入 |
| GET /api/v1/reports/signing/tasks | 脱敏明细和服务端分页 | 前端已接入 |
| POST /api/v1/reports/signing/export-jobs | 创建 CSV/XLSX 异步导出任务 | 前端已接入，页面默认 CSV |
| GET /api/v1/reports/signing/export-jobs/{jobId} | 查询导出状态 | 前端已接入并轮询 |
| GET /api/v1/reports/signing/export-jobs/{jobId}/download | 下载已完成文件 | 前端已接入 |
页面真实模式通过统一 request 单例发送 /v1/...，由 /api base URL 形成完整路径，并自动携带 X-Token。Mock 模式不调用以上接口，继续使用报表页面自己的演示数据。
2. 后端必须保持的统计口径
- 时间区间为左闭右开 [from,to)，页面传 timezone=Asia/Shanghai；
- overview 的 createdFrom/To 只约束发起统计，signedFrom/To 约束签署完成和趋势，expiredFrom/To 约束超时统计；
- 页面明细和导出只传 createdFrom/To，以便待签署任务仍能出现在明细中；
- trend 必须按 signedAt 的业务时区自然日聚合，并包含零值日期；
- departments 必须按任务就诊科室返回，不能改用模板归属科室；
- onTimeRate 是 0-1 小数；无可靠样本返回 null；
- averageSignDurationSeconds 必须基于可靠的 signStartedAt/signedAt 或等价审计字段；无样本返回 null；
- CREATED、WAITING_SIGN、SIGNED、EXPIRED、VOIDED、GENERATING、FAILED 均需保持可区分。
3. 明细分页验收
tasks 请求使用 page、size、timeDimension=CREATED、sort=createdAt、direction=desc。后端应保证：
- page 从 1 开始，size 在 1-200 范围内；
- records、page、size、total、pages 在权限过滤后保持一致；
- 默认或指定排序稳定，不能在翻页时重复或遗漏；
- taskId、templateVersionId、campusId 等标识与返回展示字段属于同一条任务快照；
- patientNameMasked、patientDisplayId、patientMobileMasked 只能是报表级脱敏字段；
- templateName、templateCategory、campusName、departmentName 和 deadlineAt/signedAt/signDurationSeconds 能够覆盖历史任务，不能要求前端再查当前可见模板列表补齐。
4. 导出任务验收
创建导出任务时页面传当前筛选条件和 format=CSV，不传 page/size，因此结果应覆盖全部匹配记录，而不是当前明细页。后端需要：
- 创建、查询、下载时均重新检查操作人有效性、报表权限和数据范围；
- 支持 PENDING、RUNNING、SUCCEEDED、FAILED、EXPIRED；
- 文件生成完成后返回有效期和 resultCount；文件过期后拒绝下载；
- 下载响应返回文件流，不暴露 storage key；
- 导出列只包含当前角色允许查看的脱敏字段；
- 记录操作者、筛选条件摘要、结果数量、生成时间、过期时间和 traceId，但不记录身份证号、完整手机号、完整病历或签名原图。
5. 联调阻塞项与前端边界
代码已经按当前 OpenAPI 完成接入，以下事项需要实际后端环境确认：
- 六个报表路径已部署且当前角色有查询/导出权限；
- 统一响应的成功 code 为 0 或 "0"，业务数据放在 data；
- 对象 query 参数按 OpenAPI 默认 form/explode 方式接收为平铺字段；
- 401、403、400、404、429 和 500 的 HTTP/业务错误能够被网关正确转发；
- download 接口的响应类型为文件流，且允许当前前端通过同源 /api 访问。
当前页面没有新增报表详情接口：明细“查看”继续跳转签署工作台，由工作台已有任务详情和签署文件能力处理。页面筛选栏只暴露 CSV，若需要 XLSX 选择器，仅需增加前端控件并复用同一导出接口。
6. 建议联调用例
- 全院近 14 天：校验 overview、tasks 的请求参数和三类时间统计。
- 选择一个院区/科室/模板分类/签署方式并输入关键词：校验 options 联动和所有接口参数一致。
- 构造跨创建日完成签署的任务：确认趋势落在 signedAt 日期，而不是 createdAt 日期。
- 翻页、改变每页条数：确认 total/pages、排序和记录不重复。
- 创建导出任务并等待完成：确认状态轮询、文件下载、resultCount 和过期下载错误。
- 用无权限角色访问：确认查询和导出均得到 403，前端不显示越权数据。