8.0 KiB
scripts
只用于本地开发与验证，不参与打包。
verify-pages.cjs — 浏览器真实渲染验证
为什么需要：lint / vue-tsc / build 通过 ≠ 页面能跑。数据加载失败导致列表空白、
解析逻辑只处理部分数据、组件渲染时抛错，这些问题在类型检查里完全看不出来，
只有真实打开浏览器渲染才发现。
用法：
# 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，不要装进项目：
cd C:/Users/<you>/.workbuddy-ai/binaries/node/workspace
<node>/npm.cmd install ws
运行脚本时指定 NODE_PATH 指向该目录：
NODE_PATH=C:/Users/<you>/.workbuddy-ai/binaries/node/workspace/node_modules \
node scripts/verify-pages.cjs
验证真实模式（关掉演示数据）另起一个 server：
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 一致）：
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 一致）：
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，后续切页取
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 是临时文件，同样已忽略。