7.9 KiB
试运行与自动化验证 Runbook
文档状态：当前操作手册，用于本地、公网、企业微信和真实 OCR 试运行验证。
当前状态（2026-05-12 / DOCG7）：R6 已通过；R7 未真实启动，R7/OPS7/DOC7 只是准备材料，不代表已启动或已上线；ME6-3 代表性企业微信真机门禁仍待确认；MIF7 是下一批移动信息架构整改合同，尚未完成。自动化、QG6 和公网视觉矩阵不能替代代表性真机验收。
本文用于 hyb-oa 本地、企业微信和公网试运行。默认策略是：能自动化的先自动化，自动化无法覆盖的才请求人工配合。
测试分层、视觉验证、SKIP、状态回填和回归门禁的制度口径，以 docs/测试规约与回归门禁.md 为准；本文只保留本地、公网、企业微信和真实 OCR 的操作步骤。
入口顺序
- 读取
AGENTS.md。 - 读取最新
issues/*.csv。 - 按任务读取事实源：
- 设计：
docs/产品设计规则.md - 报销发票：
docs/报销发票附件规则.md - Agent 交付：
docs/Agent开发交付实践.md
- 设计：
- 检查
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；涉及移动布局、企业微信或 R6 移动反馈时必须扩展到 320x568、360x740、375x667、390x844、393x873、414x896、430x932。
- 企业微信 UA 使用 iPhone +
wxwork标识。 - 截图放在
output/playwright/<issue-id>/。
移动端必须检查：
- 没有桌面表格。
scrollWidth <= viewportWidth + 2。- 底部导航高度合理，四个 Tab 中心点
elementFromPoint命中自身或子元素。 - 当前选中项不是黑色空心样式。
- 弹窗不会默认聚焦搜索框导致键盘弹出。
- 无明显文字截断、遮挡、按钮样式不一致。
- 首页一级入口使用图标宫格时，图标、标题和容器不重叠，标题不逐字换行。
- 深层 Push 页隐藏底部 Tab，使用顶部返回；吸底主操作不遮挡内容。
- 移动验收采用“跨视口自动化 + 代表性真机确认”：自动化证明响应式基线，iPhone 11、Redmi K60 或同类代表设备确认真实企业微信 WebView 行为。
企业微信验证
自动化可模拟企业微信 UA，但真实登录态仍以手机企业微信为准。
需要人工配合的节点：
- 企业微信后台应用主页、可信域名、回调域名、可见范围配置。
- 手机企业微信实际点击应用入口。
- 企业微信授权或绑定确认。
真机公网测试按 docs/trialrun/真机公网测试清单.md 执行。可先生成报告模板：
node scripts/qa/create-real-device-report.mjs
真机验证状态允许使用：
PASS：代表性真机和必要人工确认均通过。FAIL：真机复现阻断或严重问题，必须登记设备、账号、URL、步骤和证据位置。BLOCKED：缺少测试账号、企业微信后台配置、样票或网络等前置条件。PAUSED：用户或现场条件暂停验证；自动化通过也不能据此关闭真机门禁或把相关 Issue 标为完成。
公网 live smoke 和真实 OCR 准备按 docs/trialrun/公网LiveSmoke准备清单.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
发布候选进入公网或小范围试运行前，先按 docs/trialrun/发布试运行准备清单.md 完成证据整理、权限直连审计、部署预检、live smoke 和试运行分级。
系统应避免让已绑定用户反复登录。若手机企业微信能进入但仍要求登录，优先检查：
- 回调 code 是否传到后端。
- 后端是否拿到
UserId。 - 本地账号是否绑定了企业微信 userId。
- cookie domain、SameSite、Caddy 反代头是否正确。
OCR 验证
先确认当前 OCR provider：
mock只用于自动化和本地回归。- 腾讯 OCR 需要真实环境变量和网络。
发票上传问题排查顺序：
- 上传接口是否成功返回 invoice id。
- 发票是否进入
pending_ocr。 - 单票识别任务是否立即入队，周期任务是否只作为兜底。
- OCR job 是否运行。
- OCR provider 是否为腾讯而不是 mock。
- OCR 是否返回结构化字段。
- 查重是否把发票转为不可添加。
- 前端事件流或轮询兜底是否触发刷新。
- 报销详情是否自动添加到明细。
发布前可执行 pending OCR 扫描，定位卡住的票据：
node scripts/qa/check-pending-ocr.mjs --thresholds=2,5,10
脚本只输出票据 ID、上传时间、尝试次数和最后错误摘要，不读取票据文件内容。缺少 DATABASE_URL 时应输出 SKIP，不视为真实数据库健康检查通过。
发布候选本地门禁
首轮主线 A8 复跑本地门禁时，需要先用本地回归参数启动服务，再执行回归脚本。推荐参数：
SERVE_CLIENT_DIST=true
OCR_PROVIDER=mock
IM_NOTIFIER_ENABLED=true
FIELD_ENCRYPTION_KEY=<local-test-key>
PROJECT_DOMAIN_ENABLED=true
PROJECT_LINKING_ENABLED=true
PROJECT_COMMUNICATION_LOG_ENABLED=true
PROJECT_CLOSURE_CHECKLIST_ENABLED=true
注意：
FIELD_ENCRYPTION_KEY只允许使用本地测试值；生产密钥不得提交或写入文档。OCR_PROVIDER=mock只证明本地 OCR 流程，不代表真实 OCR provider 通过。IM_NOTIFIER_ENABLED=true用于覆盖通知链路；缺真实企业微信配置时，企业微信真机仍必须标SKIP。- 项目相关开关用于本地项目轻管理回归，不得被解释为扩展 P2 范围。
公网与部署
当前公网服务器信息以实际配置为准。已知历史信息：
- 服务器：
118.89.77.218 - 反代：Caddy
- 域名示例：
oa.hyinda.com
远端操作原则：
- 先备份配置和数据。
- 先确认远端目录是否为 git 工作树。
- 若远端不是 git 工作树，继续使用既有 rsync/部署脚本。
- 修改 Caddy、数据库、系统服务前必须先说明风险并等待确认。
数据库迁移漂移
如果 npx prisma migrate status 显示本地迁移历史和数据库迁移表分叉，不要自动修复。
必须暂停并让用户确认处理策略：
- 备份当前数据库。
- 对齐缺失 migration 文件。
- 或重建本地开发库并重新 seed。
- 或对生产/试运行库执行受控迁移。
禁止在未确认时执行：
prisma migrate reset- 删除迁移记录。
- 手工改生产表结构。
- 破坏性数据库命令。
收口标准
每轮交付收口至少包含：
- Issue CSV 状态真实。
- 自动化命令和结果记录在最终回复。
- 视觉截图路径记录。
- 已知阻塞明确归类为代码、测试、环境、数据或人工配置。
- 中文分批 commit。