148 行
4.3 KiB
Markdown
148 行
4.3 KiB
Markdown
# 试运行与自动化验证 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
|
||
```
|
||
|
||
若当前本地开发库存在 Prisma migration 漂移，禁止直接重置数据库。需要验证发票查重真实 HTTP 链路时，优先使用隔离临时库：
|
||
|
||
```bash
|
||
bash scripts/qa/run-isolated-regression-dedup.sh
|
||
```
|
||
|
||
该脚本会创建临时 QA 数据库、执行迁移和种子、启动临时服务、运行 `server/scripts/regression-dedup.sh`，结束后默认删除临时库。若需要保留现场，可设置 `QA_KEEP_DB=1`。
|
||
|
||
前端检查：
|
||
|
||
```bash
|
||
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`](trialrun/real-device-public-checklist.md) 执行。可先生成报告模板：
|
||
|
||
```bash
|
||
node scripts/qa/create-real-device-report.mjs
|
||
```
|
||
|
||
系统应避免让已绑定用户反复登录。若手机企业微信能进入但仍要求登录，优先检查：
|
||
|
||
- 回调 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。
|