|
|
@@ -0,0 +1,481 @@
|
|
|
+# 开放平台总体设计文档
|
|
|
+## 概述
|
|
|
+### 背景
|
|
|
+在富士行云V2平台中，将有很多的车场，人行项目接入。为了方便车场，人行项目运营方可以在他们自己已有的平台，或者其他第三方平台对接我们的数据,并提供数据服务。
|
|
|
+### 目标
|
|
|
+为了实现开放平台的功能，我们需要设计一个开放平台的总体设计文档，包括功能模块、系统架构、数据库设计、接口设计、安全设计、流量监控与分析等。
|
|
|
+### 范围
|
|
|
+本文档仅涉及开放平台的总体设计，不涉及具体的功能模块设计。
|
|
|
+## 总体设计
|
|
|
+### 系统架构
|
|
|
+系统依赖富士行云V2整体的spring cloud微服务架构。通过gateway在新的路径前缀下路由到开放平台，在通过openfeign、nacos、 load_balance 等组件实现服务间的调用。
|
|
|
+具体实现就利用我们现有的中台服务（transferService）. 在中台服务上面去建立一个新的目录（openapi）,在openapi目录下建立应用管理、接口管理、开发接口三个模块。
|
|
|
+### 功能模块
|
|
|
+#### 开放平台用户管理
|
|
|
+#### 开放平台应用管理
|
|
|
+开放平台应用管理模块负责对接车场、人行项目的应用，包括应用的注册、认证、授权、管理等。
|
|
|
+##### 新增应用
|
|
|
+在系统添加一个应用，用于对接车场、人行项目的开放接口。
|
|
|
+需要输入应用名称、服务行业、应用描述、应用logo、用户名（负责人）、手机号码。
|
|
|
+
|
|
|
+具体参数表格如下：
|
|
|
+
|
|
|
+| 字段名 | 参数名称 | 类型 | 说明 | 是否必填 |
|
|
|
+|---------------|--------|-----|-----------------|------|
|
|
|
+| name | 应用名称 | 字符串 | 应用名称 | 是 |
|
|
|
+| serviceType | 服务行业 | 字符串 | 服务行业 | 是 |
|
|
|
+| remark | 应用描述 | 字符串 | 应用描述 | 否 |
|
|
|
+| logo | 应用logo | 字符串 | 应用logo 存oss key | 否 |
|
|
|
+| userName | 用户名 | 字符串 | 负责人用户名 | 是 |
|
|
|
+| phoneNumber | 手机号码 | 字符串 | 负责人手机号码 | 是 |
|
|
|
+
|
|
|
+* 接口地址：/openapi/app/add
|
|
|
+* 请求方式：POST
|
|
|
+* 请求参数：JSON格式
|
|
|
+```json
|
|
|
+{
|
|
|
+ "name": "车场应用",
|
|
|
+ "serviceType": "车场",
|
|
|
+ "remark": "车场应用",
|
|
|
+ "logo": "osskey",
|
|
|
+ "userName": "admin",
|
|
|
+ "phoneNumber": "13800138000"
|
|
|
+}
|
|
|
+```
|
|
|
+* 响应参数：JSON格式
|
|
|
+响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "id": 1,
|
|
|
+ "name": "车场应用",
|
|
|
+ "serviceType": "车场",
|
|
|
+ "remark": "车场应用",
|
|
|
+ "logo": "osskey",
|
|
|
+ "userName": "admin",
|
|
|
+ "phoneNumber": "13800138000",
|
|
|
+ "createTime": "2021-01-01 00:00:00",
|
|
|
+ "updateTime": "2021-01-01 00:00:00",
|
|
|
+ "createUser": "admin",
|
|
|
+ "updateUser": "admin",
|
|
|
+ "expirationTime " : "2021-01-01 00:00:00",
|
|
|
+ "status" : 1, // 0启用 1禁用
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 绑定项目
|
|
|
+* 新增的应用是没有绑定项目的，需要绑定项目才能使用接口。
|
|
|
+* 通过调用系统服务获取到项目列表，选择需要绑定的项目，点击绑定按钮。
|
|
|
+* 可以绑定多个项目
|
|
|
+* 接口地址：/openapi/app/bind/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：JSON格式
|
|
|
+body 体中参数
|
|
|
+```json
|
|
|
+{
|
|
|
+ "projectIds": [1,2,3]
|
|
|
+}
|
|
|
+```
|
|
|
+* 响应参数：JSON格式
|
|
|
+响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 配置接口
|
|
|
+* 新增的应用是没有配置接口的，需要配置授权了接口，才能访问到这些开放接口。
|
|
|
+* 通过接口关联查询得到接口列表，选择需要配置的接口，点击配置按钮。
|
|
|
+* 可以配置多个接口，可以选择全部配置、部分配置。
|
|
|
+* 接口地址：/openapi/app/config/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：JSON格式
|
|
|
+body 体中参数
|
|
|
+```json
|
|
|
+{
|
|
|
+ "interfaceIds": [1,2,3]
|
|
|
+}
|
|
|
+```
|
|
|
+* 响应参数：JSON格式
|
|
|
+响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 修改有效期
|
|
|
+* 应用的有效期是可以修改的，可以根据需要修改。
|
|
|
+* 应用有效期过了，则该应用不能通过开放接口访问
|
|
|
+* 接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。
|
|
|
+* 如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。
|
|
|
+* 接口地址：/openapi/app/expiration/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：JSON格式
|
|
|
+ body 体中参数
|
|
|
+```json
|
|
|
+{
|
|
|
+ "expirationTime": "2021-01-01 00:00:00"
|
|
|
+}
|
|
|
+```
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 禁用应用
|
|
|
+* 平台新创建的应用一开始是禁用状态的。需要平台认为的开启才可以使用。
|
|
|
+* 平台也可以在之后禁用应用，禁用后该应用不能通过开放接口访问
|
|
|
+* 接口地址：/openapi/app/disable/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：路径参数
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 启用应用
|
|
|
+* 应用处于禁用状态时，需要平台认为的开启才可以使用。
|
|
|
+* 接口地址：/openapi/app/enable/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：路径参数
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 删除应用
|
|
|
+* 对于已经废弃的应用，平台可以通过接口删除
|
|
|
+* 接口地址：/openapi/app
|
|
|
+* 请求方式：delete
|
|
|
+* 请求参数：路径参数
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 重置应用秘钥
|
|
|
+* 新创建的应用的秘钥是随机生成的32位数字跟英文大写字母。
|
|
|
+* 如果用户签名秘钥存在泄露的情况，可以自己重置签名秘钥，平台也可以重置签名秘钥。
|
|
|
+* 重置的签名秘钥也是随机生成的。
|
|
|
+* 接口地址：/openapi/app/resetSignKey/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：路径参数
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 重置签名密钥
|
|
|
+* 应用的签名秘钥用户数据接口的参数加签用的。应用生成的时候，签名秘钥是随机生成的
|
|
|
+* 应用有效期过了，则该应用不能通过开放接口访问
|
|
|
+* 接口有效期可以修改比当前有效期以前，也可以修改比当前有效期以后。
|
|
|
+* 如果有效期修改在当前时间以前，也是运行的，则等于直接失效了。
|
|
|
+* 接口地址：/openapi/app/expiration/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：JSON格式
|
|
|
+ body 体中参数
|
|
|
+```json
|
|
|
+{
|
|
|
+ "expirationTime": "2021-01-01 00:00:00"
|
|
|
+}
|
|
|
+```
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 重置永久token
|
|
|
+* 方便用户调试使用，设置了永久token。
|
|
|
+* 如果用户不需要永久token，可以重置永久token。
|
|
|
+* 接口地址：/openapi/app/resetToken/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：路径参数
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 修改通知回调地址
|
|
|
+* 对于一些下行的接口，或者推送的接口，需要应用配置下行的地址。
|
|
|
+* 回调的地址支持到端口后的特定前缀。例如：http://www.baidu.com/callback, 推送的消息会发送到http://www.baidu.com/callback/push/xxx
|
|
|
+* 新创建的应用的通知回调地址为空。没有配置的情况下，平台不会推送消息。
|
|
|
+* 平台对于每个应用只支持推送一个通知回调地址。
|
|
|
+* 接口地址：/openapi/app/callback/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：JSON格式
|
|
|
+ body 体中参数
|
|
|
+```json
|
|
|
+{
|
|
|
+ "callbackAddress": "2021-01-01 00:00:00"
|
|
|
+}
|
|
|
+```
|
|
|
+* 响应参数：JSON格式
|
|
|
+ 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+##### 查询详情
|
|
|
+* 接口地址：/openapi/app/{1}
|
|
|
+* 请求方式：GET
|
|
|
+* 请求参数：路径参数
|
|
|
+* 响应参数：JSON格式
|
|
|
+* 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "id": 1,
|
|
|
+ "name": "车场应用",
|
|
|
+ "serviceType": "车场",
|
|
|
+ "remark": "车场应用",
|
|
|
+ "logo": "osskey",
|
|
|
+ "userName": "admin",
|
|
|
+ "phoneNumber": "13800138000",
|
|
|
+ "createTime": "2021-01-01 00:00:00",
|
|
|
+ "updateTime": "2021-01-01 00:00:00",
|
|
|
+ "createUser": "admin",
|
|
|
+ "updateUser": "admin",
|
|
|
+ "expirationTime " : "2021-01-01 00:00:00",
|
|
|
+ "status" : 1, // 0启用 1禁用
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 查询应用列表（分页）
|
|
|
+* 接口地址：/openapi/app/page
|
|
|
+* 请求方式：GET
|
|
|
+* 请求参数：分页参数
|
|
|
+
|
|
|
+
|
|
|
+
|
|
|
+| 参数名 | 类型 | 说明 | 是否必填 |
|
|
|
+|-------------| --- | --- | --- |
|
|
|
+| current | int | 页码 | 是 |
|
|
|
+| size | int | 每页条数 | 是 |
|
|
|
+| name | string | 应用名称 | 否 |
|
|
|
+| serviceType | string | 服务行业 | 否 |
|
|
|
+| status | int | 状态 | 否 |
|
|
|
+| phoneNumber | string | 手机号码 | 否 |
|
|
|
+
|
|
|
+* 响应参数：JSON格式
|
|
|
+* 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "total": 10,
|
|
|
+ "list": [
|
|
|
+ {
|
|
|
+ "id": 1,
|
|
|
+ "name": "车场应用",
|
|
|
+ "serviceType": "车场",
|
|
|
+ "remark": "车场应用",
|
|
|
+ "logo": "osskey",
|
|
|
+ "userName": "admin",
|
|
|
+ "phoneNumber": "13800138000",
|
|
|
+ "createTime": "2021-01-01 00:00:00",
|
|
|
+ "updateTime": "2021-01-01 00:00:00",
|
|
|
+ "createUser": "admin",
|
|
|
+ "updateUser": "admin",
|
|
|
+ "expirationTime " : "2021-01-01 00:00:00",
|
|
|
+ "status" : 1, // 0启用 1禁用
|
|
|
+ }
|
|
|
+ ]
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+#### 开放平台接口管理
|
|
|
+开放平台数据接口管理模块负责对接车场、人行项目的接口，包括接口的注册、认证、授权、管理等。我们将配置两类接口，一个是上行接口，一个是下行接口。
|
|
|
+上行接口
|
|
|
+##### 新增接口
|
|
|
+开放平台对外提供的接口，包括车场、人行项目的接口。都是在这里添加。
|
|
|
+需要的参数有，接口名称，路径，请求方式，接口类型，版本，发布状态，接口展示文档，启用状态，访问限制次数。
|
|
|
+
|
|
|
+ 具体参数表格如下：
|
|
|
+
|
|
|
+ | 字段名 | 参数名称 | 类型 | 说明 | 是否必填 |
|
|
|
+ |--------------|--------|-----|---------------------------|------|
|
|
|
+ | name | 接口名称 | 字符串 | 接口名称 | 是 |
|
|
|
+ | path | 路径 | 字符串 | 接口路径 | 是 |
|
|
|
+ | method | 请求方式 | 字符串 | 请求方式 POST PUT GET DELETE | 是 |
|
|
|
+ | type | 接口类型 | int | 接口类型 0 上行 1 下行 | 是 |
|
|
|
+ | serviceType | 业务类型 | int | 1 车位 2 支付 3 月卡 4 车场 5 优惠券 | 是 |
|
|
|
+ | version | 版本 | 字符串 | 版本号 v1 v2 ... | 是 |
|
|
|
+ | status | 发布状态 | int | 发布状态 0 未发出 1 已发布 | 是 |
|
|
|
+ | doc | 接口展示文档 | 字符串 | 接口展示文档 markdown格式 | 否 |
|
|
|
+ | enable | 启用状态 | int | 启用状态 0 启用 1 禁用 | 是 |
|
|
|
+ | limitCount | 访问限制次数 | int | 每秒访问限制次数 | 否 |
|
|
|
+
|
|
|
+* 接口地址：/openapi/interface/add
|
|
|
+* 请求方式：POST
|
|
|
+* 请求参数：JSON格式
|
|
|
+```json
|
|
|
+{
|
|
|
+ "name": "车场接口",
|
|
|
+ "path": "/api/v1/car/parking",
|
|
|
+ "method": "GET",
|
|
|
+ "type": 0,
|
|
|
+ "serviceType": 1,
|
|
|
+ "version": "v1",
|
|
|
+ "doc": "",
|
|
|
+ "limitCount": 100
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+* 响应参数：JSON格式
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "id": 1,
|
|
|
+ "name": "车场接口",
|
|
|
+ "path": "/api/v1/car/parking",
|
|
|
+ "method": "GET",
|
|
|
+ "type": 0,
|
|
|
+ "serviceType": 1,
|
|
|
+ "version": "v1",
|
|
|
+ "status": 1,
|
|
|
+ "doc": "",
|
|
|
+ "enable": 1,
|
|
|
+ "limitCount": 100,
|
|
|
+ "createTime": "2021-01-01 00:00:00",
|
|
|
+ "updateTime": "2021-01-01 00:00:00",
|
|
|
+ "createUser": "admin",
|
|
|
+ "updateUser": "admin"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 编辑接口
|
|
|
+* 对于已经发布的接口，需要修改接口信息。
|
|
|
+* 可以修改的参数有接口名称、路径、请求方式、接口类型、版本、接口展示文档、访问限制次数。参考新增的表格。
|
|
|
+* 修改的时候传入参数如果没有修改，则不传。参数为空的时候等于不修改。
|
|
|
+* 接口地址：/openapi/interface/edit/{1}
|
|
|
+* 请求方式：PUT
|
|
|
+* 请求参数：JSON格式
|
|
|
+```json
|
|
|
+{
|
|
|
+ "name": "车场接口",
|
|
|
+ "path": "/api/v1/car/parking",
|
|
|
+ "method": "GET",
|
|
|
+ "type": 0,
|
|
|
+ "serviceType": 1,
|
|
|
+ "version": "v1",
|
|
|
+ "doc": "",
|
|
|
+ "limitCount": 100
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+* 响应参数：JSON格式
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "id": 1,
|
|
|
+ "name": "车场接口",
|
|
|
+ "path": "/api/v1/car/parking",
|
|
|
+ "method": "GET",
|
|
|
+ "type": 0,
|
|
|
+ "serviceType": 1,
|
|
|
+ "version": "v1",
|
|
|
+ "status": 1,
|
|
|
+ "doc": "",
|
|
|
+ "enable": 1,
|
|
|
+ "limitCount": 100,
|
|
|
+ "createTime": "2021-01-01 00:00:00",
|
|
|
+ "updateTime": "2021-01-01 00:00:00",
|
|
|
+ "createUser": "admin",
|
|
|
+ "updateUser": "admin"
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 删除接口
|
|
|
+* 对于已经废弃的接口，需要删除接口。或者批量删除接口。
|
|
|
+* 接口地址：/openapi/interface
|
|
|
+* 请求方式：DELETE
|
|
|
+* 请求参数：
|
|
|
+ids 多个用逗号隔开
|
|
|
+* 响应参数：JSON格式
|
|
|
+* 响应示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": null
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+##### 配置接口文档
|
|
|
+接口中需要配置给开放平台
|
|
|
+##### 发布接口
|
|
|
+##### 禁用接口
|
|
|
+##### 导入接口
|
|
|
+##### 导出接口
|
|
|
+##### 查询详情
|
|
|
+##### 查询接口列表（分页）
|
|
|
+
|
|
|
+#### 开放平台安全管理
|
|
|
+开放平台安全校验模块负责对接车场、人行项目的安全校验，包括接口的安全校验、数据加密、数据权限校验、数据流量监控等。
|
|
|
+##### token生成
|
|
|
+##### token校验
|
|
|
+##### 签名方式
|
|
|
+##### 签名校验
|
|
|
+##### 接口权限校验
|
|
|
+##### 接口流量监控
|
|
|
+
|
|
|
+
|
|
|
+### 数据库设计
|
|
|
+#### 应用管理表
|
|
|
+#### 应用项目关联表
|
|
|
+#### 接口管理表
|
|
|
+#### 应用接口授权关联表
|
|
|
+#### 安全管理redis数据结构设计
|
|
|
+### 数据接口列表
|
