一份全面的“详细设计说明书”是怎样的？

对于详细设计说明书，有很多刚入行的小白对此有很多的迷惑，在这里我就接着多年的工作经验，并拿出曾经给负责的一个项目撰写的概要设计说明书来作为案例给大家展示一下，写得不好，其中也有很多欠缺之处，愿朋友们看过之后能够给出很好的批评，咱们在这里相互学习、共同进步！

1. 引言

1.1 修订记录

1.2 简述

在这片文档中，我们开始探讨每个模块该如何具体实现，每个实现中需要哪些算法、属性、参数、数据结构、接口，并以此来完成“XXXX管理平台详细设计说明书”的工作。

1.3 编写目的

本说明书确定系统的详细功能模块和数据结构，为下阶段开发工作提供依据。

1.4 背景

• 软件系统的名称： XXXX管理平台
• 本项目的任务提出者： XXX市经济和信息化委员会
• 开发本项目公司名称： XXX城投公路投资（集团）有限公司、XXX市地下空间设计研究总院有限公司（地下院）
• 公司开发项目组名称： 基于BIM协同管理平台研发组
• 软件系统的用户对象： 建设单位、设计院、施工单位
• 这个系统的基本概念： 结合BIM、GIS、Web等技术搭建一个XXXX管理平台，实现各参与方的协同交流、信息共享，实现对进度、成本、质量安全的动态掌控，实现可视化、智能化和移动化管理，为管理和决策提供帮助，提升项目的精细化管理水平，提高工程管理和决策效率，减少返工浪费，保证工期，提高工程质量和投资效益。

1.5 范围

本文根据相关资料制定，在分析了XXXX管理平台需求的基础上制定本规范，适用于XXXX管理平台的开发。

1.6 定义

• 名称： 详细设计说明书。
• MIS： 管理信息平台。
• 质量技术交底： 对一个工程项目开始时提出的要达到的质量要求。
• 人力强度： 一个工程项目每个时间段投入人力的分布。

1.7 限制条件

必须保证程序正常的连接到服务器，并保持网络的畅通。

1.8 参考资料

1. 《XXXX管理平台——计划任务书》
2. 《XXX市信息化发展专项资金项目建设方案编制大纲——XXXX管理平台》
3. 《XXXX管理平台——课题综述报告》
4. 《XXXX管理平台——技术报告》
5. 《XXXX管理平台——概要设计说明书》
6. 《XXXX管理平台——任务书盖章版》
7. 《XXXX管理平台——建设方案》
8. 《XXXX管理平台——项目研发计划说明书》

2. 任务描述

2.1 目标

根据概要设计说明书中的设计内容，对整个系统所需实现的功能以及系统的功能模块的划分和功能模块的具体实现过程提供详细的说明，为整个系统的开发、测试、评定和移交的提供基础。

2.2 详细设计方法和工具

（1）方法

• 模块结构图；
• 模块业务流程图；
• 系统整页截图；
• 详细设计说明表；
• 窗口对象说明表；
• 模块相互关系表。

（2）工具

• vsdx作图工具： 针对于模块业务流程图；
• axure原型工具： 针对于模块结构图；
• QQ自带裁切工具： 针对于业务流程图和结构图大小之间的设定；
• Goole Chrome高效截图插件： 针对于系统整页截图。

2.3  主要设计

• 软件开发生命周期方法和敏捷开发相结合。
• 自定向下，逐步求精的结构化的设计。
• 模板化组件的综合和多元化窗口利用的设计理念。

2.4  环境

（1）硬件环境

• windows服务器： CPU4核8G/操作系统windows server2008R2/SSD云盘40G/数据盘（高效云盘）512G；
• linuxs服务器： CPU4核8G/操作系统04 64/SSD云盘40G/数据盘（高效云盘）256G。

（2）软件环境

• 开发系统： CentOS；
• 操作系统： win9及以上；
• 数据库： Mysql；
• 网络协议： TCP/IP；
• 开发环境： Linux；
• 使用软件： Windows Server 2008。

3. 系统设计

3.1 设计原则

在确定目标系统的过程中，主要遵循了以下几个原则：

• 目标系统基本上完整地实现IPSec协议族，完全支持VPN的要求；
• 目标系统的服务器端一定要建立在具有自主版权的内核操作系统之上；
• 目标系统的客户端使用方便、界面友好、配置和管理简单灵活。

3.2 程序文件

3.3 全局变量

3.4 公用控件

（1）用户对象

（2）全局结构

（3）全局函数

（4）公用窗口

3.6 主窗口

