hyb-oa/docs/trialrun-runbook.md

试运行与自动化验证 Runbook

文档状态：当前操作手册，用于本地、公网、企业微信和真实 OCR 试运行验证。

本文用于 hyb-oa 本地、企业微信和公网试运行。默认策略是：能自动化的先自动化，自动化无法覆盖的才请求人工配合。

入口顺序

1. 读取 AGENTS.md。
2. 读取最新 issues/*.csv。
3. 按任务读取事实源：
   • 设计：docs/product-design-rules.md
   • 报销发票：docs/reimbursement-invoice-rules.md
   • Agent 交付：docs/agent-development-practices.md
4. 检查 git status --short，保护用户已有改动。

本地验证

后端基础检查：

cd server && npm run prisma:validate
cd server && node --check src/routes/reimbursements.js
cd server && node --check src/routes/workflow.js

后端回归：

cd server && ./scripts/regression-workflow-actions.sh
cd server && ./scripts/regression-all.sh

若当前本地开发库存在 Prisma migration 漂移，禁止直接重置数据库。需要验证发票查重真实 HTTP 链路时，优先使用隔离临时库：

bash scripts/qa/check-local-migration-drift.sh
bash scripts/qa/run-isolated-regression-dedup.sh

check-local-migration-drift.sh 只读执行 prisma migrate status 并给出风险提示，不会执行 migrate reset。run-isolated-regression-dedup.sh 会创建临时 QA 数据库、执行迁移和种子、启动临时服务、运行 server/scripts/regression-dedup.sh，结束后默认删除临时库。若需要保留现场，可设置 QA_KEEP_DB=1。

前端检查：

cd client && npm run typecheck
cd client && npm run build

Playwright 视觉验证

页面或交互改动优先用 Playwright 验证：

• PC viewport: 1440x960。
• mobile viewport: 390x844。
• 企业微信 UA 使用 iPhone + wxwork 标识。
• 截图放在 output/playwright/<issue-id>/。

移动端必须检查：

• 没有桌面表格。
• scrollWidth <= viewportWidth + 2。
• 底部导航高度合理。
• 当前选中项不是黑色空心样式。
• 弹窗不会默认聚焦搜索框导致键盘弹出。
• 无明显文字截断、遮挡、按钮样式不一致。

企业微信验证

自动化可模拟企业微信 UA，但真实登录态仍以手机企业微信为准。

需要人工配合的节点：

• 企业微信后台应用主页、可信域名、回调域名、可见范围配置。
• 手机企业微信实际点击应用入口。
• 企业微信授权或绑定确认。

真机公网测试按 docs/trialrun/real-device-public-checklist.md 执行。可先生成报告模板：

node scripts/qa/create-real-device-report.mjs

公网 live smoke 和真实 OCR 准备按 docs/trialrun/live-smoke-readiness.md 执行：

node scripts/qa/check-live-smoke-env.mjs
LIVE_SMOKE_BASE_URL=https://oa.hyinda.com bash scripts/qa/run-live-smoke-readiness.sh

系统应避免让已绑定用户反复登录。若手机企业微信能进入但仍要求登录，优先检查：

• 回调 code 是否传到后端。
• 后端是否拿到 UserId。
• 本地账号是否绑定了企业微信 userId。
• cookie domain、SameSite、Caddy 反代头是否正确。

OCR 验证

先确认当前 OCR provider：

• mock 只用于自动化和本地回归。
• 腾讯 OCR 需要真实环境变量和网络。

发票上传问题排查顺序：

1. 上传接口是否成功返回 invoice id。
2. 发票是否进入 pending_ocr。
3. 单票识别任务是否立即入队，周期任务是否只作为兜底。
4. OCR job 是否运行。
5. OCR provider 是否为腾讯而不是 mock。
6. OCR 是否返回结构化字段。
7. 查重是否把发票转为不可添加。
8. 前端事件流或轮询兜底是否触发刷新。
9. 报销详情是否自动添加到明细。

发布前可执行 pending OCR 扫描，定位卡住的票据：

node scripts/qa/check-pending-ocr.mjs --thresholds=2,5,10

脚本只输出票据 ID、上传时间、尝试次数和最后错误摘要，不读取票据文件内容。缺少 DATABASE_URL 时应输出 SKIP，不视为真实数据库健康检查通过。

公网与部署

当前公网服务器信息以实际配置为准。已知历史信息：

• 服务器：118.89.77.218
• 反代：Caddy
• 域名示例：oa.hyinda.com

远端操作原则：

• 先备份配置和数据。
• 先确认远端目录是否为 git 工作树。
• 若远端不是 git 工作树，继续使用既有 rsync/部署脚本。
• 修改 Caddy、数据库、系统服务前必须先说明风险并等待确认。

数据库迁移漂移

如果 npx prisma migrate status 显示本地迁移历史和数据库迁移表分叉，不要自动修复。

必须暂停并让用户确认处理策略：

• 备份当前数据库。
• 对齐缺失 migration 文件。
• 或重建本地开发库并重新 seed。
• 或对生产/试运行库执行受控迁移。

禁止在未确认时执行：

• prisma migrate reset
• 删除迁移记录。
• 手工改生产表结构。
• 破坏性数据库命令。

收口标准

每轮交付收口至少包含：

• Issue CSV 状态真实。
• 自动化命令和结果记录在最终回复。
• 视觉截图路径记录。
• 已知阻塞明确归类为代码、测试、环境、数据或人工配置。
• 中文分批 commit。