# ControlProxy接口

> **基本要求：**
>
> 1.返回结果的result 不应该是jsonstr格式，当它可以是json对象时，需要以json对象返回。
> 2.异常处理，约定异常格式。提供工具类返回异常格式的消息。
>
> 3.输入参数都以json格式，如参数为doId：
>
> ```json
> {
> 	"doId":"xx.yy/zz"
> }
> ```
>
> 4.正常返回：(只返回状态的接口)
>
> ```json
> {
> 	"msg":"success",
> 	"code":0,
> }
> ```
>
> 5.正常返回：(返回一共数组)
>
> ```json
> {
> 	"msg":"success",
> 	"code":0,
> 	"data":{}//要返回的数据
> }
> ```
>
> 6.异常返回：
>
> ```json
> {
> 	"msg":"missing argument",
> 	"code":1
> }
> 
> {
> 	"msg":"request to much",
> 	"code":2
> }
> ...
> ```
>
> 7.若返回一个列表的部分的接口，需要给定总数字段：（这样的接口参数需要提供count和offset）
>
> ```json
> //搜索接口返回
> //这个例子表示符合条件的一共有9999条数据，只返回count和offset限定的3条数据
> {
> "data":[
>   {},
>   {},
>   {}
> ],
>  "total":9999
> }
> ```
>
> 
>
> ## Repo元数据
>
> | 字段        | 值     | 说明                        | 示例                         |
> | ----------- | ------ | --------------------------- | ---------------------------- |
> | doId        | string | Repo的Id                    | "bdware.txte/Repo"           |
> | name        | string | Repo名称                    | "xx数字对象仓库"             |
> | owner       | string | 所有者                      | "xx局"                       |
> | contractID  | string | 合约名称或者合约ID          | "DBRepo"                     |
> | type        | string | Repo类型(待扩展)            | "Table"/"Http"               |
> | description | string | 说明                        | "这是一段关于该repo的说明"   |
> | enableIndex | bool   | 是否索引                    | true                         |
> | createTime  | long   | 创建时间                    | 1641364002477                |
> | status      | string | 状态（在线/离线）           | "online"或者"offline"        |
> | check       | string | 审核情况（提交/通过/不通过) | "submit"或"success"或"faild" |
> | operator    | string | 操作员                      | "张三"                       |
> | manager     | array  | 管理员                      | ["xx局","yy局","zz部门"]     |
>
> ### DO元数据
>
> | 字段        | 值     | 说明               | 示例                                   |
> | ----------- | ------ | ------------------ | -------------------------------------- |
> | doId        | string | do的Id             | "bdware.txte/Repo/do.dbname.tablename" |
> | name        | string | do的名称           | "xx表格"                               |
> | type        | string | Repo类型(待扩展)   | "SQL"或者"CSV"                         |
> | description | string | 说明               | "这是一段关于该DO的说明"               |
> | schema      | string | 数据格式描述(DOd?) | ""                                     |
> | createTime  | long   | 创建时间           | 1641364002477                          |
>
> ### Repo元数据示例
>
> ```json
> {
> 	"doId":"bdware.txte/Repo",
>     "name":"xx部门数据仓库",
>     "type":"？",
>     "description":"这是一个repo",
> 
>     "owner":"xx省yy市zz部门",
>     "contractID":"DBRepo",
>     "enableIndex":true, 
>     "createTime":1641364002477,
>     "status":"online",
>     "check":"submit",
>     "operator":"张三",
>     "manager":["xx局","yy局","zz部门"]
> }
> ```
>
> 
>
> ## 示例说明：getDoCount
>
> - 说明：调用搜索引擎的统计接口，返回对应repo的doId当中含有输入参数的repo的do数量
>
> - 参数：一个字符串，用于doId的模糊匹配
>
>   ```json
>   {
>   	"key":"bdware.txte/Repo"
>   }
>   ```
>
> - 正常返回：result的值是json对象而不是字符串
>
>   ```json
>   //空：
>   {
>       "data":[]
>   }
>   //非空：
>   {
>       "data":[
>           {"doId":"bdware.txte/Repo1","count":10},
>           {"doId":"bdware.txte/Repo2","count":12}
>       ],
>       "total":9999
>   }
>   //调用返回的全部内容，是正常还是异常看status字段
>   {"needSeq":false,"seq":0,"status":"Success","result":{"data":[{"doId":"bdware.txte/Repo1","count":10},{"doId":"bdware.txte/Repo2","count":12}]},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085355104_1279","action":"onExecuteResult","executeTime":"9"}
>   
>   ```
>
> - 异常返回：抛出异常，result的内容是个字符串表示异常内容或者异常的信息
>
>   ```json
>   //异常返回方式
>   YancloudUtil.exceptionReturn({"msg":"missing arguments repoId ","code":1});
>   
>   //结果
>   {"needSeq":false,"seq":0,"status":"Exception","result":{"msg":"xxx","code":1},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085126815_8926","action":"onExecuteResult","executeTime":"17"}
>   ```
>

