From edf26628adea7eb9b35aefe37ad0e71d95f9bcc4 Mon Sep 17 00:00:00 2001 From: shunli Date: Sat, 9 May 2026 17:05:44 +0800 Subject: [PATCH] =?UTF-8?q?A1-A4=20=E8=A1=A5=E5=85=85=E6=A0=87=E5=87=86?= =?UTF-8?q?=E8=BD=AF=E4=BB=B6=E5=BC=80=E5=8F=91=E6=B5=81=E7=A8=8B=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/文档索引.md | 7 ++-- docs/海音达OA-MVP需求规格说明书.md | 32 +++++++++++++------ ...02-19-standard-development-process-doc.csv | 5 +++ 3 files changed, 32 insertions(+), 12 deletions(-) create mode 100644 issues/2026-05-09_17-02-19-standard-development-process-doc.csv diff --git a/docs/文档索引.md b/docs/文档索引.md index 17a4e833..079cee2d 100644 --- a/docs/文档索引.md +++ b/docs/文档索引.md @@ -9,7 +9,7 @@ | 文档 | 用途 | 注意 | | --- | --- | --- | -| [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) | 当前 PRD 主事实源，回答做什么、先做什么、不做什么、如何验收 | 后续需求变更先改这里或对应规则文档，再拆 Issue CSV | +| [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md) | 当前 PRD 主事实源，回答做什么、先做什么、不做什么、如何验收，并固定标准软件开发流程 | 后续需求变更先改这里或对应规则文档，再拆 Issue CSV | | [需求 - 统一审批中心规约](./需求-统一审批中心规约.md) | 统一审批中心模块级开发规约，包含审批规则矩阵、状态流转和权限数据范围 | 审批相关开发拆 Issue CSV 前必须参考 | | [需求 - 报销发票 OCR 规约](./需求-报销发票OCR规约.md) | 报销、发票、OCR、附件、付款和导出模块级开发规约，包含费用类型矩阵、人工复核和验收数据集 | 报销主链路开发拆 Issue CSV 前必须参考 | | [产品口径文档](./product-decisions.md) | 已拍板的产品边界和业务规则 | 与 PRD 冲突时，以更新后的 PRD 和最新 Issue CSV 为准 | @@ -47,6 +47,7 @@ | [MCP Tools](./mcp-tools.md) | MCP 工具启用边界 | 未启用的 MCP 不得假设可用 | | [非功能基线](./ops/non-functional-baseline.md) | 安全、性能、回滚、上线最低要求 | 上线和发布前参考 | | [测试策略](./ops/testing-strategy.md) | 自动化测试和门禁策略 | QA 规划参考 | +| [Agent 交付实践](./agent-development-practices.md) | Agent 协作开发、Issue CSV、验证和提交实践 | 与 PRD 第 2 章的软件开发流程配套阅读 | ## 历史快照与归档参考 @@ -64,8 +65,8 @@ 1. 要看“现在到底做什么”：读 [海音达OA-MVP需求规格说明书](./海音达OA-MVP需求规格说明书.md)。 2. 要细化审批或报销开发任务：读对应模块规约，再拆 `issues/*.csv`。 -3. 要看“某个业务规则为什么这么定”：读 [产品口径文档](./product-decisions.md) 和对应规则文档。 -4. 要开新开发任务：先更新需求或规则文档，再新建 `issues/*.csv`。 +3. 要开新开发任务：先读 PRD 第 2 章的软件开发项目流程，再更新需求或规则文档，并新建 `issues/*.csv`。 +4. 要看“某个业务规则为什么这么定”：读 [产品口径文档](./product-decisions.md) 和对应规则文档。 5. 要判断功能是否已经做过：读 [实现状态矩阵](./feature-matrix.md) 和最新相关 Issue CSV。 6. 要上线或真机验收：读 [试运行与自动化验证 Runbook](./trialrun-runbook.md)、live smoke 清单和最新部署结果。 diff --git a/docs/海音达OA-MVP需求规格说明书.md b/docs/海音达OA-MVP需求规格说明书.md index b10e6b32..c3fcf553 100644 --- a/docs/海音达OA-MVP需求规格说明书.md +++ b/docs/海音达OA-MVP需求规格说明书.md @@ -44,16 +44,30 @@ ## 2. 软件开发项目流程 -后续所有非微小改动按以下流程推进： +后续所有非微小改动按标准软件开发流程推进。流程目标不是增加仪式感，而是保证每轮都有清晰需求、可执行方案、可验证结果、可回滚边界和可追溯记录。 -1. 需求收集与边界确认：明确目标用户、业务流程、必须做、暂不做、验收标准。 -2. 需求文档冻结：更新本文件或对应规则文档，形成产品、开发、测试共同事实源。 -3. 执行合同拆分：新建 `issues/YYYY-MM-DD_HH-mm-ss-.csv`，写清范围、验收、测试、依赖。 -4. 技术方案设计：明确接口、数据模型、权限、状态机、前端入口、回滚策略。 -5. 开发实现：按 Issue 分后端、前端、QA 阶段推进，不顺手做无关改动。 -6. 测试与回归：先单点验证，再业务流程回归，最后做 PC/移动/企业微信入口验证。 -7. 部署与验收：部署后检查 `/ready`、前端资源、关键路径、企业微信真机入口。 -8. 复盘与下一轮规划：把试运行反馈转成新 Issue CSV，不直接插入开发。 +| 阶段 | 目标 | 输入 | 输出 | 门禁 | +| --- | --- | --- | --- | --- | +| 1. 需求收集与边界确认 | 明确为什么做、谁使用、解决什么流程问题 | 用户反馈、试运行问题、业务制度、当前 PRD 和模块规约 | 需求描述、目标角色、主流程、必须做、暂不做、验收口径 | 需求不清不得进入开发；高风险歧义必须先澄清 | +| 2. 需求文档冻结 | 形成产品、开发、测试共同事实源 | 主 PRD、模块规约、产品口径文档、历史 Issue | 更新后的 PRD 或模块规约 | 没有事实源更新，不拆开发 Issue | +| 3. Issue CSV 执行合同拆分 | 把需求拆成可独立验收的任务 | 已确认需求文档 | `issues/YYYY-MM-DD_HH-mm-ss-.csv` | CSV 必须校验通过；每个 Issue 写清范围、验收、测试、依赖 | +| 4. 技术方案设计 | 明确怎么实现和怎么回滚 | Issue CSV、现有代码、数据模型、接口和权限规则 | 实现方案、接口/数据变更说明、风险和回滚策略 | 涉及权限、状态机、迁移、审批规则时必须写回滚策略 | +| 5. 开发实现 | 按 Issue 实现后端、前端、脚本或文档 | 已批准方案和 Issue CSV | 代码或文档变更、必要测试用例、变更说明 | 不顺手改无关问题；跨端任务先稳定后端契约再接前端 | +| 6. 代码审查与自查 | 发现行为回归、权限泄漏、状态非法跳转和漏测 | 完整 diff、Issue CSV、测试结果 | Review 意见、修复记录或确认无阻断问题 | 涉及权限模型、workflow、数据迁移、审批规则时必须重点审查 | +| 7. 测试与回归 | 证明单点和业务链路都可用 | 变更内容、Test_Method、回归脚本、手工验收步骤 | 命令结果、业务流程验证结果、失败项和修复记录 | 后端、前端、PC、移动、企业微信入口按影响范围验证；不能假通过 | +| 8. 部署与发布准备 | 确认环境、配置、资源和回滚路径可用 | 已验证变更、部署脚本、配置清单、回滚策略 | 部署记录、`/ready` 检查、资源版本、配置复核 | 未部署不得告知用户可去公网或企业微信真机测试 | +| 9. 业务验收 | 让目标角色按真实路径确认结果 | 已部署环境、验收账号、样例数据、验收清单 | 验收结论、遗留问题、是否进入试运行 | 用户或指定验收人未确认前，不把体验问题视为关闭 | +| 10. 复盘与下一轮规划 | 把反馈转成下一轮可执行任务 | 验收反馈、线上问题、回归缺口、试运行记录 | 新需求、缺陷清单、下一轮 Issue CSV 草案 | 不直接把反馈插入开发；先回到需求和 Issue CSV | + +### 2.1 本项目执行约束 + +- 所有非微小改动必须先有需求事实源和 Issue CSV 执行合同。 +- 开发前必须说明实现方案；需求或方案不清时先澄清，不靠代码试错。 +- `Dev_Status`、`Review1_Status`、`Regression_Status` 只能在对应验证通过后更新为 `DONE`。 +- 后端变更至少执行 Prisma 校验、语法检查和相关业务回归；前端变更至少执行 typecheck、build，并按影响范围补 Playwright 或人工视觉验证。 +- 涉及 PC、手机、企业微信入口的改动，必须验证入口、布局、deeplink 和移动端体验。 +- 涉及生产、公网、企业微信真机或真实 OCR 的结论，必须以部署后 live smoke 为准；未配置真实条件时必须明确 `SKIP` 和原因。 +- 提交应按清晰主题小批次完成，commit message 使用中文并引用 Issue ID。 --- diff --git a/issues/2026-05-09_17-02-19-standard-development-process-doc.csv b/issues/2026-05-09_17-02-19-standard-development-process-doc.csv new file mode 100644 index 00000000..a5b87736 --- /dev/null +++ b/issues/2026-05-09_17-02-19-standard-development-process-doc.csv @@ -0,0 +1,5 @@ +ID,Title,Description,Acceptance,Test_Method,Tools,Dev_Status,Review1_Status,Regression_Status,Files,Dependencies,Notes +A1,开发流程文档执行合同,"建立标准软件开发流程文档补充执行合同，并确认本轮只改文档和 Issue CSV。","1) 新 Issue CSV 校验通过；2) 范围固定为开发流程文档补充；3) 不修改 server/client 业务代码；4) 不部署。","命令：python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-09_17-02-19-standard-development-process-doc.csv；人工步骤：确认 git status 仅包含 docs 与本 Issue CSV。",python3,DONE,DONE,DONE,issues/2026-05-09_17-02-19-standard-development-process-doc.csv,"[]","本轮只沉淀标准软件开发流程，不改运行时。" +A2,补强主PRD软件开发流程,"在主 PRD 中把正常软件开发流程扩展为可执行阶段，明确输入、输出、门禁和责任边界。","1) docs/海音达OA-MVP需求规格说明书.md 的软件开发项目流程包含需求、方案、Issue CSV、开发、代码审查、测试、部署、验收、复盘；2) 每阶段有交付物和门禁；3) 明确不允许跳过需求和 Issue CSV 直接开发。","人工步骤：阅读 docs/海音达OA-MVP需求规格说明书.md 第 2 章，确认流程可指导后续开发派工和验收。",manual,DONE,DONE,DONE,docs/海音达OA-MVP需求规格说明书.md,"[""A1""]","流程参考常规 SDLC，并结合本项目 Issue CSV 与回归脚本。" +A3,同步文档索引与工程文档入口,"更新文档索引，让人工审查时能定位开发流程、Agent 交付实践和测试策略。","1) docs/文档索引.md 的当前事实源或阅读顺序说明开发流程入口；2) 保持 AGENTS、Agent 交付实践、测试策略的职责边界清晰；3) 不新增不必要文档。","命令：rg -n ""软件开发项目流程|开发流程|Agent 交付实践|测试策略|Issue CSV"" docs/文档索引.md docs/海音达OA-MVP需求规格说明书.md；人工检查链接可读。",ripgrep|manual,DONE,DONE,DONE,docs/文档索引.md,"[""A2""]","不新增流程专项文档，避免文档分散。" +A4,文档校验与提交,"执行文档和 CSV 校验，回填 Issue 状态并提交中文 commit。","1) Issue CSV 校验通过；2) git diff --check 通过；3) 关键词引用检查通过；4) A1-A4 状态回填 DONE；5) commit message 引用 A1-A4。","命令：python3 /home/shunli/.codex/skills/plan/scripts/validate_issues_csv.py issues/2026-05-09_17-02-19-standard-development-process-doc.csv；命令：git diff --check；命令：rg -n ""软件开发项目流程|代码审查|测试与回归|部署与验收|复盘"" docs/海音达OA-MVP需求规格说明书.md docs/文档索引.md。",python3|git|ripgrep|manual,DONE,DONE,DONE,issues/2026-05-09_17-02-19-standard-development-process-doc.csv|docs/海音达OA-MVP需求规格说明书.md|docs/文档索引.md,"[""A2"",""A3""]","完成后提交，说明未部署。"