A1-A5 落地测试与交付规约

2026-05-10 09:45:58 +08:00
@@ -4,6 +4,8 @@

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

+测试分层、视觉验证、SKIP、状态回填和回归门禁的制度口径，以 [`docs/测试规约与回归门禁.md`](测试规约与回归门禁.md) 为准；本文只保留本地、公网、企业微信和真实 OCR 的操作步骤。
+
 ## 入口顺序

 1. 读取 `AGENTS.md`。
@@ -0,0 +1,128 @@
+# 开发交付与变更管理规约
+
+**文档状态**：当前开发交付事实源。
+**适用范围**：hyb-oa 所有非微小代码、文档、测试、脚本和部署准备变更。
+**路线口径**：开发必须围绕最新 Issue CSV 执行；hyb-oa 是唯一业务主系统，企业微信只做基础设施，飞书路线已废弃。
+
+本文回答“一个变更怎么开始、怎么审查、什么时候提交、怎么交付”。测试细节以 [测试规约与回归门禁](./测试规约与回归门禁.md) 为准。
+
+## 1. 交付循环
+
+标准循环固定为：
+
+`需求事实源 -> Issue CSV -> 方案批准 -> 开发实现 -> 自查 / review -> 测试回归 -> 状态回填 -> commit -> 部署准备 / 验收`
+
+不得跳过 Issue CSV 直接开发非微小变更。需求、方案或验收口径不清时，先澄清或补文档。
+
+## 2. Issue 生命周期
+
+| 状态 | 含义 | 可进入条件 |
+| --- | --- | --- |
+| `TODO` | 已规划但未开始 | Issue CSV 校验通过 |
+| `DOING` | 正在实现或验证 | 依赖 Issue 已满足，方案已批准 |
+| `DONE` | 对应阶段完成 | 有实际证据支撑，不靠口头判断 |
+
+三列状态含义固定：
+
+| 字段 | DONE 条件 |
+| --- | --- |
+| `Dev_Status` | 当前 Issue 范围内实现完成，基础静态检查或文档校验通过 |
+| `Review1_Status` | 自查或 review 完成，权限、状态、数据、体验和漏测无阻断 |
+| `Regression_Status` | `Test_Method` 通过，或按 SKIP 规则记录不可执行原因 |
+
+如果回归失败，不能把 `Regression_Status` 标为 `DONE`。如果发现范围外缺口，记录到 Notes 或新 Issue。
+
+## 3. 开发边界
+
+- 每次只做当前 Issue 范围内的事，不顺手重构无关模块。
+- 跨后端和前端的任务，先稳定后端 API / 数据契约，再接前端。
+- 涉及权限、状态机、审批规则、财务状态、Prisma migration 的改动，必须写明回滚策略。
+- 不在当前 MVP 首批范围内扩展预算、ERP、AI、飞书、企业微信原生审批、复杂 BPM 或重型项目管理。
+- 未经确认不得重置数据库、编辑迁移历史、修改生产配置、暴露真实密钥或处理真实敏感数据。
+
+## 4. Review 规则
+
+Review 不只看代码格式，优先检查行为风险：
+
+| 场景 | 必查项 |
+| --- | --- |
+| 权限和数据范围 | 普通员工、审批人、财务、管理员是否看到不该看的数据 |
+| workflow / 状态机 | 状态能否非法跳转，重复审批和并发处理是否安全 |
+| 财务和发票 | 重复发票、付款状态、导出、归档和人工例外是否可追溯 |
+| 企业微信入口 | 是否只做入口和通知，审批动作是否回 OA |
+| 前端入口和导航 | PC、手机、企业微信 UA 是否进入正确页面 |
+| 数据迁移 | 是否可回滚，是否有测试库验证，是否避免生产风险 |
+| 测试覆盖 | 是否覆盖主流程、异常、权限和视觉验证 |
+
+Review 发现阻断问题时，先修复并重跑相关验证，再回填状态。
+
+## 5. 提交规则
+
+一个 Issue 或一个清晰主题一个 commit。可以按以下粒度拆分：
+
+- 文档和 Issue CSV。
+- 后端规则、接口和服务。
+- 前端页面、入口和交互。
+- 测试、回归脚本和视觉验证。
+- 部署脚本或运行手册。
+
+commit message 使用中文并引用 Issue ID，例如：
+
+```text
+A4 收口企业微信入口与通知回 OA
+A3 修复报销发票 OCR 主链路状态
+A7 收口员工导航和备用模块护栏
+```
+
+不建议把多个高风险 Issue 合成一个 commit。回归失败、状态未回填或工作区含无关改动时，不提交完成型 commit。
+
+## 6. 工作区规则
+
+提交前必须检查：
+
+- `git status --short` 只包含当前 Issue 或本次提交主题相关文件。
+- `git diff --check` 通过。
+- Issue CSV 状态和 Notes 反映真实结果。
+- 未跟踪产物、截图、报告只在需要留证时保留；否则不混入 commit。
+- 用户或其他流程产生的无关改动不得回退、覆盖或顺手提交。
+
+如果发现无关改动：
+
+- 与当前任务无关：保留，不纳入本次提交。
+- 影响当前任务：先理解并兼容，必要时暂停确认。
+- 无法判断来源且有风险：暂停说明。
+
+## 7. 部署和可测试口径
+
+本地验证通过不等于已部署。最终说明必须区分：
+
+| 状态 | 能说什么 |
+| --- | --- |
+| 未部署 | 只能说本地验证通过，不能让用户去公网或企业微信真机测试 |
+| 已部署但未 smoke | 只能说部署完成待验证 |
+| `/ready` 和前端资源通过 | 可说明公网基础可访问 |
+| 企业微信真机通过 | 可说明企业微信入口可让用户测试 |
+| 真实 OCR 通过 | 可说明真实 OCR 链路可测 |
+
+公网、企业微信真机、真实 OCR 缺配置时按 SKIP 记录，不得假通过。
+
+## 8. 完成输出
+
+每个开发类任务完成时，最终输出至少包含：
+
+- 变更摘要。
+- 关联 Issue ID。
+- 验证命令和结果。
+- 是否提交 commit，commit hash。
+- 是否部署，公网和真机是否可测。
+- 残留风险、SKIP 项和下一步建议。
+
+如果没有运行某项测试，必须说明原因，而不是省略。
+
+## 9. 与其他文档的关系
+
+- `docs/海音达OA-MVP需求规格说明书.md` 定义开发项目流程和 MVP 业务目标。
+- `issues/*.csv` 是每轮执行合同。
+- `docs/测试规约与回归门禁.md` 定义测试、视觉验证和回归门禁。
+- `docs/trialrun-runbook.md` 定义本地、公网、企业微信和真实 OCR 的操作步骤。
+- `AGENTS.md` 定义不可违反的执行硬约束。
@@ -34,6 +34,8 @@
 | [产品口径文档](./product-decisions.md) | 已拍板的产品边界和业务规则 | 与 PRD 冲突时，以更新后的 PRD 和最新 Issue CSV 为准 |
 | [报销、发票与附件规则](./reimbursement-invoice-rules.md) | 报销、发票、OCR、附件的细则 | 报销相关开发必须同时参考 |
 | [产品设计规则基线](./product-design-rules.md) | PC、移动、企业微信 WebView 的视觉和交互规则 | 页面调整必须参考 |
