45 lines
3.4 KiB
Markdown
45 lines
3.4 KiB
Markdown
|
# **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/` 目录下。
|