anian0/tech-design-v2

技术方案 v2

把需求简报转成实现契约，明确要改什么、为什么改、如何验证。技术方案必须基于现有代码，而不是泛泛描述架构。

先读取

起草前读取这些引用：

• ../project-development-v2-common/references/question-policy.md
• ../project-development-v2-common/references/delivery-contract.md
• ../project-development-v2-common/references/no-simulation-policy.md
• references/tech-design-confirmation-gates.md
• references/tech-design-quality-gates.md
• references/tech-design-template.md
• 如用户要求评估、审查、进入计划前把关，使用 project-development-review-v2。

核心规则

• 必须从已确认的需求简报开始。没有简报时，要求用户提供路径，或使用 requirements-workshop-v2。
• 设计前必须检查当前代码。不能说清当前文件、模块、API 或差距的方案，不可进入计划阶段。
• 只写会影响实现的技术决策，跳过通用架构叙述。
• 先完成设计推导，再写技术方案。不能把需求翻译成服务、API 和表清单就结束。
• 以变更契约为文档中心。
• 新技术、新模块、旧功能扩展必须有技术依据清单；没有依据时只能列为待决策或风险，不能直接定方案。
• 必须列出变更涉及的服务边界、API、数据实体、前端页面和关键用户路径，供计划阶段逐项覆盖。
• 每个 C-* 变更契约必须能归类为后端、前端、数据、配置、迁移、测试支撑或运行链路，并写清变更类型、当前证据、目标状态和具体修改。
• 每个 A-* 必须拆成可验证场景，并绑定 V-*；不能只写“覆盖 A-001”。
• 对服务边界、数据归属、失败隔离、运行链路和迁移策略必须给出理由和不变量。
• 需求包含页面、界面、日志、状态或用户反馈时，必须逐页设计 UI 契约并做页面覆盖表；无 UI 时必须显式声明。
• 必须规划测试资产落点，默认交接给 workplace/<version>/test/，并说明每个关键 V-* 对应测试、脚本、smoke 或审查清单类型。
• 技术方案必须通过矛盾审计：需求约束、技术决策、API、数据、UI、验证之间不能互相打架。
• 技术方案必须通过字段级覆盖审计：需求和验收中出现的关键对象、字段、动作、状态、错误和来源追溯，都要在 API、数据、UI 或验证契约中有落点。
• 技术方案必须通过验证引用审计：每个 V-* 引用的 API、字段、表、页面、事件和命令必须在方案中真实定义。
• 技术设计必须经过固定确认闸门。闸门确认优先级高于“少问问题”策略。
• 技术方案交付前必须完成审查记录；有阻塞级审查发现时，不得建议进入 implementation-planning-v2。
• 不创建代码、迁移、测试、项目骨架或实现分支。

流程

1. 按 delivery-contract.md 解析真实版本目录；在 workplace/<version>/requirements/ 找到当前需求简报，或使用用户给定路径。
2. 提取 R-*、A-*、特别关注点、页面/界面清单、已确认的不做范围。
3. 执行确认闸门 G1：需求理解和验收口径确认。
4. 用有目标的搜索和文件读取检查当前实现。
5. 判断新技术、新模块和旧功能扩展，创建技术依据清单；缺少依据的部分列为待决策或风险。
6. 按 references/tech-design-quality-gates.md 完成技术推导：代码证据、技术依据、架构不变量、核心设计问题、方案取舍、失败模型。
7. 执行确认闸门 G2：现状证据、技术依据、差距和不变量确认。
8. 产出现状差距：
   • 当前行为。
   • 目标行为。
   • 缺失或冲突的代码路径。
