# 开发交付与变更管理规约

**文档状态**：当前开发交付事实源。
**分类**：开发治理。
**适用范围**：hyb-oa 所有非微小代码、文档、测试、脚本和部署准备变更。
**关联 Issue**：`GOV8,WDRG,WPROC1,WPROC2`。
**最近审计**：2026-05-19。
**不得误读**：本文定义开发和变更流程，不替代具体业务 PRD、模块规约或测试规约。
**路线口径**：开发必须围绕最新 Issue CSV 执行；WDRG 后企微优先 HR/考勤改造必须先读 [企微优先开发路线图](./企微优先开发路线图.md)，再按单功能 Issue CSV 实施。采购、合同、报销、财务、AP、代账和高敏附件继续 OA 主办，ERP 未来不接入 OA。

本文回答“一个变更怎么开始、怎么审查、什么时候提交、怎么交付”。测试细节以 [测试规约与回归门禁](./测试规约与回归门禁.md) 为准。

## 1. 交付循环

标准循环固定为：

`需求事实源 -> Issue CSV -> 方案批准 -> 开发实现 -> 自查 / review -> 测试回归 -> 状态回填 -> commit -> 部署准备 / 验收`

不得跳过 Issue CSV 直接开发非微小变更。需求、方案或验收口径不清时，先澄清或补文档。

WDRG 后，企微优先 HR/考勤改造增加一层路线图门禁；WAPI/WRRA 后，运行优先和 WOUA 差异收口成为深度镜像前置：

`需求事实源 -> 设计门禁 -> 路线图门禁 -> 企微能力 POC -> 单功能 Issue CSV -> 方案批准 -> 开发实现 -> review -> QA 回归 -> 部署 / 公网验证`

路线图只控制顺序、边界、准入和退出条件；具体接口、schema、页面、权限、审计和测试仍必须在单功能 Issue CSV 中声明。阶段未退出前不得跳阶段：WOUA-FIX 已完成测试账号差异收口，但 `PASS_WITH_FINDINGS` 的剩余缺字段/归档绑定不直接放行深度镜像；WRA1 已完成 `WECOM-RUNTIME-READY-V1` 的运行入口、OAuth/绑定、脱敏消息、通讯录、人事助手和打卡只读门禁修正；WMSG1 已完成真实应用消息和 Deeplink 确认。当前 `PASS_WITH_CONFIG_GAPS` 只表示运行优先主链路可用，WAPC1 只表示审批配置准备清单已固化；WAPC2 只证明请假/补卡模板详情和审批详情只读 runner 已具备。WAPC2FLIVE 已创建 OA-POC 请假/补卡测试样件并自动复跑 WAPC2 通过；WCBK1 已完成回调只读代码、synthetic 验签/解密/解析、真实 URL 验证和一条现有 OA-POC 测试审批单事件确认。审批镜像前仍必须先完成 WACP3 补偿拉取 POC 和 WADM1 镜像数据模型设计。

## 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。

### 2.1 连续型 Issue 策略

后续默认使用“少量长期连续合同 + 多行任务 + 阶段收口”，不再为每个小反馈、小链接修正或单点讨论新建 CSV。

| 治理流 | 覆盖范围 | 进入条件 |
| --- | --- | --- |
| `GOV8` | 文档、流程、审计、Issue 管理 | 材料散、权威不清、流程模板和审计问题 |
| `R7E` | 真实扩大试运行 | 用户确认参与人、窗口、回滚和每日收口后 |
| `ORG8` | 组织账号、角色、权限、企业微信绑定 | 组织主数据或权限边界问题 |
| `WF8` | 审批、通知、催办、转审 | 审批通知能力增强，但不涉及复杂 BPM |
| `BIZ8` | OCR、票据、财务、费用、项目轻量增强 | 业务主链路增强，但不涉及 ERP 或重预算 |
| `QAOPS8` | 测试、发布、运维、上线准备 | 回归、门禁、备份、SLO、发布问题 |

连续型 Issue 规则：

