246 行
12 KiB
Markdown
246 行
12 KiB
Markdown
# 开发交付与变更管理规约
|
||
|
||
**文档状态**：当前开发交付事实源。
|
||
**分类**：开发治理。
|
||
**适用范围**：hyb-oa 所有非微小代码、文档、测试、脚本和部署准备变更。
|
||
**关联 Issue**：`GOV8`。
|
||
**最近审计**：2026-05-13。
|
||
**不得误读**：本文定义开发和变更流程，不替代具体业务 PRD、模块规约或测试规约。
|
||
**路线口径**：开发必须围绕最新 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。
|
||
|
||
### 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` 失效。
|
||
|
||
变更请求至少写清：
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| 变更原因 | 为什么现在提出 |
|
||
| 影响范围 | 影响哪些角色、流程、接口、页面、数据或文档 |
|
||
| 处理方式 | 替代原需求、追加当前行、进入同治理流后续行或进入下一阶段 |
|
||
| 测试影响 | 原测试是否仍有效，是否新增权限/视觉/公网/真机验证 |
|
||
| 回滚路径 | 如何撤销或延后 |
|
||
|
||
## 3. 开发边界
|
||
|
||
- 每次只做当前 Issue 范围内的事，不顺手重构无关模块。
|
||
- 跨后端和前端的任务，先稳定后端 API / 数据契约，再接前端。
|
||
- 涉及权限、状态机、审批规则、财务状态、Prisma migration 的改动，必须写明回滚策略。
|
||
- 不在当前 MVP 首批范围内扩展预算、ERP、AI 自动处理、飞书、复杂 BPM 或重型项目管理；企业微信原生审批只按 WFOC/DBWFOC/WFDG 口径用于 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，例如：
|
||
|
||
```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` 定义不可违反的执行硬约束。
|