9. 只有存在真实取舍时，创建 D-* 技术决策；每个决策必须写被放弃方案和取舍理由。
10. 执行确认闸门 G3：关键技术决策确认。
11. 创建 C-* 变更契约。每个契约必须指向受影响文件或模块，并关联 R-*、A-* 和 V-*。
12. 按后端、前端、数据、配置、迁移、测试支撑、运行链路分类汇总变更契约，形成 Delta 表。
13. 列出实现表面清单：服务/API/数据/UI/运行链路。
14. 如果需求含 UI，逐页列出路由、状态、反馈、API 使用和页面覆盖表；如果不含 UI，写明“无 UI 变更”。
15. 执行确认闸门 G4：实现表面、API、数据、UI 契约确认。
16. 把每个 A-* 拆成验收场景，创建 V-* 验证契约。验证必须真实可运行、可观察；无法验证时标记为 not_verified 风险并说明原因。
17. 规划测试资产：每个关键 V-* 说明建议测试目录、脚本、smoke 或审查清单落点。
18. 对多服务或前后端需求，定义至少一个闭环验证契约。
19. 做矛盾审计：逐项检查需求约束、决策、API、数据、验证是否一致。
20. 执行确认闸门 G5：验证方案、测试资产、矛盾审计和遗留风险确认。
21. 按 project-development-review-v2 的技术方案审查口径做交付前自检，尤其检查技术依据、Delta 具体性、页面覆盖、字段级覆盖、测试资产、验证引用存在性和跨文档一致性。
22. 保存到 workplace/<version>/tech-design/YYYY-MM-DD-<slug>-tech-design.md；实际路径不得保留 <version>、1.X 等占位符。
23. 最终只请求用户确认文档是否可进入 implementation-planning-v2。

变更契约标准

每个 C-* 必须包含：

• 目标文件、模块、路由、组件、表或服务。
• 分类：后端、前端、数据、配置、迁移、测试支撑或运行链路。
• 类型：新增、修改、删除、重构、配置或迁移。
• 来自代码检查的当前状态。
• 目标状态。
• 具体修改，粒度到文件、函数、字段、接口、状态或事件；不要写“优化”“完善”这类不可执行描述。
• 关联需求和验收标准。
• 关联验证编号。

如果某个变更无法关联需求，删除它，或标记为不在范围内。

验证标准

验证优先使用真实证据：

• 孤立逻辑用单元测试。
• API、数据库和服务边界用集成或契约测试。
• 用户可见路径用 UI smoke 检查。
• 相关时运行 build、typecheck 或 lint。
• 自动化不现实才使用手动步骤，且必须写清预期证据。
• 技术方案阶段不创建测试文件，但必须给计划阶段留下测试资产建议位置。

不要把“代码审查”或“人工检查”作为验证，除非写明具体可观察结果。

输出标准

使用 references/tech-design-template.md，章节保持紧凑：

• 输入需求。
• 确认记录。
• 设计推导。
• 技术依据清单。
• 现状差距。
• 技术决策。
• 变更契约。
• Delta 分类汇总。
• 实现表面清单。
• 只写变更涉及的 API、数据和 UI 契约。
• 验收场景和测试资产规划。
• 验证契约。
• 风险和待决策项。
• 给 implementation-planning-v2 的交接。

交付前自检

检查：

• G1 到 G5 均有确认记录，或明确记录用户要求跳过哪一项及其风险。
• 每个 R-* 都被至少一个 C-* 覆盖，或明确不在范围。
• 每个 A-* 都被至少一个 V-* 覆盖。
• 每个 C-* 都指向具体代码位置，或说明该位置是新增。
• 每个 C-* 都有分类、类型、当前状态、目标状态、具体修改和关联 R/A/V。
• 每个 A-* 都拆成可验证场景，且场景不是空泛复述验收标题。
• 每个核心设计决策都有当前代码证据、可选方案和取舍理由。
• 新技术、新模块、旧功能扩展都有技术依据；缺失依据时已列入待决策或风险。
• 每个服务都写清拥有的数据、提供的能力、禁止承担的责任和失败边界。
• 如果技术决策改变或削弱需求中的“已确认”约束，必须进入待决策项，不能静默覆盖。
• API、数据和验证互相引用的对象必须真实存在于方案中。
• 需求和验收中的关键字段不得在 CRUD、读取配置、数据表或验证中丢失。
• 验证步骤不得引用未定义 API、未定义表、未定义页面、未定义事件或未定义命令。
• 部署形态、服务隔离、数据库归属、API 风格在全篇必须一致。
• 每个服务边界、API、数据实体、前端页面和运行链路都进入实现表面清单。
• 有 UI 需求时，页面覆盖表逐项覆盖需求页面；无 UI 时已显式声明。
• 每个关键 V-* 都有测试资产建议位置，供 implementation-planning-v2 细化到 workplace/<version>/test/。
• 特别关注点已从需求继承到方案，并进入交接清单。
• 多服务或前后端需求有闭环 V-*。
• 没有空的大模板章节。
• 没有把 mock、fallback 或 stub 作为完成方案，除非需求明确要求。
• 审查记录中没有未处理的阻塞级发现。