chore(report): 下线「系统管理 → 报表分析」菜单及其接口与开关
This commit is contained in:
yelan
@@ -1,71 +0,0 @@
|
||||
# 报表分析接口核验与接入说明
|
||||
|
||||
> 核验基准：用户于 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，可在筛选栏增加格式选择而无需新增接口。
|
||||
@@ -1,72 +0,0 @@
|
||||
# 报表分析后端联调与验收说明
|
||||
|
||||
> 事实基准：用户于 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. 建议联调用例
|
||||
|
||||
1. 全院近 14 天：校验 overview、tasks 的请求参数和三类时间统计。
|
||||
2. 选择一个院区/科室/模板分类/签署方式并输入关键词：校验 options 联动和所有接口参数一致。
|
||||
3. 构造跨创建日完成签署的任务：确认趋势落在 signedAt 日期，而不是 createdAt 日期。
|
||||
4. 翻页、改变每页条数：确认 total/pages、排序和记录不重复。
|
||||
5. 创建导出任务并等待完成：确认状态轮询、文件下载、resultCount 和过期下载错误。
|
||||
6. 用无权限角色访问：确认查询和导出均得到 403，前端不显示越权数据。
|
||||
Reference in New Issue
Block a user