+| [测试规约与回归门禁](./测试规约与回归门禁.md) | 当前测试事实源，固定自动化、视觉验证、真机 smoke、SKIP 和状态回填规则 | A3-A8 开发和后续非微小改动必须参考 |
+| [开发交付与变更管理规约](./开发交付与变更管理规约.md) | 当前开发交付事实源，固定 Issue 生命周期、review、commit、工作区和完成输出规则 | 提交和交付前必须参考 |
 | [AGENTS 项目规则](../AGENTS.md) | Agent 协作、Issue CSV、测试和提交规则 | 执行开发前必须遵守 |

 ## 当前操作手册
@@ -86,8 +88,9 @@
 2. 要细化审批、报销、企业微信、考勤修正、采购费用、合同归档或项目轻管理开发任务：读对应模块规约，再拆 `issues/*.csv`。
 3. 要开新开发任务：先读 PRD 第 2 章的软件开发项目流程，再更新需求或规则文档，并新建 `issues/*.csv`。
 4. 要看“某个业务规则为什么这么定”：读 [产品口径文档](./product-decisions.md) 和对应规则文档。
-5. 要判断功能是否已经做过：读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。
-6. 要上线或真机验收：读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、live smoke 清单和最新部署结果。
+5. 要判断测试、视觉验证、SKIP、状态回填和提交规则：读 [测试规约与回归门禁](./测试规约与回归门禁.md) 和 [开发交付与变更管理规约](./开发交付与变更管理规约.md)。
+6. 要判断功能是否已经做过：读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。
+7. 要上线或真机验收：读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、live smoke 清单和最新部署结果。

 ## 明确废弃或不进入首批

