docs(api): 删除MMS映射API调试文档

- 移除generateAndSubmitIndexSelection标准API调试文档 - 移除getIcdMmsJson标准API调试文档 - 清理相关API接口说明和调试示例内容 - 删除Postman和cURL调试方式说明 - 移除请求响应结构定义和常见问题解答
2026-04-30 11:30:59 +08:00
parent 0dc0e4ecdc
commit 297f89ef52
2 changed files with 0 additions and 704 deletions
--- a/frontend/src/views/tools/mmsmapping/API-debug-generate-and-submit-index-selection.md
+++ b/frontend/src/views/tools/mmsmapping/API-debug-generate-and-submit-index-selection.md
@@ -1,333 +0,0 @@
-# generateAndSubmitIndexSelection 标准 API 调试文档
-
-## 1. 接口信息
-
- 接口名称：上传 ICD 后直接生成并提交映射
- Controller 方法：`generateAndSubmitIndexSelection`
- 请求方式：`POST`
- 请求路径：`/api/mms-mapping/generate-and-submit-index-selection`
- Content-Type：`multipart/form-data`
- 适用场景：前端或调试人员已经能直接给出 `indexSelection`，希望一次请求完成 ICD 解析、候选分析、索引校验和正式映射生成。
-
-源码参考：
- `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/service/MappingTaskService.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/component/MappingRequestConverter.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/component/MappingResponseConverter.java`
-
-## 2. 处理链路
-
-该接口内部按以下顺序执行：
-1. 读取上传的 `icdFile`。
-2. 解析 ICD，生成 `icdDocument`。
-3. 加载默认模板并分析候选索引。
-4. 读取同一次请求中的 `indexSelection`。
-5. 校验分组、标签、报告、`lnInst` 是否有效。
-6. 校验通过则生成正式映射 JSON；校验不通过则返回 `NEED_INDEX_SELECTION`。
-
-因此，这个接口有两类主要调试目标：
- 调试一次成功生成映射。
- 调试为什么需要重新选择索引。
-
-## 3. 请求定义
-
-### 3.1 表单字段
-
-| 字段 | 类型 | 是否必填 | 说明 |
-| --- | --- | --- | --- |
-| `icdFile` | file | 是 | ICD 文件 |
-| `request` | json part | 是 | JSON 请求体，必须作为独立 part 传入 |
-
-### 3.2 request JSON 字段
-
-`request` 结构复用 `GenerateMappingFromIcdRequest`。
-
-| 字段 | 类型 | 是否必填 | 说明 |
-| --- | --- | --- | --- |
-| `version` | string | 否 | 输出版本号，空值时按服务端默认逻辑处理 |
-| `author` | string | 否 | 作者，空值时回退到模块默认作者 |
-| `saveToDisk` | boolean | 否 | 是否落盘保存生成结果 |
-| `prettyJson` | boolean | 否 | 是否返回格式化 JSON |
-| `outputDir` | string | 否 | 落盘目录，仅 `saveToDisk=true` 时有意义 |
-| `indexSelection` | array | 否 | 直接提交的索引绑定关系；为空时会返回 `NEED_INDEX_SELECTION` |
-
-### 3.3 indexSelection 字段
-
-| 字段 | 类型 | 是否必填 | 说明 |
-| --- | --- | --- | --- |
-| `groupKey` | string | 建议必填 | 候选分组唯一键，建议直接使用候选接口返回值 |
-| `groupDesc` | string | 否 | 分组中文描述，用于兼容匹配 |
-| `bindings` | array | 是 | 当前分组下的绑定关系列表 |
-
-### 3.4 bindings 子项字段
-
-| 字段 | 类型 | 是否必填 | 说明 |
-| --- | --- | --- | --- |
-| `reportName` | string | 是 | 报告名称 |
-| `dataSetName` | string | 是 | 数据集名称 |
-| `label` | string | 是 | 模板业务标签 |
-| `lnInst` | string | 是 | 最终绑定的 `lnInst` 数字 |
-
-## 4. Postman 调试方式
-
-### 4.1 请求设置
-
-在 Postman 中选择：
- Method：`POST`
- Body：`form-data`
-
-新增两个表单项：
-1. `icdFile`
-   - 类型：`File`
-   - 值：选择本地 ICD 文件
-2. `request`
-   - 类型：`Text`
-   - 值：填写 JSON 字符串
-
-建议把 `request` 这个 part 的 Content-Type 显式设为 `application/json`。
-
-### 4.2 request 示例
-
-```json
-{
-  "version": "1.0",
-  "author": "system",
-  "saveToDisk": false,
-  "prettyJson": true,
-  "outputDir": "",
-  "indexSelection": [
-    {
-      "groupKey": "实时数据__DSSTHARM",
-      "groupDesc": "实时数据",
-      "bindings": [
-        {
-          "reportName": "brcbStHarm",
-          "dataSetName": "dsStHarm",
-          "label": "A相",
-          "lnInst": "1"
-        },
-        {
-          "reportName": "brcbStHarm",
-          "dataSetName": "dsStHarm",
-          "label": "B相",
-          "lnInst": "2"
-        }
-      ]
-    }
-  ]
-}
-```
-
-## 5. cURL 调试示例
-
-### 5.1 成功生成示例
-
-```bash
-curl -X POST "http://localhost:8080/api/mms-mapping/generate-and-submit-index-selection" \
-  -H "Accept: application/json" \
-  -F "icdFile=@D:/data/demo.icd" \
-  -F 'request={
-    "version":"1.0",
-    "author":"system",
-    "saveToDisk":false,
-    "prettyJson":true,
-    "outputDir":"",
-    "indexSelection":[
-      {
-        "groupKey":"实时数据__DSSTHARM",
-        "groupDesc":"实时数据",
-        "bindings":[
-          {
-            "reportName":"brcbStHarm",
-            "dataSetName":"dsStHarm",
-            "label":"A相",
-            "lnInst":"1"
-          }
-        ]
-      }
-    ]
-  };type=application/json'
-```
-
-### 5.2 触发 NEED_INDEX_SELECTION 示例
-
-将 `indexSelection` 置空，或故意传入非法 `label` / `lnInst`：
-
-```bash
-curl -X POST "http://localhost:8080/api/mms-mapping/generate-and-submit-index-selection" \
-  -H "Accept: application/json" \
-  -F "icdFile=@D:/data/demo.icd" \
-  -F 'request={
-    "version":"1.0",
-    "author":"system",
-    "saveToDisk":false,
-    "prettyJson":true,
-    "outputDir":"",
-    "indexSelection":[]
-  };type=application/json'
-```
-
-## 6. 最小响应定义
-
-该接口已经按场景裁剪返回值。
-
-### 6.1 SUCCESS
-
-只返回：
- `status`
- `message`
- `mappingJson`
- `savedPath`，仅 `saveToDisk=true` 且保存成功时返回
- `problems`，仅存在问题时返回
-
-### 6.2 NEED_INDEX_SELECTION
-
-只返回：
- `status`
- `message`
- `icdDocument`
- `indexCandidates`
- `problems`
-
-### 6.3 FAILED
-
-只返回：
- `status`
- `message`
- `problems`，仅存在问题时返回
-
-## 7. 响应示例
-
-### 7.1 成功响应
-
-```json
-{
-  "status": "SUCCESS",
-  "message": "映射生成成功",
-  "mappingJson": "{\"Version\":\"1.0\",\"Author\":\"system\"}"
-}
-```
-
-### 7.2 成功并落盘响应
-
-```json
-{
-  "status": "SUCCESS",
-  "message": "映射生成成功",
-  "mappingJson": "{\"Version\":\"1.0\",\"Author\":\"system\"}",
-  "savedPath": "D:/output/IED1-mapping-pretty.json"
-}
-```
-
-### 7.3 需要重新选择索引响应
-
-```json
-{
-  "status": "NEED_INDEX_SELECTION",
-  "message": "索引配置不合法，请根据候选信息完成标签与数字索引的绑定后重新提交",
-  "icdDocument": {
-    "fileName": "demo.icd",
-    "iedName": "IED1",
-    "ldInst": "LD0"
-  },
-  "indexCandidates": [
-    {
-      "groupKey": "实时数据__DSSTHARM",
-      "groupDesc": "实时数据",
-      "reportCount": 1,
-      "templateLabels": ["A相", "B相", "C相"],
-      "reports": [
-        {
-          "reportName": "brcbStHarm",
-          "dataSetName": "dsStHarm",
-          "reportDesc": "实时数据",
-          "availableLnInstValues": ["1", "2", "3"]
-        }
-      ]
-    }
-  ],
-  "problems": [
-    "分组【实时数据】中 label【A相】不在模板候选中"
-  ]
-}
-```
-
-### 7.4 失败响应
-
-```json
-{
-  "status": "FAILED",
-  "message": "ICD 解析失败：ICD 文件内容不能为空",
-  "problems": [
-    "ICD 文件内容不能为空"
-  ]
-}
-```
-
-## 8. 常见调试问题
-
-### 8.1 `request` 没有按 JSON 传入
-
-现象：
- Spring 无法正确绑定 `@RequestPart("request")`
- 返回 400 或参数解析异常
-
-处理：
- 确保 `request` 是单独的 multipart part
- 建议显式设置 `type=application/json`
-
-### 8.2 `indexSelection` 为空
-
-现象：
- 返回 `NEED_INDEX_SELECTION`
- `message` 提示索引配置缺失
-
-处理：
- 先调用 `generateFromIcdCandidates`
- 使用其返回的 `groupKey`、`templateLabels`、`availableLnInstValues` 重新组装绑定
-
-### 8.3 `groupKey` 不匹配
-
-现象：
- `problems` 中出现“未找到分组配置”
-
-处理：
- 不要自己拼 `groupKey`
- 直接使用候选接口返回值原样回传
-
-### 8.4 `label` 不合法
-
-现象：
- `problems` 中出现“label 不在模板候选中”
-
-处理：
- `label` 必须取自当前分组的 `templateLabels`
-
-### 8.5 `lnInst` 不合法
-
-现象：
- `problems` 中出现“lnInst 不在可选数字中”
-
-处理：
- `lnInst` 必须取自当前报告的 `availableLnInstValues`
-
-### 8.6 `saveToDisk=true` 但没有 `savedPath`
-
-可能原因：
- 保存过程抛异常，接口直接返回 `FAILED`
- 输出目录无权限或路径非法
-
-处理：
- 优先先用 `saveToDisk=false` 验证生成链路
- 再单独验证落盘目录权限
-
-## 9. 联调建议
-
- 首次联调建议先走两步：
-  1. 先调用 `generateFromIcdCandidates`
-  2. 根据候选结果确认 `groupKey`、`label`、`lnInst` 后，再调当前接口
- 如果只是验证“提交链路”是否通，不建议一开始就打开 `saveToDisk`
- 如果需要排查返回值最小化是否生效，重点看：
-  - `SUCCESS` 不应再返回 `icdDocument`、`indexCandidates`
-  - `NEED_INDEX_SELECTION` 不应返回 `mappingJson`
-  - `FAILED` 不应返回候选或映射结果字段
--- a/frontend/src/views/tools/mmsmapping/API-getIcdMmsJson.md
+++ b/frontend/src/views/tools/mmsmapping/API-getIcdMmsJson.md
@@ -1,371 +0,0 @@
-# getIcdMmsJson 标准 API 调试文档
-
-## 1. 文档范围
-
-本文档用于说明 `mms-mapping` 模块统一调试接口 `getIcdMmsJson` 的标准调用方式、请求结构、响应规则和联调注意事项。
-
-本文档内容以当前源码为准，主要对照以下实现：
-
- `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/MappingRequestConverter.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/component/MappingResponseConverter.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/service/impl/MappingTaskServiceImpl.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/component/MappingGenerationService.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/GenerateMappingFromIcdRequest.java`
- `tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/MappingTaskResponse.java`
-
-说明：
-
- 本文档仅描述接口契约和调试方式，不改动业务代码。
- 本次未执行 `mvn` 编译、打包或真实接口联调。
- 如文档与运行结果冲突，以源码和实际部署配置为准。
-
-## 2. 接口基本信息
-
-| 项 | 说明 |
-| --- | --- |
-| 接口名称 | `getIcdMmsJson` |
-| 请求方法 | `POST` |
-| 请求路径 | `/api/mms-mapping/get-icd-mms-json` |
-| Content-Type | `multipart/form-data` |
-| 控制器入口 | `MappingController#getIcdMmsJson` |
-| 请求组成 | `icdFile` 文件 Part + `request` JSON Part |
-| 正常业务响应体 | `MappingTaskResponse` |
-
-## 3. 接口职责
-
-该接口是 `mms-mapping` 模块的统一调试入口，串联以下两个阶段：
-
-1. 上传 ICD 文件并完成解析，生成 `icdDocument` 和 `indexCandidates`
-2. 根据 `request.indexSelection` 判断是否继续生成正式 `mappingJson`
-
-接口行为分为三种典型结果：
-
-1. `request.indexSelection` 未传或为空  
-返回 `NEED_INDEX_SELECTION`，用于引导前端或调试人员先确认标签与 `lnInst` 的绑定关系。
-2. `request.indexSelection` 已传但校验不通过  
-返回 `NEED_INDEX_SELECTION`，同时通过 `problems` 给出不合法原因，要求重新选择。
-3. `request.indexSelection` 校验通过  
-返回 `SUCCESS`，输出正式 `mappingJson`，必要时同时落盘并返回 `savedPath`。
-
-补充说明：
-
- 该接口每次都会重新解析上传的 ICD 文件，因此第二次调试仍然必须重新上传 ICD 文件。
- 该接口正常进入业务编排后，返回体类型为 `MappingTaskResponse`。
- 如果异常发生在控制器参数绑定或请求转换阶段，例如文件为空、Part 缺失、JSON Part 解析失败，则由全局异常处理器统一包装为 `HttpResult<String>`，而不是 `MappingTaskResponse`。
-
-## 4. 请求规范
-
-### 4.1 multipart/form-data Part 说明
-
-| Part 名称 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `icdFile` | File | 是 | ICD 文件，不能为空 |
-| `request` | JSON Part | 是 | 生成参数，必须按 `application/json` 发送 |
-
-说明：
-
- `request` Part 不能省略。即使第一次只想拿候选结果，也必须传一个最小 JSON。
- `request.indexSelection` 可以省略或传空数组，此时接口只返回候选结果，不生成正式映射。
-
-### 4.2 request JSON 结构
-
-```json
-{
-  "version": "2026-04-22",
-  "author": "debug-user",
-  "saveToDisk": false,
-  "prettyJson": true,
-  "outputDir": "D:/temp/mms-output",
-  "indexSelection": [
-    {
-      "groupKey": "harm",
-      "groupDesc": "谐波数据",
-      "bindings": [
-        {
-          "reportName": "brcbStHarm",
-          "dataSetName": "dsStHarm",
-          "label": "A相",
-          "lnInst": "1"
-        }
-      ]
-    }
-  ]
-}
-```
-
-### 4.3 request 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `version` | String | 否 | 输出版本号。未传或空白时，后端按当天日期补齐，格式为 `yyyy-MM-dd` |
-| `author` | String | 否 | 作者。未传或空白时，回退到配置项 `icd.mapping.default-author`，默认值为 `system` |
-| `saveToDisk` | boolean | 否 | 是否将生成结果写入磁盘 |
-| `prettyJson` | boolean | 否 | 是否输出格式化 JSON。`true` 为美化 JSON，`false` 为紧凑 JSON |
-| `outputDir` | String | 否 | 输出目录。未传或空白时，先回退到配置项 `icd.mapping.default-output-dir`；如果配置也为空，最终落到当前工作目录 |
-| `indexSelection` | Array | 否 | 标签与 `lnInst` 的最终绑定关系。未传或为空时，只返回候选结果 |
-
-### 4.4 indexSelection 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `groupKey` | String | 是 | 分组唯一键，必须使用第一次响应里返回的原值 |
-| `groupDesc` | String | 否 | 分组中文描述，便于调试查看 |
-| `bindings` | Array | 是 | 当前业务分组下最终确认的绑定关系列表 |
-
-### 4.5 bindings 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-| --- | --- | --- | --- |
-| `reportName` | String | 是 | 绑定发生在哪个报告上，例如 `brcbStHarm` |
-| `dataSetName` | String | 是 | 绑定发生在哪个数据集上，例如 `dsStHarm` |
-| `label` | String | 是 | 业务标签，例如 `A相`、`最大值`、`实时数据` |
-| `lnInst` | String | 是 | 标签最终绑定到的逻辑节点实例值，例如 `1`、`2`、`3` |
-
-## 5. 标准调试流程
-
-### 5.1 第一次调试：只获取候选结果
-
-用途：
-
- 上传 ICD 文件
- 获取 `icdDocument`
- 获取 `indexCandidates`
- 确认每个业务分组下可选的 `reportName`、`dataSetName` 和 `availableLnInstValues`
-
-调用要求：
-
- `request` Part 仍然必须传
- `request.indexSelection` 可以不传，或传空数组
-
-预期结果：
-
- `status = NEED_INDEX_SELECTION`
- 响应中返回 `icdDocument`
- 响应中返回 `indexCandidates`
-
-### 5.2 第二次调试：带索引绑定生成正式结果
-
-用途：
-
- 根据第一次返回的 `indexCandidates` 组装 `request.indexSelection`
- 再次上传同一个 ICD 文件
- 生成正式 `mappingJson`
-
-调用要求：
-
- 必须继续上传 `icdFile`
- `groupKey` 必须沿用第一次返回值
- `reportName`、`dataSetName`、`lnInst` 必须与第一次返回的候选结果匹配
-
-预期结果：
-
- `status = SUCCESS`
- 响应中返回 `mappingJson`
- 当 `saveToDisk = true` 时，响应中额外返回 `savedPath`
-
-### 5.3 第二次调试但绑定不合法
-
-适用场景：
-
- `groupKey` 与候选结果不匹配
- `reportName` 或 `dataSetName` 不在候选集中
- `lnInst` 不在 `availableLnInstValues` 内
- 绑定关系缺失、不完整或结构错误
-
-预期结果：
-
- `status = NEED_INDEX_SELECTION`
- 响应中仍然返回 `icdDocument` 和 `indexCandidates`
- `problems` 返回具体问题列表，要求重新确认绑定关系
-
-## 6. 响应规范
-
-### 6.1 正常业务响应体
-
-接口正常进入业务编排后，统一返回 `MappingTaskResponse`。该对象使用了 `@JsonInclude(JsonInclude.Include.NON_EMPTY)`，空字段和空集合不会参与序列化。
-
-基础字段说明：
-
-| 字段 | 类型 | 说明 |
-| --- | --- | --- |
-| `status` | Enum | 本次处理状态，可能为 `SUCCESS`、`NEED_INDEX_SELECTION`、`FAILED` |
-| `message` | String | 状态说明或错误提示 |
-| `icdDocument` | Object | 需要重新选择索引时返回的 ICD 解析结果 |
-| `mappingJson` | String | 正式生成成功后的映射 JSON 文本 |
-| `savedPath` | String | 结果已落盘时返回的绝对路径 |
-| `indexCandidates` | Array | 待绑定状态下返回的索引候选分组 |
-| `problems` | Array | 模板校验、候选分析或绑定校验问题 |
-
-字段出现规则：
-
-| 状态 | 必有字段 | 可能出现字段 |
-| --- | --- | --- |
-| `SUCCESS` | `status`、`message`、`mappingJson` | `savedPath`、`problems` |
-| `NEED_INDEX_SELECTION` | `status`、`message`、`icdDocument`、`indexCandidates` | `problems` |
-| `FAILED` | `status`、`message` | `problems` |
-
-### 6.2 NEED_INDEX_SELECTION 响应示例
-
-```json
-{
-  "status": "NEED_INDEX_SELECTION",
-  "message": "索引配置缺失，请根据候选信息完成标签与数字索引的绑定后重新提交",
-  "icdDocument": {
-    "fileName": "demo.icd",
-    "iedName": "IED1",
-    "ldInst": "LD0",
-    "ldPrefix": "LD",
-    "logicalNodes": [
-      {
-        "lnInst": "1"
-      }
-    ]
-  },
-  "indexCandidates": [
-    {
-      "groupKey": "harm",
-      "groupDesc": "谐波数据",
-      "reportCount": 1,
-      "templateLabels": [
-        "A相",
-        "B相",
-        "C相"
-      ],
-      "reports": [
-        {
-          "reportName": "brcbStHarm",
-          "dataSetName": "dsStHarm",
-          "reportDesc": "谐波报告",
-          "availableLnInstValues": [
-            "1",
-            "2",
-            "3"
-          ]
-        }
-      ]
-    }
-  ]
-}
-```
-
-说明：
-
- `icdDocument` 实际字段可能比示例更多。
- 如果本次是“索引配置不合法”而不是“索引配置缺失”，通常还会返回 `problems`。
-
-### 6.3 SUCCESS 响应示例
-
-```json
-{
-  "status": "SUCCESS",
-  "message": "映射生成成功",
-  "mappingJson": "{\n  \"version\": \"2026-04-22\",\n  \"author\": \"debug-user\",\n  \"ied\": \"IED1\",\n  \"ld\": \"LD\",\n  \"instList\": []\n}"
-}
-```
-
-说明：
-
- `mappingJson` 是字符串字段，字段值本身是一段 JSON 文本。
- 当 `saveToDisk = true` 时，响应中还会额外返回 `savedPath`。
-
-### 6.4 FAILED 响应示例
-
-```json
-{
-  "status": "FAILED",
-  "message": "映射生成失败：加载 DefaultCfg.txt 失败：默认模板文件不存在：template/DefaultCfg.txt",
-  "problems": [
-    "加载 DefaultCfg.txt 失败：默认模板文件不存在：template/DefaultCfg.txt"
-  ]
-}
-```
-
-说明：
-
- `FAILED` 主要对应服务编排阶段捕获到的运行异常，例如 ICD 解析、模板加载、映射生成、序列化或落盘失败。
- 并非所有错误都会进入 `FAILED`。如果异常发生在控制器参数绑定或请求转换阶段，会走全局异常处理器，而不是这里的业务响应结构。
-
-## 7. 全局异常响应说明
-
-以下场景通常不会返回 `MappingTaskResponse`，而是由 `GlobalBusinessExceptionHandler` 统一包装：
-
- `icdFile` 缺失或为空
- `request` Part 缺失
- `request` Part 的 `Content-Type` 不是 `application/json`
- `multipart/form-data` 结构不合法
- JSON 反序列化失败或框架参数绑定失败
-
-这类异常最终会包装为统一的 `HttpResult<String>` 响应，具体字段结构以全局公共响应定义为准，本文不展开其完整协议，只强调：
-
- 不能把这类错误等同理解为 `MappingTaskResponse.status = FAILED`
- 联调时应先区分“业务响应体”与“全局异常包装”
-
-## 8. 调试示例
-
-### 8.1 curl 示例：第一次调用，只获取候选结果
-
-```powershell
-curl.exe -X POST "http://localhost:8080/api/mms-mapping/get-icd-mms-json" `
-  -H "Accept: application/json" `
-  -F 'icdFile=@D:/data/demo.icd' `
-  -F 'request={"prettyJson":true,"saveToDisk":false};type=application/json'
-```
-
-### 8.2 curl 示例：第二次调用，带索引绑定直接生成 MMS JSON
-
-```powershell
-curl.exe -X POST "http://localhost:8080/api/mms-mapping/get-icd-mms-json" `
-  -H "Accept: application/json" `
-  -F 'icdFile=@D:/data/demo.icd' `
-  -F 'request={"version":"2026-04-22","author":"debug-user","prettyJson":true,"saveToDisk":false,"indexSelection":[{"groupKey":"harm","groupDesc":"谐波数据","bindings":[{"reportName":"brcbStHarm","dataSetName":"dsStHarm","label":"A相","lnInst":"1"},{"reportName":"brcbStHarm","dataSetName":"dsStHarm","label":"B相","lnInst":"2"},{"reportName":"brcbStHarm","dataSetName":"dsStHarm","label":"C相","lnInst":"3"}]}]};type=application/json'
-```
-
-## 9. Postman 调试要点
-
-1. `Body` 选择 `form-data`
-2. `icdFile` 类型选择 `File`
-3. `request` 保持文本输入，但该 Part 的 `Content-Type` 必须显式设置为 `application/json`
-4. 第一次调试不要省略 `request` Part，只是不传 `indexSelection`
-5. 第二次调试时必须继续上传 ICD 文件，并严格按第一次返回的候选结果组装绑定关系
-
-## 10. 常见问题
-
-### 10.1 为什么第一次调试也必须传 `request`
-
-因为控制器方法签名使用的是 `@RequestPart("request") GenerateMappingFromIcdRequest request`，该 Part 本身就是必填参数。第一次调试可以只传最小 JSON，但不能完全省略。
-
-### 10.2 为什么没有传 `indexSelection`，却没有返回 `FAILED`
-
-这是接口设计的正常行为。`indexSelection` 缺失或为空时，业务语义不是“接口执行失败”，而是“还需要前端继续确认索引绑定”，因此返回的是 `NEED_INDEX_SELECTION`。
-
-### 10.3 `saveToDisk=true` 但没有传 `outputDir`，结果会保存到哪里
-
-处理顺序如下：
-
-1. 先读取请求中的 `outputDir`
-2. 如果请求空白，则回退到配置项 `icd.mapping.default-output-dir`
-3. 如果配置项也为空，则最终落到当前工作目录
-
-### 10.4 `version` 不传时会变成什么
-
-后端在正式生成映射文档时，会把空白 `version` 自动补成当天日期，格式为 `yyyy-MM-dd`。
-
-### 10.5 `mappingJson` 为什么是字符串，不是嵌套对象
-
-因为当前响应结构中 `mappingJson` 定义为 `String`，接口返回的是一段已经序列化好的 JSON 文本，而不是再次展开后的对象结构。
-
-### 10.6 什么情况下会返回 `problems`
-
-`problems` 主要用于承载以下问题：
-
- 默认模板校验问题
- 索引候选分析问题
- `indexSelection` 绑定校验问题
- 服务编排阶段捕获到的异常原因
-
-## 11. 当前边界
-
- 当前文档仅覆盖 `getIcdMmsJson` 接口，不覆盖 `get-icd` 与 `get-mms-json` 的独立接口文档
- 当前文档重点描述业务返回体与调试方式，不展开全局 `HttpResult` 的完整协议
- 示例中的 `icdDocument`、`indexCandidates` 和 `mappingJson` 为结构化示意，实际字段数量与内容以运行结果为准