# 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` 字段和值为结构化示意，实际成功码和提示文案以公共响应实现为准