docs(mms-mapping): 移除过时的 API 调试文档并优化代码注释

- 删除了过时的 getIcdMmsJson 标准 API 调试文档
- 为 GenerateMappingFromIcdRequest 类添加 Swagger 注解和 API 模型描述
- 更新 IndexBindingRequest、IndexCandidateReportItemResponse、IndexCandidateResponse
  和 IndexSelectionGroupRequest 类的注释和 Swagger 注解
- 为 IcdToXmlResponse 类添加完整的 Swagger 注解和 getter/setter 方法
- 在 MappingController 中添加新的 API 接口注释和参数说明
- 为 JsonToXmlRequest 类添加 API 模型注解和参数说明
- 在调试工具中增加 indexCandidates JSON 输出功能便于复制使用

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/controller/MappingController.java

@@ -2,26 +2,36 @@ package com.njcn.gather.icd.mapping.controller;
 
 import com.njcn.common.pojo.annotation.OperateInfo;
 import com.njcn.common.pojo.enums.common.LogEnum;
+import com.njcn.common.pojo.enums.response.CommonResponseEnum;
+import com.njcn.common.pojo.response.HttpResult;
 import com.njcn.common.utils.LogUtil;
 import com.njcn.gather.icd.mapping.component.IcdToXmlRequestConverter;
 import com.njcn.gather.icd.mapping.component.IcdToXmlResponseConverter;
+import com.njcn.gather.icd.mapping.component.IndexSelectionBuildService;
 import com.njcn.gather.icd.mapping.component.MappingRequestConverter;
 import com.njcn.gather.icd.mapping.component.MappingResponseConverter;
 import com.njcn.gather.icd.mapping.pojo.bo.GenerateMappingResult;
 import com.njcn.gather.icd.mapping.pojo.bo.IcdToXmlGenerateResult;
 import com.njcn.gather.icd.mapping.pojo.dto.GenerateFromIcdCommand;
 import com.njcn.gather.icd.mapping.pojo.dto.IcdToXmlGenerateCommand;
+import com.njcn.gather.icd.mapping.pojo.param.BuildIndexSelectionRequest;
 import com.njcn.gather.icd.mapping.pojo.param.GenerateMappingFromIcdRequest;
 import com.njcn.gather.icd.mapping.pojo.param.IcdToXmlGenerateRequest;
+import com.njcn.gather.icd.mapping.pojo.param.IndexCandidateRequest;
 import com.njcn.gather.icd.mapping.pojo.param.JsonToXmlRequest;
 import com.njcn.gather.icd.mapping.pojo.param.SubmitIndexSelectionRequest;
 import com.njcn.gather.icd.mapping.pojo.vo.IcdToXmlResponse;
+import com.njcn.gather.icd.mapping.pojo.vo.IndexConfirmGroupResponse;
+import com.njcn.gather.icd.mapping.pojo.vo.IndexSelectionGroupResponse;
 import com.njcn.gather.icd.mapping.pojo.vo.MappingTaskResponse;
 import com.njcn.gather.icd.mapping.service.MappingTaskService;
 import com.njcn.gather.icd.mapping.service.impl.IcdToXmlTaskAppService;
 import com.njcn.gather.icd.mapping.utils.DateUtils;
 import com.njcn.web.controller.BaseController;
+import com.njcn.web.utils.HttpResultUtil;
 import io.swagger.annotations.Api;
+import io.swagger.annotations.ApiImplicitParam;
+import io.swagger.annotations.ApiImplicitParams;
 import io.swagger.annotations.ApiOperation;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
@@ -33,6 +43,8 @@ import org.springframework.web.bind.annotation.RequestPart;
 import org.springframework.web.bind.annotation.RestController;
 import org.springframework.web.multipart.MultipartFile;
 
+import java.util.List;
+
 /**
  * ICD 映射接口入口。
  */