系统主窗口继承自模板模式。当窗口打开时根据网卡地址获取栏目代码及名称，调用父类函数设置栏目及管理员信息。为减少访问数据库次数，提高查询速度，将常用数据表：功能模块、默认条件、栏目代码、用户代码、管理性质、模块编码、编码设置、编码明细、通用模块、独立功能、列表信息下载到本地缓存中，即将其保存到全局结构中。

3.7 主菜单

系统主菜单继承自基础架构。为了方便查询功能的使用及扩展，所有查询功能均不挂在菜单项中，而是通过各功能模块所对应的窗口名称将其打开，因此主菜单只需增加以下项目：

功能：

• 打开： 打开功能模块窗口。
• 关闭： 关闭功能模块窗口。
• 编辑： 对功能模块进行维护。
• 权限： 设置用户查询权限。
• 刷新： 重新检索功能模块表，用于对功能模块修改后刷新屏幕。

4. 界面设计要求

用户界面采用扁平化的设计风格，美观和简洁的同时，便于用户进行操作，也增加了整个系统运行的稳定性、加载能力。

4.1 用户界面设计规则

（1）字体

PingFang SC、Helvetics Neue、Arial、Hiragino Sans GB、Microsoft Yahei、微软雅黑、STHeiti、华文细黑、sans-serif，正常体/400微粗体，（12至20）px，黑色/白色（打印文字不在此限）。

（2）风格

采用全屏网页设计，扁平化、视差化的化繁为简的设计思维，让整个网站的整体性、统一性、灵活性、自适应性、流畅性得到了相对的提高，也使得平台的功能处理和管理能力在这些特点的加持之下得到综合性的展示。

（3）色系

• 主题色调： 蓝、白、黑。
• 嵌入色调： 灰、绿、红。

（1）控件

1）尺寸

在合理的布局下尽可能多的显示控件内的内容。

2）布局

按照操作流程或浏览顺序自左至右、由上而下的排放各种控件，使界面整体协调、简洁、美观大方。

3）自适应父对象的尺寸改变

控件应具有自适应父对象的尺寸改变的能力，当父对象的尺寸发生变化时，控件应能自动改变自己的尺寸并使界面保持整体协调，尽量减少因父对象的尺寸改变而带来的操作或浏览上的不便。

5. 模块结构设计

5.1 概述

XXXX管理平台主要有用户管理、工程模型、信访管理、进度管理、质量管理、安全管理、风险管理、监测可视化、投资管理、腾地管理、运维管理、文件管理、工程周报、视频监控14个功能模块，根据这些功能模块，以对应的结构图对其进行解析，用更加简单的方式来展示每一个功能模块的基本结构和主要的功能点。

5.2 用户管理模块

（1）概述

用户管理模块分为用户列表和用户组列表两个大项，根据项目的实际需求，可创建不同的用户多用户角色，同时该角色可分配相应的操作权限。

（2）模块所涉及的文件

（3）用户管理模块结构图

5.3 工程模型

（1）概述

工程模型可以进行web浏览和漫游，可以通过旋转平移等简单操作查看整个模型，并可通过模型树快速点选构件，并可进行隐藏，亦可以通过剖面框、开洞等控件对模型进行多角度多方位的查看。

（2）模块所涉及的文件

（3）工程模型模块结构图

5.4 信访管理

（1）概述

将12345、投诉信箱等投诉渠道获得的针对工程各施工工地产生的投诉工单，根据来源、时间、工段、地区、类型进行分类统计并关联模型，形成分析图表，并且推送相关施工单位进行情况的核实与反馈，帮助指挥部对确实存在的问题进行监管与督促整改。

（2）模块所涉及的文件

（3）信访管理模块结构图

5.5 进度管理

（1）概述

分析利用WBS编辑器，完成施工段划分、WBS和进度计划创建，建立WBS与Microsoft Project的双向链接；通过BIM模型，对施工进度进行查询、调整和控制，使计划进度和实际进度既可以用甘特图表示，也可以以动态的3D图形展现出来，实现施工进度的4D动态管理;可提供任意WBS节点或3D施工段及构件工程信息的实时查询、计划与实际进度的追踪和分析等功能。

（2）模块所涉及的文件

（3）进度管理模块结构图

5.6 质量管理

（1）概述

主要以验收数据为依据，围绕部件、区域和时间展开分析，并给出结论和建议。

系统将质量或检验报告与BIM信息模型相关联，可以实时查询任意WBS节点或施工段及构件的施工质量情况，并可自动生成工程质量统计分析报表，使相关人员能够对工程质量问题进行查看及处理回复。

（2）模块所涉及的文件

（3）质量管理模块结构图