## 一、ControlProxy.yjs @李智

### 1.addRepo

- 说明：调用Gateway的addLocalRepo，由GateWay检查参数等，正确返回代码为0，错误返回提供具体错误代码及原因

- 参数

  ```json
  {
  	"doId":"bdware.txte/Repo",
      "name":"xx部门数据仓库",
      "type":"？",
      "description":"这是一个repo",
  
      "owner":"xx省yy市zz部门",
      "contractID":"DBRepo",
      "enableIndex":true, 
      "createTime":1641364002477,
      "status":"online",
      "check":"submit",
      "operator":"张三",
      "manager":["xx局","yy局","zz部门"]
  }
  ```

  

- 正常返回

  ```json
  {
      "msg":"success",
      "rrt":"110ms",
      "code":0
  }
  ```

- 异常返回：msg：错误信息，code：错误代码

  ```json
  {
      "msg":"missing arguments repoId ",
      "code":1
  }
  ```

  

### 2.pingRepo

- 说明

- 参数

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```

- 正常返回

  ```json
  {
      "msg":"success",
      "rrt":"110ms",
      "code":0,
      "repoInfo":
      {
          "doId":"bdware.txte/Repo",
          "name":"xx部门数据仓库",
          "type":"？",
          "description":"这是一个repo",
  
          "owner":"xx省yy市zz部门",
          "contractID":"DBRepo",
          "enableIndex":true, 
          "createTime":1641364002477,
          "status":"online",
          "check":"submit",
          "operator":"张三",
          "manager"：["xx局","yy局","zz部门"]
  	}//repo元数据
  }
  ```

- 异常返回

  ```json
  {
      "msg":"repo is unconnected",
      "code":1
  }
  ```
  

### 3.getRepoList

- 说明

- 参数：无

- 正常返回

  ```json
  {
      "data":[
          {},//repo元数据
          {},//repo元数据
          {}//repo元数据
      ],
      "total":9999
  }
  ```
  
- 异常返回

  

  ```json
  {
      "msg":"repo is unconnected",
      "code":1
  }
  ```
  
  

### 4.deleteRepo

- 说明

- 参数

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```

- 正常返回

  ```json
  {
      "msg":"success",
      "code":0
  }
  ```

- 异常返回：msg：错误信息，code：错误代码

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```

  

### 5.deleteRepoList（4和5是同一个）

- 说明

- 参数

  ```json
  [
      {"doId":"bdware.ss/Repox"},
      {"doId":"bdware.ss/Repoy"}
  ]
  ```

- 正常返回

  ```json
  {
      [{
      "msg":"success",
      "code":0
  },
      {
      "msg":"success",
      "code":0
  },
  {
      "msg":"success",
      "code":0
  }]
  }
  ```
  
- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```
  

### 6.updateRepo

- 说明

- 参数：全部元数据

  ```json
   {
          "doId":"bdware.txte/Repo",
          "name":"xx部门数据仓库",
          "type":"？",
          "description":"这是一个repo",
  
          "owner":"xx省yy市zz部门",
          "contractID":"DBRepo",
          "enableIndex":true, 
          "createTime":1641364002477,
          "status":"online",
          "check":"submit",
          "operator":"张三",
          "manager"：["xx局","yy局","zz部门"]
  }
  ```
  
  - 正常返回
  
  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```
  
- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```
  


## 二、networking.yjs @范博

### 1.getRouterInfo

- 说明

- 参数：无

- 正常返回

  ```json
  {
      "date": 1642467459759,
      "name": "next路由器",
      "doId": "bdwaretest.loccall.next1",
      "version": "2.1",
      "address": "127.0.0.1:2222",
      "status": "已审核",
      "protocol": "IRP",
      "pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```

- 异常返回

  ```json  {
  {
      "msg":"can not found repo",
      "code":1
  }
  ```



### 2.listLRS

- 说明

- 参数:无

- 说明：该接口暂时不会有太多数据，因此没有提供total字段和count，offset方式

