20 KiB
开发交付与变更管理规约
文档状态：当前开发交付事实源。
分类：开发治理。
适用范围：hyb-oa 所有非微小代码、文档、测试、脚本和部署准备变更。
关联 Issue：GOV8,WDRG,WPROC1,WPROC2,WEGOV1。
最近审计：2026-05-19。
不得误读：本文定义开发和变更流程，不替代具体业务 PRD、模块规约或测试规约。
路线口径：开发必须围绕最新 Issue CSV 执行；WDRG/WEGOV1 后企微优先 HR/考勤改造必须先读 企微优先开发路线图，再按单功能 Issue CSV 实施。企微成熟功能优先上线，OA 做自建留存、审计、入口、消息和应急兜底；采购、合同、报销、财务、AP、代账和高敏附件继续 OA 主办，ERP 未来不接入 OA。
本文回答“一个变更怎么开始、怎么审查、什么时候提交、怎么交付”。测试细节以 测试规约与回归门禁 为准。
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 测试审批单事件确认；WACP3R 已完成补偿拉取公网只读复跑，当时发现的回调证据未持久化已由 WARCH1 DB 回调事件承接；WREAD1 已完成请假/补卡真机可读性确认，结论 PASS_READABLE，同意单击风险进入后续设计。WEGOV1 后，WADM1/WARCH1/WARCH2 已完成模型设计、最小历史留存和正式只读查询；WROAD2+OPS 只做测试账号受控上线和每日巡检，完整审批镜像仍必须另建合同。
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（真实事件已确认） -> WEGOV1 企微主办治理与自建留存路线修正 -> WACP3/WACP3R 补偿拉取 POC -> WREAD1 审批可读性与误审批防护门禁 -> WADM1 自建留存/镜像数据模型设计 -> WARCH1 最小自建历史留存实现 -> WARCH2 正式只读历史查询 -> WROAD2+OPS 受控上线与每日巡检 -> WARCH3 归档稳定化自动巡检 -> WCHECK1 打卡摘要留存 -> WEXT1 外出/加班 dry-run -> WOPS1 巡检告警降噪 -> WROAD2-CLOSEOUT 三天验收 -> WROAD2-BIZ1 三天业务冒烟 -> WAPPR1 审批规则规范化 -> WAUTO1 自动证据汇总 -> WEXT1LD 外出/加班 live 前 dry-run -> WFULLSMOKE1 三天全域最终目标测试 -> WROUTE2 测试号收口到最小镜像路线锁定 -> WEXT1-LIVE 外出/加班测试号 live POC -> 四类测试号证据和审批规则门禁通过后问答 WREAL1 小范围真实试用（首批 1 名真实员工 + 1 名审批人/管理员观察） -> 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，且依赖项满足。
- 已读对应事实源、企微优先开发路线图 和 企微 API 能力目录。
- 明确做什么、不做什么、读写边界、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。 - 企业微信自建应用不按完整隔离 sandbox 处理；默认用真实企业内受控测试域、synthetic 自动测试、公网 live runner 和少量真机确认。
- 自建留存相关合同必须说明保存哪些规范化数据和外部关联键，以及不保存哪些 Secret、token、密文或无治理原始 payload。
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 验证、验签、解密、幂等和重复投递。
- 补偿拉取先证明按时间窗口拿到审批单号并可拉取审批详情。
- 镜像表先设计字段、状态机、幂等键、索引和隐私保留边界；WADM1 已固定审批留存、回调事件、补偿拉取、对账 finding、打卡/人事快照边界，WARCH1 已实现请假/补卡最小留存切片，WARCH2 已提供正式只读查询。WROAD2+OPS 后仍需 WARCH3、WCHECK1 和 WEXT1 决策后再进入完整镜像。
- 应急接管和恢复回写必须等镜像稳定后再做。
3. 开发边界
- 每次只做当前 Issue 范围内的事，不顺手重构无关模块。
- 跨后端和前端的任务，先稳定后端 API / 数据契约，再接前端。
- 涉及权限、状态机、审批规则、财务状态、Prisma migration 的改动，必须写明回滚策略。
- 不在当前 MVP 首批范围内扩展预算、ERP、AI 自动处理、飞书、复杂 BPM 或重型项目管理；ERP 未来不接入 OA。企业微信原生审批只按 WFOC/DBWFOC/WFDG/WDRG 口径用于 HR/考勤员工日常审批优先复用，不迁移报销、财务、采购、合同、项目或高敏附件等 OA 主办流程。后续企微/OA 运行时迁移先做
WECOM-CAPABILITY-POC-V1，再按 企微优先开发路线图 拆单功能 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，例如：
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定义不可违反的执行硬约束。