309 lines
9.0 KiB
Markdown
309 lines
9.0 KiB
Markdown
|
# buildIndexConfirmData / buildIndexSelection 标准 API 调试文档
|
|||
|
|
|
|||
|
|
## 1. 文档范围
|
|||
|
|
|
|||
|
|
本文档用于说明 `mms-mapping` 模块中 `buildIndexConfirmData`、`buildIndexSelection` 两个调试接口的标准调用方式、请求结构、响应规则和联调注意事项。
|
|||
|
|
|
|||
|
|
本文档内容以当前源码为准，主要对照以下实现：
|
|||
|
|
|
|||
|
|
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/controller/MappingController.java`
|
|||
|
|
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/component/IndexSelectionBuildService.java`
|
|||
|
|
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/IndexCandidateRequest.java`
|
|||
|
|
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/BuildIndexSelectionRequest.java`
|
|||
|
|
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/IndexConfirmGroupResponse.java`
|
|||
|
|
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/IndexSelectionGroupResponse.java`
|
|||
|
|
|
|||
|
|
说明：
|
|||
|
|
|
|||
|
|
- 两个接口当前统一返回 `HttpResult<T>` 标准包装。
|
|||
|
|
- 业务异常和参数异常仍由全局异常处理器统一包装。
|
|||
|
|
- 本次仅整理接口标准出口和调试文档，未改动索引组装算法。
|
|||
|
|
- 本次未执行 `mvn` 编译、打包或真实接口联调。
|
|||
|
|
|
|||
|
|
## 2. 接口一：buildIndexConfirmData
|
|||
|
|
|
|||
|
|
### 2.1 基本信息
|
|||
|
|
|
|||
|
|
| 项 | 说明 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 接口名称 | `buildIndexConfirmData` |
|
|||
|
|
| 请求方法 | `POST` |
|
|||
|
|
| 请求路径 | `/api/mms-mapping/build-index-confirm-data` |
|
|||
|
|
| Content-Type | `application/json` |
|
|||
|
|
| 控制器入口 | `MappingController#buildIndexConfirmData` |
|
|||
|
|
| 成功响应体 | `HttpResult<List<IndexConfirmGroupResponse>>` |
|
|||
|
|
|
|||
|
|
### 2.2 接口职责
|
|||
|
|
|
|||
|
|
该接口用于把 `getIcdMmsJson` 或 `getICD` 返回的 `indexCandidates` 转换成前端可直接展示和确认的弹窗模型。
|
|||
|
|
|
|||
|
|
转换后的确认模型主要补充以下信息：
|
|||
|
|
|
|||
|
|
- 每个分组下去重后的标签列表
|
|||
|
|
- 每个标签可配置的目标报告
|
|||
|
|
- 每个标签多个目标报告的 `lnInst` 共同候选值
|
|||
|
|
- 当共同候选值只有一个时，自动给出 `defaultLnInst`
|
|||
|
|
|
|||
|
|
### 2.3 请求体
|
|||
|
|
|
|||
|
|
请求体为 `IndexCandidateRequest[]`，也就是候选分组数组。
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
[
|
|||
|
|
{
|
|||
|
|
"groupKey": "统计数据__DSSTATISTICDATA",
|
|||
|
|
"groupDesc": "统计数据",
|
|||
|
|
"reportCount": 2,
|
|||
|
|
"templateLabels": [
|
|||
|
|
"A相",
|
|||
|
|
"B相",
|
|||
|
|
"C相",
|
|||
|
|
"间谐波1"
|
|||
|
|
],
|
|||
|
|
"reports": [
|
|||
|
|
{
|
|||
|
|
"reportName": "brcbStatistic",
|
|||
|
|
"dataSetName": "dsStatisticData",
|
|||
|
|
"reportDesc": "统计数据报告",
|
|||
|
|
"availableLnInstValues": [
|
|||
|
|
"1",
|
|||
|
|
"2",
|
|||
|
|
"3",
|
|||
|
|
"11",
|
|||
|
|
"12",
|
|||
|
|
"13"
|
|||
|
|
]
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"reportName": "brcbStatisticInter",
|
|||
|
|
"dataSetName": "dsStIHarm",
|
|||
|
|
"reportDesc": "间谐波统计报告",
|
|||
|
|
"availableLnInstValues": [
|
|||
|
|
"11",
|
|||
|
|
"12",
|
|||
|
|
"13"
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.4 成功响应示例
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "200",
|
|||
|
|
"msg": "buildIndexConfirmData,成功",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"groupKey": "统计数据__DSSTATISTICDATA",
|
|||
|
|
"groupDesc": "统计数据",
|
|||
|
|
"labelItems": [
|
|||
|
|
{
|
|||
|
|
"label": "A相",
|
|||
|
|
"required": false,
|
|||
|
|
"configurableOnce": true,
|
|||
|
|
"commonLnInstValues": [
|
|||
|
|
"1",
|
|||
|
|
"2",
|
|||
|
|
"3"
|
|||
|
|
],
|
|||
|
|
"targets": [
|
|||
|
|
{
|
|||
|
|
"reportName": "brcbStatistic",
|
|||
|
|
"dataSetName": "dsStatisticData",
|
|||
|
|
"reportDesc": "统计数据报告",
|
|||
|
|
"availableLnInstValues": [
|
|||
|
|
"1",
|
|||
|
|
"2",
|
|||
|
|
"3"
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
说明：
|
|||
|
|
|
|||
|
|
- `code`、`msg`、`data` 为标准 `HttpResult` 包装字段。
|
|||
|
|
- `data` 中的每个元素对应一个确认分组。
|
|||
|
|
- 若请求体为空数组，当前实现会返回成功响应，`data` 为空数组。
|
|||
|
|
|
|||
|
|
## 3. 接口二：buildIndexSelection
|
|||
|
|
|
|||
|
|
### 3.1 基本信息
|
|||
|
|
|
|||
|
|
| 项 | 说明 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| 接口名称 | `buildIndexSelection` |
|
|||
|
|
| 请求方法 | `POST` |
|
|||
|
|
| 请求路径 | `/api/mms-mapping/build-index-selection` |
|
|||
|
|
| Content-Type | `application/json` |
|
|||
|
|
| 控制器入口 | `MappingController#buildIndexSelection` |
|
|||
|
|
| 成功响应体 | `HttpResult<List<IndexSelectionGroupResponse>>` |
|
|||
|
|
|
|||
|
|
### 3.2 接口职责
|
|||
|
|
|
|||
|
|
该接口用于根据前端确认模型 `confirmData` 和用户最终选择结果 `confirmedData`，展开生成正式的 `indexSelection` 结构，供 `getMmsJson` 或 `getIcdMmsJson` 第二次提交时直接复用。
|
|||
|
|
|
|||
|
|
该接口会在生成前做以下校验：
|
|||
|
|
|
|||
|
|
- `request` 不能为空
|
|||
|
|
- `confirmData` 不能为空
|
|||
|
|
- `confirmedData` 中不能出现未知分组
|
|||
|
|
- 每个分组下不能出现未知标签
|
|||
|
|
- 已启用标签必须选择合法的 `lnInst`
|
|||
|
|
- `lnInst` 必须同时落在该标签所有目标报告的允许范围内
|
|||
|
|
|
|||
|
|
### 3.3 请求体
|
|||
|
|
|
|||
|
|
请求体为 `BuildIndexSelectionRequest`，包含两部分：
|
|||
|
|
|
|||
|
|
- `confirmData`：接口一返回并由前端回传的确认模型
|
|||
|
|
- `confirmedData`：用户在界面上实际确认后的启用状态和 `lnInst`
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"confirmData": [
|
|||
|
|
{
|
|||
|
|
"groupKey": "harm",
|
|||
|
|
"groupDesc": "谐波数据",
|
|||
|
|
"labelItems": [
|
|||
|
|
{
|
|||
|
|
"label": "A相",
|
|||
|
|
"required": false,
|
|||
|
|
"configurableOnce": true,
|
|||
|
|
"defaultLnInst": "1",
|
|||
|
|
"commonLnInstValues": [
|
|||
|
|
"1",
|
|||
|
|
"2",
|
|||
|
|
"3"
|
|||
|
|
],
|
|||
|
|
"targets": [
|
|||
|
|
{
|
|||
|
|
"reportName": "brcbStHarm",
|
|||
|
|
"dataSetName": "dsStHarm",
|
|||
|
|
"reportDesc": "谐波报告",
|
|||
|
|
"availableLnInstValues": [
|
|||
|
|
"1",
|
|||
|
|
"2",
|
|||
|
|
"3"
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
"confirmedData": [
|
|||
|
|
{
|
|||
|
|
"groupKey": "harm",
|
|||
|
|
"labelItems": [
|
|||
|
|
{
|
|||
|
|
"label": "A相",
|
|||
|
|
"enabled": true,
|
|||
|
|
"lnInst": "1"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.4 成功响应示例
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "200",
|
|||
|
|
"msg": "buildIndexSelection,成功",
|
|||
|
|
"data": [
|
|||
|
|
{
|
|||
|
|
"groupKey": "harm",
|
|||
|
|
"groupDesc": "谐波数据",
|
|||
|
|
"bindings": [
|
|||
|
|
{
|
|||
|
|
"reportName": "brcbStHarm",
|
|||
|
|
"dataSetName": "dsStHarm",
|
|||
|
|
"label": "A相",
|
|||
|
|
"lnInst": "1"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
说明：
|
|||
|
|
|
|||
|
|
- 返回结果中的 `data` 就是可直接提交给 `getMmsJson` / `getIcdMmsJson` 的 `indexSelection`。
|
|||
|
|
- 只有启用且校验通过的标签才会被展开进最终 `bindings`。
|
|||
|
|
|
|||
|
|
### 3.5 失败响应说明
|
|||
|
|
|
|||
|
|
如果请求结构不合法或业务校验失败，会进入全局异常处理，返回统一 `HttpResult<String>`。常见场景包括：
|
|||
|
|
|
|||
|
|
- `request` 为空
|
|||
|
|
- `confirmData` 为空
|
|||
|
|
- `confirmedData` 中存在未知分组
|
|||
|
|
- 某个标签未选择 `lnInst`
|
|||
|
|
- 选择的 `lnInst` 不在共同候选范围内
|
|||
|
|
- 选择的 `lnInst` 不在目标报告允许范围内
|
|||
|
|
|
|||
|
|
示例：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "500",
|
|||
|
|
"msg": "buildIndexSelection,参数异常",
|
|||
|
|
"data": "分组【谐波数据】的标签【A相】未选择 lnInst"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
说明：
|
|||
|
|
|
|||
|
|
- 这里的 `code`、`msg` 以公共异常包装实现为准，不保证与示例完全一致。
|
|||
|
|
- 具体错误文案由 `IndexSelectionBuildService` 抛出的 `IllegalArgumentException` 决定。
|
|||
|
|
|
|||
|
|
## 4. 标准调试顺序
|
|||
|
|
|
|||
|
|
推荐按以下顺序联调：
|
|||
|
|
|
|||
|
|
1. 先调用 `getIcdMmsJson` 或 `getICD` 获取 `indexCandidates`
|
|||
|
|
2. 把 `indexCandidates` 原样提交给 `buildIndexConfirmData`
|
|||
|
|
3. 前端根据返回的确认模型组装 `confirmedData`
|
|||
|
|
4. 调用 `buildIndexSelection` 生成正式 `indexSelection`
|
|||
|
|
5. 把 `indexSelection` 提交给 `getMmsJson` 或 `getIcdMmsJson` 生成正式 `mappingJson`
|
|||
|
|
|
|||
|
|
## 5. curl 调试示例
|
|||
|
|
|
|||
|
|
### 5.1 buildIndexConfirmData
|
|||
|
|
|
|||
|
|
```powershell
|
|||
|
|
curl.exe -X POST "http://localhost:8080/api/mms-mapping/build-index-confirm-data" `
|
|||
|
|
-H "Content-Type: application/json" `
|
|||
|
|
-d "[{\"groupKey\":\"harm\",\"groupDesc\":\"谐波数据\",\"reportCount\":1,\"templateLabels\":[\"A相\",\"B相\",\"C相\"],\"reports\":[{\"reportName\":\"brcbStHarm\",\"dataSetName\":\"dsStHarm\",\"reportDesc\":\"谐波报告\",\"availableLnInstValues\":[\"1\",\"2\",\"3\"]}]}]"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.2 buildIndexSelection
|
|||
|
|
|
|||
|
|
```powershell
|
|||
|
|
curl.exe -X POST "http://localhost:8080/api/mms-mapping/build-index-selection" `
|
|||
|
|
-H "Content-Type: application/json" `
|
|||
|
|
-d "{\"confirmData\":[{\"groupKey\":\"harm\",\"groupDesc\":\"谐波数据\",\"labelItems\":[{\"label\":\"A相\",\"required\":false,\"configurableOnce\":true,\"defaultLnInst\":\"1\",\"commonLnInstValues\":[\"1\",\"2\",\"3\"],\"targets\":[{\"reportName\":\"brcbStHarm\",\"dataSetName\":\"dsStHarm\",\"reportDesc\":\"谐波报告\",\"availableLnInstValues\":[\"1\",\"2\",\"3\"]}]}]}],\"confirmedData\":[{\"groupKey\":\"harm\",\"labelItems\":[{\"label\":\"A相\",\"enabled\":true,\"lnInst\":\"1\"}]}]}"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 6. 当前边界
|
|||
|
|
|
|||
|
|
- 本文档只覆盖 `buildIndexConfirmData` 和 `buildIndexSelection`
|
|||
|
|
- `getIcdMmsJson` 独立调试方式仍以 `API-getIcdMmsJson.md` 为准
|
|||
|
|
- 示例中的 `HttpResult` 字段和值为结构化示意，实际成功码和提示文案以公共响应实现为准
|