# scripts

只用于本地开发与验证，不参与打包。

## verify-pages.cjs — 浏览器真实渲染验证

**为什么需要**：`lint` / `vue-tsc` / `build` 通过 ≠ 页面能跑。数据加载失败导致列表空白、
解析逻辑只处理部分数据、组件渲染时抛错，这些问题在类型检查里完全看不出来，
只有真实打开浏览器渲染才发现。

**用法**：

```bash
# 1. 起 dev server（另开一个终端）
npm run dev

# 2. 抓验证码图片，然后自己看图认出数字
node scripts/login.cjs
#    图片在 scripts/.captcha.png，例如显示 8944

# 3. 带验证码登录，会话写入 scripts/.session.json
node scripts/login.cjs 8944

# 4. 跑渲染验证：打开页面、截图、断言关键内容、收集运行时错误
node scripts/verify-pages.cjs
```

截图输出到仓库根目录的 `screenshots/`。

**环境变量**：

| 变量                                  | 默认值                                     | 说明                   |
| ------------------------------------- | ------------------------------------------ | ---------------------- |
| `VERIFY_URL`                          | `http://127.0.0.1:5173/`                   | 目标地址               |
| `VERIFY_ROUTES`                       | `/management/documents,/workbench/signing` | 要验证的路由，逗号分隔 |
| `VERIFY_OUT`                          | `<repo>/screenshots`                       | 截图输出目录           |
| `CHROME_PATH`                         | Chrome 默认安装路径                        | Chrome 可执行文件      |
| `VERIFY_USERNAME` / `VERIFY_PASSWORD` | `admin` / `admin`                          | 登录账号               |
| `VERIFY_BASE_URL`                     | `http://127.0.0.1:5173`                    | 登录接口所在地址       |

**依赖**：需要 `ws`（CDP 通信）。装到隔离 workspace，不要装进项目：

```bash
cd C:/Users/<you>/.workbuddy-ai/binaries/node/workspace
<node>/npm.cmd install ws
```

运行脚本时指定 `NODE_PATH` 指向该目录：

```bash
NODE_PATH=C:/Users/<you>/.workbuddy-ai/binaries/node/workspace/node_modules \
  node scripts/verify-pages.cjs
```

**验证真实模式**（关掉演示数据）另起一个 server：

```bash
VITE_MOCK_DOCUMENTS=false VITE_MOCK_SIGNING=false npx vite --port 5199
VERIFY_URL=http://127.0.0.1:5199/ node scripts/verify-pages.cjs
```

## verify-editor-marks.cjs — 占位符 / 勾选框胶囊验证

**为什么需要**：占位符胶囊（`utils/signing-editor-marks`）是**只改渲染、不改数据**的实现——
它靠 wangEditor 的 `decorate` 把文本切成叶子再挂样式。这种写法有两类问题编译期完全看不出来：

- 叶子切分 / 样式挂载没生效 → 胶囊根本没渲染出来（看起来"功能没做"）；
- 装饰破坏了 Slate 的光标偏移计算 → 点击胶囊后光标落点错位、编辑时字符插到别处。

所以必须真实打开编辑器，一边看渲染一边点进去打字。

**用法**（登录步骤同 `verify-pages.cjs`，注意端口要和实际 dev server 一致）：

```bash
node scripts/login.cjs              # 抓验证码，看图认数字
node scripts/login.cjs 8944         # 登录
VERIFY_URL=http://127.0.0.1:5174/ node scripts/verify-editor-marks.cjs
```

脚本会：打开文档库 → 新增文档（弹出 Word 编辑器）→ 依次插入 3 个占位符与 2 个勾选框 →
输出编辑区探针（胶囊数量/文案/配色/类型角标）与「占位符检查」面板文案 →
点进胶囊中部插入一个 `X`，验证字符确实落在占位符内部。

**两个关键断言**：

- `panelText` 显示「N 个填写项」——面板读的就是 `editor.getHtml()` 的序列化结果，
  能数出填写项即证明**底层仍是 `｛…｝` 纯文本**，保存 / 签署链路的口径没被改动；
- 点进胶囊后插入 `X` 得到 `｛患者X签名｝`——证明装饰没有破坏光标偏移计算。

