嵌入式架构文档全景图：需求文档、概要设计、详细设计、测试文档、接口文档的定位与关系

做嵌入式开发这么多年，我见过太多团队一上来就撸代码，文档能省则省。结果呢？项目后期联调时发现接口对不上，需求理解有偏差，测试用例不知道覆盖什么场景。说白了，文档不是写给领导看的，是写给未来的自己看的。

今天咱们就把这五类核心文档的定位和关系捋清楚。你想想看，一个嵌入式系统从想法到落地，信息是怎么一步步从模糊变清晰的？

1. 需求文档：一切故事的起点

需求文档是源头。它回答的是「系统要做什么」，而不是「怎么做」。我个人习惯把需求文档分成两层：

• 用户需求：从使用者视角描述功能，比如「按下按键后LED在2秒内点亮」。
• 系统需求：从技术视角分解，比如「GPIO中断响应延迟不超过1ms」。

2. 概要设计：画好系统骨架

概要设计是架构师的主战场。它回答的是「系统由哪些模块组成，模块之间怎么通信」。说白了，就是画好那张架构图。

我记得刚带项目时，总觉得概要设计可以简单写写，反正后面有详细设计。结果有一次，两个模块的通信协议在概要设计里没定死，详细设计阶段各搞各的，联调时才发现数据格式不兼容。嗯，从那以后我再也不敢在概要设计里留模糊地带了。

概要设计通常包含：

• 系统模块划分与职责
• 模块间接口定义（消息、信号、共享内存等）
• 关键数据流与控制流
• 硬件资源分配（MCU选型、外设分配、内存布局）

下面这张图展示了需求文档如何驱动概要设计，以及概要设计如何向下游输出：

3. 详细设计：把每个螺丝拧到位

详细设计是概要设计的展开。它回答的是「每个模块内部怎么实现」。比如一个UART驱动模块，概要设计只说了「负责串口收发」，详细设计就要写出：

• 环形缓冲区的大小与操作方式
• 中断服务程序的执行流程
• 错误处理与超时机制
• API函数的参数、返回值、前置条件

举个例子，一个简单的状态机实现：

/* 详细设计中的状态机描述 */
状态：IDLE -> SENDING -> WAIT_ACK -> IDLE
触发条件：
  - IDLE: 收到发送请求 -> SENDING
  - SENDING: 数据发送完成 -> WAIT_ACK
  - WAIT_ACK: 收到ACK或超时 -> IDLE
超时处理：WAIT_ACK状态持续500ms未收到ACK，重发最多3次

4. 测试文档：给质量上把锁

测试文档不是开发完了才写的。我个人习惯在概要设计阶段就开始规划测试策略。测试文档包含：

测试类型	对应文档	验证目标
单元测试	详细设计	每个函数/模块的正确性
集成测试	概要设计 + 接口文档	模块间交互的正确性
系统测试	需求文档	系统是否满足所有需求
验收测试	用户需求	用户是否接受

5. 接口文档：团队协作的契约

接口文档是概要设计和详细设计的产物，但它独立存在。为什么？因为接口是团队协作的边界。硬件工程师、软件工程师、测试工程师，大家都靠接口文档对齐。

接口文档要写清楚：

• 函数原型（参数类型、返回值、错误码）
• 数据结构定义（字节对齐、大小端）
• 通信协议（帧格式、超时、重传机制）
• 依赖关系（调用顺序、资源互斥）

6. 五类文档的关系总结

这五类文档不是孤立的，它们形成了一条信息传递链：

1. 需求文档定义「做什么」
2. 概要设计定义「系统长什么样」
3. 详细设计定义「每个零件怎么做」
4. 接口文档定义「零件之间怎么连接」
5. 测试文档验证「做出来的对不对」

每一份文档都约束着下一份文档，同时下一份文档也会反馈验证上一份文档的正确性。这就是文档驱动开发的核心逻辑。