夜雨聆风软件定版之后最痛苦的事
VCU定版文档到底在写什么
VPERED-032 · 软件工程系列
VCU软件定版那天，你跑了最后一遍HIL全用例，点了"代码冻结"。然后PM说："写个定版文档吧，下周评审。" 你看了看commit log——32个提交、5个bug修复、3个功能新增、还有2个已知问题决定不修——然后打开了一个空白文档。
这是每个VCU工程师的必经时刻。定版文档不是"写个README"——它是这一版软件的唯一可信记录，六年后有人排查定速巡航的一个边界bug时，唯一能依赖的就是这份文档。
· · ·
① 文档要回答的三个核心问题
一份合格的定版文档必须让半年后的任何一个同事（或你自己）能回答这三个问题：
· · ·
② 功能变更记录：别贴commit log
commit log是写给自己和同事看的开发流水账，定版文档是写给评审人和未来维护者看的变更地图。每条变更必须包含三个要素：
注意"变更原因"列要关联到JIRA/问题编号或台架发现的故障现象，不是"代码逻辑优化"这种废话——未来有人翻文档找bug根因时，唯一的线索就是这一列。
· · ·
③ 文档评审：定版不是一个人说了算
定版文档写完了不等于定版完成了。在VCU软件工程里，任何一次正式定版都必须通过技术评审会——这是由至少三位工程师交叉验证你的设计决策和测试数据的正式流程，不是「发个邮件请大家看看」。评审不通过，代码不能合并到release分支。
评审会的必到人员：文档作者、至少一位动力域软件工程师（review代码逻辑）、一位HIL测试工程师（review测试覆盖和边界）、以及功能安全工程师（如果变更涉及到ASIL相关项）。如果你的改动跨了模块边界——比如扭矩协调改到了热管理——对应的模块owner也必须出席，不是「请他们看看」，是评审通过需要他们签字。
评审中会被追问的三类核心问题：第一，「这个变更会不会引入新的故障模式」——功能安全工程师拿着FMEA表对照你的变更列表，逐一确认。第二，「这些数据是在什么工况下测的」——HIL工程师会追问测试边界是否覆盖了所有规范要求（比如扭矩控制不能只在常温下测，要有-30°C和55°C各一次）。第三，「为什么这个问题不修」——如果遗留问题清单里有个影响范围不明确的bug，评审组会要求你补测数据或修改「不修」的风险评估。
一个典型的评审周期：D-3发文档给评审组预读，D-day开评审会（1小时review + 0.5小时提问讨论），如果通过则当场签署；如果被退回，你有2个工作日改稿并重新提交，3个工作日内安排二次评审。实际经验：第一次就过审的文档不到30%，大部分人都会被退回至少一次。
下面这张表是评审会上逐项检查的checklist——提前自检一遍，能帮你避免80%的退回：
被退回不是坏事。评审的本质是「让多双眼睛在你合并代码之前发现隐患」——功能安全工程师在评审时发现一个FMEA漏洞，比实车验证阶段发现同样的漏洞，成本低了至少一个数量级。
· · ·
④ 数据对标：三个表缺一不可
定版文档的第二大部分是数据对比——证明这版软件比上一版好，而不是改坏了什么。三个必须有的表：
▲ V05 vs V06 数据对标（简化示例） ▲ |
三个表的顺序：HIL台架数据 → 实车数据 → 与上一版对标。缺一个，评审会上必被技术负责人打回来——这不是形式主义，而是保证没有人"偷着改"。
· · ·
⑤ 工具链：文档不是Word就够了
新人常犯的一个错觉：定版文档就是打开Word开始写。实际上，一份能通过评审的定版文档背后是一个完整的工具链——文档主体的每个数字、每张图、每个结论，都需要能从工具链追溯到原始来源。
版本控制：Git vs Confluence vs 内部Wiki。最推荐的做法是用Markdown写文档、用Git管理版本——好处是每个版本改了什么、什么时候改的、谁改的，都和代码仓库的分支一一对应。用Confluence或内部Wiki写定版文档也可以，但必须遵守一个铁律：定版后锁定页面，禁止后续编辑。见过太多案例：定版三个月后有人「顺手」改了Wiki上的一个数字，后面排查bug的人引用了一个错误的版本。
从JIRA到文档：每个数字都要有出处。变更原因那一栏写的不应该是你的理解，而应该是可追溯的JIRA编号或问题单号。评审时被问到「这个扭矩纹波从3.2A降到1.1A是在哪个工况测的」，你应该能立即指到HIL测试报告的具体页面和Test Case编号。做不到这一点，评审人不会信任你的数据。
测试结果关联：别只写「测试通过」。每个测试结论后面应该跟一个引用——可以是HIL自动化测试的Report ID，也可以是手动测试的记录表编号。这样几年后有人想复现你的测试，不用猜你当时是怎么测的。Git仓库里建一个tests/reports/目录存所有测试报告的PDF或截图，然后在文档里引用路径。
截图管理：命名决定生死。HIL上位机截图、INCA录波图、CAN报文时序图——这些东西如果不加命名规范，三个月后就是一堆不可读的垃圾。推荐的截图命名格式：[测试项]_[工况]_V[版本号]_[日期].png，例如TorqueStep_25degC_V06_20250412.png。截图中的关键信号通道、触发时刻、异常点都要在文档正文中用文字标注说明，不能「看图说话」。
· · ·
⑥ 遗留问题清单：诚实地写「不修」
定版文档里最难写的部分不是技术分析——是承认有些bug你知道但没有修。但这恰恰是文档最重要的价值。
关键是量化影响。 不能说"影响不大"——要说"低温环境预热时间多2~3分钟"。不说"偶发"——要说"复现率<2%，约每50次出现1次"。用数字说话，评审人才能判断这个"不修"到底能不能被接受。
· · ·
⑦ 最常被退回的三种写法
据不完全统计，评审会上被退回的定版文档，原因几乎不超出以下三种。每种都有一个经典的BAD写法和一个GOOD写法——看完你会明白评审人为什么看到BAD那句话就直接打回。
退回原因一：描述太模糊——「优化了控制逻辑」 |
BAD写的「优化」和「提升」两个词在评审人眼里等于「没写」——改了什么算法、用什么参数替代了什么参数、效果量化到什么程度，这三样必须用具体的名字和数字说出来。
退回原因二：缺少边界工况——「测过，没问题」 |
评审人每次看到「测试通过」四个字都会追问同一个问题：「通过了哪些测试？」——你没列出来，评审人默认认为你没测过那些边界工况。不如一开始就把所有测过的工况写清楚。
退回原因三：数据没有上下文——「纹波从3.2A降到1.1A」 |
数据本身不能让评审人判断你的改善是有意义的还是碰巧在某个工况下看起来好。BAD写法里那个65%看起来漂亮，但评审人不知道这个结果是在什么工况下测的——如果是空载低转速下测的，那这个改进值对实际驾驶毫无意义。GOOD写法给出了具体工况、以及改进的技术原因（参数怎么调的），这才是一份能被信任的数据。
用这三组BAD/GOOD自检一遍你的定版文档——如果任何一条变更写不出GOOD版本，说明你对这次变更的理解还不够深，不是文档的问题，是变更本身还没想清楚。
· · ·
⑧ 最后：什么样的定版文档算好文档
好文档的标准不是你花了多长时间写，而是三年后有人能不看代码就搞清楚这版软件做了什么决策。具体来说：
变更记录：每个变更都有原因（关联到问题/故障）和验证方法（不是"测试通过"四个字）。数据对标：HIL、实车、上一版对比三张表齐全，任何一项有退化的数字都有解释。遗留问题：每个"不修"的bug都有量化影响描述和明确的关闭计划。
这一篇的核心结论：VCU定版文档的价值不在当下——在三年后有人排查bug时。一份合格的文档回答三个问题（改了什么、对比了什么数据、哪些已知没修），并且每个回答都用具体数字支撑。它不是commit log的摘抄，而是一份软件决策的可追溯地图。 |
下一篇：工程师35岁不是危机——跨领域理解力才是不会被AI替代的竞争力。
· · ·
VPERED 前进挡 汽车软件工程师的技术笔记 写真实的技术，做有用的思考 |