5.7 安全管理

（1）概述

主要以验收数据为依据，围绕部件、区域和时间展开分析，并给出结论和建议。

系统将安全报告与BIM信息模型相关联，可以实时查询任意WBS节点或施工段及构件的施工安全情况，并可自动生成工程安全统计分析报表，使相关人员能够对工程安全问题进行查看及处理回复。

（2）模块所涉及的文件

（3）安全管理模块结构图

5.8 风险管理

（1）概述

通过设置风险判定规则或相关人员手动录入相关数据，针对不同风险源位置以及风险等级，标注相应的风险或安全标识，亦可实时展现工程风险状态分布。相关人员也可以通过移动端拍照和定位功能，实现风险监察。

（2）模块所涉及的文件

（3）风险管理模块结构图

5.9 监测可视化

（1）概述

以BIM模型为基础，将施工方、监理方以及第三方监测数据与4D信息模型相关联，可以反映了当前工程安全状况（危险区域和预警区域）、实时查询任意施工段及周边环境的安全情况，并可进行预警信息自动推送。

（2）模块所涉及的文件

（3）监测可视化模块结构图

5.10 投资管理

（1）概述

基于BIM模型自动生成工程量表，并可自动根据进度情况生成周、月、季度的工程量统计和指定时间段的工程量，并可以根据施工进度预测下一计算区间的工程量。

（2）模块所涉及的文件

（3）投资管理模块结构图

5.11 腾地管理

（1）概述

通过相关人员录入的腾地相关信息，对工程的腾地情况进行整理汇总，包括腾地的地点、所属区属、长度、面积等。并与模型相关联，直观反映腾地的完成情况以及未完成的原因。

（2）模块所涉及的文件

（3）腾地管理模块结构图

5.12 运维管理

（1）概述

目标是为后期的运维提供一套完整的设施和设备信息，便于后期运营过程中使用。

该系统包括设备管理、设施管理两个部分。

（2）模块所涉及的文件

（3）运维管理模块结构图

5.13 文件管理

（1）概述

对设计方上传的BIM成果进行管理，设计方BIM成果包括市政管线综合、交通碰撞报告等应用成果，按照版本和类别进行管理和调用，方便资料的查找和整理。

（2）模块所涉及的文件

（3）文件管理模块结构图

5.14 工程周报

（1）概述

基于平台所管理的工程量数，每周对文件进行填报和查看。

（2）模块所涉及的文件

（3）工程周报模块结构图

5.15 视频监控

（1）概述

通过与施工现场监控摄像头的数据对接，能够获取即时的监控图像，相关人员也能够控制摄像头的方向，实现通过平台即能观察施工现场的具体情况。

（2）模块所涉及的文件

（3）视频监控模块结构图

6. 平台各模块的设计说明

6.1 概述

平台各模块的设计说明包括各模块业务流程图、各模块的详细设计说明表、窗口对象说明表、相互关系说明表，从多方面对各个模块的功能、类型、性能、算法逻辑、接口用详细多元精准的表结构进行阐述，以求此种描述方法来让项目文档更加的全面和详细。

6.2 用户管理模块

（1）用户管理业务流程图

（2）用户管理设计说明

1）模块详细设计说明

用户管理详细设计说明表：

编号：说明01

2）窗口对象说明

用户管理窗口对象说明表：

编号：窗口01

3）模块相互关系设计说明

用户管理相互关系说明表：

编号：关系01

6.3 工程模型模块

（1）工程模型业务流程图

（2）工程模型设计说明

1）模块详细设计说明

工程模型详细设计说明表：

编号：说明02

2）窗口对象说明

工程模型窗口对象说明表

编号：窗口02

3）模块相互关系设计说明

工程模型相互关系说明表

编号：关系01

6.4 信访管理模块

（1）信访管理业务流程图

（2）信访管理设计说明

1）模块详细设计说明

信访管理详细设计说明表

编号：说明03

2）窗口对象说明

信访管理窗口对象说明表

编号：窗口03

3） 模块相互关系设计说明

信访管理相互关系说明表

编号：关系03

6.5 进度管理模块

（1）进度管理业务流程图

（2）进度管理设计说明

1）模块详细设计说明

进度管理详细设计说明表

编号：说明04

2）窗口对象说明

进度管理窗口对象说明表

编号：窗口04

3）模块相互关系设计说明

进度管理相互关系说明表

编号：关系04

6.6 质量管理模块

（1）质量管理业务流程图

（2）质量管理设计说明

1）模块详细设计说明

质量管理详细设计说明表

编号：说明05

2）窗口对象说明

质量管理窗口对象说明表

