简介这份《软件架构文档(样例)》面向软件架构师、系统分析师及需要规范架构文档写作的开发人员提供一份可直接参考的架构设计文档范本帮助团队解决架构描述不统一、视图划分不清、需求与设计脱节等常见问题。资源包内共1个doc文件约247KB采用标准软件架构文档模板组织内容可套用于中小型业务系统的架构立项与评审场景。目录涵盖简介、架构表示方式、架构目标和约束、用例视图、逻辑视图、部署视图等章节简介部分交代目的、范围、术语缩略语与参考资料架构表示方式说明UML等建模手段的选用架构目标和约束聚焦性能、安全性、可扩展性与可维护性等质量属性用例视图细化申请注册、用户注册审核、用户角色管理、角色权限管理与车型、配件信息管理等业务用例逻辑视图按Application层、Business Service层Service包、Model包与Middleware层分层展开并附数据流程与数据存储说明。已有770人学习参考适合作为架构文档撰写模板或教学案例帮助读者快速建立分层清晰、视图完整的文档骨架与沟通依据。1. 一份「软件架构文档(样例).doc」为什么总在评审会上被翻两页就合上评审现场最尴尬的一幕是有人把《软件架构文档(样例).doc》投到屏幕上问一句这两个模块为什么要拆开翻遍六十页只找到一张截图和一句采用分层设计。问题不在写得太少而在于它按写作者自己的顺序组织先背景再选型最后贴图唯独没有回答读者带着来的问题——边界在哪、接口是什么、改坏了谁兜、决策依据还能不能翻出来。标题里的 doc 不只是扩展名它意味着一套交付形态评审要看、归档要留、变更要追的正式件而样例两个字说明多数团队真正缺的不是长篇论述是一份能照着改的骨架。下面按骨架怎么定、文件怎么生成、上位机和智驾这类场景怎么变体、版本怎么追这条线走适合正在补架构文档的研发、要交差的技术负责人以及被评审意见反复打回的人。2. 软件架构文档(样例)的最小骨架视图、读者与决策记录一份被反复打开的文档一定是因为它每次都能在三十秒内命中某个人的具体问题。所以骨架不是写什么而是谁来查、查什么、多久会失效。先把这三件事定下来后面填内容才有收敛的方向。2.1 先定读者再定章节顺序新入职开发、测试、现场支持、评审人、外部供应商这五类人翻同一份 doc 的姿势完全不同。按读者倒推章节比按背景—需求—设计—实现的教科书顺序有效得多。读者带着什么问题来必须命中的章节更新触发条件新入职开发我从哪个文件开始改模块划分、目录结构、构建方式每次拆合模块测试这次改动影响多大范围接口清单、依赖关系接口签名或频率变更现场支持装在哪、怎么升级、怎么回退部署视图、配置项、升级步骤每次发版评审人当初为什么这么选决策记录、被否方案每次评审结论落地外部供应商我给谁提供什么数据边界接口、数据格式、时序协议版本变更排在前面的章节应该是改动最频繁但每次只改几行的部分比如接口表和决策记录排在后面的才是上下文、术语表这类半年不动的内容。很多样例文档反过来排导致读者每次都要翻到第四十页才能找到接口自然没人看。另一个实用做法是给每章标注有效期接口表跟着版本走部署视图跟着环境走决策记录永久有效只追加不修改。谁负责维护、什么时候必须回看直接写在章节标题下面一行小字评审时争议会少一半。2.2 四个必填视图加一份决策记录视图不是画得越多越好是缺了哪个就会被问住就补哪个。工程上够用的最小集合是四个视图加一份 ADR再多就是装饰。视图回答的问题最少要有的内容常见坑上下文视图系统边界在哪外部依赖是谁一张框图、外部实体、交互协议画成内部模块图边界反而模糊模块视图代码怎么分谁依赖谁分层、模块职责、允许的依赖方向只写名字不写不允许调用谁运行视图进程/线程怎么跑数据怎么流进程划分、线程模型、消息通道只画部署不画线程排查时无用接口视图谁给谁什么数据、什么频率接口名、方向、协议、周期、失效行为缺失效行为测试无法造用例决策记录为什么是它而不是另一个上下文、选项、结论、代价只记结论半年后没人敢改模块视图里最有价值的不是有哪些模块而是哪些依赖是禁止的。写清楚采集层不得直接调用 UI 层比画十个框更能拦住后续的架构腐化。接口视图里最容易被漏掉的是失效行为超时怎么办、乱序怎么办、字段越界怎么办这部分不写测试只能凭猜线上就只能凭运气。决策记录建议一条一个文件编号后不删除。被否掉的方案同样要留写清当时因为什么否掉因为半年后一定有人重新提出来。2.3 一份可以照抄的 Markdown 骨架源文件用 Markdown 写好处是能 diff、能分支、能进评审流程交付时再转成 docx。下面这份骨架里的字段不是装饰每一个都在后面生成和校验环节被用到。--- doc_type: 软件架构文档 system: 电池管理上位机 version: 1.3.0 status: baseline # draft | review | baseline updated: 2025-06-18 owner: 架构组 --- # 范围与读者 # 架构总览上下文视图 # 模块划分与职责边界 # 关键接口清单见附录 A # 运行与部署视图 # 关键决策记录ADR-001 ~ ADR-00N # 附录 A 接口表 # 附录 B 术语表文件头的 version 和 status 决定了这份文件能不能被引用status 为 draft 时只允许评论不允许作为开发依据改成 baseline 才允许被下游引用。标题里故意不写1.这类编号编号交给转换工具自动生成否则插入一章就会导致后面全部手改改漏一个就是跳号。2.4 样例 doc 的目录与命名约定目录结构定死之后自动化才有落脚点。我一般用下面这种布局源文件唯一、生成件不入库。docs/ architecture.md # 唯一源文件所有人改这里 adr/ ADR-001-通信框架选型.md ADR-002-插件加载方式.md assets/ ref.docx # 转 docx 用的参考样式 ctx.png dist/ 软件架构文档_v1.3.0_20250618.docx # 只放生成件不进版本管理交付件命名统一成名称_版本_日期中间用下划线日期用八位。这样按文件名排序就是按时间排序归档时不用打开文件确认新旧。dist 目录写进 .gitignore避免有人手改生成件之后又覆盖回去导致改动凭空消失。3. 从 Markdown 到 doc/docx软件架构文档的自动化生成链路手工维护 Word 版本最大的问题是无法 diff两份 docx 摆在面前谁也说不清这一版到底改了哪三行。所以工程上的通行做法是源文件用纯文本交付件按需生成评审意见回写到源文件再重新生成。3.1 源文件用 Markdown、交付件转 docx 的分工Markdown 负责内容正确docx 负责交付形态。前者进 git能做逐行 diff、能做合并请求、能在评审里精确指出改了哪句后者带样式、带目录、带页眉适合发给不装开发环境的评审人和归档系统。分工的边界要讲清楚任何内容修改都改 Markdown任何人不得在 docx 上直接改字。如果评审现场有人直接在 docx 里批注流程是批注收集—回写 Markdown—重新生成而不是改完 Word 另存一份。这条规矩不立两周后就会出现三个互相冲突的版本。另一个容易忽略的点是参考样式字体、标题级别、表格边框、页眉页脚全部预先在一份 ref.docx 里调好。生成时套用交付件才不会出现标题是等线、正文是宋体、表格没边框的拼凑感——这类问题在评审场合很掉分而且和内容质量无关。3.2 用 pandoc 生成带编号目录的 docx转换环节的核心命令不复杂参数才是关键。下面这条是一份能直接用的基线# 先人工用 Word/WPS 调好一份 ref.docx字体、标题样式、表格边框、页眉页脚 pandoc docs/architecture.md \ --reference-docassets/ref.docx \ # 套用样式交付件不裸奔 --toc --toc-depth3 \ # 生成三级目录 --number-sections \ # 标题自动编号 1 / 1.1 / 1.1.1 --fromgfmpipe_tables \ # 解析 GitHub 风格表格 -o dist/软件架构文档_v1.3.0_20250618.docx参数逐个说明--reference-doc决定所有样式换一套参考文档就能换一种交付外观内容不用动--toc-depth3只收三级标题收太深目录会占两页--number-sections让编号由工具算源文件里坚决不手写编号--fromgfmpipe_tables决定了管道表格能不能被识别少了这个参数接口表会变成一堆竖线和文字。命令建议包一层 shell 脚本同时做三件事检查文件头 version 是否与输出文件名一致、检查 status 是否为 baseline、生成后输出文件大小。文件大小是个低成本的有效校验正常几十页的文档只有几 KB基本可以断定转换中途失败了。3.3 用 python-docx 把接口表批量灌进 docx接口清单往往来自代码或配置手抄进文档必然对不上。常见做法是让接口定义只存在一份文档生成时读同一份数据。# build_iface_table.py —— 把 ifaces.csv 追加成文档附录避免手抄接口 import csv from docx import Document doc Document(dist/base.docx) # 基于 pandoc 产出的文件续写 doc.add_heading(附录 A 接口清单, level1) rows list(csv.DictReader(open(ifaces.csv, encodingutf-8))) table doc.add_table(rows1, cols5) table.style Table Grid # 不设样式部分阅读器里看不到边框 head table.rows[0].cells for i, name in enumerate([接口名, 方向, 协议, 周期(ms), 失效行为]): head[i].text name for r in rows: # 一行一条接口字段与 CSV 表头同名 cells table.add_row().cells cells[0].text r[name] cells[1].text r[direction] cells[2].text r[proto] cells[3].text r[period_ms] cells[4].text r[on_timeout] doc.save(dist/软件架构文档_v1.3.0_20250618.docx)逻辑上分三步加载 pandoc 产出的基线文档、追加一级标题、按 CSV 逐行写表格。Table Grid样式必须显式指定否则表格在部分阅读器和打印预览里没有边框看起来像排版事故。字段顺序刻意把失效行为放在最后一列并且不允许为空——这一列空着的接口测试阶段一定会回头找你。ifaces.csv的列名要和代码里的常量、以及文档里的表头保持同源改动时三处一起改。更彻底的做法是从接口定义文件IDL、protobuf、YAML直接生成 CSV中间不出现人工环节。3.4 目录、表格与交叉引用最容易翻车的三个点现象根因处理方式目录条目点不动静态文本目录不是 Word 域需要可点目录时在 Word 里重建域或接受静态目录编号跳号、层级错乱源文件里手写了3.1标题内不写编号统一交给--number-sections表格跨页丢表头参考样式未设标题行重复在 ref.docx 的表格样式里勾选重复标题行图号引用错位中文题注与域混用图号用题注域统一管理别手工编号这些问题的共同点是出在样式和工具链却总被当成内容问题在评审会上讨论。建议把转换命令和参考样式一起纳入版本管理谁改的样式、改完哪份文档走样了能直接查出来。4. Qt 上位机与智驾软件架构文档的分层写法差异同样叫架构文档上位机项目和智驾项目的写法差别很大。前者关心交互和线程后者关心时序和失效把一套模板硬套到两边结果就是两边都觉得没用。4.1 Qt 上位机软件架构文档把线程模型和信号槽写清楚Qt 上位机软件架构文档最常被漏掉的是线程模型。UI 线程、采集线程、数据处理线程怎么划跨线程用信号槽还是队列界面卡顿的锅最后都落在这里。层次职责允许依赖文档必须写清的点界面层控件、视图模型、交互业务层哪些耗时操作禁止在 UI 线程执行业务层状态机、流程编排通信层、数据层状态迁移条件与异常分支通信层串口/TCP/总线收发、协议解析无收发周期、断线重连策略数据层配置、日志、历史数据无落盘频率与容量上限写清允许的依赖方向比列模块重要界面层不得直接读串口、通信层不得弹窗这两条写进去后续加需求时有人想抄近路就会先来问一句。信号槽的跨线程连接方式自动连接还是队列连接建议在文档里显式标注这类细节在代码里是默认行为在评审时却是争议焦点。插件化设计的上位机还要额外写一节插件加载时机、插件与主程序的接口版本、插件崩溃时主程序的行为。不写这段现场加一个插件就把主程序带崩了。4.2 智驾软件架构文档功能链路、时序与失效约束智驾软件架构文档的读者更关心这条链路跑完要多久、慢了会怎样。所以文档的主线不是模块清单而是功能链路加时间预算。一条典型链路感知—融合—规划—控制至少要给出每个环节的处理周期、允许的最大延迟、超时后的降级动作。比如融合环节给 40 ms 预算超时就退化为上一帧结果并置降级标志——这句话写进文档测试才知道要构造什么样的延迟注入用例。安全性相关内容建议单列一节写清哪些输出属于安全相关、失效时必须进入什么状态而不是散落在各模块描述里。另一个差异是接口的时间属性必须量化周期、抖动容忍、时钟基准、时间戳单位。写周期约 20 ms和写周期 20 ms抖动不超过 2 ms时间戳取系统单调时钟毫秒是两份完全不同的文档后者才能被测试直接转成断言。4.3 接口表与时序描述的可复制模板接口定义用结构化文件维护文档和代码生成时读同一份是两边都省事的做法。# ifaces.yaml —— 一份定义同时喂给文档生成和代码生成 - name: BatteryStatus direction: plc_to_ui # 数据流向评审必看 proto: Modbus-TCP period_ms: 200 # 既是文档字段也是代码里的常量 timeout_ms: 600 # 超时判定写进失效处理章节 payload: - {field: soc, type: uint16, unit: %, range: 0~100} - {field: soh, type: uint16, unit: %, range: 0~100} on_timeout: 界面置灰并记录告警 # 失效行为测试照着造用例字段设计上有三处是有意为之direction强制写明流向避免评审时对着接口名猜谁调谁period_ms和timeout_ms成对出现超时值一般取周期的三倍写在同一处便于统一调整on_timeout是自由文本但必填它同时是文档内容和测试用例的来源。不同场景下这张表要补的列不一样场景必须补的列原因Qt 上位机线程归属、信号槽连接方式跨线程问题排查依赖这两列智驾链路抖动容忍、时钟基准、降级状态时序问题无法用单一周期描述对外接口协议版本、鉴权方式、字段废弃策略供应商升级节奏不由你控制5. 架构文档的变更追溯与打开异常排查技巧文档写完之后真正花时间的是两件事判断这次改动动了什么契约以及交付件在别人机器上打不开时怎么快速定位。5.1 用 diff 与结构校验盯住文档漂移改文档时最该被拦下来的不是文字修订而是章节消失——章节消失往往意味着某个约束不再有人维护。# 1) 先看这一版动了哪些文件、多少行 git --no-pager diff --stat HEAD~1 -- docs/architecture.md # 2) 只比标题结构章节增删比正文措辞重要得多 grep -nE ^#{1,3} docs/architecture.md /tmp/new.txt git show HEAD~1:docs/architecture.md | grep -nE ^#{1,3} /tmp/old.txt diff /tmp/old.txt /tmp/new.txt第一条命令给出改动规模第二条把章节树抽出来单独比。如果 diff 里出现以开头的标题行说明有章节被删掉了这类改动应当在合并请求里单独说明理由。把这两条放进提交前钩子成本很低但能挡住大部分顺手删了一节的情况。5.2 doc/docx 打不开或无法预览时的排查顺序交付件在不同机器上的表现不一致绝大多数不是文件坏了而是打开方式或关联出了问题。按下面顺序排查通常两步内定位。现象大概率原因快速验证处理提示无法预览 doc文件在只读缓存目录里被直接打开先另存到本地磁盘再打开另存为本地副本别人能开、本机空白文件带了锁定标记或关联被改右键属性看有无解除锁定解除锁定或重新建关联打开后字体编号全乱生成时未套参考样式看标题字体是否混排用--reference-doc重新生成文件只有几 KB生成脚本中断只写了骨架unzip -l xx.docx看有无 word/document.xml重跑生成脚本菜单新建里没有 WPS doc安装时未勾选模板组件看安装目录下有无模板文件修复安装或直接编辑 Markdown 源文件unzip -l这一招值得记住docx 本质是 zip 包内部缺少word/document.xml就说明生成过程根本没走完和阅读器无关。至于菜单新建没有 WPS doc这类情况在文档工作流里其实不重要——源文件是 Markdown新建文档这个动作本身就不该存在交付件一律从流水线里生成dist 目录不进版本管理需要 diff 的永远只有 architecture.md 和 adr/ 下的那些文件。本文还有配套的精品资源点击获取 软件架构文档样例：从骨架到docx自动化与变更追溯
简介这份《软件架构文档(样例)》面向软件架构师、系统分析师及需要规范架构文档写作的开发人员提供一份可直接参考的架构设计文档范本帮助团队解决架构描述不统一、视图划分不清、需求与设计脱节等常见问题。资源包内共1个doc文件约247KB采用标准软件架构文档模板组织内容可套用于中小型业务系统的架构立项与评审场景。目录涵盖简介、架构表示方式、架构目标和约束、用例视图、逻辑视图、部署视图等章节简介部分交代目的、范围、术语缩略语与参考资料架构表示方式说明UML等建模手段的选用架构目标和约束聚焦性能、安全性、可扩展性与可维护性等质量属性用例视图细化申请注册、用户注册审核、用户角色管理、角色权限管理与车型、配件信息管理等业务用例逻辑视图按Application层、Business Service层Service包、Model包与Middleware层分层展开并附数据流程与数据存储说明。已有770人学习参考适合作为架构文档撰写模板或教学案例帮助读者快速建立分层清晰、视图完整的文档骨架与沟通依据。1. 一份「软件架构文档(样例).doc」为什么总在评审会上被翻两页就合上评审现场最尴尬的一幕是有人把《软件架构文档(样例).doc》投到屏幕上问一句这两个模块为什么要拆开翻遍六十页只找到一张截图和一句采用分层设计。问题不在写得太少而在于它按写作者自己的顺序组织先背景再选型最后贴图唯独没有回答读者带着来的问题——边界在哪、接口是什么、改坏了谁兜、决策依据还能不能翻出来。标题里的 doc 不只是扩展名它意味着一套交付形态评审要看、归档要留、变更要追的正式件而样例两个字说明多数团队真正缺的不是长篇论述是一份能照着改的骨架。下面按骨架怎么定、文件怎么生成、上位机和智驾这类场景怎么变体、版本怎么追这条线走适合正在补架构文档的研发、要交差的技术负责人以及被评审意见反复打回的人。2. 软件架构文档(样例)的最小骨架视图、读者与决策记录一份被反复打开的文档一定是因为它每次都能在三十秒内命中某个人的具体问题。所以骨架不是写什么而是谁来查、查什么、多久会失效。先把这三件事定下来后面填内容才有收敛的方向。2.1 先定读者再定章节顺序新入职开发、测试、现场支持、评审人、外部供应商这五类人翻同一份 doc 的姿势完全不同。按读者倒推章节比按背景—需求—设计—实现的教科书顺序有效得多。读者带着什么问题来必须命中的章节更新触发条件新入职开发我从哪个文件开始改模块划分、目录结构、构建方式每次拆合模块测试这次改动影响多大范围接口清单、依赖关系接口签名或频率变更现场支持装在哪、怎么升级、怎么回退部署视图、配置项、升级步骤每次发版评审人当初为什么这么选决策记录、被否方案每次评审结论落地外部供应商我给谁提供什么数据边界接口、数据格式、时序协议版本变更排在前面的章节应该是改动最频繁但每次只改几行的部分比如接口表和决策记录排在后面的才是上下文、术语表这类半年不动的内容。很多样例文档反过来排导致读者每次都要翻到第四十页才能找到接口自然没人看。另一个实用做法是给每章标注有效期接口表跟着版本走部署视图跟着环境走决策记录永久有效只追加不修改。谁负责维护、什么时候必须回看直接写在章节标题下面一行小字评审时争议会少一半。2.2 四个必填视图加一份决策记录视图不是画得越多越好是缺了哪个就会被问住就补哪个。工程上够用的最小集合是四个视图加一份 ADR再多就是装饰。视图回答的问题最少要有的内容常见坑上下文视图系统边界在哪外部依赖是谁一张框图、外部实体、交互协议画成内部模块图边界反而模糊模块视图代码怎么分谁依赖谁分层、模块职责、允许的依赖方向只写名字不写不允许调用谁运行视图进程/线程怎么跑数据怎么流进程划分、线程模型、消息通道只画部署不画线程排查时无用接口视图谁给谁什么数据、什么频率接口名、方向、协议、周期、失效行为缺失效行为测试无法造用例决策记录为什么是它而不是另一个上下文、选项、结论、代价只记结论半年后没人敢改模块视图里最有价值的不是有哪些模块而是哪些依赖是禁止的。写清楚采集层不得直接调用 UI 层比画十个框更能拦住后续的架构腐化。接口视图里最容易被漏掉的是失效行为超时怎么办、乱序怎么办、字段越界怎么办这部分不写测试只能凭猜线上就只能凭运气。决策记录建议一条一个文件编号后不删除。被否掉的方案同样要留写清当时因为什么否掉因为半年后一定有人重新提出来。2.3 一份可以照抄的 Markdown 骨架源文件用 Markdown 写好处是能 diff、能分支、能进评审流程交付时再转成 docx。下面这份骨架里的字段不是装饰每一个都在后面生成和校验环节被用到。--- doc_type: 软件架构文档 system: 电池管理上位机 version: 1.3.0 status: baseline # draft | review | baseline updated: 2025-06-18 owner: 架构组 --- # 范围与读者 # 架构总览上下文视图 # 模块划分与职责边界 # 关键接口清单见附录 A # 运行与部署视图 # 关键决策记录ADR-001 ~ ADR-00N # 附录 A 接口表 # 附录 B 术语表文件头的 version 和 status 决定了这份文件能不能被引用status 为 draft 时只允许评论不允许作为开发依据改成 baseline 才允许被下游引用。标题里故意不写1.这类编号编号交给转换工具自动生成否则插入一章就会导致后面全部手改改漏一个就是跳号。2.4 样例 doc 的目录与命名约定目录结构定死之后自动化才有落脚点。我一般用下面这种布局源文件唯一、生成件不入库。docs/ architecture.md # 唯一源文件所有人改这里 adr/ ADR-001-通信框架选型.md ADR-002-插件加载方式.md assets/ ref.docx # 转 docx 用的参考样式 ctx.png dist/ 软件架构文档_v1.3.0_20250618.docx # 只放生成件不进版本管理交付件命名统一成名称_版本_日期中间用下划线日期用八位。这样按文件名排序就是按时间排序归档时不用打开文件确认新旧。dist 目录写进 .gitignore避免有人手改生成件之后又覆盖回去导致改动凭空消失。3. 从 Markdown 到 doc/docx软件架构文档的自动化生成链路手工维护 Word 版本最大的问题是无法 diff两份 docx 摆在面前谁也说不清这一版到底改了哪三行。所以工程上的通行做法是源文件用纯文本交付件按需生成评审意见回写到源文件再重新生成。3.1 源文件用 Markdown、交付件转 docx 的分工Markdown 负责内容正确docx 负责交付形态。前者进 git能做逐行 diff、能做合并请求、能在评审里精确指出改了哪句后者带样式、带目录、带页眉适合发给不装开发环境的评审人和归档系统。分工的边界要讲清楚任何内容修改都改 Markdown任何人不得在 docx 上直接改字。如果评审现场有人直接在 docx 里批注流程是批注收集—回写 Markdown—重新生成而不是改完 Word 另存一份。这条规矩不立两周后就会出现三个互相冲突的版本。另一个容易忽略的点是参考样式字体、标题级别、表格边框、页眉页脚全部预先在一份 ref.docx 里调好。生成时套用交付件才不会出现标题是等线、正文是宋体、表格没边框的拼凑感——这类问题在评审场合很掉分而且和内容质量无关。3.2 用 pandoc 生成带编号目录的 docx转换环节的核心命令不复杂参数才是关键。下面这条是一份能直接用的基线# 先人工用 Word/WPS 调好一份 ref.docx字体、标题样式、表格边框、页眉页脚 pandoc docs/architecture.md \ --reference-docassets/ref.docx \ # 套用样式交付件不裸奔 --toc --toc-depth3 \ # 生成三级目录 --number-sections \ # 标题自动编号 1 / 1.1 / 1.1.1 --fromgfmpipe_tables \ # 解析 GitHub 风格表格 -o dist/软件架构文档_v1.3.0_20250618.docx参数逐个说明--reference-doc决定所有样式换一套参考文档就能换一种交付外观内容不用动--toc-depth3只收三级标题收太深目录会占两页--number-sections让编号由工具算源文件里坚决不手写编号--fromgfmpipe_tables决定了管道表格能不能被识别少了这个参数接口表会变成一堆竖线和文字。命令建议包一层 shell 脚本同时做三件事检查文件头 version 是否与输出文件名一致、检查 status 是否为 baseline、生成后输出文件大小。文件大小是个低成本的有效校验正常几十页的文档只有几 KB基本可以断定转换中途失败了。3.3 用 python-docx 把接口表批量灌进 docx接口清单往往来自代码或配置手抄进文档必然对不上。常见做法是让接口定义只存在一份文档生成时读同一份数据。# build_iface_table.py —— 把 ifaces.csv 追加成文档附录避免手抄接口 import csv from docx import Document doc Document(dist/base.docx) # 基于 pandoc 产出的文件续写 doc.add_heading(附录 A 接口清单, level1) rows list(csv.DictReader(open(ifaces.csv, encodingutf-8))) table doc.add_table(rows1, cols5) table.style Table Grid # 不设样式部分阅读器里看不到边框 head table.rows[0].cells for i, name in enumerate([接口名, 方向, 协议, 周期(ms), 失效行为]): head[i].text name for r in rows: # 一行一条接口字段与 CSV 表头同名 cells table.add_row().cells cells[0].text r[name] cells[1].text r[direction] cells[2].text r[proto] cells[3].text r[period_ms] cells[4].text r[on_timeout] doc.save(dist/软件架构文档_v1.3.0_20250618.docx)逻辑上分三步加载 pandoc 产出的基线文档、追加一级标题、按 CSV 逐行写表格。Table Grid样式必须显式指定否则表格在部分阅读器和打印预览里没有边框看起来像排版事故。字段顺序刻意把失效行为放在最后一列并且不允许为空——这一列空着的接口测试阶段一定会回头找你。ifaces.csv的列名要和代码里的常量、以及文档里的表头保持同源改动时三处一起改。更彻底的做法是从接口定义文件IDL、protobuf、YAML直接生成 CSV中间不出现人工环节。3.4 目录、表格与交叉引用最容易翻车的三个点现象根因处理方式目录条目点不动静态文本目录不是 Word 域需要可点目录时在 Word 里重建域或接受静态目录编号跳号、层级错乱源文件里手写了3.1标题内不写编号统一交给--number-sections表格跨页丢表头参考样式未设标题行重复在 ref.docx 的表格样式里勾选重复标题行图号引用错位中文题注与域混用图号用题注域统一管理别手工编号这些问题的共同点是出在样式和工具链却总被当成内容问题在评审会上讨论。建议把转换命令和参考样式一起纳入版本管理谁改的样式、改完哪份文档走样了能直接查出来。4. Qt 上位机与智驾软件架构文档的分层写法差异同样叫架构文档上位机项目和智驾项目的写法差别很大。前者关心交互和线程后者关心时序和失效把一套模板硬套到两边结果就是两边都觉得没用。4.1 Qt 上位机软件架构文档把线程模型和信号槽写清楚Qt 上位机软件架构文档最常被漏掉的是线程模型。UI 线程、采集线程、数据处理线程怎么划跨线程用信号槽还是队列界面卡顿的锅最后都落在这里。层次职责允许依赖文档必须写清的点界面层控件、视图模型、交互业务层哪些耗时操作禁止在 UI 线程执行业务层状态机、流程编排通信层、数据层状态迁移条件与异常分支通信层串口/TCP/总线收发、协议解析无收发周期、断线重连策略数据层配置、日志、历史数据无落盘频率与容量上限写清允许的依赖方向比列模块重要界面层不得直接读串口、通信层不得弹窗这两条写进去后续加需求时有人想抄近路就会先来问一句。信号槽的跨线程连接方式自动连接还是队列连接建议在文档里显式标注这类细节在代码里是默认行为在评审时却是争议焦点。插件化设计的上位机还要额外写一节插件加载时机、插件与主程序的接口版本、插件崩溃时主程序的行为。不写这段现场加一个插件就把主程序带崩了。4.2 智驾软件架构文档功能链路、时序与失效约束智驾软件架构文档的读者更关心这条链路跑完要多久、慢了会怎样。所以文档的主线不是模块清单而是功能链路加时间预算。一条典型链路感知—融合—规划—控制至少要给出每个环节的处理周期、允许的最大延迟、超时后的降级动作。比如融合环节给 40 ms 预算超时就退化为上一帧结果并置降级标志——这句话写进文档测试才知道要构造什么样的延迟注入用例。安全性相关内容建议单列一节写清哪些输出属于安全相关、失效时必须进入什么状态而不是散落在各模块描述里。另一个差异是接口的时间属性必须量化周期、抖动容忍、时钟基准、时间戳单位。写周期约 20 ms和写周期 20 ms抖动不超过 2 ms时间戳取系统单调时钟毫秒是两份完全不同的文档后者才能被测试直接转成断言。4.3 接口表与时序描述的可复制模板接口定义用结构化文件维护文档和代码生成时读同一份是两边都省事的做法。# ifaces.yaml —— 一份定义同时喂给文档生成和代码生成 - name: BatteryStatus direction: plc_to_ui # 数据流向评审必看 proto: Modbus-TCP period_ms: 200 # 既是文档字段也是代码里的常量 timeout_ms: 600 # 超时判定写进失效处理章节 payload: - {field: soc, type: uint16, unit: %, range: 0~100} - {field: soh, type: uint16, unit: %, range: 0~100} on_timeout: 界面置灰并记录告警 # 失效行为测试照着造用例字段设计上有三处是有意为之direction强制写明流向避免评审时对着接口名猜谁调谁period_ms和timeout_ms成对出现超时值一般取周期的三倍写在同一处便于统一调整on_timeout是自由文本但必填它同时是文档内容和测试用例的来源。不同场景下这张表要补的列不一样场景必须补的列原因Qt 上位机线程归属、信号槽连接方式跨线程问题排查依赖这两列智驾链路抖动容忍、时钟基准、降级状态时序问题无法用单一周期描述对外接口协议版本、鉴权方式、字段废弃策略供应商升级节奏不由你控制5. 架构文档的变更追溯与打开异常排查技巧文档写完之后真正花时间的是两件事判断这次改动动了什么契约以及交付件在别人机器上打不开时怎么快速定位。5.1 用 diff 与结构校验盯住文档漂移改文档时最该被拦下来的不是文字修订而是章节消失——章节消失往往意味着某个约束不再有人维护。# 1) 先看这一版动了哪些文件、多少行 git --no-pager diff --stat HEAD~1 -- docs/architecture.md # 2) 只比标题结构章节增删比正文措辞重要得多 grep -nE ^#{1,3} docs/architecture.md /tmp/new.txt git show HEAD~1:docs/architecture.md | grep -nE ^#{1,3} /tmp/old.txt diff /tmp/old.txt /tmp/new.txt第一条命令给出改动规模第二条把章节树抽出来单独比。如果 diff 里出现以开头的标题行说明有章节被删掉了这类改动应当在合并请求里单独说明理由。把这两条放进提交前钩子成本很低但能挡住大部分顺手删了一节的情况。5.2 doc/docx 打不开或无法预览时的排查顺序交付件在不同机器上的表现不一致绝大多数不是文件坏了而是打开方式或关联出了问题。按下面顺序排查通常两步内定位。现象大概率原因快速验证处理提示无法预览 doc文件在只读缓存目录里被直接打开先另存到本地磁盘再打开另存为本地副本别人能开、本机空白文件带了锁定标记或关联被改右键属性看有无解除锁定解除锁定或重新建关联打开后字体编号全乱生成时未套参考样式看标题字体是否混排用--reference-doc重新生成文件只有几 KB生成脚本中断只写了骨架unzip -l xx.docx看有无 word/document.xml重跑生成脚本菜单新建里没有 WPS doc安装时未勾选模板组件看安装目录下有无模板文件修复安装或直接编辑 Markdown 源文件unzip -l这一招值得记住docx 本质是 zip 包内部缺少word/document.xml就说明生成过程根本没走完和阅读器无关。至于菜单新建没有 WPS doc这类情况在文档工作流里其实不重要——源文件是 Markdown新建文档这个动作本身就不该存在交付件一律从流水线里生成dist 目录不进版本管理需要 diff 的永远只有 architecture.md 和 adr/ 下的那些文件。本文还有配套的精品资源点击获取