133 lines
6.3 KiB
Markdown
133 lines
6.3 KiB
Markdown
# 文档库管理 —— 真实接口验证报告
|
||
|
||
- 验证日期：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. 验证环境注意事项
|
||
|
||
供后续复现参考：
|
||
|
||
1. **请求头是 `X-Token`，不是 `Authorization: Bearer`**（见 `utils/request.ts`）。
|
||
用 curl 直连后端调试时写错会得到 `40100 请先登录`，容易误判成 token 失效。
|
||
2. **后端会话实际存活约 10 分钟**，而登录响应里的 `expiresAt` 声明 2 小时。
|
||
登录与验证必须串在同一条命令里执行（`node scripts/login.cjs <code> && node <verify>.cjs`），
|
||
否则必然被踢回 `/login`，表现为「页面上找不到按钮」。
|
||
3. 文档库的弹窗是自定义 `.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
|
||
```
|