- 正常返回

  ```json
  {
      //"result":"success",
      "data":[
          {
              "protocol":"DO-IRP协议","name":"ee","pubKey":"046c31d1e4f0056325c352a6c9934c1d15a51ef4b5bc552387a1c43188b2317a1863a9072cf612c2c15e5353083cf47e2024b49e416e8f6f8d4b0db496b67336f5","version":"2.0","address":"1.1.1.1:333","doId":"bdtest5.r1.121111111444","date":1643340044943
          },
          {"protocol":"DO-IRP协议","name":"aaa","pubKey":"04bb83950bf8f0b02cc9c95eb25a30950958e2c271c423c28a3612f5bc199a94c55c637d15876e442c265e1b3f970fb167ba59a489157f279955d69a12359501df","version":"2.0","address":"1.1.1.1:44","doId":"bdtest5.r1.ss","date":1645510310038},{"protocol":"DO-IRP协议","name":"test2","pubKey":"04bb83950bf8f0b02cc9c95eb25a30950958e2c271c423c28a3612f5bc199a94c55c637d15876e442c265e1b3f970fb167ba59a489157f279955d69a12359501df","version":"2.0","address":"1.1.1.1:44","doId":"bdtest5.r1.test2","date":1645510310038},
          {"protocol":"DO-IRP协议","name":"test","pubKey":"04982fc8507302c57a0389de1f6fc8a72c70577dff15fb0f23d3898742ac7684ace75c3b12dec94b8866ffcea9ef4795c09074327e4f1822b546cc6f783931da94","version":"2.0","address":"1.1.1.1:55","doId":"bdtest5.r1.tttTest","date":1643338165008
          }
      ],
      "count":4
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```



### 3.updateLRS

- 说明

- 参数

  ```json
  {
      "date": 1642467459759,
      "oldName": "路由器",
      "oldDoId": "bdwaretest.loccall.next0",
      "name": "next路由器",
      "doId": "bdwaretest.loccall.next1",
      "version": "2.1",
      "address": "127.0.0.1:2222",
      "status": "已审核",
      "protocol": "IRP",
      "pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```

- 正常返回:新的doid

  ```json
  {
      "data":"xxx.xx/aa";
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```



### 4.createLRS（除了oldname和olddoid，其他和undate一样）

- 说明

- 参数

  ```json
  {
      "date": 1642467459759,
      "name": "next路由器",
      "doId": "bdwaretest.loccall.next1",
      "version": "2.1",
      "address": "127.0.0.1:2222",
      "status": "已审核",
      "protocol": "IRP",
      "pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```
  
- 正常返回

  ```json
  {
      "data":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```



### 5.deleteLRS

- 说明

- 参数

  ```json
  {
      "name": "Repo1",
      "doId": "bdwaretest.loccall/Repo1",
  "pubKey":"04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```
  
- 正常返回

  ```json
  {
      "data":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```



### 6.listRepo（同listLRS）

- 说明

- 参数

  ```json
  {
      "doId":"...",
      "address":"...", 
      "owner":"...",
      "...":"..."
  }
  ```

- 正常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```



### 7.updateRepo（同updateLRS）

- 说明

- 参数

  ```json
  {
      "doId":"...",
      "address":"...", 
      "owner":"...",
      "...":"..."
  }
  ```

- 正常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```



### 8.createRepo(同createLRS)

- 说明

- 参数

  ```json
  {
      "date": 1642467459759,
      "name": "Repo1",
      "doId": "bdwaretest.loccall/Repo1",
      "version": "2.1",
      "address": "tcp://127.0.0.1:21042",
      "status": "已审核",
      "protocol": "DOIP",
      "pubKey": "04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```