@@ -0,0 +1,118 @@
+# 测试规约与回归门禁
+
+**文档状态**：当前测试事实源。
+**适用范围**：hyb-oa MVP 首轮开发 A3-A8，以及后续所有非微小改动。
+**路线口径**：hyb-oa 是唯一业务主系统和唯一审批中心；企业微信只做入口、身份、通知和打卡原始采集；飞书和企业微信原生审批不进入当前路线。
+
+本文回答“什么时候测试、测什么、怎么判定通过、怎么记录跳过”。具体业务验收仍以主 PRD、模块规约和最新 Issue CSV 为准。
+
+## 1. 基本原则
+
+- 测试不是 A8 才开始；每个 Issue 完成开发后必须立即按 `Test_Method` 验证。
+- A8 是总回归和试运行门禁，用来证明 A2-A7 组合后仍然可用。
+- 自动化优先，自动化无法覆盖时必须写清人工步骤、执行人、环境和结论。
+- 测试失败不得假通过；必须先归类为代码问题、测试桩问题、环境问题、数据问题或人工配置问题。
+- 涉及公网、企业微信真机、真实 OCR、真实凭据时，只能在条件真实可用后给通过结论；缺配置必须标 `SKIP`。
+
+## 2. 测试分层
+
+| 层级 | 目标 | 典型手段 | 通过口径 |
+| --- | --- | --- | --- |
+| 静态检查 | 证明代码和配置可解析 | `prisma:validate`、`node --check`、`typecheck`、`build`、`git diff --check` | 命令退出码为 0 |
+| 单元测试 | 证明局部规则正确 | Vitest route/service/unit tests | 相关用例通过，新增规则有覆盖 |
+| 脚本回归 | 证明后端业务链路可跑通 | `regression-workflow-actions.sh`、`regression-dedup.sh`、`regression-ocr.sh`、`regression-all.sh` | 脚本成功，失败项可追溯 |
+| E2E | 证明真实页面流程可用 | Playwright PC、mobile、WeCom UA | 主流程完成，页面状态和接口状态一致 |
+| 视觉验证 | 证明页面可用且不割裂 | Playwright 截图、DOM 指标、人工审查 | 无桌面页误入手机、无明显遮挡和溢出 |
+| 真机 / 公网 smoke | 证明部署环境可用 | `/ready`、前端资源、企业微信真机、真实 OCR | 真实条件可用且记录证据；缺条件标 `SKIP` |
+| 人工验收 | 证明业务角色认可 | 员工、审批人、财务、管理员按清单操作 | 验收人确认或记录遗留问题 |
+
+## 3. Issue 内测试时机
+
+| 时机 | 必做动作 |
+| --- | --- |
+| 开发前 | 确认 Issue CSV 已写清 `Acceptance`、`Test_Method`、依赖和回滚说明 |
+| 后端改完 | 跑 Prisma 校验、相关 `node --check`、相关单测或回归脚本 |
+| 前端改完 | 跑 `typecheck`、`build`，涉及页面时跑相关 Playwright |
+| UI 或入口改完 | 做 PC、移动或企业微信 UA 视觉验证 |
+| Review 前 | 确认 diff 只包含当前 Issue 范围，失败测试已修复或明确阻塞 |
+| 回填 DONE 前 | `Test_Method` 已执行并通过，或有明确 SKIP 证据 |
+| Commit 前 | `git diff --check` 通过，Issue 状态和 Notes 已反映真实结果 |
+
+`Dev_Status=DONE` 表示开发完成且基础检查通过；`Review1_Status=DONE` 表示自查或 review 无阻断；`Regression_Status=DONE` 表示业务流程级验证通过或明确 SKIP。
+
+## 4. MVP 首轮测试矩阵
+
+| Issue | 自动化测试 | 视觉 / 入口验证 | 备注 |
+| --- | --- | --- | --- |
+| A3 报销发票 OCR 主链路 | `regression-dedup.sh`、`regression-ocr.sh`、报销主流程 E2E、发票 OCR E2E | PC 报销详情、移动报销、上传/OCR 状态、重复提示、付款/导出入口 | OCR 真实 provider 缺配置时标 `SKIP`，mock 只证明本地链路 |
+| A4 企业微信入口绑定通知回 OA | wecom auth 单测、notification dispatcher 单测、WeCom 入口 E2E | 登录页、未绑定提示、移动入口、WeCom UA deeplink | 真机企业微信验证留到 A8 |
+| A5 请假补卡外出加班与考勤口径 | leave route 语法、请假流程 E2E、团队日历 E2E | PC 请假、移动请假、团队状态或日历 | 不接企业微信打卡 API，不重造定位和人脸 |
+| A6 P1 采购合同项目最小可用 | procurement 回归、采购/项目 E2E、合同台账人工或 E2E | 采购申请、合同台账、项目详情 | 不扩展预算、ERP、AI、复杂招采 |
+| A7 权限导航与备用模块护栏 | `typecheck`、`build`、权限导航 E2E | 员工、主管、财务、管理员入口对比 | 前端隐藏不能替代服务端权限 |
+| A8 总回归门禁 | `regression-all.sh`、前端 build、web gates、live smoke env check | PC、移动、企业微信 UA 组合截图 | 未部署不得告知用户可公网或真机测试 |
+
+## 5. 视觉验证规则
+
+涉及 PC、手机或企业微信 WebView 的页面改动，默认补视觉验证。截图建议放在 `output/playwright/<issue-id>/`，文件名包含页面、角色和视口。
+
+| 场景 | 视口和入口 | 必查项 |
+| --- | --- | --- |
+| PC | 1440x960，普通浏览器 | 导航清晰、主流程入口可见、信息密度合适、无内部码值主展示 |
+| 手机 | 390x844，普通移动浏览器 | 无桌面宽表、无横向滚动、底部导航不遮挡、按钮可点 |
+| 企业微信 UA | iPhone + `wxwork` UA | 默认进入 `/mobile`，deeplink 回 OA，未绑定提示可理解 |
+| 弹窗 / 表单 | PC 和移动至少各一次 | 文字不截断、不遮挡、不会默认弹键盘影响首屏 |
+
+移动端硬性检查：
+
+- `scrollWidth <= viewportWidth + 2`。
+- 不出现 PC 侧边栏或桌面表格主体验。
+- 不把 UUID、内部状态码、技术错误作为主要展示文案。
+- 上传、提交、审批、付款等关键按钮状态清楚。
+- 异常提示能指导用户下一步操作。
+
+## 6. SKIP 规则
+
+只有确实缺少外部条件时才能标 `SKIP`。`SKIP` 不是通过，必须写清原因和后续补测条件。
+
+| 场景 | 可 SKIP 条件 | 必须记录 |
+| --- | --- | --- |
+| 企业微信真机 | 缺 CorpID、AgentID、可信域名、回调域名、可见范围或手机企业微信账号 | 缺哪个配置、自动化已覆盖哪些、A8 何时补 |
+| 真实 OCR | 缺腾讯 OCR 凭据、网络或真实样票授权 | 当前 provider、mock 覆盖范围、真实 OCR 补测步骤 |
+| 公网 smoke | 未部署或公网域名不可用 | 本地验证结果、部署前置条件 |
+| 生产数据验证 | 无授权、无脱敏样本或存在数据风险 | 不执行原因、需要谁批准 |
+
+## 7. 失败处理
+
+测试失败后先分类，再决定修复方式：
+
+| 分类 | 处理方式 |
+| --- | --- |
+| 代码问题 | 当前 Issue 内修复并重跑相关测试 |
+| 测试桩问题 | 修测试夹具或 mock，不能降低真实验收口径 |
+| 环境问题 | 记录环境差异，必要时重启本地服务或切换隔离测试库 |
+| 数据问题 | 使用 seed、隔离测试库或清理本轮产生的数据；不得直接重置生产库 |
+| 人工配置问题 | 记录缺失配置，A8 或部署阶段补测 |
+
+如果失败暴露出超出当前 Issue 的业务缺口，不能顺手扩大实现，应记录到 Notes 或新 Issue。
+
+## 8. 回填和证据
+
+Issue 状态回填必须基于证据：
+
+- `Dev_Status=DONE`：实现完成，静态检查或对应基础测试通过。
+- `Review1_Status=DONE`：自查或 review 已确认无阻断风险。
+- `Regression_Status=DONE`：流程级测试通过，或按 SKIP 规则记录不可执行原因。
+
+最终回复和 commit 前至少说明：
+
+- 改了什么，对应哪个 Issue。
+- 跑了哪些命令，结果如何。
+- 哪些测试 SKIP，原因是什么。
+- 是否部署；未部署时不得引导用户去公网或企业微信真机测试。
+
+## 9. 与其他文档的关系
+
+- 主 PRD 回答“做什么、为什么、如何验收”。
+- 本文回答“如何测试和何时可过门禁”。
+- `docs/trialrun-runbook.md` 回答“本地、公网、企业微信、真实 OCR 怎么操作”。
+- `docs/开发交付与变更管理规约.md` 回答“如何 review、提交和交付变更”。
@@ -66,6 +66,8 @@

 ### 2.1 本项目执行约束

