Files

yexb 81e4ff4009 feat(mms-mapping): 添加索引确认和选择构建功能

- 新增 buildIndexConfirmData 和 buildIndexSelection 两个调试接口
- 添加完整的请求参数和响应结果的数据结构定义
- 实现索引候选数据到确认模型的转换逻辑
- 实现确认结果到正式索引选择的展开生成功能
- 添加详细的 API 调试文档和使用示例
- 集成参数校验和业务规则验证机制

2026-05-06 13:24:18 +08:00

9.0 KiB

Raw Blame History

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[]，也就是候选分组数组。

示例：

[
  {
    "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 成功响应示例

{
  "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

示例：

{
  "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 成功响应示例

{
  "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 不在目标报告允许范围内

示例：

{
  "code": "500",
  "msg": "buildIndexSelection,参数异常",
  "data": "分组【谐波数据】的标签【A相】未选择 lnInst"
}

说明：

这里的 code、msg 以公共异常包装实现为准，不保证与示例完全一致。
具体错误文案由 IndexSelectionBuildService 抛出的 IllegalArgumentException 决定。

4. 标准调试顺序

推荐按以下顺序联调：

先调用 getIcdMmsJson 或 getICD 获取 indexCandidates
把 indexCandidates 原样提交给 buildIndexConfirmData
前端根据返回的确认模型组装 confirmedData
调用 buildIndexSelection 生成正式 indexSelection
把 indexSelection 提交给 getMmsJson 或 getIcdMmsJson 生成正式 mappingJson

5. curl 调试示例

5.1 buildIndexConfirmData

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

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

9.0 KiB Raw Blame History Unescape Escape