第3章：ADAS文档体系总览
各位同学，今天我们来聊聊ADAS文档体系的全貌。说实话，我刚入行那会儿，觉得写文档就是浪费时间。代码能跑就行，要什么文档？后来在一个量产项目上吃了大亏——需求变更没人通知，设计改了测试不知道，最后交付前发现一堆问题。嗯，从那以后，我再也不敢轻视文档体系了。
3.1 为什么需要文档体系？
你想想看，一个ADAS系统有多复杂？感知、决策、控制，每个模块都有几十个功能点。没有文档，你怎么保证团队里20个人对同一个功能的理解是一致的？
我个人习惯把文档体系比作「房子的骨架」。代码是装修，测试是验收，但骨架决定了房子能不能立起来。ADAS文档体系的核心价值就三点：
- 可追溯：从用户需求到代码实现，每一步都有据可查
- 可复用：下一个项目不用从头造轮子
- 可审计：功能安全认证（ISO 26262）要求你必须有文档
重要提醒：ADAS文档不是写给别人看的，是写给自己和团队看的。我见过太多团队，项目做完了文档还是空的，等出了问题才后悔。
3.2 四大文档类型详解
ADAS文档体系主要分四类：需求文档、设计文档、测试文档、用户手册。每一类都有自己的生命周期和管理方式。
3.2.1 需求文档
需求文档是源头。说白了，就是「系统要做什么」。我在项目中遇到过最头疼的事，就是需求写得太模糊。比如「车辆应能检测行人」——检测多远？什么光照条件？雨天行不行？这些不写清楚，后面全是坑。
需求文档通常包括：
- 系统需求规格（SRS）：功能需求、性能需求、接口需求
- 功能需求列表：每个功能的详细描述
- 用例（Use Case）：典型场景和边界场景
我的经验：写需求时，多用「应（shall）」而不是「将（will）」。ISO 26262里明确要求用「shall」表示强制需求。我曾经因为用词不规范，被审核老师追着改了三天。
3.2.2 设计文档
设计文档回答的是「系统怎么做」。从架构设计到详细设计，层层递进。我个人习惯把设计文档分成三层：
| 层级 | 内容 | 读者 |
|---|---|---|
| 系统架构设计 | 模块划分、数据流、接口定义 | 架构师、项目经理 |
| 子系统设计 | 算法选型、状态机、时序图 | 开发工程师 |
| 详细设计 | 数据结构、函数接口、伪代码 | 实现工程师 |
设计文档最容易犯的错是什么？写得太细。我记得有个同事，把每个函数的参数类型都写进去了，结果代码一改，文档就得重写。设计文档应该关注「为什么这么设计」，而不是「代码长什么样」。
3.2.3 测试文档
测试文档是质量的守门员。ADAS系统涉及安全，测试文档尤其重要。测试文档包括：
- 测试计划：测什么、怎么测、用什么工具
- 测试用例：输入、预期输出、测试步骤
- 测试报告：结果、缺陷分析、覆盖率
避坑指南：我曾经在一个项目里，测试用例写了3000条，但全是正常场景。结果上线第一天，一个边界场景就出了问题。记住，测试文档要覆盖正常、异常、边界三种情况。
3.2.4 用户手册
用户手册是给最终用户看的。ADAS的用户手册有个特点——用户可能只看一遍，但这一遍必须能救命。所以用户手册要写得：
- 简洁：别写技术术语，用户不懂什么是「卡尔曼滤波」
- 场景化：告诉用户「什么情况下系统会报警」
- 有图有真相：示意图比文字管用一百倍
3.3 文档生命周期管理
文档不是写完了就完事的。它有自己的生命周期：创建→评审→发布→维护→归档。
我建议用版本号来管理文档。比如：
- Draft（草稿）：0.1、0.2... 内部评审用
- Review（评审）：0.9 表示即将定稿
- Release（发布）：1.0 正式版本
- Update（更新）：1.1、1.2... 变更记录要清晰
为什么要有生命周期？因为ADAS系统是迭代开发的。需求变了，设计就得改；设计改了，测试用例就得更新。没有生命周期管理，你根本不知道哪个版本是当前有效的。
关键点：文档和代码要同步管理。我建议用Git来管理文档，和代码放在同一个仓库里。这样每次代码变更，文档变更记录一目了然。
3.4 文档间的关联关系
四大文档不是孤立的。它们之间有一条清晰的追溯链：
用户需求 → 系统需求 → 架构设计 → 详细设计 → 测试用例 → 测试报告
每个环节都可以追溯到上一个环节。比如，一个测试用例应该能追溯到它测试的是哪个需求。这就是所谓的「双向追溯」。
我在项目中常用一个简单的表格来管理追溯关系：
| 需求ID | 需求描述 | 设计模块 | 测试用例ID |
|---|---|---|---|
| REQ-001 | FCW应在车速>30km/h时激活 | FCW_Manager | TC-001, TC-002 |
| REQ-002 | 报警延迟应<500ms | FCW_Timing | TC-003 |
你想想看，如果没有这个追溯表，需求变更了，你怎么知道哪些设计要改、哪些测试要重跑？
3.5 我的文档管理建议
最后，分享几个我这些年总结出来的经验：
- 模板先行：每个项目开始前，先把文档模板定好。别让每个人自己发挥，否则风格五花八门，后期合并时想死的心都有。
- 评审不能省：文档评审和代码评审一样重要。我建议至少做两轮评审——技术评审和格式评审。
- 自动化工具：能用工具就别用手工。比如用Doxygen生成接口文档，用PlantUML画时序图，用Markdown写需求。
- 持续维护：文档不是一次性的。每次迭代结束，花半天时间更新文档。别等到项目结束再补，那时候你早忘了当初为什么这么设计。
小技巧：我习惯在文档开头加一个「变更记录」表格。每次修改都写上日期、修改人、修改内容。这样三年后回头看，还能知道当时发生了什么。
好了，这一章的内容就到这里。文档体系看起来繁琐，但它是ADAS系统开发的基石。下一章我们会深入讲需求文档怎么写，到时候我会拿一个实际项目案例来拆解。