- 同类型、同目标、同风险域的问题进入同一个连续 CSV。
- 只有跨业务域、跨风险等级、跨里程碑，或当前治理流阶段性收口后，才新建下一版 CSV。
- 一个连续 CSV 内用领域前缀表达子类，例如 `GOV8-DOC-*`、`ORG8-PERM-*`、`WF8-NOTIFY-*`。
- 旧 Issue CSV 保留为历史审计证据，不删除、不批量回写、不移动到归档目录。
- 如果新治理流替代旧合同，只在新 CSV 的 `Notes` 或文档索引中说明 `supersedes`。
- 当前可执行合同只在 `docs/文档索引.md` 和 `docs/文档事实源状态矩阵.md` 中暴露，避免主入口被历史 Issue 淹没。
- 文档类变更优先更新现有事实源、模块规约、操作手册、证据文档或当前连续 Issue CSV；只有现有文档无法承载、需要独立审计证据或用户明确要求时，才新建文档。

### 2.2 需求冻结和变更请求

非微小需求必须先进入需求事实源和当前同类型连续 CSV。需求冻结后，新增想法默认进入后续池；只有同时满足以下条件，才允许并入当前轮：

- 不扩大当前治理流范围。
- 不改变已批准验收口径。
- 不引入新的权限、状态机、数据迁移或生产风险。
- 不增加未覆盖测试面。
- 不导致当前 `Test_Method` 失效。

变更请求至少写清：

| 字段 | 说明 |
| --- | --- |
| 变更原因 | 为什么现在提出 |
| 影响范围 | 影响哪些角色、流程、接口、页面、数据或文档 |
| 处理方式 | 替代原需求、追加当前行、进入同治理流后续行或进入下一阶段 |
| 测试影响 | 原测试是否仍有效，是否新增权限/视觉/公网/真机验证 |
| 回滚路径 | 如何撤销或延后 |

### 2.3 路线图门禁和单功能合同

WDRG 后，企微优先 HR/考勤路线采用“路线图门禁 + 单功能 Issue CSV”：

| 层级 | 作用 | 不承担 |
| --- | --- | --- |
| 路线图 | 固定阶段顺序、准入/退出门禁、并行规则和禁止跳过项 | 不写详细接口、schema、页面或迁移 |
| POC 合同 | 只读或低风险探测企微 API、配置、回调、模板和权限能力 | 不迁移运行时主流程 |
| 单功能合同 | 明确一个功能的接口、数据、权限、页面、审计、失败处理、测试和回滚 | 不顺手开发下一个阶段 |

当前企微优先路线顺序固定为：

`WECOM-CAPABILITY-POC-V1 -> wecom_hr_master_sync_v1 -> runtime_first_wecom_enablement -> WOUA-FIX / WECOM-RUNTIME-READY-V1 -> WAPC1 审批配置准备 -> WAPC2 请假/补卡只读 POC -> WAPC2F 自动生成 POC 样件 -> WAPC2FLIVE live 创建与 WAPC2 自动复跑 -> WCBK1 回调只读 POC（真实事件已确认） -> WACP3 补偿拉取 POC -> WADM1 镜像数据模型设计 -> wecom_attendance_approval_mirror_v1 -> oa_hr_emergency_mode_v1 -> wecom_recovery_writeback_v1 -> wecom_ruleops_v1`

允许并行处理线上缺陷、正式使用阻断、真实反馈扫尾和 QA-only 脚本维护；但采购、合同、报销、付款、AP、代账和高敏附件等 OA 主办域必须另开合同，不得混入企微 HR/考勤路线。

### 2.4 三层门禁

企微后续开发默认采用三层门禁：