- 正常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```



### 9.deleteRepo（同deleteLRS）

- 说明

- 参数

  ```json
  {
      "name": "next路由器",
      "doId": "bdwaretest.loccall.next1",
      "pubKey": "04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```
  
- 正常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "doId":"bdware.ss/Repox"
  }
  ```



### 10.setRootRouterInfo(和Create一样)

- 说明

- 参数

  ```json
  {
      "date": 1642467459759,
      "name": "Repo1",
      "doId": "bdwaretest.loccall/Repo1",
      "version": "2.1",
      "address": "tcp://127.0.0.1:21042",
      "status": "已审核",
      "protocol": "DOIP",
      "pubKey": "04d1924329f72ced148f6f333fb985ccbaa31b1e3aacf10be5f43d4a4ff5ad88899a005e79e37fc06993e1d66ada8cf8b711cb36f59538bb7d3e39e70fa9360ddd"
  }
  ```

- 正常返回

  ```json
  {
      "data":"bdware.ss/Repox"
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```

### 11.reInit

- 说明

- 参数：无

- 正常返回

  ```json
  {
      "data":"verify and start server success"
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```





## 三、repodetail.yjs

### 1.getDoList	@张宏伟

- 说明：如果指定repo，那么就是指定repo的dolist，否则是全部的

- 参数

  ```json
  {"doId":"xxx"}
  //或者
  {}
  ```
  
- 正常返回

  ```json
  {
  	"data":[{},{},{}],
      "total":9999
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```

### 2.getRepoTopology

- 说明

- 参数

  ```json
  {
      "doId":"..."
  }
  ```
  
- 正常返回

  ```json
  {
      "data":[
          {"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]},
          {"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]},
          {"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]},
          {"name":"小店区仓库","doId":"bdware.ss.ab/Repo1","previousNode":["bdware.ss/Gateway1","bdware.ss/Gateway2"]}
             ],
      "total":9999
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```





### 3.getStaticIndex(先不管)

- 说明

- 




### 4.fakeList（略

- 说明

- 




## 四、search.yjs

### 1.getDoCount	@张宏伟

- 说明：调用搜索引擎的统计接口，返回对应repo的doId当中含有输入参数的repo的do数量

- 参数：一个字符串，用于doId的模糊匹配

  ```json
  bdware.txte/Repo
  ```

- 正常返回：result的值是json对象而不是字符串

  ```json
  //空：
  {
      "data":[],
      "total":0
  }
  //非空：
  {
      "data":[
          {"doId":"bdware.txte/Repo1","count":10},
          {"doId":"bdware.txte/Repo2","count":12}
      ],
      "total":2
  }
  //调用返回的全部内容，是正常还是异常看status字段
  {"needSeq":false,"seq":0,"status":"Success","result":{"data":[{"doId":"bdware.txte/Repo1","count":10},{"doId":"bdware.txte/Repo2","count":12}]},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085355104_1279","action":"onExecuteResult","executeTime":"9"}
  ```

- 异常返回：抛出异常，result的内容是个字符串表示异常内容

  ```json
  {"needSeq":false,"seq":0,"status":"Exception","result":{"msg":"xxx","code":1},"isInsnLimit":false,"totalGas":0,"executionGas":0,"extraGas":0,"size":0,"eventRelated":false,"responseID":"1645085126815_8926","action":"onExecuteResult","executeTime":"17"}
  ```
  
  

### 2.countRecordByDate	@董瑞

- 说明：

  >  //=====全域监管：数字对象溯源 针对单个DO的，通过SQL查询来实现。
  >   //根据 doId --> 找到“数字对象世系” 
  >   //86.500.1/Repo.1/Doab
  >   //根据 doId+时间范围+interval+protocol --> 不同operation的统计数据 （AuditProxy)
  >   //countDORecordByDate()
  >   //{"doId":xxxx,"startTime","endTime","interval","eventPrefix":["doip_create","doip_update"]}
  >   //{"eventxxx":[1,2,3],"event2":[1,2,3]}
  >
  >   //根据 doId +查找条件（时间范围  protocol operation user?) +offset/count -->总数+指定条数的数组（AuditProxy)
  >   // queryDoRecordByDate
  >   //{"doId":xxxx,"startTime","endTime","eventPrefix":["doip_create","doip_update"]}
  >   //{"count":xx, "data":[{doip_request的某一行。},]}
  >   // queryDoRecordByOffset
  >   //{"doId":xxxx,"offset","count","eventPrefix":["doip_create","doip_update"]}
  >   //{"total":xx,"count":xx, "data":[{doip_request的某一行。},]}
  >   //==============

- 参数：下面的内容表示owner字段当中包含"xxx"且doid当中包含"aibd"的结果

  ```json
  {
      "startTime":1641454745128,
      "endTime":1641494745128,
      "interval":5000,
      "eventPrefix":["abc"]
  }
  ```

- 正常返回：repo元数据的数组，每一个{}表示一个元数据

  ```json
  {
      "doip_search":[1,2,3,4],
      "doip_create":[5,6,7,8]
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```







### 3.getDoFilter	@张宏伟

- 说明：按照某一字段值的范围查询

- 参数：下面是按照字段createTime的时间来查询，count和offset可缺省

  ```json
  {
      "type":"creatTime",
      "count":10,
      "offset":0,
      "from":"1141363811328",
      "to":"1941363811328"
  }
  ```

  

- 正常返回：repo元数据的数组，每一个{}表示一个元数据

  ```json
  {
      "data":[
          {},{},{}
      ],
      "total":3
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```

### 4.search

- 说明：支持多个字段的搜索

- 参数：下面的内容表示owner字段当中包含"xxx"且doid当中包含"aibd"的结果

  ```json
  {
      "params":[
          {"type":"owner","keyword":"xxx"},
          {"type":"doid","keyword":"aibd"}
      ],
      "count":10,
      "offset":0
  }
  ```

- 正常返回：repo元数据的数组，每一个{}表示一个元数据

  ```json
  {
      "data":[
          {},{},{}
      ],
      "total":3
  }
  ```

- 异常返回

  ```json
  {
      "msg":"can not found repo",
      "code":1
  }
  ```