编号：窗口05

3）模块相互关系设计说明

质量管理相互关系说明表

编号：关系05

6.7 安全管理模块

（1）安全管理业务流程图

（2）安全管理设计说明

1）模块详细设计说明

安全管理详细设计说明表

编号：说明06

2）窗口对象说明

安全管理窗口对象说明表

编号：窗口06

3）模块相互关系设计说明

安全管理相互关系说明表

编号：关系06

6.8 风险管理模块

（1）风险管理业务流程图

（2）风险管理设计说明

1）模块详细设计说明

风险管理详细设计说明表

编号：说明07

2）窗口对象说明

风险管理窗口对象说明表

编号：窗口07

3）模块相互关系设计说明

风险管理相互关系说明表

编号：关系07

6.9 监测可视化模块

（1）监测可视化业务流程图

（2）监测可视化设计说明

1）模块详细设计说明

监测可视化详细设计说明表

编号：说明08

2）窗口对象说明

监测可视化窗口对象说明表

编号：窗口08

3）模块相互关系设计说明

监测可视化相互关系说明表

编号：关系08

6.10  投资管理模块

（1）投资管理业务流程图

（2）投资管理设计说明

1）模块详细设计说明

投资管理详细设计说明表

编号：说明09

2）窗口对象说明

投资管理窗口对象说明表

编号：窗口09

3）模块相互关系设计说明

投资管理相互关系说明表

编号：关系09

6.11  腾地管理模块

（1）腾地管理业务流程图

（2）腾地管理设计说明

1）模块详细设计说明

腾地管理详细设计说明表

编号：说明10

2)窗口对象说明

腾地管理窗口对象说明表

编号：窗口10

3)模块相互关系设计说明

腾地管理相互关系说明表

编号：关系10

6.12  运维管理模块

（1）运维管理业务流程图

（2）运维管理设计说明

1）模块详细设计说明

运维管理详细设计说明表

编号：说明11

2）窗口对象说明

运维管理窗口对象说明表

编号：窗口11

3）模块相互关系设计说明

运维管理相互关系说明表

编号：关系11

6.13  文件管理模块

（1）文件管理业务流程图

（2）文件管理设计说明

1）模块详细设计说明

文件管理详细设计说明表

编号：说明12

2）窗口对象说明

文件管理窗口对象说明表

编号：窗口12

3）模块相互关系设计说明

文件管理相互关系说明表

编号：关系12

6.14  工程周报模块

（1）工程周报业务流程图

（2）工程周报设计说明

1）模块详细设计说明

工程周报详细设计说明表

编号：说明13

2）窗口对象说明

工程周报窗口对象说明表

编号：窗口13

3）模块相互关系设计说明

工程周报相互关系说明表

编号：关系13

6.15  视频监控模块

（1）视频监控业务流程图

（2）视频监控设计说明

1）模块详细设计说明

视频监控详细设计说明表

编号：说明14

2）窗口对象说明

视频监控窗口对象说明表

编号：窗口14

3）模块相互关系设计说明

视频监控相互关系说明表

编号：说明14

7. 文档附录

7.1 概述

这一部分主要是对详细设计文档中未提及或者有所遗漏的分析内容进行补充，这些和以上部分相比并不是必需的，所以将这些不必需的内容在附录这里进行一一阐述。

7.2 数据存储设计描述

（1）结构化数据存储描述

用于存储来自客户端的业务数据，并满足对所存储数据的安全、检索、统计等需求。

结构化数据常使用数据库来存储，数据库目前主要分为以下两大类：

1. 关系型数据库（SQL）： 建立在关系模型基础上的数据库，借助于集合代数等数学概念和方法来处理数据库中的数据。现实世界中的各种实体以及实体之间的各种联系均用关系模型来表示，可以用SQL语句方便的在一个表以及多个表之间做非常复杂的数据查询；关系型数据库支持复杂的事务管理，对于一致性要求较高的操作，常借助于数据库的事务管理保证程序操作的一致性，常见的有：SQLServer（付费）、Oracle（付费）、MySQL、DB2（付费）等；
2. 非关系型数据库（NOSQL）： 其数据存储可以不固定的表格模式，也经常会避免使用SQL的JOIN操作，一般有水平可扩展性的特征，由于减少了对数据依赖关系的管理，对数据管理的重点放在了存储和检索上，因此相对SQL数据库，NOSQL数据库具备相抵较高的性能以及横向扩展能力，常用的有MongoDB、ElasticSearch等。

根据业务场景的需要，BIM数据中心的建设选用主流的关系型数据库和非关系型数据库进行搭建。

