yexb
81e4ff4009
- 新增 buildIndexConfirmData 和 buildIndexSelection 两个调试接口 - 添加完整的请求参数和响应结果的数据结构定义 - 实现索引候选数据到确认模型的转换逻辑 - 实现确认结果到正式索引选择的展开生成功能 - 添加详细的 API 调试文档和使用示例 - 集成参数校验和业务规则验证机制
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` 字段和值为结构化示意，实际成功码和提示文案以公共响应实现为准
|