Files

T

yelan fc22d22f85 feat(config): 按业务模块拆分 Mock 开关

用 VITE_MOCK_* 系列环境变量替换全局 VITE_USE_MOCK，各模块独立控制演示数据
启用，并新增 src/utils/mock-flags.ts 统一解析缺省值。文档库关闭演示库时
如实提示接口待接入，避免静默沿用本地数据或覆盖已保存内容。

2026-09-15 09:47:31 +08:00

6.0 KiB

Raw Blame History

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

核验基准：用户于 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，可在筛选栏增加格式选择而无需新增接口。

6.0 KiB Raw Blame History Unescape Escape