开发交付与变更管理规约

文档状态：当前开发交付事实源。 适用范围：hyb-oa 所有非微小代码、文档、测试、脚本和部署准备变更。 路线口径：开发必须围绕最新 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。

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，例如：

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

5.5 KiB 原始文件 Blame 文件历史