4、需求文档撰写：功能需求、性能指标、接口定义、环境要求、交付物清单
说实话，我见过太多项目死在需求文档上。
有的文档写得像天书，开发看不懂。有的写得像散文，测试没法测。还有的干脆没有文档，全靠口头传话——结果呢？项目延期、成本超支、双方扯皮。
我自己带过的项目里，因为需求不明确导致的返工，至少占了总工时的30%。所以今天咱们好好聊聊，一份靠谱的嵌入式需求文档到底该怎么写。
4.1 功能需求：别写“系统要稳定”，写“按键按下后LED亮”
功能需求是文档的核心。但很多人容易犯一个毛病——写得过于抽象。
比如“系统应具备良好的用户体验”，这话说了等于没说。什么叫“良好”？谁来定义？
我个人的习惯是：每个功能需求必须可验证。也就是说，测试人员拿到文档后，能明确知道“这个功能通过/不通过”。
功能需求撰写要点：
- 用“主语+动作+条件”的句式：例如“当温度传感器检测到超过50℃时，蜂鸣器以1Hz频率鸣叫”。
- 区分“必须”和“可选”：用MoSCoW方法（Must have, Should have, Could have, Won't have）给需求排优先级。
- 每个功能要有唯一编号：比如FUNC-001、FUNC-002，方便后续追溯。
- 避免模糊词汇：像“快速”、“大概”、“尽可能”这类词，统统删掉。
举个例子，我之前做过一个智能门锁项目。客户说“要能远程开锁”。我追问：“远程开锁的延迟要求是多少？网络断了怎么办？如果手机没电了，有没有备用方案？”
你看，一个简单的功能需求，背后能拆出好几个子需求。不写清楚，后面全是坑。
4.2 性能指标：用数字说话，别用形容词
性能指标这块，我踩过最大的坑就是——指标定得太高，实现不了；或者定得太低，客户不买账。
我记得有一次做工业控制项目，客户要求“响应时间要快”。我问：“多快算快？”他说：“反正要快。”最后我们反复沟通，才确定是“从传感器触发到执行器动作，不超过10ms”。
你看，有了具体数字，大家心里都有底。
| 性能指标类别 | 示例 | 说明 |
|---|---|---|
| 实时性 | 中断响应时间 ≤ 5μs | 明确是硬实时还是软实时 |
| 功耗 | 待机电流 ≤ 10μA | 区分工作模式、休眠模式 |
| 精度 | ADC采样精度 ±0.5% | 包含温度漂移、老化等因素 |
| 存储 | 日志存储 ≥ 30天 | 按每天100条、每条256字节计算 |
| 通信 | 丢包率 ≤ 0.1% | 在指定距离和环境下测试 |
小技巧：性能指标最好附带测试条件。比如“在25℃室温、无遮挡环境下，Wi-Fi通信丢包率≤0.1%”。否则同样的指标，不同环境测出来天差地别。
4.3 接口定义：画图比写字管用
接口定义这块，我强烈建议图文并茂。纯文字描述接口，开发人员容易理解偏差。
我曾经遇到过一个项目，文档里写“UART接口，波特率115200”。结果硬件工程师接了TX/RX，软件工程师以为要接流控线。最后查了半天，才发现是文档没写清楚是“三线制”还是“五线制”。
接口定义应该包含：
- 硬件接口：引脚定义、电平标准（3.3V/5V）、连接器型号、线序图。
- 软件接口：API函数原型、参数说明、返回值定义、调用时序。
- 通信协议：帧格式、校验方式、超时重传机制、数据包结构。
// 示例：软件接口定义
/**
* @brief 设置设备工作模式
* @param mode 0-待机模式，1-工作模式，2-休眠模式
* @return 0-成功，-1-参数错误，-2-模式切换失败
*/
int set_device_mode(uint8_t mode);嗯，这里要注意：接口定义一旦确定，尽量不要改。改接口的代价，往往比重新写代码还大。
4.4 环境要求：别让开发环境成为拦路虎
环境要求这部分，很多人觉得不重要，随便写两句就过去了。但我想说，环境问题往往是项目延期的隐形杀手。
我有个朋友接了个外包项目，文档里只写了“使用Keil开发”。结果项目做到一半，发现客户指定的MCU只能用IAR编译。最后折腾了两周移植代码，白白浪费了工期。
环境要求清单（建议逐项确认）：
- 开发工具：IDE版本、编译器版本、调试器型号
- 硬件平台：MCU型号、开发板版本、仿真器接口
- 软件依赖：RTOS版本、协议栈版本、第三方库及许可证
- 测试环境：示波器带宽、逻辑分析仪通道数、信号发生器频率范围
- 生产环境：温度范围、湿度要求、EMC等级、供电电压波动
说白了，环境要求写得越细，后面扯皮的概率越低。我一般会在文档里附上“环境搭建检查表”，开发人员拿到后逐项打勾，确保环境一致。
4.5 交付物清单：白纸黑字，避免“我以为”
交付物清单是需求文档的收尾部分，也是最容易产生纠纷的地方。
客户以为你会提供原理图、PCB源文件、BOM表、源码、烧录工具、测试报告……但你可能只打算给个hex文件。你看，双方预期完全不一样。
我建议的交付物清单模板：
| 交付物 | 格式要求 | 交付时间节点 | 验收标准 |
|---|---|---|---|
| 需求文档 | PDF + Word | 项目启动后第1周 | 双方签字确认 |
| 设计文档 | PDF + 源文件 | 项目中期评审前 | 通过内部评审 |
| 源代码 | ZIP压缩包，含注释 | 项目验收前 | 编译通过，无警告 |
| 原理图/PCB | Altium Designer 源文件 + PDF | 硬件调试前 | 通过DRC检查 |
| 测试报告 | PDF，含测试用例和结果 | 项目验收时 | 所有用例通过 |
| 烧录文件 | hex/bin + 烧录说明 | 项目验收时 | 可正常烧录运行 |
避坑指南：我曾经因为没写清楚“源代码是否包含第三方库”，导致项目交付后客户发现少了几个关键驱动文件。后来我学乖了，在交付物清单里专门加了一行：“第三方库清单及许可证文件”。
最后说一句，需求文档不是写完了就完事。它需要双方签字确认，并且作为后续变更管理的基准。任何需求变更，都要走正式的变更流程，更新文档版本。
你想想看，如果连需求都没对齐，后面的开发、测试、验收，那不都是在沙滩上盖楼吗？