| 门禁 | 作用 | 退出口径 |
| --- | --- | --- |
| 路线门禁 | 决定阶段顺序、禁止跳过项和是否允许并行 | 最新路线图、PRD 和 Issue CSV 不冲突 |
| 能力门禁 | 证明官方 API、Secret、权限、可信 IP、模板、回调和测试数据可用 | POC runner 返回 `PASS`、`NEEDS_CONFIG` 或真实 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG` |
| 实现门禁 | 控制代码、单测、回归、公网验证、状态回填和提交 | `Test_Method` 通过或真实 SKIP，事实源和 Issue 状态已回写 |

Definition of Ready：

- 已有 Issue CSV，且依赖项满足。
- 已读对应事实源、[企微优先开发路线图](./企微优先开发路线图.md) 和 [企微 API 能力目录](./企微API能力目录.md)。
- 明确做什么、不做什么、读写边界、Secret 来源和失败分类，不允许运行时猜 Secret。
- 明确测试账号、申请人、审批人和自审校验；审批类 POC 默认不得自己申请自己审批。
- 明确 live 写入开关、回滚或清理方式、脱敏报告边界和人工确认点。

Definition of Done：

- `Test_Method` 全部执行并真实通过，或按缺配置规则记录 `NEEDS_CONFIG` / `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`。
- Issue 状态和 Notes 反映实际结果，不用口头判断代替证据。
- 文档事实源、索引、矩阵和必要 skill 已同步。
- 本地门禁通过；面向公网或企微可测的能力已部署并通过 `/ready`、runtime smoke、public bundle scan 或对应 live runner。
- 已完成中文 commit，并在最终说明中区分“已部署”和“仅本地验证”。

自动化优先规则：

- 能用 runner 自动生成、自动检查、自动复跑的，不要求人工手动操作。
- 人工只处理写入批准、Secret/Token/EncodingAESKey 配置、企微后台无法 API 化的配置、真机确认和风险拍板。
- 缺配置必须输出 `NEEDS_CONFIG` 或 `SKIP/BLOCKED_BY_EXTERNAL_CONFIG`，不得伪造成 PASS。

WPROC2 后，三层门禁先由可执行 process gate 承接：

- 基线检查：`node scripts/qa/check-process-contract.mjs --baseline`。
- 单合同检查：`node scripts/qa/check-process-contract.mjs --issue <csv> --profile <profile> --json`。
- 首批 profile 为 `general`、`docs-only`、`wecom` 和 `wecom-approval-fixture`。
- WAPC2F 和后续高风险企微合同在实现前必须先通过 baseline gate 和对应 profile gate；`scripts/check-minimal.sh` 已接入 baseline gate。

高风险能力进入实现前必须先有 POC：

- 真实回调先证明 URL 验证、验签、解密、幂等和重复投递。
- 补偿拉取先证明按时间窗口拿到审批单号并可拉取审批详情。
- 镜像表先设计字段、状态机、幂等键、索引和隐私保留边界。
- 应急接管和恢复回写必须等镜像稳定后再做。

## 3. 开发边界

- 每次只做当前 Issue 范围内的事，不顺手重构无关模块。
- 跨后端和前端的任务，先稳定后端 API / 数据契约，再接前端。
- 涉及权限、状态机、审批规则、财务状态、Prisma migration 的改动，必须写明回滚策略。
- 不在当前 MVP 首批范围内扩展预算、ERP、AI 自动处理、飞书、复杂 BPM 或重型项目管理；ERP 未来不接入 OA。企业微信原生审批只按 WFOC/DBWFOC/WFDG/WDRG 口径用于 HR/考勤员工日常审批优先复用，不迁移报销、财务、采购、合同、项目或高敏附件等 OA 主办流程。后续企微/OA 运行时迁移先做 `WECOM-CAPABILITY-POC-V1`，再按 [企微优先开发路线图](./企微优先开发路线图.md) 拆单功能 Issue CSV 开发。
- 未经确认不得重置数据库、编辑迁移历史、修改生产配置、暴露真实密钥或处理真实敏感数据。

## 3.1 只读审计和排障边界

公网、数据库、日志和 MCP 排障默认按只读审计处理。需要生产数据核验、schema 比对、台账校验或线上排障时，先进入 `mode:audit-readonly` 或当前 Issue 的只读步骤，再确认工具边界。

- MCP 工具目录以 `docs/mcp-tools.md` 为事实源；若该文件不存在或未声明可用工具，视为 MCP 未启用。
- PostgreSQL MCP 只能使用 `postgres:query` 做 `SELECT`、schema、计数、汇总和账本核验，且必须使用只读账号和最小权限连接串。
- 禁止通过排障工具执行 `INSERT`、`UPDATE`、`DELETE`、DDL、迁移、状态修复、配置改写或任何会改变业务数据的操作。
- 日志、截图、查询结果和人工记录只能保留摘要、时间、责任人、命令或证据路径；不得把真实密码、token、连接串、票据图片、身份证号、手机号等敏感字段写入仓库。
- 需要展示真实数据时先脱敏，只保留问题定位所需的最小字段；无法脱敏时只写结论和外部安全存放位置。
- 如果排障结论需要写库、修复数据或改生产配置，必须停止只读流程，另开或更新当前连续 Issue，补方案、回滚路径和人工确认后再执行。

## 3.2 方案和计划模板

后续非微小变更在实施前必须至少给出以下轻量模板内容。模板可以写在回复、Issue CSV `Notes` 或对应规约中，但必须可审计。

### 需求整理模板

| 字段 | 要求 |
| --- | --- |
| 背景 | 真实反馈、试运行问题、业务制度或技术风险 |
| 目标角色 | 员工、审批人、财务、管理员、老板/负责人等 |
| 主流程 | 从发起到验收的业务路径 |
| 必须做 | 当前轮必须完成的行为 |
| 暂不做 | 明确冻结或后续池能力 |
| 验收口径 | 用户或自动化如何判断完成 |

### 设计方案模板

| 字段 | 要求 |
| --- | --- |
| 数据/API | 新增或变更的数据、接口、字段和兼容性 |
| 权限 | 服务端授权、角色边界、敏感字段和审计 |
| 状态流 | 状态转换、非法跳转、并发和重复提交 |
| 页面 | PC、移动、企业微信入口和视觉规则 |
| 异常 | 缺配置、失败、重试、SKIP 和用户提示 |
| 回滚 | 代码、配置、数据、迁移和发布回滚路径 |
| 测试影响 | 需要新增或复跑的验证 |

### 开发计划模板

| 字段 | 要求 |
| --- | --- |
| 治理流 | GOV8/R7E/ORG8/WF8/BIZ8/QAOPS8 |
| Issue 行 | 对应 CSV 行 ID |
| 文件范围 | `docs/`、`server/`、`client/`、`scripts/qa/` 等 |
| 依赖 | 前置 Issue 行和外部条件 |
| 交接物 | 代码、文档、脚本、API 契约、测试证据 |

### 测试方案模板

| 字段 | 要求 |
| --- | --- |
| 主流程 | 至少覆盖一个业务流程级验证 |
| 异常流程 | 权限不足、缺配置、失败、重复提交、撤回/驳回等 |
| 权限 | 普通员工、审批人、财务、管理员边界 |
| 视觉 | PC、移动、企业微信 UA 和关键视口 |
| 公网/真机 | `/ready`、public bundle、live readiness、真实 OCR、真机反馈 |
| SKIP 条件 | 只允许真实外部条件缺失时 SKIP，且必须记录补测条件 |

### 测试计划模板

| 字段 | 要求 |
| --- | --- |
| 执行时机 | 开发前、后端后、前端后、review 前、回填前、commit 前 |
| 命令 | 可复现命令或人工步骤 |
| 环境 | 本地、公网匿名、带凭据、企业微信真机 |
| 证据路径 | artifacts、output、报告、Issue CSV Notes |
| 负责人 | backend/frontend/qa/ops 或人工验收角色 |
| 阻断条件 | 哪些失败必须停止推进 |

## 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/试运行与自动化验证手册.md` 定义本地、公网、企业微信和真实 OCR 的操作步骤。
- `AGENTS.md` 定义不可违反的执行硬约束。