+详细测试、视觉验证、SKIP、状态回填和回归门禁以 [测试规约与回归门禁](./测试规约与回归门禁.md) 为准；Issue 生命周期、review、commit、工作区和交付输出以 [开发交付与变更管理规约](./开发交付与变更管理规约.md) 为准。
+
 - 所有非微小改动必须先有需求事实源和 Issue CSV 执行合同。
 - 开发前必须说明实现方案；需求或方案不清时先澄清，不靠代码试错。
 - `Dev_Status`、`Review1_Status`、`Regression_Status` 只能在对应验证通过后更新为 `DONE`。
@@ -354,6 +356,7 @@ OA 是公司唯一正式审批中心。以下审批必须在 OA 内提交、审
 - 涉及后端时执行 Prisma、语法和相关回归脚本。
 - 涉及前端时执行 typecheck、build 和相关 Playwright。
 - 涉及公网或企业微信真机时，必须部署后检查 `/ready`、前端资源和真实入口。
+- 测试和提交证据必须符合 [测试规约与回归门禁](./测试规约与回归门禁.md) 与 [开发交付与变更管理规约](./开发交付与变更管理规约.md)。

 ---

@@ -0,0 +1,6 @@
+ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes
+A1,测试与交付流程现状确认,"审查当前 PRD、文档索引、试运行 Runbook、AGENTS 和 agent 交付实践，确认测试、视觉验证、提交和交付门禁的分散位置。","1) 确认现有文档已覆盖主开发流程；2) 确认缺口集中在测试规约和开发交付规约；3) 不新增业务范围。","流程级验证：只读核对 docs/文档索引.md、docs/海音达OA-MVP需求规格说明书.md、docs/trialrun-runbook.md、docs/agent-development-practices.md 和 AGENTS.md；命令：rg 检索 Test_Method、Regression_Status、视觉验证、commit、SKIP。","rg|manual",DONE,DONE,DONE,"docs/*.md|AGENTS.md","[]","已确认现有流程分散在 PRD、AGENTS、Runbook 和 agent 实践中；本轮只补测试与交付规约，不改业务代码。"
+A2,新增测试规约与回归门禁,"新增 docs/测试规约与回归门禁.md，固化自动化测试、视觉验证、真机 smoke、SKIP 和状态回填规则。","1) 明确每个 Issue 完成后立即测试，A8 只做总回归；2) 明确 A3-A8 测试矩阵；3) 明确视觉验证与 SKIP 规则；4) 明确测试失败归类和不可假通过。","流程级验证：人工检查文档能回答何时测、测什么、怎么记录 SKIP、何时可回填 DONE；命令：rg -n ""测试分层|A3|A8|视觉验证|SKIP|Regression_Status"" docs/测试规约与回归门禁.md。","manual|rg",DONE,DONE,DONE,"docs/测试规约与回归门禁.md","[""A1""]","已新增测试事实源；本 Issue 只改文档，不运行后端或前端构建。"
+A3,新增开发交付与变更管理规约,"新增 docs/开发交付与变更管理规约.md，固化 Issue 生命周期、review、提交拆分、工作区和完成输出规则。","1) 明确 TODO/DOING/DONE 条件；2) 明确一个 Issue 或清晰主题一个 commit；3) 明确重点 review 场景；4) 明确提交前工作区和完成报告要求。","流程级验证：人工检查文档能指导后续 A3-A8 开发提交；命令：rg -n ""TODO|DOING|DONE|commit|Review1_Status|工作区|部署"" docs/开发交付与变更管理规约.md。","manual|rg",DONE,DONE,DONE,"docs/开发交付与变更管理规约.md","[""A1""]","已新增开发交付事实源；未改 AGENTS 硬规则，后续如重复遗漏再同步 AGENTS 或 Skill。"
+A4,更新主 PRD 文档索引和 Runbook 引用,"把两份新规约挂接到当前事实源和当前操作手册入口，避免规则分散导致人工审查遗漏。","1) docs/文档索引.md 包含两份新规约入口；2) 主 PRD 软件开发流程和工程验收章节引用两份新规约；3) trialrun-runbook 保持操作手册定位，仅补引用。","流程级验证：rg 检查主 PRD、文档索引、Runbook 中包含两份规约链接；人工检查没有重新引入飞书、企业微信原生审批或扩大 A3-A8 范围。","manual|rg",DONE,DONE,DONE,"docs/文档索引.md|docs/海音达OA-MVP需求规格说明书.md|docs/trialrun-runbook.md","[""A2"",""A3""]","已更新 PRD、文档索引和 Runbook 引用；未移动或删除历史文档，未扩大业务范围。"
+A5,文档校验提交拆分和 A3 准备,"完成本轮文档治理校验并单独提交，为后续 A3 报销发票 OCR 主链路开发准备清晰门禁。","1) 新 Issue CSV 校验通过；2) git diff --check 通过；3) 引用检查通过；4) 文档治理作为独立 commit 提交；5) 工作区无非预期残留。","命令：python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-10_09-40-20-quality-gates-delivery-governance.csv；命令：git diff --check；命令：rg -n ""测试规约与回归门禁|开发交付与变更管理规约|Test_Method|Regression_Status|视觉验证|SKIP|commit"" docs issues/2026-05-10_09-40-20-quality-gates-delivery-governance.csv。","python3|git|rg|manual",DONE,DONE,DONE,"docs/*.md|issues/2026-05-10_09-40-20-quality-gates-delivery-governance.csv","[""A2"",""A3"",""A4""]","文档治理校验通过；本轮不部署；后续 A3 开发必须按新规约补测试、视觉验证、review 和 commit 证据。"