3.6 编制文档：系统设计说明书¶
把分散的设计成果，整理成一份能指导开发的说明书¶
系统设计说明书不是前五节内容的简单拼接
架构图、页面原型、E-R 图、接口清单和权限矩阵分别解决不同问题。编制说明书时，要统一它们的名称、范围、规则和版本，让开发者能够从需求找到设计，从页面找到接口，从接口找到数据和业务规则。
一份有效的设计说明书不一定很长，但必须让团队知道“准备怎样实现、为什么这样设计、遇到不同情况怎样处理”。
本节学习目标
汇总并整理前五节设计成果，建立需求、模块、页面、接口和数据之间的追踪关系，编制结构清楚、内容一致、能够指导编码与测试的《系统设计说明书》初稿。
🎯 本节完成后，你要交付¶
| 成果 | 要求 |
|---|---|
| 《系统设计说明书》初稿 | 结构完整，能够覆盖核心需求和前五节设计成果 |
| 设计追踪表 | 建立需求、模块、页面、接口、数据表和状态规则之间的对应关系 |
| 图表与附件清单 | 所有原型、架构图、E-R 图和接口材料都有编号、标题和引用位置 |
| 文档变更记录 | 记录文档版本、修改内容、修改人和确认状态 |
| 待确认问题清单 | 将尚未决定的问题集中列出，说明负责人和完成时间 |
本节形成的是可评审的初稿。下一节还要通过设计评审发现问题、修改内容并形成最终版本。
📦 第一步：整理已有设计材料¶
先建立材料清单，不要一边寻找文件一边拼接文档。
| 来源 | 应有成果 | 编入说明书的位置 |
|---|---|---|
| 3.1 明确方案 | 设计目标、项目约束、技术选型、关键决策 | 设计概述、技术方案 |
| 3.2 设计架构 | 系统架构图、模块图、职责表、分层与目录 | 总体架构、功能模块 |
| 3.3 设计原型 | 页面清单、核心原型、页面状态和流程图 | UI 原型与页面流程 |
| 3.4 设计数据 | E-R 图、表清单、数据字典、约束和索引 | 数据库设计 |
| 3.5 完善规则 | 接口清单、权限矩阵、状态机和错误码 | 接口、权限与状态设计 |
建议建立设计材料目录¶
目录名称可以根据项目调整，但不要把正式版本、临时截图和过期草稿混在一起。
编制前检查材料¶
- 每项材料都有明确的最新版本；
- 图片和附件能够正常打开；
- 图中的文字清楚可读；
- 页面、模块、接口和数据表使用稳定名称；
- 待确认问题已经单独记录；
- 没有将真实密码、密钥和隐私数据放入文档。
先整理材料，再开始写正文
如果同一张图存在“最终版”“最终版2”“真的最终版”等多个文件，应先确认保留哪一个。无法判断版本的材料很容易让说明书内部产生矛盾。
👥 第二步：明确文档读者和使用场景¶
系统设计说明书不是只交给教师评分，它还要服务后续开发、测试、协作和答辩。
| 读者 | 主要关心什么 | 文档应提供什么 |
|---|---|---|
| 开发者 | 功能怎样拆分、代码怎样组织、接口和数据怎样使用 | 架构、模块职责、接口、表结构和业务规则 |
| 测试者 | 什么情况下允许操作、成功和失败结果是什么 | 页面流程、状态转换、权限、错误码和验收对应关系 |
| 项目成员 | 谁负责什么、模块之间怎样配合 | 模块边界、依赖关系和统一约定 |
| 教师或评审者 | 设计是否符合需求、范围是否合理、方案是否可行 | 设计依据、关键决策、追踪关系和风险说明 |
| 未来的自己 | 当时为什么这样设计、修改会影响哪里 | 决策理由、版本记录和待改进事项 |
写作时可以不断追问：
一个没有参加当前讨论的人，只阅读这份说明书，能否理解系统怎样实现核心业务？
🧭 第三步：搭建说明书目录¶
对于课程项目，可以采用下面的结构。章节数量不是评价重点，关键是内容能互相对应。
推荐目录¶
项目规模较小时可以合并章节。例如把“部署、质量与安全考虑”缩成一节，但核心架构、原型、数据、接口、权限和状态不应缺失。
目录服务于内容，不追求形式复杂
不要为了让文档看起来正式而设置大量空章节。确实不适用的内容可以说明“不涉及”及原因，不要复制与项目无关的通用文字。
✍️ 第四步：编写文档概述¶
文档开头要让读者快速知道这是什么项目、设计到什么范围、以什么材料为依据。
编写目的¶
可以采用下面的表达方式：
不要只写“为了完成课程任务，特编写此文档”。编写目的应说明文档准备解决什么协作和实现问题。
项目范围¶
简要说明：
- 系统服务哪些用户；
- 解决什么核心问题；
- 本期实现哪些主要功能；
- 哪些内容明确不在本期范围；
- 文档覆盖到什么设计深度。
范围应与《项目选题立项书》和《需求分析说明书》一致，不要在设计说明书中悄悄扩大功能。
设计依据¶
| 文档或材料 | 版本或日期 | 本文档使用的内容 |
|---|---|---|
| 《项目选题立项书》 | V1.0 | 项目目标、范围和约束 |
| 《需求分析说明书》 | V1.1 | 用户、功能、流程、规则和验收条件 |
| 原型评审记录 | 2026-04-20 | 页面调整和交互确认结果 |
| 课程技术规范 | 当前版本 | 技术环境、文档和交付要求 |
术语与缩写¶
| 术语或缩写 | 含义 |
|---|---|
| 活动管理员 | 可以创建、发布和关闭活动的管理角色 |
| 有效报名 | 当前处于 VALID 状态并计入活动名额的报名记录 |
| API | 前端与后端之间的数据访问接口 |
只有项目中容易产生歧义或频繁使用的术语需要解释，不必把常见技术名词全部抄进来。
🧩 第五步：将设计内容写成“图、表、说明”¶
设计说明书不应只放图片，也不应全是大段文字。每项关键设计最好包含三部分：
- 图：帮助读者快速理解结构、流程或关系；
- 表：给出准确的名称、字段、权限和规则；
- 说明：解释设计理由、边界、异常和注意事项。
架构章节的写法¶
原型章节的写法¶
每个核心页面至少说明：
| 内容 | 示例 |
|---|---|
| 页面任务 | 学生查看活动信息并决定是否报名 |
| 使用角色 | 学生 |
| 主要信息 | 名称、时间、地点、名额、介绍和报名状态 |
| 主要操作 | 返回列表、立即报名、取消报名 |
| 页面状态 | 加载中、名额已满、已报名、请求失败 |
| 相关接口 | ACT-02、SIGN-01、SIGN-02 |
数据库章节的写法¶
E-R 图后面应有关系说明，数据表清单后面应有完整数据字典。不要只粘贴建表 SQL，因为 SQL 不容易让所有读者快速理解业务含义。
接口章节的写法¶
接口清单覆盖全部主要接口；详细说明优先覆盖：
- 用户登录和身份相关接口；
- 会新增、修改或删除业务数据的接口；
- 会改变业务状态的接口；
- 涉及角色和数据权限的接口；
- 规则复杂或容易失败的核心接口。
普通字典查询或简单详情接口可以使用统一表格简要说明，不必为每个接口重复相同文字。
🔗 第六步：建立需求与设计追踪关系¶
追踪表用于证明每个核心需求都有设计支撑，也帮助发现多余设计和遗漏内容。
需求—设计追踪表示例¶
| 需求编号 | 需求说明 | 功能模块 | 页面 | 接口 | 数据表 | 权限或状态 |
|---|---|---|---|---|---|---|
| FR-01 | 学生浏览已发布活动 | 活动管理 | 活动列表、详情页 | ACT-01、ACT-02 | activity |
学生可查看 PUBLISHED 活动 |
| FR-02 | 学生报名活动 | 活动报名 | 活动详情页 | SIGN-01 | activity_signup、activity |
学生本人；活动为 PUBLISHED |
| FR-03 | 学生查看本人报名 | 活动报名 | 我的报名页 | SIGN-03 | activity_signup、activity |
只能查看当前用户数据 |
| FR-04 | 管理员发布活动 | 活动管理 | 活动编辑、管理页 | ACT-03、ACT-04 | activity |
管理员；DRAFT → PUBLISHED |
使用追踪表发现问题¶
| 现象 | 可能的问题 | 处理方式 |
|---|---|---|
| 需求没有页面 | 用户没有功能入口 | 补充页面或说明由其他入口完成 |
| 页面没有接口 | 页面数据来源或操作方式不清 | 补充接口或说明为纯前端行为 |
| 接口没有数据表 | 数据来源和保存方式不清 | 补充数据设计或说明来自外部服务 |
| 状态没有操作入口 | 状态可能无法进入或退出 | 检查页面和接口设计 |
| 设计没有需求编号 | 可能擅自扩大了范围 | 找到依据或删除多余设计 |
追踪不是为了填满表格
只对核心需求和关键设计建立追踪即可。重点是能够发现遗漏、矛盾和无依据设计，不是把每个按钮和字段都机械编号。
🏷️ 第七步：统一名称、编号和交叉引用¶
统一业务名称¶
同一个概念在整份文档中应使用相同名称：
建议统一编号¶
| 对象 | 编号示例 | 用途 |
|---|---|---|
| 功能需求 | FR-01 | 需求与设计追踪 |
| 核心接口 | SIGN-01 | 接口、页面和测试引用 |
| 图 | 图 3-1 系统架构图 | 正文交叉引用 |
| 表 | 表 5-2 活动表数据字典 | 快速定位内容 |
| 设计决策 | ADR-01 | 记录重要方案及理由 |
编号一旦在团队中使用，不要随意改变。删除内容后也不必为了连续好看而重新编号所有接口，否则会影响代码注释、测试记录和讨论历史。
正确引用图表¶
不要写“如下图”“见上表”后让读者自己寻找。可以写：
🖼️ 第八步：规范图表和附件¶
图表基本要求¶
- 每张图和表都有明确标题；
- 图中文字在正常页面宽度下清楚可读；
- 使用与正文一致的业务名称；
- 箭头、颜色和线型有明确含义；
- 正文中说明图表达了什么；
- 修改设计后同步更新图片和说明；
- 不保留原型工具默认的无关示例内容。
Mermaid 图的优点¶
Mermaid 源码可以与 Markdown 文档一起版本管理，名称修改后更容易同步。适合绘制：
- 系统架构图；
- 功能模块图；
- 页面流程图；
- E-R 图；
- 业务状态机；
- 核心业务时序图。
复杂 UI 原型仍可以使用专业原型工具，导出图片后放入附件目录，并在正文中引用。
图片引用示例¶
图片文件名应体现内容，例如 activity-detail.png，不要使用 截图1.png、未命名.png。
正文保留关键内容，附件保存完整细节
核心架构、流程、表清单和接口约定应在正文中直接出现。大量页面原型、完整数据字典或接口导出文件可以放入附件，但正文必须提供说明和访问路径。
⚖️ 第九步：控制文档详略¶
应该重点写清的内容¶
- 影响多个模块的技术和架构决策；
- 核心业务流程及其页面、接口和数据变化；
- 容易产生不同理解的业务规则；
- 权限、数据范围和业务状态；
- 失败、边界和数据一致性处理；
- 与课程模板或常规做法不同的设计。
可以简要说明的内容¶
- 框架默认行为且项目没有特殊修改的部分；
- 简单、重复的基础查询接口；
- 原型中显而易见的普通布局细节；
- 与核心流程无关的低风险配置。
不应该出现的内容¶
- 从其他项目复制、与当前项目无关的架构描述；
- 已经取消但没有删除或标注的旧方案；
- 无法解释的复杂技术和中间件；
- 大段代码实现细节；
- 未验证的“高并发、高可用、绝对安全”等口号；
- 真实账号、密码、密钥、身份证号等敏感数据。
写得多不等于设计得好
如果几十页文字无法回答“一个报名请求怎样经过系统、检查哪些规则、修改哪些数据”，文档仍然不能指导开发。优先保证核心设计准确、一致、可追踪。
🔄 第十步：管理版本和变更¶
设计会随着评审和开发逐步调整，但每次改变都应留下记录。
文档变更记录¶
| 版本 | 日期 | 修改内容 | 修改人 | 状态 |
|---|---|---|---|---|
| V0.1 | 2026-04-10 | 建立说明书目录和总体架构 | 项目成员 | 草稿 |
| V0.2 | 2026-04-15 | 补充原型、数据库和接口设计 | 项目成员 | 待评审 |
| V0.3 | 2026-04-22 | 根据评审意见调整权限和状态 | 项目成员 | 已修改 |
| V1.0 | 2026-04-25 | 完成评审并确认开发基线 | 项目组、教师 | 已确认 |
什么变化需要同步更新文档¶
| 变化 | 需要检查的内容 |
|---|---|
| 增加或删除功能 | 需求、模块、页面、接口、数据和追踪表 |
| 修改页面字段 | 原型、接口参数、数据字典和校验规则 |
| 修改业务状态 | 页面按钮、接口规则、数据库取值和测试场景 |
| 修改权限 | 菜单、接口、数据范围和权限矩阵 |
| 修改表结构 | E-R 图、数据字典、SQL、接口字段和初始化数据 |
| 修改技术方案 | 架构图、部署方式、风险和关键决策记录 |
文档与代码不一致时，不能默认代码永远正确
先判断是需求和设计已经正式变更但文档没有更新，还是代码偏离了已确认方案。确认事实后再同步修改，避免用错误实现反过来覆盖正确设计。
❓ 第十一步：集中管理待确认问题¶
不要把“待定”“可能”“以后再说”散落在各章节中。统一建立问题清单：
| 编号 | 问题 | 影响范围 | 负责人 | 计划确认时间 | 状态 | 结论 |
|---|---|---|---|---|---|---|
| Q-01 | 活动取消后是否保留报名历史？ | 数据表、状态机、查询接口 | 项目成员 | 4 月 20 日 | 待确认 | — |
| Q-02 | 游客是否可以浏览活动？ | 页面入口、接口权限 | 教师、项目成员 | 4 月 20 日 | 已确认 | 允许查看已发布活动 |
影响核心流程、数据库结构或权限边界的问题，应在进入编码前解决。暂时不影响项目骨架的问题可以保留，但要明确负责人和处理时间。
🤖 第十二步：用 AI 辅助整理和检查文档¶
AI 适合帮助整理结构、统一术语、生成追踪表和发现矛盾，但不能替你确认业务决定。
整理文档提示词¶
一致性检查提示词¶
人工审核 AI 整理结果¶
- 是否保留了原设计的真实含义；
- 是否把“待确认”擅自改成了确定结论；
- 是否添加了不存在的技术、接口、表或角色；
- 是否为了文字流畅删除了关键条件和异常；
- 图表编号和链接是否真实存在；
- 追踪表中的对应关系是否可以逐项验证；
- 自己能否解释文档中的每个关键决定。
语言通顺不能代替事实正确
AI 可以把文档写得很像正式报告，但它也可能统一了错误术语、补全了不存在的功能。编制完成后必须回到需求、原型、数据库和接口材料逐项核对。
📋 《系统设计说明书》模板¶
下面的模板可以直接复制到项目文档中，再用真实设计内容替换提示文字：
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 | |
✅ 本节自查¶
- 文档说明了编写目的、项目范围、设计依据和目标读者；
- 文档范围与立项书、需求分析说明书保持一致；
- 技术选型、系统架构和项目结构相互一致；
- 架构、模块、原型、数据库、接口、权限和状态内容完整；
- 核心设计同时具有图、表和必要文字说明；
- 每个核心需求都能追踪到模块、页面、接口和数据；
- 页面操作、接口字段和数据字典使用一致名称；
- 权限矩阵同时说明角色和数据范围；
- 状态值和转换规则在页面、接口与数据库中一致；
- 图表具有清楚标题，文字可读，正文中有引用和说明；
- 所有附件链接和图片路径都能正常打开；
- 过期方案已删除或清楚标记，没有与当前方案混用；
- 待确认问题集中记录，并有负责人和计划时间；
- 文档包含版本、修改日期、修改内容和当前状态；
- 文档没有真实密码、密钥、隐私数据和无关模板内容；
- 项目成员能够依据文档拆分开发和测试任务。
当一个没有参与设计讨论的同学能够根据说明书说清系统结构，并能找到实现某项核心功能需要的页面、接口、数据和规则，这份初稿就具备了进入评审的条件。
📝 总结¶
- 说明书是统一设计基线：把架构、原型、数据、接口、权限和状态整理成一致方案；
- 不是简单拼接材料：要统一名称、编号、版本和相互引用；
- 用追踪关系发现遗漏：核心需求都应能找到对应模块、页面、接口和数据；
- 重点写清关键决定和规则：设计理由、业务边界、权限、状态和失败情况不能省略；
- 先形成可评审初稿：待确认问题明确记录，下一节再通过评审完成定稿。