From 69fe0e691d205953c7b3cc75f69409897a204ad8 Mon Sep 17 00:00:00 2001
From: houwei <houwei@jsspisoft.com>
Date: Fri, 28 Jun 2024 12:14:28 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9api=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/_sidebar.md      |   5 +-
 docs/api/equipment.md | 591 ++++++++++++++++++++++++++++++++++++++++++
 docs/api/readme.md    |  20 ++
 3 files changed, 614 insertions(+), 2 deletions(-)
 create mode 100644 docs/api/equipment.md
 create mode 100644 docs/api/readme.md

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 82a464ce..73b1dc63 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,3 +1,4 @@
 * [首页](/)
-  
-* [API接口文档](api/api_list.md)
\ No newline at end of file
+* [API说明](api/readme.md)  
+* [系统管理](api/api_list.md)
+* [设备管理](api/equipment.md)
\ No newline at end of file
diff --git a/docs/api/equipment.md b/docs/api/equipment.md
new file mode 100644
index 00000000..f2ee2ebe
--- /dev/null
+++ b/docs/api/equipment.md
@@ -0,0 +1,591 @@
+# 设备相关模块
+
+## API接口一览表
+
+| 接口分类      | 接口描述                         | API接口                               | 权限                   |
+| ------------- | -------------------------------- | ------------------------------------- | ---------------------- |
+| 2.1设备类型   | 2.1.1获取所有设备类型信息        | /api/equipment/type/list              |                        |
+| 2.2物模型     | 2.2.1获取物模型列表              | /api/equipment/model/list             |                        |
+|               | 2.2.2物模型新增                  | /api/equipment/model/add              | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.3物模型修改                  | /api/equipment/model/update           | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.4物模型删除                  | /api/equipment/model/delete           | SYS_AUTHORITY_ID_ADMIN |
+| 2.2物模型属性 | 2.2.5获取物模型属性列表          | /api/equipment/model/attribute/list   |                        |
+|               | 2.2.6物模型属性新增              | /api/equipment/model/attribute/add    | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.7物模型属性修改              | /api/equipment/model/attribute/update | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.8物模型属性删除              | /api/equipment/model/attribute/delete | SYS_AUTHORITY_ID_ADMIN |
+| 2.2物模型方法 | 2.2.9获取物模型方法列表          | /api/equipment/model/service/list     |                        |
+|               | 2.2.10物模型方法新增             | /api/equipment/model/service/add      | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.11物模型方法修改             | /api/equipment/model/service/update   | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.12物模型方法删除             | /api/equipment/model/service/delete   | SYS_AUTHORITY_ID_ADMIN |
+|               | 2.2.13 Excel导出物模型属性和方法 | /api/equipment/model/export           |                        |
+|               | 2.2.14 Excel导入物模型属性和方法 | /api/equipment/model/import           | SYS_AUTHORITY_ID_ADMIN |
+| 2.3设备台账   | 2.3.1 设备查询                   |                                       |                        |
+|               | 2.3.2 设备新增                   |                                       |                        |
+|               | 2.3.3 设备修改                   |                                       |                        |
+|               | 2.3.4 设备删除                   |                                       |                        |
+
+### 2.1 设备类型相关接口
+
+#### 2.1.1 获取所有设备类型信息
+
+POST 请求接口
+
+> /api/equipment/type/list
+
+请求参数
+
+无
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"equipmentTypeId": "10001",
+			"equipmentTypeName": "风电场"
+		},
+		{
+			"equipmentTypeId": "10002",
+			"equipmentTypeName": "机组"
+		}
+	]
+}
+```
+
+### 2.2 物模型相关接口
+
+#### 2.2.1 获取物模型列表
+POST 请求接口
+
+> /api/equipment/model/list
+
+请求参数
+
+```json
+{
+    "objectType":"10002",
+    "iotModelName":"倍福机组",
+    "iotModelCode":"beckhoff"    
+}
+```
+
+入参描述
+
+| 参数名       | 参数类型 | 可选 | 描述       |
+| ------------ | -------- | ---- | ---------- |
+| objectType   | String   | yes  | 设备类型ID |
+| iotModelName | String   | yes  | 物模型名称 |
+| iotModelCode | String   | yes  | 物模型编码 |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"id": "123",
+			"objectType": "10002",
+			"iotModelCode": "beckhoff",
+			"iotModelName": "倍福机组",
+			"revision": 1,
+			"createdBy": "admin",
+			"createdTime": "2024-06-27 15:08:23",
+			"updatedBy": "admin",
+			"updatedTime": "2024-06-27 15:08:23"
+		}
+	]
+}
+```
+
+注意： 按设备类型、物模型名称进行排序
+
+#### 2.2.2物模型新增
+POST 请求接口
+
+> /api/equipment/model/add
+
+请求参数
+
+```json
+{
+    "objectType": "10002",
+    "iotModelCode": "beckhoff",
+    "iotModelName": "倍福机组",
+    "revision": 1,
+    "createdBy": "admin",
+    "createdTime": "2024-06-27 15:08:23"
+}
+```
+
+入参描述
+
+| 参数名       | 参数类型 | 可选 | 描述       |
+| ------------ | -------- | ---- | ---------- |
+| objectType   | 字符串   | No   | 设备类型ID |
+| iotModelCode | 字符串   | No   | 物模型编码 |
+| iotModelName | 字符串   | No   | 物模型名称 |
+| revision     | 数值     | No   | 乐观锁     |
+| createdBy    | 字符串   | Yes  | 创建人     |
+| createdTime  | 字符串   | Yes  | 创建时间   |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"id": "123",
+			"objectType": "10002",
+			"iotModelCode": "beckhoff",
+			"iotModelName": "倍福机组",
+			"revision": 1,
+			"createdBy": "admin",
+			"createdTime": "2024-06-27 15:08:23",
+			"updatedBy": "admin",
+			"updatedTime": "2024-06-27 15:08:23"
+		}
+	]
+}
+```
+
+
+#### 2.2.3物模型修改
+
+POST 请求接口
+
+> /api/equipment/model/update
+
+请求参数
+
+```json
+{
+    "id": "123",
+    "objectType": "10002",
+    "iotModelCode": "beckhoff",
+    "iotModelName": "倍福机组",
+    "revision": 1,
+    "createdBy": "admin",
+    "createdTime": "2024-06-27 15:08:23"
+}
+```
+
+入参描述
+
+| 参数名       | 参数类型 | 可选 | 描述       |
+| ------------ | -------- | ---- | ---------- |
+| id           | 字符串   | No   | 主键ID     |
+| objectType   | 字符串   | No   | 设备类型ID |
+| iotModelCode | 字符串   | No   | 物模型编码 |
+| iotModelName | 字符串   | No   | 物模型名称 |
+| revision     | 数值     | No   | 乐观锁     |
+| updatedBy    | 字符串   | Yes  | 更新人     |
+| updatedTime  | 字符串   | Yes  | 更新时间   |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "更新成功",
+	"success": true
+}
+```
+
+#### 2.2.4物模型删除
+
+POST 请求接口
+
+> /api/equipment/model/delete
+
+请求参数
+
+```json
+{
+    "id": "123"
+}
+```
+
+入参描述
+
+| 参数名       | 参数类型 | 可选 | 描述       |
+| ------------ | -------- | ---- | ---------- |
+| id           | 字符串   | No   | 主键ID     |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "删除成功",
+	"success": true
+}
+```
+
+#### 2.2.5获取物模型属性列表              
+
+POST 请求接口
+> /api/equipment/model/attribute/list 
+
+请求参数
+
+```json
+{
+    "iotModelId":"123"
+}
+```
+
+入参描述
+
+| 参数名     | 参数类型 | 可选 | 描述     |
+| ---------- | -------- | ---- | -------- |
+| iotModelId | String   | No   | 物模型ID |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"id": "45678",
+			"iotModelId": "123",
+			"attributeCode": "grGenPowerForProcess",
+			"attributeName": "发电机功率实时值",
+            "attributeType":138,
+            "porder":1,
+			"revision": 1,
+			"createdBy": "admin",
+			"createdTime": "2024-06-27 15:08:23",
+			"updatedBy": "admin",
+			"updatedTime": "2024-06-27 15:08:23"
+		}
+	]
+}
+```
+
+#### 2.2.6物模型属性新增 
+
+POST 请求接口
+> /api/equipment/model/attribute/add  
+
+请求参数
+
+```json
+{
+    "iotModelId": "123",
+    "attributeCode": "grGenPowerForProcess",
+    "attributeName": "发电机功率实时值",
+    "attributeType":138,
+    "porder":1,
+    "revision": 1,
+    "createdBy": "admin",
+    "createdTime": "2024-06-27 15:08:23"
+}
+```
+
+入参描述
+
+| 参数名        | 参数类型 | 可选 | 描述                                 |
+| ------------- | -------- | ---- | ------------------------------------ |
+| iotModelId    | 字符串   | No   | 所属物模型ID                         |
+| attributeCode | 字符串   | No   | 属性编码                             |
+| attributeName | 字符串   | No   | 属性名称                             |
+| attributeType | 数值     | No   | 属性类型 138模拟量139累积量140离散量 |
+| porder        | 数值     | No   | 顺序号                               |
+| revision      | 数值     | No   | 乐观锁                               |
+| createdBy     | 字符串   | Yes  | 创建人                               |
+| createdTime   | 字符串   | Yes  | 创建时间                             |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"id": "45678",
+            "iotModelId": "123",
+            "attributeCode": "grGenPowerForProcess",
+            "attributeName": "发电机功率实时值",
+            "attributeType":138,
+            "porder":1,
+            "revision": 1,
+            "createdBy": "admin",
+            "createdTime": "2024-06-27 15:08:23",
+            "updatedBy": "admin",
+			"updatedTime": "2024-06-27 15:08:23"
+		}
+	]
+}
+```
+
+
+
+#### 2.2.7物模型属性修改    
+
+POST 请求接口
+>/api/equipment/model/attribute/update 
+
+请求参数
+
+```json
+{
+    "id": "45678",
+    "iotModelId": "123",
+    "attributeCode": "grGenPowerForProcess",
+    "attributeName": "发电机功率实时值",
+    "attributeType":138,
+    "porder":1,
+    "revision": 1,
+    "updatedBy": "admin",
+    "updatedTime": "2024-06-27 15:08:23"
+}
+```
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "更新成功",
+	"success": true
+}
+```
+
+
+
+#### 2.2.8物模型属性删除              
+
+POST 请求接口
+ > /api/equipment/model/attribute/delete 
+
+请求参数
+
+```json
+{
+    "id": "45678"
+}
+```
+
+入参描述
+
+| 参数名 | 参数类型 | 可选 | 描述   |
+| ------ | -------- | ---- | ------ |
+| id     | 字符串   | No   | 主键ID |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "删除成功",
+	"success": true
+}
+```
+
+#### 2.2.9获取物模型方法列表 
+
+POST 请求接口
+>/api/equipment/model/service/list     
+
+请求参数
+
+```json
+{
+    "iotModelId":"123"
+}
+```
+
+入参描述
+
+| 参数名     | 参数类型 | 可选 | 描述     |
+| ---------- | -------- | ---- | -------- |
+| iotModelId | String   | No   | 物模型ID |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"id": "78901",
+			"iotModelId": "123",
+			"serviceCode": "grActivePowerSetPointValue",
+			"serviceName": "功率设定值",
+            "serviceType":146,
+            "porder":1,
+			"revision": 1,
+			"createdBy": "admin",
+			"createdTime": "2024-06-27 15:08:23",
+			"updatedBy": "admin",
+			"updatedTime": "2024-06-27 15:08:23"
+		}
+	]
+}
+```
+
+#### 2.2.10物模型方法新增            
+
+POST 请求接口
+> /api/equipment/model/service/add      
+
+请求参数
+
+```json
+{
+    "iotModelId": "123",
+    "serviceCode": "grActivePowerSetPointValue",
+    "serviceName": "功率设定值",
+    "serviceType":146,
+    "porder":1,
+    "revision": 1,
+    "createdBy": "admin",
+    "createdTime": "2024-06-27 15:08:23"
+}
+```
+
+入参描述
+
+| 参数名      | 参数类型 | 可选 | 描述                       |
+| ----------- | -------- | ---- | -------------------------- |
+| iotModelId  | 字符串   | No   | 所属物模型ID               |
+| serviceCode | 字符串   | No   | 方法编码                   |
+| serviceName | 字符串   | No   | 方法名称                   |
+| serviceType | 数值     | No   | 属性类型 146 遥调 147 遥控 |
+| porder      | 数值     | No   | 顺序号                     |
+| revision    | 数值     | No   | 乐观锁                     |
+| createdBy   | 字符串   | Yes  | 创建人                     |
+| createdTime | 字符串   | Yes  | 创建时间                   |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "操作成功",
+	"success": true,
+	"data": [
+		{
+			"id": "78901",
+            "iotModelId": "123",
+            "serviceCode": "grActivePowerSetPointValue",
+            "serviceName": "功率设定值",
+            "serviceType":146,
+            "porder":1,
+            "revision": 1,
+            "createdBy": "admin",
+            "createdTime": "2024-06-27 15:08:23",
+            "updatedBy": "admin",
+			"updatedTime": "2024-06-27 15:08:23"
+		}
+	]
+}
+```
+
+#### 2.2.11物模型方法修改         
+
+POST 请求接口
+>/api/equipment/model/service/update   
+
+请求参数
+
+```json
+{
+    "id": "78901",
+    "iotModelId": "123",
+    "serviceCode": "grActivePowerSetPointValue",
+    "serviceName": "功率设定值",
+    "serviceType":146,
+    "porder":1,
+    "revision": 1,
+    "updatedBy": "admin",
+    "updatedTime": "2024-06-27 15:08:23"
+}
+```
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "更新成功",
+	"success": true
+}
+```
+
+#### 2.2.12物模型方法删除         
+
+POST 请求接口
+>/api/equipment/model/service/delete 
+
+请求参数
+
+```json
+{
+    "id": "78901"
+}
+```
+
+入参描述
+
+| 参数名 | 参数类型 | 可选 | 描述   |
+| ------ | -------- | ---- | ------ |
+| id     | 字符串   | No   | 主键ID |
+
+返回报文
+
+```json
+{
+	"code": 200,
+	"msg": "删除成功",
+	"success": true
+}
+```
+
+#### 2.2.13 Excel导出物模型属性和方法
+
+POST 请求接口
+
+> /api/equipment/model/export
+
+请求参数
+
+```json
+{
+    "id": "123"
+}
+```
+
+入参描述
+
+| 参数名 | 参数类型 | 可选 | 描述     |
+| ------ | -------- | ---- | -------- |
+| id     | 字符串   | No   | 物模型ID |
+
+返回 Excel文件，分成两个Sheet页，第一个sheet页是属性，第二个sheet页是方法，按【porder】排序显示
+
+
+
+#### 2.2.14 Excel导入物模型属性和方法
+
+
+
+
+
diff --git a/docs/api/readme.md b/docs/api/readme.md
new file mode 100644
index 00000000..84a7a462
--- /dev/null
+++ b/docs/api/readme.md
@@ -0,0 +1,20 @@
+# 概述
+
+## 接口约定
+
+系统中的所有接口均遵循以下约定。
+
+1. 除了与文件上传/下载相关的接口外，都是`POST`请求，请求报文使用`JSON`格式。
+2. 文件下载使用GET请求(此种类型，加解密再讨论下)。
+3. 文件上传使用POST请求，请求报文使用`multipart/form-data`格式。
+
+## 加密/解密
+
+请求报文，Header中需要添加参数
+
+| 参数名称 | 说明     |   备注  |
+| -------- | -------- | --- |
+| token    | 令牌     |   需要鉴权的API 才需要添加此参数  |
+| V        | 加密向量 |  必须添加   |
+
+加密采用AES/CBC/ZeroPadding加密方式，密钥长度为16位。，IV长度为16位（每次请求时随机生成）。
\ No newline at end of file