（2）非结构化数据存储描述

用于存储文件、图片、视频等非结构化数据，并满足用户对这类数据的检索，存取，由于非结构化数据存储要解决的关键问题是：

1. 单个数据集，也既文件比较大；
2. 对单个文件的写入读取，依赖于硬盘的读写速度，单个硬盘的读写是有极限的；
3. 多个用户同时请求一个文件数据时的并发处理。

基于以上问题，非结构化数据的存储解决的核心是协调多块硬盘对文件进行统一的读写，增加单个读写事务性能。

GridFS是 MongoDB的一个用来存储/获取大型数据（图像、音频、视频等类型的文件）的规范。它相当于一个存储文件的文件系统，但它的数据存储在 MongoDB的集合中。GridFS能存储超过文档尺寸限制（16 MB）的文件。

GridFS将文件分解成块，将每块数据保存在不同的文档中，每块大小最高为 255 KB，通过对分片逻辑结构的管理满足对使得大文件具备分布式存储的能力，借助于MongoDB的分布式管理，提高数据中心对大文件的分布式存储、检索。

（3）日志数据存储描述

ELK架构功能示意图，如下：

Logstash：通过Logstash的日志收集功能，对服务端的硬件性能日志，应用请求的访问、响应日志、数据库CUDI日志进行收集，根据各类日志的格式，在Logstash中编写日志收集规则。

Elasticsearch：存储通过Logstash收集到的日志信息，用于后续查询；ES的使用并不仅限于对日志的收集，所有结构化的数据都可以存储在ES中，ES是一个实时的分布式搜索分析引擎， 它能让你以一个之前从未有过的速度和规模，去探索结构化数据。

ES被用作全文检索、结构化搜索、分析以及这三个功能的组合，通过ES存储的数据具备以下能力：

1. 分布式存储能力，ES支持集群部署，在适合的硬件配置下可以用于存储海量数据；
2. 丰富的查询接口，ES的查询接口遵循RESTful API规范，通过ES可以在不需要后端代码介入的情况下直接通过RESTful API对数据进行查询和写入；
3. 通过RESTful API进行复杂的聚合搜索，而不仅限于普通的全文检索查询。

Kibana：是一个针对Elasticsearch的开源分析及可视化平台，用来搜索、查看交互存储在Elasticsearch索引中的数据。使用Kibana，可以通过各种图表进行高级数据分析及展示。

Kibana让海量数据更容易理解。它操作简单，基于浏览器的用户界面可以快速创建仪表板（dashboard）实时显示Elasticsearch查询动态。

Kibana Dashboard界面截图，如下：

使用Kibana制作图表时所使用的数据检索规则是使用Lucene语句编写的聚合查询规则，Lucene是一套用于全文检索和搜索的开放源代码程序库，由Apache软件基金会支持和提供。Lucene提供了一个简单却强大的应用程序接口，能够做全文索引和搜索，在Java开发环境里Lucene是一个成熟的免费开放源代码工具。

就其本身而论，Lucene是现在并且是这几年，最受欢迎的免费Java信息检索程序库；

7.3 测试计划

对本系统进行单体测试的计划，主要有一下几个方面：

• 对测试的各个方面的技术要求；
• 对测试的各个方面的输入数据；
• 对测试问题的记录方式；
• 对测试流程的控制方式；
• 对测试时间段或者阶段性的设定；
• 对测试的预期效果、进度安排、人员职责、设备条件驱动程序及其各个模块等的规定。

7.4 各模块的注释设计

说明准备在本系统中安排的注释，如：

• 注释说明各个模块开始编写的时间，编写人员，修改的时间，编写的名称，及其基本功能。
• 注释说明各个模块的主要功能开始编写的功能简述、编写人员、编写的时间。
• 注释说明各个模块延伸副模块的编写的时间，编写人员，修改的时间，编写的名称，及其基本功能。
• 注释说明各个模块延伸副模块的主要功能开始编写的功能简述、编写人员、编写的时间。
• 加在各个模块的一些限制条件的注释说明和条件要求。
• 加在各分支点的注释说明各种条件。

尚未解决的问题

暂无。

结语

如果这篇详细设计文档当您有什么疑问的话，请以以上的参考资料内列出的文档内容一同研读，整体结构请以《XXXX管理平台——概要设计说明书》为基础。

另外请路过的朋友们多多支持哈，笔者在这里先谢谢了，以后会有更多优质的文章在这个平台上进行发布，请尽请期待呦！

本文由 @卧枕江山 原创发布于人人都是产品经理。未经许可，禁止转载

题图来自Unsplash，基于CC0协议