文档库管理 —— 真实接口验证报告

验证日期：2026-09-17
验证对象：clinical-web 文档库管理（/management/documents）
数据来源：MEDISIGN 后端 https://ipad.shenynet.com（真实接口，VITE_MOCK_DOCUMENTS=false）
验证方式：真实浏览器（Chrome headless + CDP）驱动真实页面，非静态审查

1. 结论

文档库管理在真实接口下功能完整、闭环可用。

从「新增文书」到「发布」再到「发起签署」的完整链路全部走通，每一步后端均返回 200，页面运行时错误 0 条。

此前记录的「后端模板写接口作废（POST /v1/templates 稳定 500、列表恒 0 条）」已不成立，写接口已恢复正常。

2. 只读功能验证

功能	结果	说明
列表加载	通过	真实模板正确渲染，科室三级分组（科室 → 分类 → 文书）正常
科室页签	通过	按实际科室归类，无科室的模板归入「未指定科室」
状态页签	通过	按后端原始状态过滤，`PENDING_REVIEW` 与 `REJECTED` 未合并
搜索	通过	按名称/编号/科室过滤正确
预览弹窗	通过	正文真实取回（列表接口只给哈希，已正确补穿透版本详情）
预览 - 签署预览页签	通过	占位符按演示患者填充，渲染正常
编辑弹窗	通过	名称/编号/说明/正文全部正确带出
新增弹窗	通过	空表单；院区取真实 UUID；版本号显示「由后端按 vN 自动生成」
加载态/错误态	通过	有独立加载态与错误态，未把失败降级成空态

3. 写操作与版本工作流验证

新建测试文书「【自动化测试】签署链路验证」（编号 AUTO-TEST-800004）后逐步执行：

步骤	卡片动作	后端接口	状态变化
1	保存文书	`POST /v1/templates` + `POST /v1/templates/{id}/versions`	（新建）→ 草稿
2	提交审核	`POST .../versions/{vid}/submit-review`	草稿 → 待审核
3	驳回	`POST .../versions/{vid}/reject`	待审核 → 已驳回
4	重新提交	`POST .../versions/{vid}/submit-review`	已驳回 → 待审核
5	审核通过	`POST .../versions/{vid}/approve`	待审核 → 审核通过
6	发布	`POST .../versions/{vid}/publish`	审核通过 → 已发布
7	发起	`GET .../versions/{vid}`（取真实正文）	打开「新增签署任务」，模板已自动选中

驳回意见经 reject 的 comment 参数提交，用于留痕。

3.1 动作按钮文案随状态变化

前端按后端状态计算卡片主动作，文案不是固定值：

后端状态	卡片动作
`DRAFT`	提交审核
`PENDING_REVIEW`	审核通过 / 驳回
`REJECTED`	重新提交
`APPROVED`	发布
`PUBLISHED`	发起
`DISABLED`	重新启用

写自动化脚本或写测试用例时若写死「提交审核」，在后续步骤会全部点空。

3.2 工作流确认框的确认按钮文案

确认框的确认按钮文案等于动作名本身（「提交审核」「发布」「确认驳回」），不是「确定」。按 /确定|确认/ 匹配文字会点不到，应按 .el-button--primary 定位。

4. 接口调用清单（本次验证实际打到）

GET  /api/v1/auth/me
GET  /api/v1/campuses
GET  /api/v1/departments
GET  /api/v1/templates                      列表（分页拉全量）
GET  /api/v1/templates/{id}                 模板详情
GET  /api/v1/templates/{id}/versions        版本列表
GET  /api/v1/templates/{id}/versions/{vid}  版本详情（正文来源）
POST /api/v1/templates                      新建模板
POST /api/v1/templates/{id}/versions        新建版本
POST /api/v1/templates/{id}/versions/{vid}/submit-review
POST /api/v1/templates/{id}/versions/{vid}/reject
POST /api/v1/templates/{id}/versions/{vid}/approve
POST /api/v1/templates/{id}/versions/{vid}/publish

全部 200。

5. 已知限制与未覆盖项

5.1 入口未开放（既有设计，非本次回归）

版本历史：getTemplateVersions 与 DocumentVersionDialog 均已实现，但卡片上没有「版本」按钮（DocumentTemplateCard 中 showVersionAction = false），用户无法从 UI 进入。
下架 / 归档：同样没有按钮（showRemoveAction = false）。因此本次测试创建的文书无法通过 UI 清理，只能走接口归档。

5.2 混合模式下的模板树

当前本地配置为「文档库真实 + 签署工作台演示数据」。此配置下点「发起」，「新增签署任务」弹窗左侧的模板树仍为演示数据（含后端不存在的文书），仅从文档库带入的那一份是真实的。

原因：该弹窗调用 getSigningTemplates()，它读的是 mockFlags.signing。将签署端也切到真实接口后，该模板树才会只显示后端真实模板。

5.3 未验证项

手写板设备桥接、线上签署回调、打印服务（后端尚未提供，前端为占位）
模板包导出（showExportMessage 为占位提示，后端无对应接口）

6. 验证环境注意事项

供后续复现参考：

请求头是 X-Token，不是 Authorization: Bearer（见 utils/request.ts）。用 curl 直连后端调试时写错会得到 40100 请先登录，容易误判成 token 失效。
后端会话实际存活约 10 分钟，而登录响应里的 expiresAt 声明 2 小时。登录与验证必须串在同一条命令里执行（node scripts/login.cjs <code> && node <verify>.cjs），否则必然被踢回 /login，表现为「页面上找不到按钮」。
文档库的弹窗是自定义 .dialog-mask，不是 Element Plus 的 .el-dialog。关闭要点 .dialog-mask .close-button（预览 / Word 编辑器）或 .dialog-close（版本弹窗）。关不掉会导致下一个弹窗因 visible 未变化而不触发重置，造出「状态没重置」的假象。

7. 遗留测试数据

测试文书「【自动化测试】签署链路验证」（编号 AUTO-TEST-800004）当前为已发布状态，保留在联调环境以便继续验证发起签署。不需要时归档即可：

POST /api/v1/templates/{templateId}/versions/{versionId}/archive

6.3 KiB Raw Blame History Unescape Escape