From fc55d6ebc17065c585ed6f47534d578f8081f019 Mon Sep 17 00:00:00 2001 From: zhangkunshi Date: Mon, 20 Apr 2026 13:37:57 +0800 Subject: [PATCH] =?UTF-8?q?fix(architecture):=20=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E6=B5=81=E6=94=B9=E4=B8=BA=E4=B8=9A=E5=8A=A1=E5=88=86=E5=8F=89?= =?UTF-8?q?=E5=88=B0=E5=BC=80=E5=8F=91+=E6=B5=8B=E8=AF=95=E5=B9=B6?= =?UTF-8?q?=E8=A1=8C(=E9=9D=9E=E4=B8=B2=E8=A1=8C=E9=93=BE)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用户指出架构图里的错误 —— 把数据流画成 业务 → 开发 → 测试 → 运维 → 业务 是错的。测试篇方法论(docs/chapters/04-testing/FULL.md § 1) 明确规定测试从 PRD 阶段就参与可测性评审,是业务的并行消费者, 不是开发下游。 ## 修正三处 1. ARCHITECTURE.md 数据流 Mermaid - PRD 推给 开发+测试(并行)而非只推给开发 - 加 "testability-review.md" 节点 - 开发 ↔ 测试 API 契约双向对齐 - 加"为什么测试要提前并行参与"对比表 2. docs/architecture/information-sharing.md ASCII 图 - 产品下叉两路:开发 + 测试 并行 - "提测 → 测试执行 → 准出" 合流 - 准出 → 运维 - 新增"关键分叉:PRD 的双消费"小节 - 新增第二节"为什么测试要并行参与"对比表(传统 vs 本框架) 3. docs/chapters/00-adoption/mode-a-greenfield.md 时序图 - 原"业务 → 开发 → 测试 → 运维"串行改为 业务 → [开发 / 测试 并行] → 提测 → 运维 - 加关键节奏说明 - 指向 ARCHITECTURE.md 的正式数据流 确保和测试篇方法论的"需求评审门禁"(可测性评审)一致。 --- ARCHITECTURE.md | 47 ++++-- docs/architecture/information-sharing.md | 134 +++++++++++++----- .../chapters/00-adoption/mode-a-greenfield.md | 19 ++- 3 files changed, 152 insertions(+), 48 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 097c9f7..1e22005 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -88,6 +88,8 @@ graph TB ## 二、数据流图 · Markdown 在四场景间流动 +> ⚠️ 重要: **测试不是开发下游**,测试从 PRD 阶段就**与开发并行**参与(可测性评审)。这是 [`测试篇`](./docs/chapters/04-testing/) 的核心设计 —— 不要把它画成串行链。 + ```mermaid flowchart LR subgraph 业务 @@ -101,7 +103,8 @@ flowchart LR end subgraph 测试 - STRATEGY[test-strategy.md] --> CASES[test-cases.md] + TESTABILITY["可测性评审意见
testability-review.md"] --> STRATEGY[test-strategy.md] + STRATEGY --> CASES[test-cases.md] CASES --> SUBMISSION[submission.md] SUBMISSION --> REPORT[test-report.md] end @@ -112,23 +115,51 @@ flowchart LR INC --> PM[postmortem.md] end - RULES -.->|PRD 变更
link-prd-to-design.js| DESIGN - API -.->|开发变更
recommend-regression.js| CASES - REPORT -.->|测试准出
generate-release-plan.js| PLAN - PM -.->|改进项
incident-to-requirement.js| PRD + %% 业务产出同时推给开发和测试(并行) + PRD -->|需求评审门禁| DESIGN + PRD -->|需求评审门禁| TESTABILITY + + %% 开发与测试之间的 API 契约对齐 + API <-.->|契约双向锁定| CASES + + %% 测试准出 → 运维发布 + REPORT -->|准出门禁| PLAN + + %% 联动脚本(虚线 = Sprint 4 产出的自动化) + RULES -.->|link-prd-to-design.js| DESIGN + API -.->|recommend-regression.js| CASES + REPORT -.->|generate-release-plan.js| PLAN + PM -.->|incident-to-requirement.js| PRD style 业务 fill:#e8f5e9 style 开发 fill:#e3f2fd style 测试 fill:#fff3e0 style 运维 fill:#f3e5f5 + style TESTABILITY fill:#fffde7,stroke:#f57f17,stroke-width:2px ``` **关键观察**: -- **实线**: 场景内部产出物演进 -- **虚线**: 跨场景联动(Sprint 4 的 4 个联动脚本) -- **闭环**: 运维 → 业务(复盘改进项回流需求池),形成**完整回路** +- **业务产出是"双消费"**: PRD 同时推给开发(开始设计)和测试(做可测性评审)。两条线**并行启动**,不是串行 +- **测试是业务的并行下游,不是开发的下游**: 测试可测性评审是一个**门禁**,评审通过后业务才算真正交付 +- **开发 ↔ 测试 双向**: API 契约是开发 + 测试共同锁定(测试从用例角度反推 API 是否可测,开发从实现角度反推用例是否可编) +- **实线 = 产出物+门禁**,**虚线 = Sprint 4 联动脚本**(自动检测触发下一环) +- **闭环**: 运维 → 业务(复盘改进项)→ PRD → 开发+测试 并行 - 每个节点都是 **Git 里的 Markdown 文件**,不是数据库记录 +### 为什么测试要提前并行参与? + +这是测试方法论的核心观点(详见 `docs/chapters/04-testing/FULL.md § 1`): + +| 🤔 传统做法 | ✅ 本框架做法 | +|-----------|-------------| +| 业务写完 PRD → 开发写代码 → 给测试 | 业务写 PRD → 开发 + 测试**同时**接手 | +| 测试在提测时才发现"验收标准模糊" | PRD 评审时就卡住模糊需求,回炉重写 | +| Bug 发现在测试阶段,改动成本高 | 把"可测性"作为**PRD 的准出门禁** | +| 开发 - 测试 信息不对称,临近上线才对齐契约 | API 契约从需求阶段就共同设计 | + +- `tools/cross-platform/scripts/check-prd.js` + `score-testability.js` 就是这套理念的自动化 +- 本仓库 `docs/chapters/04-testing/04-gates/requirements-gate.md` 专门定义了"需求评审门禁" + 详细扩展见 [docs/architecture/information-sharing.md](./docs/architecture/information-sharing.md)。 --- diff --git a/docs/architecture/information-sharing.md b/docs/architecture/information-sharing.md index 49305f3..11248cd 100644 --- a/docs/architecture/information-sharing.md +++ b/docs/architecture/information-sharing.md @@ -8,39 +8,101 @@ ## 一、核心模型 +> ⚠️ 关键:**测试不是开发下游**,测试从 PRD 阶段就与开发**并行**参与可测性评审。 +> 这是本框架测试篇的核心设计。下图把这个并行关系画清楚。 + ``` -┌────────────────────────────────────────────────────────────────┐ -│ 当前信息共享模式(无中心化服务端) │ -├────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ -│ │ 产品 │ → │ 开发 │ → │ 测试 │ → │ 运维 │ │ -│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ -│ │ │ │ │ │ -│ PRD.md 设计+ADR 用例+提测单 Runbook/复盘 │ -│ 业务规则 API 契约 Bug 报告 发布计划 │ -│ │ │ │ │ │ -│ └─────────────┴─────────────┴─────────────┘ │ -│ ↓ │ -│ ┌──────────────┐ │ -│ │ Git 仓库 │ ← 唯一真实源 │ -│ │ main branch │ │ -│ └──────┬───────┘ │ -│ ↓ │ -│ ┌───────────────────────┐ │ -│ │ CI 门禁 │ │ -│ │ + 跨场景联动脚本 │ ← 自动触发下一环 │ -│ │ + 度量采集 (每周) │ │ -│ └──────────┬────────────┘ │ -│ ↓ │ -│ ┌───────────────────────┐ │ -│ │ Jira / 禅道 / IM / │ ← 可选镜像/广播 │ -│ │ Confluence / Slack │ (非权威源) │ -│ └───────────────────────┘ │ -└────────────────────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────────────┐ +│ 当前信息共享模式(无中心化服务端 · 测试并行参与) │ +├─────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ │ +│ │ 产品 │ │ +│ └────┬────┘ │ +│ PRD.md │ +│ 业务规则 │ +│ │ │ +│ ┌───────────┴───────────┐ │ +│ │(PRD 推给开发 + 测试) │ │ +│ ▼ ▼ │ +│ ┌─────────┐ 并行 ┌─────────┐ │ +│ │ 开发 │ ◄───────► │ 测试 │ │ +│ └────┬────┘ 契约双向 └────┬────┘ │ +│ 设计 可测性评审 │ +│ ADR 测试策略 │ +│ API 契约 测试用例 │ +│ │ │ │ +│ └───────────┬───────────┘ │ +│ 提测 (submission.md) │ +│ ▼ │ +│ (测试执行 / Bug) │ +│ ▼ │ +│ 准出报告 test-report.md │ +│ ▼ │ +│ ┌─────────┐ │ +│ │ 运维 │ │ +│ └────┬────┘ │ +│ Runbook / 发布计划 │ +│ 事件报告 / 复盘 │ +│ │ │ +│ │ (复盘改进项) │ +│ ↓ │ +│ ↩─── 回流到 产品 backlog │ +│ │ +│ ───────────────────────────────────────────────────────────────── │ +│ │ +│ 所有以上产出物都是 Markdown,统一入: │ +│ ┌──────────────┐ │ +│ │ Git 仓库 │ ← 唯一真实源 │ +│ │ main branch │ │ +│ └──────┬───────┘ │ +│ ↓ │ +│ ┌───────────────────────┐ │ +│ │ CI 门禁 │ │ +│ │ + 跨场景联动脚本 │ ← 自动触发下一环 │ +│ │ + 度量采集 (每周) │ │ +│ └──────────┬────────────┘ │ +│ ↓ │ +│ ┌───────────────────────┐ │ +│ │ Jira / 禅道 / IM / │ ← 可选镜像/广播 │ +│ │ Confluence / Slack │ (非权威源) │ +│ └───────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────┘ ``` -## 二、四个核心特征 +### 关键分叉:PRD 的"双消费" + +产品写完 PRD 并**不是**先给开发,等开发做完再给测试。PRD 一产出,**立即**: +- 推给 **开发**: 开始技术方案设计、ADR、API 契约 +- 推给 **测试**: 做可测性评审(门禁)、起测试策略、列用例大纲 + +测试可测性评审通过,PRD 才算真正进入"可交付"状态。这是业务篇和测试篇共同约定的**需求评审门禁**(见 `docs/chapters/04-testing/04-gates/requirements-gate.md`)。 + +### 开发 ↔ 测试 的双向协作 + +- **开发主导**: API 契约 / 数据模型 / 内部设计 +- **测试反推**: 这些设计能不能测? 边界情况够不够清晰? 异常路径覆盖了吗? +- **产出物**: 共同锁定的 `api-contract.md`,两边都有修改权 + 评审权 + +这个双向箭头在"提测"时合流 —— 开发提交提测单,测试审核通过后进入执行阶段。 + +## 二、为什么测试要并行参与(对比表) + +| 🤔 传统做法 | ✅ 本框架做法 | 好处 | +|-----------|-------------|------| +| PRD 完稿 → 开发写代码 → 代码完成 → 给测试 | PRD 完稿 → **开发 + 测试 并行启动** | 测试不等代码,提前 40% 时间 | +| 测试在提测时才发现"验收标准模糊" | PRD 评审就卡住模糊需求,打回重写 | 返工成本从"修代码"降为"修文字" | +| Bug 发现在测试阶段,改代码 | 问题发现在需求阶段,改文档 | 修复成本按阶段递增 10 倍 | +| 开发独立设计 API,测试临近上线才对齐 | API 契约从需求阶段共同锁定 | 开发-测试信息对称,减少 integration bug | + +相关自动化: +- `tools/cross-platform/scripts/check-prd.js` - PRD 结构校验(测试视角) +- `tools/cross-platform/scripts/score-testability.js` - PRD 可测性打分(0-100) +- `tools/cross-platform/scripts/coverage-analysis.js` - 用例 ↔ 需求 关联检测 +- `tools/cross-platform/scripts/link-prd-to-design.js` - PRD 变更影响面(业务 → 开发) +- `tools/cross-platform/scripts/recommend-regression.js` - 代码改动推荐回归(开发 → 测试) + +## 三、四个核心特征 ### 2.1 Git = 唯一真实源 @@ -77,7 +139,7 @@ Jira / Confluence / 企业微信 / 钉钉 等**是镜像**,不是权威: --- -## 三、按场景详述产出物流向 +## 四、按场景详述产出物流向 ### 3.1 业务产出 @@ -119,7 +181,7 @@ Jira / Confluence / 企业微信 / 钉钉 等**是镜像**,不是权威: --- -## 四、跨场景联动(Sprint 4 产出) +## 五、跨场景联动(Sprint 4 产出) 4 个脚本把上面的"单向流动"串成**闭环**: @@ -151,7 +213,7 @@ flowchart LR --- -## 五、优点 vs 缺点 · 坦诚分析 +## 六、优点 vs 缺点 · 坦诚分析 ### ✅ 优点 @@ -186,7 +248,7 @@ flowchart LR --- -## 六、最小起步 · 某团队用这套方法论的 Day 1 +## 七、最小起步 · 某团队用这套方法论的 Day 1 **假设**: 一个 5 人团队,有 GitHub 企业账号,用企业微信。 @@ -200,7 +262,7 @@ flowchart LR --- -## 七、反模式 · 不要这样用 +## 八、反模式 · 不要这样用 | ❌ 反模式 | 为什么不行 | 正确做法 | |---------|----------|---------| @@ -212,7 +274,7 @@ flowchart LR --- -## 八、相关文档 +## 九、相关文档 - [ARCHITECTURE.md](../../ARCHITECTURE.md) · 本文的上层视图(四层架构) - [PLAN.md § Phase 2 ⑤](../../PLAN.md) · 本文的初稿来源 diff --git a/docs/chapters/00-adoption/mode-a-greenfield.md b/docs/chapters/00-adoption/mode-a-greenfield.md index 446fc9d..71660ad 100644 --- a/docs/chapters/00-adoption/mode-a-greenfield.md +++ b/docs/chapters/00-adoption/mode-a-greenfield.md @@ -13,14 +13,25 @@ ## 推荐的时序 -按"业务 → 开发 → 测试 → 运维"顺序展开，每个阶段完成前置产出物后再进入下一阶段。 +业务先行产出 PRD;**PRD 一出 → 开发 + 测试并行启动**(测试不在开发下游,详见 [ARCHITECTURE.md § 数据流](../../../ARCHITECTURE.md#二数据流图--markdown-在四场景间流动)),两条线汇合到提测,再推进到运维。 ``` -Week 0 Day 1-3 Day 4-7 Week 2 Week 3+ - 立项 → 业务 → 开发设计 → 测试设计 → 实施迭代 - Kickoff PRD完成 设计完成 用例完成 按周 Sprint +Week 0 Day 1-3 Day 4-7 Week 2 Week 3+ + 立项 → 业务 PRD → ┌─ 开发设计 / ADR ─┐ + Kickoff PRD 完成 │ ├─→ 提测 → 测试执行 → 实施迭代 + └─ 测试策略 / 用例 ─┘ Week 2 末 按周 Sprint + (两条并行) + ↑ + PRD 评审门禁(测试主导可测性评审) + 不过,开发 + 测试 都不启动 ``` +关键节奏: +- **Day 1-3**: 业务做 PRD · 测试做可测性评审 · 开发提前看 PRD 了解范围 +- **Day 4-7**: 开发写设计+ADR · 测试写测试策略+用例大纲(**并行**,互不等) +- **Week 2 末**: 开发提测,测试审核提测单,进入执行 +- **Week 3+**: 实施迭代,运维准备发布 + --- ## 起步清单（按顺序执行）