139 lines
5.9 KiB
Markdown
139 lines
5.9 KiB
Markdown
# 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`（插入字符后）。
|
||
|
||
## 踩过的坑
|
||
|
||
改脚本前先读这段，都是实际踩出来的。
|
||
|
||
### 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` 是临时文件，同样已忽略。
|