**项目名称**

**详细设计说明书**

| 文件状态：    | 文档密级： | 公开                         |
|---------------|------------|------------------------------|
| 【 】草稿     |            |                              |
| 【 】修改稿   |            |                              |
| 【√】正式发布 |            |                              |
|               | 当前版本： | 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、有哪些日常维护需求，并且如何处理。