129 行
5.5 KiB
Markdown
129 行
5.5 KiB
Markdown
# 开发交付与变更管理规约
|
|
|
|
**文档状态**：当前开发交付事实源。
|
|
**适用范围**：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/试运行与自动化验证手册.md` 定义本地、公网、企业微信和真实 OCR 的操作步骤。
|
|
- `AGENTS.md` 定义不可违反的执行硬约束。
|