截图：`04-editor-marks.png`（整窗）、`04b-editor-marks-zoom.png`（编辑区 4 倍放大，用来核对胶囊细节）、
`05-editor-marks-caret.png`（插入字符后）。

## verify-signature-click.cjs — 点击文中签名位采集签名

**为什么需要**：签名位的点击采集横跨三层（`utils/signing-document` 渲染 → `SigningDocumentInteractive`
事件委托 → 签署页弹窗与回灌），每一层都可能在编译期看不出问题：

- 渲染层挂了 `data-sign-action` 但没人监听 → 看着像按钮，点了没反应；
- 事件委托的 `closest()` 没做容器校验 → 容器外的事件也会误触发；
- 回灌走了「整篇重渲染」而不是就地改写 → 正在输入的填写项连同光标一起丢。

所以必须真的用鼠标点、真的在签字板上画一笔、再看签名图有没有回到那一个签名位上。

**用法**（登录步骤同上，端口要和实际 dev server 一致）：

```bash
node scripts/login.cjs              # 抓验证码，看图认数字
node scripts/login.cjs 8944         # 登录
VERIFY_URL=http://127.0.0.1:5173/ node scripts/verify-signature-click.cjs
```

脚本会：打开签署工作台 → 选一个「待签署」任务 → 输出签名位探针 → 真实点击「医师签名」→
在签字板上画一笔并确认 → 复检回显与页脚提示 → 用键盘 `Enter` 触发「患者签名」的采集入口。

**关键断言**：

- 空签名位必须同时有 `data-sign-action=signature`、`role=button`、`tabindex=0`、
  `cursor: pointer` 与 `✍ 点击签名` 文案——少一样就是「看着能点其实不能点」；
- 采集后该签名位出现 `img.sign-doc-signature` 且 `src` 是 `data:image/png`，
  同时采集入口被摘掉（`data-sign-action` 与 `sign-field--actionable` 都消失）；
- **患者签名位的采集入口不能被误伤**——医师签名采完，患者签名还得能点；
- 页脚不再把已采集的签名位列进「还有签名位待采集」。

截图：`06-signature-actions.png`（初始：两个签名位都是可点入口）、
`07-signature-dialog.png`（弹窗标题指向被点的签名位）、`08-signature-applied.png`（回显 + 页脚更新）、
`09-signature-keyboard.png`（键盘触发）。

## 踩过的坑

改脚本前先读这段，都是实际踩出来的。

### 1. 登录不要 stub，走真实登录

MEDISIGN 后端对无效 token 返回 **401**，而 `utils/request.ts` 的响应拦截器收到 401 会
`clearAuthStorage()` + 跳登录页。伪造会话很容易被踢出去。

如果确实要 stub XHR（比如只想验证某个组件），**必须实现完整响应**：
`getAllResponseHeaders` / `getResponseHeader` / `onloadend` 一个都不能少。
只设 `responseText` 会让 axios 在解析响应头时抛错、**Promise 永不 settle**，
路由守卫的 `await` 一直挂着 → `#app` 只剩 `<!---->`、**整页空白**。
这个现象极易被误判成「页面渲染挂了」，实际是验证脚本自己的 bug。

### 2. 验证码是强制的

不传 `captchaId` / `captchaCode` 会报「验证码错误或已过期」。
验证码有时效，抓图和登录要连着做。

### 3. CDP 连续导航在 SPA 里不可靠

`Page.navigate` 连续调用时：

- `pushState` 跳转**不触发** `Page.loadEventFired`
- 轮询 `document.readyState` 会立刻通过，但读到的是**旧文档**

结果就是断言拿到上一个页面的内容，看起来像「导航了但没渲染」。

正确做法（脚本已采用）：只做**一次**整页 `Page.navigate`，后续切页取

```js
document.getElementById('app').__vue_app__.config.globalProperties.$router
```

调 `router.push()`。注意 `history.pushState` + 手动派发 `popstate` 对 Vue Router **无效**。

### 4. 文件用 .cjs 后缀

`package.json` 里有 `"type": "module"`，`.js` 会被当成 ES 模块，
而这里用 `require` 更简单，所以显式声明成 CommonJS。

## 安全提醒

`scripts/.session.json` 里是**真实 token**，已在 `.gitignore` 中忽略，**不要提交**。
`.captcha.json` / `.captcha.png` 是临时文件，同样已忽略。