@@ -61,11 +73,15 @@ public class MappingController extends BaseController {
     /** 响应转换器，按接口阶段裁剪最小返回字段。 */
     private final IcdToXmlTaskAppService  icdToXmlTaskAppService;
 
+    /** ICD 结构确认弹窗结果组装服务。 */
+    private final IndexSelectionBuildService indexSelectionBuildService;
+
     /**
      * 上传 ICD 文件，返回候选结果和可编辑的 ICD 解析结果。
      */
     @OperateInfo(info = LogEnum.BUSINESS_COMMON)
     @ApiOperation("上传 ICD 文件并生成索引候选")
+    @ApiImplicitParam(name = "icdFile", value = "ICD 文件", required = true, dataType = "__file", paramType = "form")
     @PostMapping(value = "/get-icd", consumes = {"multipart/form-data"})
     public MappingTaskResponse getICD(@RequestPart("icdFile") MultipartFile icdFile) {
         String methodDescribe = getMethodDescribe("getICD");
@@ -80,6 +96,7 @@ public class MappingController extends BaseController {
      */
     @OperateInfo(info = LogEnum.BUSINESS_COMMON)
     @ApiOperation("获取 MMS JSON")
+    @ApiImplicitParam(name = "request", value = "索引确认后生成 MMS JSON 参数", required = true, dataType = "SubmitIndexSelectionRequest")
     @PostMapping("/get-mms-json")
     public MappingTaskResponse getMmsJson(@Validated @RequestBody SubmitIndexSelectionRequest request) {
         String methodDescribe = getMethodDescribe("getMmsJson");
@@ -95,6 +112,10 @@ public class MappingController extends BaseController {
      */
     @OperateInfo(info = LogEnum.BUSINESS_COMMON)
     @ApiOperation("上传 ICD 后直接获取 MMS JSON")
+    @ApiImplicitParams({
+            @ApiImplicitParam(name = "icdFile", value = "ICD 文件", required = true, dataType = "__file", paramType = "form"),
+            @ApiImplicitParam(name = "request", value = "上传 ICD 后直接生成映射参数", required = true, dataType = "GenerateMappingFromIcdRequest", paramType = "form")
+    })
     @PostMapping(value = "/get-icd-mms-json", consumes = {"multipart/form-data"})
     public MappingTaskResponse getIcdMmsJson(@RequestPart("icdFile") MultipartFile icdFile,
                                              @Validated @RequestPart("request") GenerateMappingFromIcdRequest request) {
@@ -107,12 +128,45 @@ public class MappingController extends BaseController {
         return responseConverter.fromSubmitResult(result);
     }
 
+    /**
+     * 根据页面回传的 indexCandidates 生成弹窗确认模型。
+     */
+    @OperateInfo(info = LogEnum.BUSINESS_COMMON)
+    @ApiOperation("根据 indexCandidates 生成确认数据")
+    @ApiImplicitParam(name = "indexCandidates", value = "索引候选分组列表", required = true, dataType = "List")
+    @PostMapping("/build-index-confirm-data")
+    public HttpResult<List<IndexConfirmGroupResponse>> buildIndexConfirmData(@RequestBody List<IndexCandidateRequest> indexCandidates) {
+        String methodDescribe = getMethodDescribe("buildIndexConfirmData");
+        LogUtil.njcnDebug(log, "{}，开始根据 indexCandidates 生成确认数据，candidateCount={}",
+                methodDescribe, indexCandidates == null ? 0 : indexCandidates.size());
+        List<IndexConfirmGroupResponse> result = indexSelectionBuildService.buildConfirmData(indexCandidates);
+        return HttpResultUtil.assembleCommonResponseResult(CommonResponseEnum.SUCCESS, result, methodDescribe);
+    }
+
+    /**
+     * 根据前端确认后的结果生成最终 indexSelection。
+     */
+    @OperateInfo(info = LogEnum.BUSINESS_COMMON)
+    @ApiOperation("根据确认结果生成 indexSelection")
+    @ApiImplicitParam(name = "request", value = "根据确认结果生成 indexSelection 参数", required = true, dataType = "BuildIndexSelectionRequest")
+    @PostMapping("/build-index-selection")
+    public HttpResult<List<IndexSelectionGroupResponse>> buildIndexSelection(@RequestBody BuildIndexSelectionRequest request) {
+        String methodDescribe = getMethodDescribe("buildIndexSelection");
+        LogUtil.njcnDebug(log, "{}，开始根据确认结果生成 indexSelection，confirmGroupCount={}, confirmedGroupCount={}",
+                methodDescribe,
+                request == null || request.getConfirmData() == null ? 0 : request.getConfirmData().size(),
+                request == null || request.getConfirmedData() == null ? 0 : request.getConfirmedData().size());
+        List<IndexSelectionGroupResponse> result = indexSelectionBuildService.buildIndexSelection(request);
+        return HttpResultUtil.assembleCommonResponseResult(CommonResponseEnum.SUCCESS, result, methodDescribe);
+    }
+
     /**
      * 直接将 MMS JSON 转换为 XML 文件。
      * 适用于已经通过 getIcdMmsJson 获得 JSON 后，单独进行 XML 转换的场景。
      */
     @OperateInfo(info = LogEnum.BUSINESS_COMMON)
     @ApiOperation("MMS JSON 转 XML")
+    @ApiImplicitParam(name = "request", value = "MMS JSON 转 XML 参数", required = true, dataType = "JsonToXmlRequest")
     @PostMapping("/get-xml-from-json")
     public IcdToXmlResponse getXmlFromJson(@Validated @RequestPart("request") JsonToXmlRequest request) {
         String methodDescribe = getMethodDescribe("getXmlFromJson");

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/GenerateMappingFromIcdRequest.java

@@ -1,38 +1,43 @@
 package com.njcn.gather.icd.mapping.pojo.param;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
+
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * 候选接口请求体。
- *
- * 当前主要承载输出版本、作者、落盘选项等基础参数。
- * 为兼容旧调用，仍保留 indexSelection 字段，但候选接口本身不依赖该字段。
+ * 上传 ICD 后直接生成映射的请求参数。
  */
 @Data
+@ApiModel("上传 ICD 后直接生成映射的请求参数")
 public class GenerateMappingFromIcdRequest {
 
-    /** 输出版本号。为空时后端默认补当天日期。 */
+    /** 映射版本号。 */
+    @ApiModelProperty("映射版本号，空时默认使用当天日期")
     private String version;
 
-    /** 作者。为空时使用模块默认作者。 */
+    /** 映射作者。 */
+    @ApiModelProperty("映射作者，空时使用模块默认作者")
     private String author;
 
-    /** 是否保存到磁盘。 */
+    /** 是否落盘。 */
+    @ApiModelProperty("是否将生成结果落盘保存")
     private boolean saveToDisk;
 
-    /** 是否返回格式化 JSON。 */
+    /** 是否格式化 JSON。 */
+    @ApiModelProperty("是否返回格式化后的 JSON")
     private boolean prettyJson;
 
-    /** 输出目录。saveToDisk=true 时才会用到。 */
+    /** 输出目录。 */
+    @ApiModelProperty("输出目录，仅在 saveToDisk=true 时生效")
     private String outputDir;
 
     /**
-     * 兼容保留的索引选择结果。
-     *
-     * 当前候选接口会直接返回 indexCandidates 和 icdDocument；
-     * 正式提交时请改用 get-mms-json 接口。
+     * 兼容保留的索引绑定结果。
+     * 正式提交流程建议改用 get-mms-json 接口。
      */
+    @ApiModelProperty("兼容保留的索引绑定结果，正式提交建议改用 get-mms-json 接口")
     private List<IndexSelectionGroupRequest> indexSelection = new ArrayList<IndexSelectionGroupRequest>();
-}
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/IndexBindingRequest.java

@@ -1,24 +1,29 @@
 package com.njcn.gather.icd.mapping.pojo.param;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
+
 /**
- * 单条索引绑定请求。
- *
- * 一条绑定只表达一个最小关系：
- * 某个报告 reportName 下，使用某个标签 label 与某个 lnInst 数字做绑定。
+ * 单条索引绑定请求项。
  */
 @Data
+@ApiModel("单条索引绑定请求项")
 public class IndexBindingRequest {
 
-    /** 绑定发生在哪个报告上，例如 brcbStHarm。 */
+    /** 报告名称。 */
+    @ApiModelProperty("报告名称")
     private String reportName;
 
-    /** 绑定发生在哪个数据集上，例如 dsStHarm。 */
+    /** 数据集名称。 */
+    @ApiModelProperty("数据集名称")
     private String dataSetName;
 
-    /** 业务标签，例如最大值、最小值、实时数据。 */
+    /** 模板标签。 */
+    @ApiModelProperty("模板标签")
     private String label;
 
-    /** 当前标签最终绑定到的 lnInst 数字，例如 1、2、3。 */
+    /** 最终绑定的 lnInst 值。 */
+    @ApiModelProperty("最终绑定的 lnInst 值")
     private String lnInst;
-}
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/IndexSelectionGroupRequest.java

@@ -1,28 +1,28 @@
 package com.njcn.gather.icd.mapping.pojo.param;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
+
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * 单个业务分组的索引选择请求。
- *
- * 用于回传某个业务分组下，前端最终确认的多条绑定关系。
+ * 单个业务分组的索引选择请求参数。
  */
 @Data
+@ApiModel("单个业务分组的索引选择请求参数")
 public class IndexSelectionGroupRequest {
 
-    /**
-     * 分组唯一键。
-     *
-     * 该值由后端在 NEED_INDEX_SELECTION 场景返回，前端应原样回传，
-     * 避免仅依赖中文描述做匹配。
-     */
+    /** 分组唯一键。 */
+    @ApiModelProperty("分组唯一键，需原样回传后端返回值")
     private String groupKey;
 
-    /** 分组中文描述，例如“实时数据”“统计数据”。 */
+    /** 分组中文描述。 */
+    @ApiModelProperty("分组中文描述")
     private String groupDesc;
 
-    /** 当前业务分组下，用户最终确认的绑定关系。 */
+    /** 当前分组最终确认的绑定关系。 */
+    @ApiModelProperty("当前分组最终确认的绑定关系")
     private List<IndexBindingRequest> bindings = new ArrayList<IndexBindingRequest>();
-}
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/JsonToXmlRequest.java

@@ -1,25 +1,18 @@
 package com.njcn.gather.icd.mapping.pojo.param;
-import java.util.ArrayList;
-import java.util.List;
+
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 
 /**
- * JSON 转 XML 请求参数。
+ * MMS JSON 转 XML 的请求参数。
  */
+@ApiModel("MMS JSON 转 XML 的请求参数")
 public class JsonToXmlRequest {
 
-    /**
-     * MMS 映射 JSON 字符串。
-     * 由 getIcdMmsJson 接口返回的 mappingJson 字段提供。
-     */
+    /** MMS 映射 JSON 字符串。 */
+    @ApiModelProperty(value = "MMS 映射 JSON 字符串", required = true)
     private String mappingJson;
 
-    /**
-     * 索引选择结果（用于重建索引映射配置）。
-     * 如果提供了 indexSelection，则会重新构建索引映射；
-     * 如果为空，则使用默认的索引映射配置。
-     */
-
-
     public String getMappingJson() {
         return mappingJson;
     }
@@ -27,6 +20,4 @@ public class JsonToXmlRequest {
     public void setMappingJson(String mappingJson) {
         this.mappingJson = mappingJson;
     }
-
-
 }

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/param/SubmitIndexSelectionRequest.java

@@ -1,37 +1,45 @@
 package com.njcn.gather.icd.mapping.pojo.param;
 
-import lombok.Data;
 import com.njcn.gather.icd.mapping.pojo.bo.icd.IcdDocument;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
 
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * 提交索引绑定并生成映射的请求体。
- *
- * 第二个接口不再重复上传 ICD 文件，而是直接接收前端确认或修改后的 ICD 解析结果。
+ * 提交索引绑定并生成 MMS JSON 的请求参数。
  */
 @Data
+@ApiModel("提交索引绑定并生成 MMS JSON 的请求参数")
 public class SubmitIndexSelectionRequest {
 
-    /** 前端基于候选接口返回值确认或修改后的 ICD 解析结果。 */
+    /** ICD 解析结果。 */
+    @ApiModelProperty("ICD 解析结果，通常来自候选接口返回")
     private IcdDocument icdDocument;
 
-    /** 输出版本号。为空时后端默认补当天日期。 */
+    /** 映射版本号。 */
+    @ApiModelProperty("映射版本号，空时默认使用当天日期")
     private String version;
 
-    /** 作者。为空时使用模块默认作者。 */
+    /** 映射作者。 */
+    @ApiModelProperty("映射作者，空时使用模块默认作者")
     private String author;
 
-    /** 是否保存到磁盘。 */
+    /** 是否落盘。 */
+    @ApiModelProperty("是否将生成结果落盘保存")
     private boolean saveToDisk;
 
-    /** 是否返回格式化 JSON。 */
+    /** 是否格式化 JSON。 */
+    @ApiModelProperty("是否返回格式化后的 JSON")
     private boolean prettyJson;
 
-    /** 输出目录。saveToDisk=true 时才会用到。 */
+    /** 输出目录。 */
+    @ApiModelProperty("输出目录，仅在 saveToDisk=true 时生效")
     private String outputDir;
 
     /** 用户最终确认的索引绑定关系。 */
+    @ApiModelProperty("用户最终确认的索引绑定关系")
     private List<IndexSelectionGroupRequest> indexSelection = new ArrayList<IndexSelectionGroupRequest>();
-}
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/IcdToXmlResponse.java

@@ -1,36 +1,103 @@
 package com.njcn.gather.icd.mapping.pojo.vo;
 
-
 import com.njcn.gather.icd.mapping.pojo.enums.GenerateStatus;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 
 import java.util.ArrayList;
 import java.util.List;
 
-// 手动写getter/setter，避免Lombok依赖问题
+/**
+ * MMS JSON 转 XML 的响应。
+ */
+@ApiModel("MMS JSON 转 XML 的响应")
 public class IcdToXmlResponse {
-    private GenerateStatus status;
-    private String message;
-    private String iedName;
-    private String ldInst;
-    private String savedPath;
-    private MappingDocumentResponse mappingDocument;
-    private List<IndexCandidateResponse> indexCandidates = new ArrayList<IndexCandidateResponse>();
-    private List<String> problems = new ArrayList<String>();
-    public GenerateStatus getStatus() { return status; }
-    public void setStatus(GenerateStatus status) { this.status = status; }
-    public String getMessage() { return message; }
-    public void setMessage(String message) { this.message = message; }
-    public String getIedName() { return iedName; }
-    public void setIedName(String iedName) { this.iedName = iedName; }
-    public String getLdInst() { return ldInst; }
-    public void setLdInst(String ldInst) { this.ldInst = ldInst; }
 
-    public String getSavedPath() { return savedPath; }
-    public void setSavedPath(String savedPath) { this.savedPath = savedPath; }
-    public MappingDocumentResponse getMappingDocument() { return mappingDocument; }
-    public void setMappingDocument(MappingDocumentResponse mappingDocument) { this.mappingDocument = mappingDocument; }
-    public List<IndexCandidateResponse> getIndexCandidates() { return indexCandidates; }
-    public void setIndexCandidates(List<IndexCandidateResponse> indexCandidates) { this.indexCandidates = indexCandidates; }
-    public List<String> getProblems() { return problems; }
-    public void setProblems(List<String> problems) { this.problems = problems; }
-}
+    @ApiModelProperty("本次接口处理状态")
+    private GenerateStatus status;
+
+    @ApiModelProperty("状态说明或错误提示")
+    private String message;
+
+    @ApiModelProperty("IED 名称")
+    private String iedName;
+
+    @ApiModelProperty("逻辑设备实例名")
+    private String ldInst;
+
+    @ApiModelProperty("落盘后的绝对路径")
+    private String savedPath;
+
+    @ApiModelProperty("生成后的映射文档摘要")
+    private MappingDocumentResponse mappingDocument;
+
+    @ApiModelProperty("索引候选分组，存在待确认场景时返回")
+    private List<IndexCandidateResponse> indexCandidates = new ArrayList<IndexCandidateResponse>();
+
+    @ApiModelProperty("处理过程中发现的问题列表")
+    private List<String> problems = new ArrayList<String>();
+
+    public GenerateStatus getStatus() {
+        return status;
+    }
+
+    public void setStatus(GenerateStatus status) {
+        this.status = status;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    public String getIedName() {
+        return iedName;
+    }
+
+    public void setIedName(String iedName) {
+        this.iedName = iedName;
+    }
+
+    public String getLdInst() {
+        return ldInst;
+    }
+
+    public void setLdInst(String ldInst) {
+        this.ldInst = ldInst;
+    }
+
+    public String getSavedPath() {
+        return savedPath;
+    }
+
+    public void setSavedPath(String savedPath) {
+        this.savedPath = savedPath;
+    }
+
+    public MappingDocumentResponse getMappingDocument() {
+        return mappingDocument;
+    }
+
+    public void setMappingDocument(MappingDocumentResponse mappingDocument) {
+        this.mappingDocument = mappingDocument;
+    }
+
+    public List<IndexCandidateResponse> getIndexCandidates() {
+        return indexCandidates;
+    }
+
+    public void setIndexCandidates(List<IndexCandidateResponse> indexCandidates) {
+        this.indexCandidates = indexCandidates;
+    }
+
+    public List<String> getProblems() {
+        return problems;
+    }
+
+    public void setProblems(List<String> problems) {
+        this.problems = problems;
+    }
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/IndexCandidateReportItemResponse.java

@@ -1,27 +1,34 @@
 package com.njcn.gather.icd.mapping.pojo.vo;
 
-import lombok.Data;
 import com.fasterxml.jackson.annotation.JsonInclude;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
 
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * 业务分组下的单个报告候选响应。
+ * 索引候选中的单个报告响应项。
  */
-@JsonInclude(JsonInclude.Include.NON_EMPTY)
 @Data
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@ApiModel("索引候选中的单个报告响应项")
 public class IndexCandidateReportItemResponse {
 
     /** 报告名称。 */
+    @ApiModelProperty("报告名称")
     private String reportName;
 
     /** 数据集名称。 */
+    @ApiModelProperty("数据集名称")
     private String dataSetName;
 
     /** 报告描述。 */
+    @ApiModelProperty("报告描述")
     private String reportDesc;
 
-    /** 当前报告可选的 `lnInst` 数值。 */
+    /** 当前报告可选的 lnInst 值列表。 */
+    @ApiModelProperty("当前报告可选的 lnInst 值列表")
     private List<String> availableLnInstValues = new ArrayList<String>();
-}
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/IndexCandidateResponse.java

@@ -1,33 +1,38 @@
 package com.njcn.gather.icd.mapping.pojo.vo;
 
-import lombok.Data;
 import com.fasterxml.jackson.annotation.JsonInclude;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
 
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * 索引候选响应对象。
- *
- * 一个候选对应一个业务分组，分组下可包含多个报告，
- * 前端据此完成模板标签与 `lnInst` 的人工绑定。
+ * 索引候选分组响应。
  */
-@JsonInclude(JsonInclude.Include.NON_EMPTY)
 @Data
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@ApiModel("索引候选分组响应")
 public class IndexCandidateResponse {
 
     /** 分组唯一键。 */
+    @ApiModelProperty("分组唯一键")
     private String groupKey;
 
     /** 分组中文描述。 */
+    @ApiModelProperty("分组中文描述")
     private String groupDesc;
 
-    /** 当前分组包含的报告数。 */
+    /** 当前分组包含的报告数量。 */
+    @ApiModelProperty("当前分组包含的报告数量")
     private int reportCount;
 
-    /** 模板里配置的可选标签。 */
+    /** 模板中配置的可选标签。 */
+    @ApiModelProperty("模板中配置的可选标签")
     private List<String> templateLabels = new ArrayList<String>();
 
     /** 当前分组下的报告候选列表。 */
+    @ApiModelProperty("当前分组下的报告候选列表")
     private List<IndexCandidateReportItemResponse> reports = new ArrayList<IndexCandidateReportItemResponse>();
-}
+}

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/MappingDocumentResponse.java

@@ -1,28 +1,37 @@
 package com.njcn.gather.icd.mapping.pojo.vo;
 
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
 import lombok.Data;
+
 /**
  * 映射文档摘要响应。
- *
- * 用于返回最终映射结果中的关键信息摘要。
  */
 @Data
+@ApiModel("映射文档摘要响应")
 public class MappingDocumentResponse {
+
     /** 映射文档版本。 */
+    @ApiModelProperty("映射文档版本")
     private String version;
 
     /** 映射文档作者。 */
+    @ApiModelProperty("映射文档作者")
     private String author;
 
     /** 输出 JSON 中的 IED。 */
+    @ApiModelProperty("输出 JSON 中的 IED")
     private String ied;
 
     /** 输出 JSON 中的 LD。 */
+    @ApiModelProperty("输出 JSON 中的 LD")
     private String ld;
 
     /** ReportMap 条目数量。 */
+    @ApiModelProperty("ReportMap 条目数量")
     private int reportCount;
 
     /** DataSetList 分组数量。 */
+    @ApiModelProperty("DataSetList 分组数量")
     private int dataSetCount;
 }

tools/mms-mapping/src/main/java/com/njcn/gather/icd/mapping/pojo/vo/MappingTaskResponse.java

@@ -1,39 +1,48 @@
 package com.njcn.gather.icd.mapping.pojo.vo;
 
-import lombok.Data;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.njcn.gather.icd.mapping.pojo.bo.icd.IcdDocument;
 import com.njcn.gather.icd.mapping.pojo.enums.GenerateStatus;
+import io.swagger.annotations.ApiModel;
+import io.swagger.annotations.ApiModelProperty;
+import lombok.Data;
 
 import java.util.ArrayList;
 import java.util.List;
 
 /**
- * ICD 映射接口统一响应。
- *
- * 按接口阶段仅返回当前场景必需字段；空字段和空集合不参与序列化。
+ * ICD 映射统一响应。
  */
-@JsonInclude(JsonInclude.Include.NON_EMPTY)
 @Data
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@ApiModel("ICD 映射统一响应")
 public class MappingTaskResponse {
+
     /** 本次接口处理状态。 */
+    @ApiModelProperty("本次接口处理状态")
     private GenerateStatus status;
 
     /** 状态说明或错误提示。 */
+    @ApiModelProperty("状态说明或错误提示")
     private String message;
 
-    /** 候选接口或需要重新选择索引时返回的 ICD 解析结果。 */
+    /** ICD 解析结果。 */
+    @ApiModelProperty("ICD 解析结果，在需要确认索引时返回")
     private IcdDocument icdDocument;
 
     /** 正式生成成功后的完整映射 JSON。 */
+    @ApiModelProperty("正式生成成功后的完整映射 JSON")
     private String mappingJson;
 
-    /** 生成文件落盘后的绝对路径。 */
+    /** 落盘后的绝对路径。 */
+    @ApiModelProperty("落盘后的绝对路径")
     private String savedPath;
 
     /** 待绑定状态下返回的索引候选分组。 */
+    @ApiModelProperty("待绑定状态下返回的索引候选分组")
     private List<IndexCandidateResponse> indexCandidates = new ArrayList<IndexCandidateResponse>();
 
     /** 模板校验、候选分析或绑定校验问题。 */
+    @ApiModelProperty("模板校验、候选分析或绑定校验问题")
     private List<String> problems = new ArrayList<String>();
-}
+}