# 试运行与自动化验证 Runbook 本文用于 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`，保护用户已有改动。 ## 本地验证后端基础检查： ```bash cd server && npm run prisma:validate cd server && node --check src/routes/reimbursements.js cd server && node --check src/routes/workflow.js ``` 后端回归： ```bash cd server && ./scripts/regression-workflow-actions.sh cd server && ./scripts/regression-all.sh ``` 前端检查： ```bash cd client && npm run typecheck cd client && npm run build ``` ## Playwright 视觉验证页面或交互改动优先用 Playwright 验证： - PC viewport: 1440x960。 - mobile viewport: 390x844。 - 企业微信 UA 使用 iPhone + `wxwork` 标识。 - 截图放在 `output/playwright//`。移动端必须检查： - 没有桌面表格。 - `scrollWidth <= viewportWidth + 2`。 - 底部导航高度合理。 - 当前选中项不是黑色空心样式。 - 弹窗不会默认聚焦搜索框导致键盘弹出。 - 无明显文字截断、遮挡、按钮样式不一致。 ## 企业微信验证自动化可模拟企业微信 UA，但真实登录态仍以手机企业微信为准。需要人工配合的节点： - 企业微信后台应用主页、可信域名、回调域名、可见范围配置。 - 手机企业微信实际点击应用入口。 - 企业微信授权或绑定确认。系统应避免让已绑定用户反复登录。若手机企业微信能进入但仍要求登录，优先检查： - 回调 code 是否传到后端。 - 后端是否拿到 `UserId`。 - 本地账号是否绑定了企业微信 userId。 - cookie domain、SameSite、Caddy 反代头是否正确。 ## OCR 验证先确认当前 OCR provider： - `mock` 只用于自动化和本地回归。 - 腾讯 OCR 需要真实环境变量和网络。发票上传问题排查顺序： 1. 上传接口是否成功返回 invoice id。 2. 发票是否进入 `pending_ocr`。 3. OCR job 是否运行。 4. OCR provider 是否为腾讯而不是 mock。 5. OCR 是否返回结构化字段。 6. 查重是否把发票转为不可添加。 7. 前端状态查询是否轮询并刷新。 8. 报销详情是否自动添加到明细。 ## 公网与部署当前公网服务器信息以实际配置为准。已知历史信息： - 服务器：`118.89.77.218` - 反代：Caddy - 域名示例：`oa.hyinda.com` 远端操作原则： - 先备份配置和数据。 - 先确认远端目录是否为 git 工作树。 - 若远端不是 git 工作树，继续使用既有 rsync/部署脚本。 - 修改 Caddy、数据库、系统服务前必须先说明风险并等待确认。 ## 数据库迁移漂移如果 `npx prisma migrate status` 显示本地迁移历史和数据库迁移表分叉，不要自动修复。必须暂停并让用户确认处理策略： - 备份当前数据库。 - 对齐缺失 migration 文件。 - 或重建本地开发库并重新 seed。 - 或对生产/试运行库执行受控迁移。禁止在未确认时执行： - `prisma migrate reset` - 删除迁移记录。 - 手工改生产表结构。 - 破坏性数据库命令。 ## 收口标准每轮交付收口至少包含： - Issue CSV 状态真实。 - 自动化命令和结果记录在最终回复。 - 视觉截图路径记录。 - 已知阻塞明确归类为代码、测试、环境、数据或人工配置。 - 中文分批 commit。