架构设计文档
文档定位：本文是
<System Or Project Name>的架构设计主文档，负责描述目标、边界、分层、数据流、模块职责与验证约束。 适用读者：架构设计者、实现者、审阅者、运维与后续维护者。 冲突处理：若本文与运行真相文档冲突，以当前 canonical runtime/README 真相文档为准；本文负责设计意图与结构，不伪装当前已落地状态。
0. 摘要
0.1 一句话摘要
用 1~3 句说明系统解决什么问题、采用什么核心架构、主要设计收益是什么。
0.2 设计结论速览
- 设计对象：
<system> - 设计目标：
<goal> - 核心架构模式：
<pattern> - 关键边界：
<boundary> - 当前状态：
<draft/approved/partially-landed>
0.3 读者导航
- 如果你要快速理解系统入口与边界，先读
1. 背景与目标 - 如果你要看整体分层，先读
4. 总体架构 - 如果你要开始实现，先读
6. 模块职责与10. 验证方案 - 如果你要判断风险，先读
9. 风险与权衡
1. 背景与目标
1.1 问题背景
说明当前系统或业务为何需要这份设计文档。
1.2 设计目标
- 功能目标：
<goal> - 工程目标：
<goal> - 运行目标：
<goal> - 维护目标：
<goal>
1.3 非目标
明确本文不负责解决什么，避免设计边界失控。
2. 术语与约定
2.1 术语表
| 术语 | 定义 | 备注 |
|---|---|---|
<term> |
<definition> |
<canonical/legacy/alias> |
2.2 命名约定
- canonical 名称：
<name> - compatibility / legacy 名称：
<name> - 缩写规则：
<rule>
3. 约束条件
3.1 业务约束
<constraint>
3.2 工程约束
<constraint>
3.3 运行约束
<constraint>
3.4 安全 / 合规 / 成本约束
<constraint>
4. 总体架构
4.1 架构总图
Client / Caller
-> Ingress / API Boundary
-> Control / Routing Layer
-> Core Service Layer
-> State / Storage Layer
-> External Provider / Dependency4.2 设计风格
说明采用的是分层架构、事件驱动、插件式、单体模块化、微服务、网关式等哪种主风格，以及原因。
4.3 核心设计原则
- 单一 canonical 入口
- 明确边界与不变量
- 可观测性优先
- 最小耦合
- 可替换性与可维护性
5. 请求流 / 数据流
5.1 主请求链路
1. <entry>
2. <validation/auth>
3. <routing/decision>
4. <core handling>
5. <state update>
6. <response/egress>5.2 状态流 / 数据流
说明关键状态从哪里来、如何流转、在哪里持久化、如何被读取。
5.3 异常路径
列出关键失败路径与回收逻辑。
6. 模块职责划分
6.1 模块清单
| 模块 | 职责 | 输入 | 输出 | 依赖 |
|---|---|---|---|---|
<module> |
<responsibility> |
<input> |
<output> |
<dependency> |
6.2 模块边界
- 哪个模块拥有什么
- 哪个模块不应该拥有什么
- 哪些职责不得跨层泄漏
6.3 接口契约
说明模块之间通过哪些接口、数据结构或事件交互。
7. 状态、存储与配置
7.1 状态分类
- 运行时状态
- 持久化状态
- 缓存状态
- 配置状态
7.2 配置入口
列出配置文件、环境变量、机器合同字段、默认值与覆盖关系。
7.3 数据一致性与恢复
说明写入、恢复、回滚、重试、幂等与容灾思路。
8. 观测与运维设计
8.1 健康检查
- public health
- internal health
- readiness / liveness
8.2 指标与日志
- 关键指标
- 关键日志
- 关键 debug 面
8.3 运维动作
说明常见运维动作及其顺序。
9. 风险、权衡与替代方案
9.1 主要风险
| 风险 | 影响 | 触发条件 | 缓解措施 |
|---|---|---|---|
<risk> |
<impact> |
<trigger> |
<mitigation> |
9.2 权衡说明
说明为什么选当前方案，不选另一个方案。
9.3 被拒绝方案
记录被否决方案与否决原因。
10. 验证方案
10.1 验证目标
说明设计被认为“成立”需要验证哪些点。
10.2 验证矩阵
| 维度 | 检查项 | 方法 | 通过标准 |
|---|---|---|---|
<dimension> |
<check> |
<method> |
<pass> |
10.3 观测证据
说明需要保留哪些日志、截图、接口返回、拓扑证据或运行产物。
11. 实施路线
11.1 分阶段落地
- Phase 0：
<phase> - Phase 1：
<phase> - Phase 2：
<phase>
11.2 变更边界
说明每一阶段允许改什么、不允许改什么。
11.3 回滚边界
说明失败时如何最小回退。
12. 开放问题
<open-question>
13. 附录
13.1 参考文档
<reference>
13.2 相关代码与路径
<path>
13.3 历史记录
<history-note>
