cps-develop-docs/02 - Design Standard/2.4 项目文档与架构决策规范.md

2.4 项目文档与架构决策规范

本规范旨在确保团队在开发过程中留下清晰、可追溯的技术资产。代码解释了“怎么做”，而文档和架构决策记录 (ADR) 必须解释“为什么这么做”。

2.4.1 核心设计文档库 (Design Documents)

在任何复杂业务模块或新微服务进入编码阶段之前，必须完成以下设计文档的编写并经过评审（Review）：

1. 实体关系与存储设计
   • ER 图 (Entity-Relationship Diagram)：必须使用 Mermaid 语法绘制。
   • 数据字典 (Data Dictionary)：以 Markdown 表格形式列出核心表的结构，必须包含：字段名、数据类型、是否允许空值、默认值、索引类型及业务备注。
2. 系统交互与流转设计
   • 时序图 (Sequence Diagram)：对于涉及多个组件（如前端、后端、第三方支付网关）的交互流程，必须使用 Mermaid 时序图表达。
   • 状态机图 (State Diagram)：对于生命周期复杂的实体（如订单、审批流），必须使用 Mermaid 状态机图明确状态的合法流转路径。
3. 接口契约设计
   • API 文档：必须遵循 OpenAPI 3.0 规范，或使用统一的 YApi/Swagger 等平台维护。绝不接受口头契约或微信截图。

2.4.2 架构决策记录规范 (ADR - Architecture Decision Records)

在系统演进过程中，我们会面临无数的“选型分歧”或“折衷方案（Trade-offs）”。为了避免后人“挖坟”时产生疑惑（“当时为什么不用 Redis 而要用 MySQL 悲观锁？”），我们强制引入 ADR 机制。

1. 触发 ADR 的场景

• 引入新的编程语言、核心框架或底层基础设施（如消息队列、搜索引擎）。
• 模块从单体中剥离为独立的微服务。
• 核心业务链路的重构或底层数据结构的重大变更。
• 团队内部产生严重技术分歧，最终拍板定案的结果。

2. ADR 的存储与命名

• 所有 ADR 文件必须以 Markdown 格式集中存储在项目代码库的 docs/adr/ 或 01 - Knowledge & Prompts/Architecture Decision Records/ 目录下。
• 命名规范：[流水号]-[决策的简短描述].md，例如：0001-use-redis-for-distributed-locks.md。

3. ADR 标准模板内容

一份合格的 ADR 必须包含以下结构：

• Title (标题)：[流水号] - [简短描述]
• Status (状态)：Proposed (提议中) / Accepted (已接受) / Deprecated (已废弃) / Superseded (被取代)
• Context (背景/上下文)：我们面临什么问题？业务痛点是什么？
• Decision (决策)：我们决定采用什么方案？（要求明确、不含糊）
• Consequences (后果/影响)：这个决策带来了什么好处（Pros）？我们做出了哪些妥协或承担了什么负面影响（Cons）？

---

🤖 [附加] AI 助手执行协议 (AI Output Schema)

绝对红线 1：在要求输出设计文档时，AI 必须使用原生的 Mermaid 语法块渲染 erDiagram、sequenceDiagram 或 stateDiagram。 绝对红线 2：当遇到“实现方法分歧”、“技术选型交叉路口”或“需要改变既定架构”时，严禁 AI 自行决定。AI 必须暂停生成代码，向用户提出选项（Pros & Cons），并在获得用户明确回复后，自动按照 ADR 模板生成一份 Markdown 记录文件，放置于 01 - Knowledge & Prompts/Architecture Decision Records/ 目录下。