fujian_water_biz_doc/templates/302-详细设计说明书(V1.1).md

731 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

**项目名称**
**详细设计说明书**
| 文件状态: | 文档密级: | 公开 |
|---------------|------------|------------------------------|
| 【 】草稿 | | |
| 【 】修改稿 | | |
| 【√】正式发布 | | |
| | 当前版本: | V1.1 |
| | 作者: | |
| | 完成日期: | |
## 版本历史
| 日期 | 版本号 | 作者 | 备注 |
|---|---|---|---|
| | V1.0 | | 起草 |
| **修改内容** | | | |
| **增加内容** | | | |
| **删除内容** | | | |
| | V1.1 | 曾力 | |
| **修改内容** | 3系统设计章节调整1模块中的"业务算法和流程"拆分为"业务规则"和"业务流程"2缓存、消息队列、定时任务、数据设计等合并到中间件和其他设计 | | |
| **增加内容** | | | |
| **删除内容** | | | |
# 目录
- [目录](#目录)
- [前言](#前言)
- [编写目的](#编写目的)
- [背景与任务](#背景与任务)
- [术语与缩略语](#术语与缩略语)
- [参考资料](#参考资料)
- [系统总体设计](#系统总体设计)
- [逻辑架构](#逻辑架构)
- [物理架构](#物理架构)
- [对外接口](#对外接口)
- [子系统列表](#子系统列表)
- [子系统相互关系与接口](#子系统相互关系与接口)
- [子系统1设计](#子系统1设计)
- [功能与界面](#功能与界面)
- [工程目录](#工程目录)
- [模块列表](#模块列表)
- [模块间关系](#模块间关系)
- [功能关系群1](#功能关系群1)
- [功能关系群2](#功能关系群2)
- [模块设计](#模块设计)
- [模块1](#模块1)
- [功能](#功能)
- [功能1](#功能1)
- [设计图](#设计图)
- [功能描述](#功能描述)
- [输入输出数据](#输入输出数据)
- [业务算法和流程](#业务算法和流程)
- [数据设计](#数据设计)
- [方法说明](#方法说明)
- [其他说明](#其他说明)
- [功能2](#功能2)
- [接口](#接口)
- [接口1](#接口1)
- [接口2](#接口2)
- [模块2](#模块2)
- [功能](#功能-1)
- [功能1](#功能1-1)
- [设计图](#设计图-1)
- [功能描述](#功能描述-1)
- [输入输出数据](#输入输出数据-1)
- [业务规则](#业务规则)
- [业务流程](#业务流程)
- [数据设计](#数据设计-1)
- [方法说明](#方法说明-1)
- [其他说明](#其他说明-1)
- [功能2](#功能2-1)
- [接口](#接口-1)
- [接口1](#接口1-1)
- [接口2](#接口2-1)
- [中间件和其他设计](#中间件和其他设计)
- [缓存设计](#缓存设计)
- [Redis](#redis)
- [其他](#其他)
- [消息队列设计](#消息队列设计)
- [Kafka](#kafka)
- [其他](#其他-1)
- [定时任务设计](#定时任务设计)
- [数据库设计](#数据库设计)
- [数据字典设计](#数据字典设计)
- [对外接口](#对外接口-1)
- [非功能性需求的设计](#非功能性需求的设计)
- [性能的考虑](#性能的考虑)
- [兼容性的考虑](#兼容性的考虑)
- [安全的考虑](#安全的考虑)
- [可移植性的考虑](#可移植性的考虑)
- [集成与测试的考虑](#集成与测试的考虑)
- [可扩展性的考虑](#可扩展性的考虑)
- [可靠性的考虑](#可靠性的考虑)
- [可维护性的考虑](#可维护性的考虑)
# 前言
文档编写原则:
**1、所有修改调整都必须如实记录**
**2、对系统功能的修改都必须对修改进行说明**
整个文档编写说明:
1、文档编写完成后请删除文档中出现的全部"填写说明"
2、提交前请刷新"目录"、"图表目录" 更新页眉页脚;
3、本说明书对整个软件系统按如下结构方式进行划分"系统"、"子系统"、"模块"
4、如果系统相对简单不需要做"系统"、"子系统"的划分,则可直接按照"系统"、"模块"的层次划分即可\-\--把"子系统"修改为"模块"。
## 编写目的
## 背景与任务
## 术语与缩略语
填写说明:在本文当中出现的专业性、缩略、专有和难懂性的词组或短语
| **术语、缩写** | **解释** |
|---|---|
| | |
| | |
## 参考资料
# 系统总体设计
## 逻辑架构
填写说明:需要有架构图和文字说明,若有必要需要分清层级。
## 物理架构
填写说明从物理部署方面说明系统架构有必要的话需要标明IP端口协议容器负载均衡设计防火墙设计等。
## 对外接口
| 接口编号 | 接口名称(标识) | 功能描述 | 接口协议 | 输入参数 | 输出结果 |
|---|---|---|---|---|---|
| | | | | | |
## 子系统列表
| 子系统编号 | 子系统名称(标识) | 功能描述 | 开发方式 |
|---|---|---|---|
| | | | 采购/外包/自行开发/复用 |
## 子系统相互关系与接口
填写说明明确子系统之间的调用关系、子系统间的接口消息、数据结构以及相关子系统之间的协同工作可以使用结构图、交互事务图、消息序列图、ER
图描述。
# 子系统1设计
填写说明:
1、标题上加入子系统的编号及名称标识
2、设计子系统整体框架子系统的逻辑结构。
3、模块的划分与依赖关系定义、模块之间的接口定义、模块功能定义。
## 功能与界面
填写说明:说明子系统功能、作用范围等,展示子系统界面。
## 工程目录
填写说明:展示并介绍系统的工程目录结构以及主要模块的作用。
## 模块列表
| 模块编号 | 模块名称(标识) | 功能描述 | 开发方式 |
|---|---|---|---|
| | | | 采购/外包/自行开发/复用 |
## 模块间关系
### 功能关系群1
填写说明用UML图描述各个模块间的关系并介绍对应关系群的功能。
### 功能关系群2
填写说明用UML图描述各个模块间的关系并介绍对应关系群的功能。
## 模块设计
### 模块1
填写说明:标题上加入模块的编号及名称(标识)。
#### 功能
填写说明:说明该模块具备什么样的基本功能,粘贴对应界面。
##### 功能1
###### 设计图
界面或原型图
###### 功能描述
1. 功能概述
说明功能用途,功能操作的前提业务和后继业务,操作后的影响等
2. 操作权限
说明功能用途,功能操作前提及操作后的影响等
3. 功能约束
说明功能是否有约束,及约束描述
###### 输入输出数据
1. 输入数据
描述用户输入的数据(包括任何输入设备)以及这些数据的有效性检验规则。
描述从物理模型中的哪些表获取数据以及获取这些数据的条件。
2. 输出数据
描述功能所产生的数据以及这些数据的表现形式。
###### 业务算法和流程
从业务角度详细描述根据输入数据产生输出数据的业务算法和流程.
###### 数据设计
功能实现涉及的局部数据结构说明,包括数据结构名称,功能说明,具体数据结构说明(定义、注释设计、取值)等。相关数据库表,数据存储设计(具体说明需要以文件方式保存的数据文件名、数据存储格式、数据项及属性等。),以及数据流转等。
###### 方法说明
说明本功能中的各个方法,包括方法名称及其所在文件,功能,格式,参数,全局变量,局部变量,返回值,算法说明,使用约束等。
示例:主要方法以及方法的作用。
| 方法名 | 方法作用 | 输入参数(是否必填) | 返回数据 |
|---|---|---|---|
| addUser | 添加用户 | name用户名 | Boolean类型true |
| | | phone电话 | |
| | | | |
###### 其他说明
##### 功能2
#### 接口
填写说明:列出与其它模块的接口,与其它系统或硬件的接口。
##### 接口1
a、**接口名称**
| ⽤户注册接口 |
|---|
b、**接口描述**
| 1. ⽤户信息注册<br>2. ⽤户可以通过 ⼿机号/邮箱 进⾏注册<br>3. 同⼀个 ⼿机号/邮箱只能注册⼀个账号 |
|---|
c、**请求地址**
| {apiAddress}/api/user/signup |
|---|
d、**请求方式**
| POST |
|---|
e、**请求参数**
1\) Header参数
| 参数名 | 必选 | 类型/参数值 | 说明 |
|---|---|---|---|
| Content-Type | 是 | application/json | 请求参数类型 |
2\) Body参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| account | 是 | string | 1 < length < 50 | 户账号 | |
| passcode | | string | 1 < length < 50 | 密码 | 密码(passcode)的加密式为 xxxxxx |
| checkCode | | string | length = 6 | 验证码 | |
3\) 请求实例
```json
{
"account": 1001,
"passcode": 123456,
"checkCode": 1
}
```
f、**响应参数**
1\) 返回参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| | | | | | |
| | | | | | |
| | | | | | |
2\) 返回示例
```json
{
"code": 200,
"msg": "成功",
"data": null
}
```
g、**备注**
h、**错误响应码**
| 错误码 | 错误描述 | 原因 | 解决方案 | 示例值 |
|---|---|---|---|---|
| SYSTEMERROR | 返回错误 | 系统超时 | 请使相同 参数再次调 API | 001 |
##### 接口2
a、**接口名称**
| 户注册接口 |
|---|
b、**接口描述**
| 1. 户信息注册<br>2. ⽤户可以通过 ⼿机号/邮箱 进⾏注册<br>3. 同⼀个 ⼿机号/邮箱只能注册⼀个账号 |
|---|
c、**请求地址**
| {apiAddress}/api/user/signup |
|---|
d、**请求方式**
| POST |
|---|
e、**请求参数**
1\) Header参数
| 参数名 | 必选 | 类型/参数值 | 说明 |
|---|---|---|---|
| Content-Type | 是 | application/json | 请求参数类型 |
2\) Body参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| account | 是 | string | 1 < length < 50 | 户账号 | |
| passcode | | string | 1 < length < 50 | 密码 | 密码(passcode)的加密式为 xxxxxx |
| checkCode | | string | length = 6 | 验证码 | |
3\) 请求实例
```json
{
"account": 1001,
"passcode": 123456,
"checkCode": 1
}
```
f、**响应参数**
1\) 返回参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| | | | | | |
| | | | | | |
| | | | | | |
2\) 返回示例
```json
{
"code": 200,
"msg": "成功",
"data": null
}
```
g、**备注**
h、**错误响应码**
| 错误码 | 错误描述 | 原因 | 解决方案 | 示例值 |
|---|---|---|---|---|
| SYSTEMERROR | 返回错误 | 系统超时 | 请使相同 参数再次调 API | 001 |
### 模块2
填写说明标题上加入模块的编号及名称标识)。
#### 功能
填写说明说明该模块具备什么样的基本功能粘贴对应界面
##### 功能1
###### 设计图
界面或原型图
###### 功能描述
4. 功能概述
说明功能用途功能操作的前提业务和后继业务操作后的影响等
5. 操作权限
说明功能用途功能操作前提及操作后的影响等
6. 功能约束
说明功能是否有约束及约束描述
###### 输入输出数据
3. 输入数据
详细描述用户输入的数据(包括任何输入设备)以及这些数据的有效性检验规则
详细描述从物理模型中的哪些表获取数据以及获取这些数据的条件
4. 输出数据
详细描述功能所产生的数据以及这些数据的表现形式
###### 业务规则
从业务角度详细描述根据输入数据产生输出数据的业务算法.
###### 业务流程
从业务角度详细描述业务流程.
###### 数据设计
功能实现涉及的局部数据结构说明包括数据结构名称功能说明具体数据结构说明定义注释设计取值)相关数据库表数据存储设计具体说明需要以文件方式保存的数据文件名数据存储格式数据项及属性等。),以及数据流转等
###### 方法说明
说明本功能中的各个方法包括方法名称及其所在文件,功能格式参数全局变量局部变量返回值算法说明,使用约束等
示例主要方法以及方法的作用
| 方法名 | 方法作用 | 输入参数是否必填 | 返回数据 |
|---|---|---|---|
| addUser | 添加用户 | name用户名 | Boolean类型true |
| | | phone电话 | |
| | | | |
###### 其他说明
##### 功能2
#### 接口
填写说明列出与其它模块的接口与其它系统或硬件的接口
##### 接口1
a、**接口名称**
| 户注册接口 |
|---|
b、**接口描述**
| 1. 户信息注册<br>2. ⽤户可以通过 ⼿机号/邮箱 进⾏注册<br>3. 同⼀个 ⼿机号/邮箱只能注册⼀个账号 |
|---|
c、**请求地址**
| {apiAddress}/api/user/signup |
|---|
d、**请求方式**
| POST |
|---|
e、**请求参数**
1\) Header参数
| 参数名 | 必选 | 类型/参数值 | 说明 |
|---|---|---|---|
| Content-Type | 是 | application/json | 请求参数类型 |
2\) Body参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| account | 是 | string | 1 < length < 50 | 户账号 | |
| passcode | | string | 1 < length < 50 | 密码 | 密码(passcode)的加密式为 xxxxxx |
| checkCode | | string | length = 6 | 验证码 | |
3\) 请求实例
```json
{
"account": 1001,
"passcode": 123456,
"checkCode": 1
}
```
f、**响应参数**
1\) 返回参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| | | | | | |
| | | | | | |
| | | | | | |
2\) 返回示例
```json
{
"code": 200,
"msg": "成功",
"data": null
}
```
g、**备注**
h、**错误响应码**
| 错误码 | 错误描述 | 原因 | 解决方案 | 示例值 |
|---|---|---|---|---|
| SYSTEMERROR | 返回错误 | 系统超时 | 请使相同 参数再次调 API | 001 |
##### 接口2
a、**接口名称**
| 户注册接口 |
|---|
b、**接口描述**
| 1. 户信息注册<br>2. ⽤户可以通过 ⼿机号/邮箱 进⾏注册<br>3. 同⼀个 ⼿机号/邮箱只能注册⼀个账号 |
|---|
c、**请求地址**
| {apiAddress}/api/user/signup |
|---|
d、**请求方式**
| POST |
|---|
e、**请求参数**
1\) Header参数
| 参数名 | 必选 | 类型/参数值 | 说明 |
|---|---|---|---|
| Content-Type | 是 | application/json | 请求参数类型 |
2\) Body参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| account | 是 | string | 1 < length < 50 | 户账号 | |
| passcode | | string | 1 < length < 50 | 密码 | 密码(passcode)的加密式为 xxxxxx |
| checkCode | | string | length = 6 | 验证码 | |
3\) 请求实例
```json
{
"account": 1001,
"passcode": 123456,
"checkCode": 1
}
```
f、**响应参数**
1\) 返回参数
| 参数名 | 必选 | 类型 | 限制条件 | 说明 | 备注 |
|---|---|---|---|---|---|
| | | | | | |
| | | | | | |
| | | | | | |
2\) 返回示例
```json
{
"code": 200,
"msg": "成功",
"data": null
}
```
g、**备注**
h、**错误响应码**
| 错误码 | 错误描述 | 原因 | 解决方案 | 示例值 |
|---|---|---|---|---|
| SYSTEMERROR | 返回错误 | 系统超时 | 请使相同 参数再次调 API | 001 |
## 中间件和其他设计
### 缓存设计
#### Redis
| IP | 端口 | 用户名 | 密码 |
|---|---|---|---|
| | | | |
| 作用 | Key | Value | 过期时间 |
|---|---|---|---|
| | | | |
| | | | |
#### 其他
### 消息队列设计
#### Kafka
| 作用 | Topic | Consumer |
|---|---|---|
| | | |
#### 其他
### 定时任务设计
| 使用工具 | 功能描述 | 方法名称 | 调用周期 |
|---|---|---|---|
| | | | |
### 数据库设计
填写说明数据库设计说明书》,附上源文件链接
### 数据字典设计
填写说明数据字典》,附上源文件链接
## 对外接口
填写说明描述该软件子系统与外部实体的接口包括用户界面软件接口硬件接口和通信接口有提供接口文档的填写见接口文档》,附上源文件链接
| 接口编号 | 接口名称标识 | 功能描述 | 接口协议 | 输入参数 | 输出结果 |
|---|---|---|---|---|---|
| | | | | | |
# 非功能性需求的设计
## 性能的考虑
填写说明为满足延时吞吐量等性能在既定硬件环境约束下所采取的设计方案
## 兼容性的考虑
填写说明对以前版本的兼容以及平滑升级的考虑
## 安全的考虑
填写说明作为应用软件在安全方面更多的是考虑访问控制包括使用什么样的权限管理分配验证方案
## 可移植性的考虑
填写说明系统如果有跨平台的需求要考虑操作系统中间件应用服务器特性数据库及第三方服务移植描述如何在不同的平台移植是否为可配置的
## 集成与测试的考虑
填写说明各个子系统以及模块以什么先后次序进行开发集成组装和测试即是采用自底向上法还是自顶向下法
## 可扩展性的考虑
填写说明不仅有对系统功能扩展的设计考虑还要考虑系统的性能扩展即可伸缩性
1如何最低成本地添加新的功能
2如何最低成本的复制一个新系统并且新旧系统可以做成统一体
## 可靠性的考虑
填写说明对故障检测故障隔离故障恢复容错冗余备份的设计考虑
## 可维护性的考虑
填写说明
1系统模块是否可以装配功能模块是否可以配置整个系统是否已经参数化
2提供什么样的维护方式接口及界面
3有哪些日常维护需求并且如何处理