本篇要回答的问题：一篇合格的设计文档（重点是架构设计文档）应该包含哪些内容要素？系统的概要设计与模块的详细设计在交付物规格与实现原理的表达上有何不同？
上一讲 “69 | 团队的共识管理” 从协同角度谈了共识的重要性，而设计文档正是共识的载体。本质上，无论是 “产品文档” 还是 “架构文档”，都是设计文档的一种——谈的都是 “需求如何被满足” 这件事的共识。本讲落到具体：架构设计文档怎么写。
产品经理 vs 架构师：一体两面
两者对人的能力要求很像，但分工不同、关注维度不同：
| 角色 | 主导工作 | 关注维度关键词 |
|---|---|---|
| 产品经理 | 产品设计：如何以产品特性系统化满足用户需求 | 用户需求、技术赋能、商业成功 |
| 架构师 | 架构设计：业务系统如何系统化分解与交付 | 用户需求、技术实现、业务迭代 |
关键判断：一个企业的使命、愿景与价值观，就是这个企业最高维度的 “设计”。
设计文档的内容骨架
所有设计文档的内容组织逻辑相通，大体三段：
| 要素 | 写法要求 | 说明 |
|---|---|---|
| 现状 | 不要长篇累牍 | 只陈述与本次改变相关的重要事实，强调其存在性与重要性 |
| 需求 | 不要长篇累牍 | 痛点够痛大家都知道，需求陈述是对痛点与改进方向的一次共识确认 |
| 需求满足方式 | 要详写 | 包含 “交付物规格”（使用界面）+ “实现原理” 两方面 |
交付物规格与实现原理在产品 / 架构两类设计中的对照：
| 维度 | 产品设计 | 架构设计 |
|---|---|---|
| 交付物规格 | 产品原型 | 网络 API 协议 / 包导出的公开类或函数 |
| 实现原理 | UserStory 业务流怎么完成 | UserStory 如何被程序逻辑实现 |
指导公式：程序 = 数据结构 + 算法。谈实现总是从数据结构（内存 / 外存 / 表结构）和算法（UML 时序图 / 伪代码）两个维度去描述。
多个设计方案的对比
一篇文档有时面对多个可能的实现方式。概要描述两方案的本质差别，从以下维度对比：
| 对比维度 | 适用倾向 |
|---|---|
| 易实施性与可维护性（工程效率） | 绝大部分业务以此为先 |
| 时间复杂度与空间复杂度（成本性能） | 成本 / 性能敏感业务，先保证达标再考虑工程效率 |
关键判断：确定倾向后就以一种方案为主撰写，不对放弃的方案过多展开。若两套方案优势不显著，写两套独立文档是被鼓励的——“设计” 是头等大事，在此 “多浪费点时间” 会换来十倍百倍回报。
使用界面（接口）：概要设计 vs 详细设计
| 设计层级 | 第一关心 | 核心关注点 |
|---|---|---|
| 模块的详细设计 | 模块本身 | 接口是否简单、自然体现需求；避免变更、向前兼容 |
| 系统的概要设计 | 模块关系 | 其次才是各模块核心接口（把关键 UserStory 串起来） |
怎么表达模块关系？几种思路对比：
| 表达方式 | 评价 |
|---|---|
| 基于单个 UserStory 画模块调用流程图 | 未对模块关系做抽象，不适合放设计文档，更适合对客户讲 SDK 原理；纯业务流用 UML 时序图更好 |
| 对调用接口分类（常规 DOM API / 事件 Event / 插件 Plugin） | 不同接口类型代表不同依赖关系（参考 MVC 框架图） |
| 架构分解视角（最小核心系统 + 正交分解的周边系统） | 如画图程序模块关系图，有助理解分解逻辑 |
关键判断：模块关系图的表达是非常粗糙的，为了共识精确，仍需把各模块核心使用界面（接口）明确表达出来。
实现原理的表达
| 设计层级 | 是否交代数据结构 | 表达重点 |
|---|---|---|
| 模块详细设计 | 需要 | 先讲清数据结构，再讲各 UserStory 业务流程 |
| 系统概要设计 | 无需 | 只讲清不同模块的配合关系（各 UserStory 业务流程） |
无论是否画 UML 时序图，伪代码（Pseudo Code）设计都是必需的，其语义必须精确、在团队内形成默契（如网络请求用 qiniu httptest 语法、MongoDB 用 JS 脚本文法、MySQL 直接用 SQL）。
总结
本讲在 “45 讲” 模块级设计文档的基础上，较全面地补充了产品设计、系统概要设计等各类设计文档在细节上与模块设计文档的异同。核心是把 “现状 / 需求 / 需求满足方式” 三段骨架，落实到 “交付物规格 + 实现原理” 两个表达维度上。
先把"是什么"回答清楚
| 概念 | 一句话说明 |
|---|---|
| 设计文档 | 关于 “需求如何被满足” 的共识载体，产品文档与架构文档都属此类 |
| 交付物规格（使用界面） | 别人要怎么使用我——API 协议 / 公开类函数 / 产品原型 |
| 实现原理 | 我是怎么做到的——数据结构 + 算法 |
| 模块关系表达 | 概要设计的第一关心，可用接口分类或核心+周边正交分解来呈现 |
一句话速记
现状与需求都点到为止，把笔墨全砸在 “需求满足方式” 上：先讲清楚 “别人怎么用我”（接口规格），再用 “数据结构 + 算法 + 精确伪代码” 讲清 “我怎么做到”。
几条值得记住的判断
- 产品经理与架构师是一体两面，能力相似但关注维度不同。
- 方案不显著时，写两套独立设计文档值得鼓励——设计阶段的 “浪费” 回报巨大。
- 模块关系图天生粗糙，必须辅以精确的核心接口表达才能形成可靠共识。
思考题
回到你手头的项目：你的设计文档里，“现状 / 需求” 是否写得太长，而真正该详写的 “交付物规格 + 实现原理” 反而一笔带过？你表达模块关系时，是停留在粗糙的流程图，还是真正抽象出了模块间的依赖类型？
