hyb-oa/docs/开发交付与变更管理规约.md

开发交付与变更管理规约

文档状态：当前开发交付事实源。 分类：开发治理。 适用范围：hyb-oa 所有非微小代码、文档、测试、脚本和部署准备变更。 关联 Issue：GOV8。 最近审计：2026-05-13。 不得误读：本文定义开发和变更流程，不替代具体业务 PRD、模块规约或测试规约。 路线口径：开发必须围绕最新 Issue CSV 执行；hyb-oa 是唯一业务主系统，企业微信只做基础设施，飞书路线已废弃。

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

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。

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 淹没。

2.2 需求冻结和变更请求

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

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

变更请求至少写清：

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

3. 开发边界

• 每次只做当前 Issue 范围内的事，不顺手重构无关模块。
• 跨后端和前端的任务，先稳定后端 API / 数据契约，再接前端。
• 涉及权限、状态机、审批规则、财务状态、Prisma migration 的改动，必须写明回滚策略。
• 不在当前 MVP 首批范围内扩展预算、ERP、AI、飞书、企业微信原生审批、复杂 BPM 或重型项目管理。
• 未经确认不得重置数据库、编辑迁移历史、修改生产配置、暴露真实密钥或处理真实敏感数据。

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 定义不可违反的执行硬约束。