第三章 文档结构总览与模板框架
本章适用场景
- 首次搭建机器人原型说明书体系的项目团队，需要统一文档骨架。
- 已有零散技术文档但缺乏结构标准，需要进行重构归档的场合。
- 跨部门协作时，需确保项目成员、评审专家、客户对文档结构有一致预期。
前置条件
- 已完成机器人原型的需求分析与系统架构定义（至少完成功能框图）。
- 项目组指定了文档主编（技术写作角色）与各模块技术负责人。
- 团队确认使用本标准模板，并承诺后续迭代中维持结构不变。
操作步骤
- 确定文档分层结构：按“封面→目录→正文模块→附录”四大块划分，正文内再按子系统/功能域分章。
- 选取标准模板：从项目知识库或本指南附录B中拷贝空白说明书模板（.docx / .md / .typ 格式），字段预填版本、日期、保密等级。
- 填充正文模块：各模块负责人按SOP填写对应章节，必须包含概述、规格参数、接口定义、测试验证四节，缺一不可。
- 附录收尾：收集全部设计图纸、物料清单、测试记录、术语表，按字母顺序或时间顺序编入附录。
- 一致性审查：主编校验封面信息、目录页码、正文交叉引用、附录索引，确保无断裂或歧义。
输入输出物
| 类型 | 名称 | 来源/去向 |
|---|---|---|
| 输入 | 系统总体方案设计报告 | 系统架构师提供 |
| 输入 | 各子系统技术规范草稿 | 机械/电气/软件工程师提供 |
| 输出 | 《机器人原型说明书》V1.0（含封面、目录、4+正文模块、附录） | 交付项目经理与客户评审 |
| 输出 | 模板调整建议清单 | 反馈至流程SOP课程维护组 |
责任边界
- 文档主编：负责框架完整性、版本控制、格式统一、最终签发。
- 各模块责任人：对其负责章节的技术准确性、数据真实性、图表清晰度负责。
- 质量保证（QA）：审查结构合规性（本指南第3章要求）和可读性。
- 项目经理：审核封面保密等级与分发范围，批准文档发布。
记录材料
以下为各模块应保留的记录表单或检查表：
| 模块 | 必备记录 | 归档位置 |
|---|---|---|
| 封面 | 版本历史表、保密协议签署页 | 项目文档库 / 封面后页 |
| 目录 | 自动生成的页码索引（无手动填写） | 封面之后 |
| 正文模块 | 各章签名/评审时间戳 | 章末“变更记录”区域 |
| 附录 | 图纸编号清单、物料BOM版本、术语定义表 | 附录A、B、C…… |
异常处理
| 异常场景 | 处理措施 |
|---|---|
| 某子系统无独立模块，需合并到通用章节 | 在正文“通用平台”下创建子章节，并在目录中标注“本系统合并自X/Y模块” |
| 附录内容过多（>100页） | 拆分独立成《附录专册》，在说明书正文附录索引页写明专册编号及下载链接 |
| 封面信息与正文版本不一致 | 主编触发版本对齐会议，强制锁定封面版本号与正文第一页的版本声明一致 |
| 目录页码全部错位 | 检查是否为模板域代码未更新，重新生成目录域（Word：Ctrl+A → F9） |
验收标准
- 封面包含项目全称、文档编号、版本、日期、保密等级、主编签章区域。
- 目录自动生成且页码与正文完全匹配，无手动修改痕迹。
- 正文模块包含且仅包含：概述、规格参数、接口定义、测试验证四个子节，顺序不可颠倒。
- 附录至少包含：术语表、图纸清单、物料BOM（V1.0或更高）、测试原始记录。
- 全文交叉引用（如“参见附录A”）的标号与实际附录编号一一对应。
- 经过至少一次主编与QA的全量通读，无事实错误、无矛盾术语、无空章节。
要点提示：封面与目录是文档的“入口”，正文模块是“内核”，附录是“支撑文档仓库”。本模板要求正文内部必须包含概述、规格参数、接口定义、测试验证四个子节，这是保证说明书可维护性的最小完备集合。
实践建议：在项目启动初期，由文档主编组织一次30分钟的“结构对齐会”，对全体模块负责人展示本图，并逐节点确认各自模块是否满足“四个子节”要求。常见问题是“规格参数”与“接口定义”内容重叠——此时需明确边界：规格参数只写数值与公差，接口定义写位置、类型、协议等配对信息。
常见错误：部分团队将“测试验证”简化为几句话，或完全依靠独立的测试报告代替。须知测试验证是正文模块的固定子节，即使只有一句话“测试结果合格，详见附录D”也必须存在。缺失该子节将导致文档结构不合格，不予签发。
记录材料存档要求
- 封面与目录需扫描成PDF带签章，连同原始可编辑文件一起归档。
- 正文模块的各章末尾必须保留
【变更记录】表格，记录修改日期、修改人、修改摘要。 - 附录中如果包含外部引用文件（如CAD图纸），必须在附录索引页注明文件名称、格式、存放路径。
以下为封面页元数据区域的示例（来自模板文件 cover_metadata.yaml）：
project_name: "R2-D2 Service Robot Prototype"
document_id: "R2D2-PROTO-SPEC-001"
version: "v1.0.0"
date: "2027-04-15"
classification: "Internal"
editor: "zhang.wei@robotcorp.com"
approval_chain:
- reviewer: "li.ming"
date: "2027-04-10"
- approver: "wang.xiao"
date: "2027-04-12"
将此YAML段嵌入封面页背面，即可实现机器可读的元数据管理，与正文模板联动。