# 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
```

## 踩过的坑

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

### 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` 是临时文件，同样已忽略。