增加注释

src/main/java/com/nbport/zgwl/contractpush/config/ContractPushProperties.java

@@ -19,48 +19,68 @@ public class ContractPushProperties {
     @Data
     public static class Settlement {
 
+        /** 系统标识 */
         private String systemKey;
 
+        /** 密钥（用于获取 token） */
         private String secretKey;
 
+        /** 获取 token 的 GET 接口地址 */
         private String tokenUrl;
 
+        /** 推送合同数据 POST 接口地址 */
         private String pushContractUrl;
 
+        /** 查询合同审批 POST 接口地址 */
         private String approveQueryUrl;
 
+        /** 合同归档 POST 接口地址 */
         private String archiveUrl;
 
+        /** 审批查看页面的基础 URL（单点登录拼接用） */
         private String approveViewBaseUrl;
     }
 
     @Data
     public static class DataCollection {
 
+        /** 系统标识 */
         private String systemKey;
 
+        /** 密钥（用于获取 token） */
         private String secretKey;
 
+        /** 业务系统编码（每个子系统唯一，如 ECP/DSSP） */
         private String sysCode;
 
+        /** 获取 token 的 GET 接口地址 */
         private String tokenUrl;
 
+        /** 文件上传 POST 接口地址 */
         private String uploadUrl;
 
+        /** 相对方信息采集 POST 接口地址 */
         private String collectOppositesUrl;
 
+        /** 主体信息采集 POST 接口地址 */
         private String collectZtbsUrl;
 
+        /** 合同信息采集 POST 接口地址 */
         private String collectContractUrl;
 
+        /** 履行计划反馈 POST 接口地址 */
         private String collectPlanFeedbackUrl;
 
+        /** 合同完结 POST 接口地址 */
         private String collectContractCloseUrl;
 
+        /** 合同归档 POST 接口地址 */
         private String collectContractArchiveUrl;
 
+        /** 审批信息查询 POST 接口地址 */
         private String queryApproveInfoUrl;
 
+        /** 审批查看页面的基础 URL（单点登录拼接用） */
         private String approveViewBaseUrl;
     }
 }

src/main/java/com/nbport/zgwl/contractpush/dto/ApproveQueryRequestDTO.java

@@ -12,13 +12,18 @@ public class ApproveQueryRequestDTO implements Serializable {
 
     private static final long serialVersionUID = 1L;
 
+    /** 认证凭证，不传则 Service 内部自动获取 */
     private String token;
 
+    /** 创建人手机号（用于查询该用户相关的审批） */
     private String phoneNum;
 
+    /** 结算平台合同唯一编码（用于精确查询） */
     private String contractSysId;
 
+    /** 合同编号（法务系统生成） */
     private String contractCode;
 
+    /** 合同ID（法务系统返回） */
     private String contractId;
 }

src/main/java/com/nbport/zgwl/contractpush/dto/ApproveViewUrlRequestDTO.java

@@ -12,7 +12,9 @@ public class ApproveViewUrlRequestDTO implements Serializable {
 
     private static final long serialVersionUID = 1L;
 
+    /** 合同ID（法务系统返回的 contractId） */
     private String contractId;
 
+    /** 查看人的用户标识，用于单点登录 ssoToken 参数 */
     private String ivUser;
 }

src/main/java/com/nbport/zgwl/contractpush/dto/PushPayloadDTO.java

@@ -16,7 +16,9 @@ public class PushPayloadDTO implements Serializable {
 
     private static final long serialVersionUID = 1L;
 
+    /** 认证凭证（可选，不传则 Service 内部自动获取） */
     private String token;
 
+    /** 接口报文内容（符合法务系统接口规范的实际业务 JSON 数据） */
     private Map<String, Object> payload = new LinkedHashMap<>();
 }

src/main/java/com/nbport/zgwl/contractpush/dto/PushTokenRequestDTO.java

@@ -12,7 +12,9 @@ public class PushTokenRequestDTO implements Serializable {
 
     private static final long serialVersionUID = 1L;
 
+    /** 系统标识（覆盖配置中的默认值） */
     private String systemKey;
 
+    /** 密钥（覆盖配置中的默认值） */
     private String secretKey;
 }

src/main/java/com/nbport/zgwl/contractpush/handler/ContractPushRequestHandler.java

@@ -14,10 +14,12 @@ import java.util.Map;
 @Component
 public class ContractPushRequestHandler {
 
+    /** 复制 payload 副本，避免修改原始对象 */
     public Map<String, Object> copyPayload(Map<String, Object> payload) {
         return payload == null ? new LinkedHashMap<>() : new LinkedHashMap<>(payload);
     }
 
+    /** 补全结算平台请求体：body 中加入 token */
     public Map<String, Object> prepareSettlementPayload(Map<String, Object> payload, String token) {
         Map<String, Object> requestBody = copyPayload(payload);
         if (StrUtil.isBlank(token)) {
@@ -27,6 +29,7 @@ public class ContractPushRequestHandler {
         return requestBody;
     }
 
+    /** 补全数据采集请求体：body 中加入 sys_code 和 timeStamp */
     public Map<String, Object> prepareDataCollectionPayload(Map<String, Object> payload, String sysCode) {
         Map<String, Object> requestBody = copyPayload(payload);
         if (StrUtil.isBlank(sysCode)) {
@@ -37,6 +40,7 @@ public class ContractPushRequestHandler {
         return requestBody;
     }
 
+    /** 构建数据采集请求头：cj_token 必填，systemKey 按需携带 */
     public Map<String, String> buildDataCollectionHeaders(String token, String systemKey, boolean includeSystemKey) {
         if (StrUtil.isBlank(token)) {
             throw new ServiceException("数据采集 cj_token 不能为空");

src/main/java/com/nbport/zgwl/contractpush/service/DataCollectionPushService.java

@@ -35,6 +35,7 @@ public class DataCollectionPushService {
         this.requestHandler = requestHandler;
     }
 
+    /** 获取数据采集接口调用凭证（cj_token） */
     public Map<String, Object> getToken(PushTokenRequestDTO requestDTO) {
         String systemKey = requestDTO != null && StrUtil.isNotBlank(requestDTO.getSystemKey())
                 ? requestDTO.getSystemKey()
@@ -49,6 +50,7 @@ public class DataCollectionPushService {
         return httpUtils.get(properties.getDataCollection().getTokenUrl(), query);
     }
 
+    /** 上传文件到法务系统（如合同附件、签订依据等） */
     public Map<String, Object> upload(MultipartFile file, String token) {
         Map<String, String> headers = requestHandler.buildDataCollectionHeaders(
                 resolveCollectionToken(token),
@@ -58,30 +60,37 @@ public class DataCollectionPushService {
         return httpUtils.postMultipart(properties.getDataCollection().getUploadUrl(), file, headers);
     }
 
+    /** 相对方信息采集：将相对方信息推送给法务系统 */
     public Map<String, Object> collectOpposites(PushPayloadDTO requestDTO) {
         return postCollectionJson(properties.getDataCollection().getCollectOppositesUrl(), requestDTO, false);
     }
 
+    /** 主体信息采集：将签约主体信息推送给法务系统 */
     public Map<String, Object> collectZtbs(PushPayloadDTO requestDTO) {
         return postCollectionJson(properties.getDataCollection().getCollectZtbsUrl(), requestDTO, false);
     }
 
+    /** 合同信息采集：将合同数据推送给法务系统 */
     public Map<String, Object> collectContract(PushPayloadDTO requestDTO) {
         return postCollectionJson(properties.getDataCollection().getCollectContractUrl(), requestDTO, false);
     }
 
+    /** 履行计划反馈：将合同收付款履行情况反馈给法务系统 */
     public Map<String, Object> collectPlanFeedback(PushPayloadDTO requestDTO) {
         return postCollectionJson(properties.getDataCollection().getCollectPlanFeedbackUrl(), requestDTO, false);
     }
 
+    /** 合同完结：通知法务系统合同已完结 */
     public Map<String, Object> collectContractClose(PushPayloadDTO requestDTO) {
         return postCollectionJson(properties.getDataCollection().getCollectContractCloseUrl(), requestDTO, false);
     }
 
+    /** 合同归档：签署版本文档推送给法务系统存档 */
     public Map<String, Object> collectContractArchive(PushPayloadDTO requestDTO) {
         return postCollectionJson(properties.getDataCollection().getCollectContractArchiveUrl(), requestDTO, false);
     }
 
+    /** 查询合同审批信息 */
     public Map<String, Object> queryApproveInfo(ApproveQueryRequestDTO requestDTO) {
         Map<String, Object> body = new LinkedHashMap<>();
         body.put("contractCode", requestDTO == null ? null : requestDTO.getContractCode());
@@ -100,6 +109,7 @@ public class DataCollectionPushService {
         return httpUtils.postJson(properties.getDataCollection().getQueryApproveInfoUrl(), requestBody, headers);
     }
 
+    /** 生成审批查看地址（单点登录跳转） */
     public Map<String, Object> buildApproveViewUrl(ApproveViewUrlRequestDTO requestDTO) {
         if (requestDTO == null || StrUtil.isBlank(requestDTO.getContractId()) || StrUtil.isBlank(requestDTO.getIvUser())) {
             throw new ServiceException("contractId 和 ivUser 不能为空");
@@ -116,6 +126,7 @@ public class DataCollectionPushService {
         return result;
     }
 
+    /** 通用数据采集 POST 请求（拼装 headers + body 后发起调用） */
     private Map<String, Object> postCollectionJson(String url, PushPayloadDTO requestDTO, boolean includeSystemKeyHeader) {
         String token = resolveCollectionToken(requestDTO == null ? null : requestDTO.getToken());
         Map<String, String> headers = requestHandler.buildDataCollectionHeaders(
@@ -130,6 +141,7 @@ public class DataCollectionPushService {
         return httpUtils.postJson(url, requestBody, headers);
     }
 
+    /** 获取数据采集 token，优先用入参，没有则自动调用 getToken 接口获取 */
     private String resolveCollectionToken(String inputToken) {
         if (StrUtil.isNotBlank(inputToken)) {
             return inputToken;

src/main/java/com/nbport/zgwl/contractpush/service/SettlementPushService.java

@@ -34,6 +34,7 @@ public class SettlementPushService {
         this.requestHandler = requestHandler;
     }
 
+    /** 获取结算平台调用凭证 */
     public Map<String, Object> getToken(PushTokenRequestDTO requestDTO) {
         String systemKey = requestDTO != null && StrUtil.isNotBlank(requestDTO.getSystemKey())
                 ? requestDTO.getSystemKey()
@@ -44,6 +45,7 @@ public class SettlementPushService {
         return httpUtils.get(properties.getSettlement().getTokenUrl(), query);
     }
 
+    /** 推送合同数据到结算平台 */
     public Map<String, Object> pushContract(PushPayloadDTO requestDTO) {
         String token = resolveSettlementToken(requestDTO == null ? null : requestDTO.getToken());
         Map<String, Object> body = requestHandler.prepareSettlementPayload(
@@ -53,6 +55,7 @@ public class SettlementPushService {
         return httpUtils.postJson(properties.getSettlement().getPushContractUrl(), body, null);
     }
 
+    /** 查询合同审批记录 */
     public Map<String, Object> queryApproveInfo(ApproveQueryRequestDTO requestDTO) {
         Map<String, Object> body = new LinkedHashMap<>();
         body.put("token", resolveSettlementToken(requestDTO == null ? null : requestDTO.getToken()));
@@ -61,6 +64,7 @@ public class SettlementPushService {
         return httpUtils.postJson(properties.getSettlement().getApproveQueryUrl(), body, null);
     }
 
+    /** 推送合同归档到结算平台 */
     public Map<String, Object> pushArchive(PushPayloadDTO requestDTO) {
         String token = resolveSettlementToken(requestDTO == null ? null : requestDTO.getToken());
         Map<String, Object> body = requestHandler.prepareSettlementPayload(
@@ -70,6 +74,7 @@ public class SettlementPushService {
         return httpUtils.postJson(properties.getSettlement().getArchiveUrl(), body, null);
     }
 
+    /** 生成结算平台审批查看地址（单点登录） */
     public Map<String, Object> buildApproveViewUrl(ApproveViewUrlRequestDTO requestDTO) {
         if (requestDTO == null || StrUtil.isBlank(requestDTO.getContractId()) || StrUtil.isBlank(requestDTO.getIvUser())) {
             throw new ServiceException("contractId 和 ivUser 不能为空");
@@ -86,6 +91,7 @@ public class SettlementPushService {
         return result;
     }
 
+    /** 获取结算平台 token，优先用入参，没有则自动调用 getToken 接口获取 */
     private String resolveSettlementToken(String inputToken) {
         if (StrUtil.isNotBlank(inputToken)) {
             return inputToken;

src/main/java/com/nbport/zgwl/contractpush/utils/ContractPushHttpUtils.java

@@ -33,12 +33,14 @@ public class ContractPushHttpUtils {
         this.restTemplate = contractPushRestTemplate;
     }
 
+    /** GET 请求，queryParams 会自动拼接到 URL 上 */
     public Map<String, Object> get(String url, Map<String, String> queryParams) {
         String finalUrl = ContractPushUrlUtils.appendQuery(url, queryParams);
         ResponseEntity<String> response = restTemplate.getForEntity(finalUrl, String.class);
         return parseResponse(response.getBody());
     }
 
+    /** POST JSON 请求，可自定义请求头 */
     public Map<String, Object> postJson(String url, Map<String, Object> body, Map<String, String> headers) {
         HttpHeaders httpHeaders = new HttpHeaders();
         httpHeaders.setContentType(MediaType.APPLICATION_JSON);
@@ -48,6 +50,7 @@ public class ContractPushHttpUtils {
         return parseResponse(response.getBody());
     }
 
+    /** 上传文件（POST MULTIPART） */
     public Map<String, Object> postMultipart(String url, MultipartFile file, Map<String, String> headers) {
         if (file == null || file.isEmpty()) {
             throw new ServiceException("上传文件不能为空");
@@ -65,6 +68,7 @@ public class ContractPushHttpUtils {
         return parseResponse(response.getBody());
     }
 
+    /** 将 MultipartFile 转为 ByteArrayResource（保留原始文件名） */
     private ByteArrayResource toByteArrayResource(MultipartFile file) {
         try {
             return new ByteArrayResource(file.getBytes()) {

src/main/java/com/nbport/zgwl/contractpush/utils/ContractPushUrlUtils.java

@@ -17,6 +17,7 @@ public final class ContractPushUrlUtils {
     private ContractPushUrlUtils() {
     }
 
+    /** 在 URL 后追加查询参数（自动处理 ? 和 & 拼接，值为空不追加） */
     public static String appendQuery(String url, Map<String, String> queryParams) {
         if (queryParams == null || queryParams.isEmpty()) {
             return url;
@@ -30,6 +31,7 @@ public final class ContractPushUrlUtils {
         return url + (url.contains("?") ? "&" : "?") + joiner;
     }
 
+    /** 拼装审批查看地址（拼接 id 和 ssoToken 参数） */
     public static String buildApproveViewUrl(String baseUrl, String contractId, String ivUser) {
         if (StrUtil.isBlank(baseUrl)) {
             throw new ServiceException("审批查看地址未配置");

src/main/java/com/nbport/zgwl/manifest/domain/ContractTemplateManage.java

@@ -13,6 +13,10 @@ import java.io.Serial;
 import java.io.Serializable;
 import java.time.LocalDateTime;
 
+/**
+ * 模板管理表 实体
+ * 对应数据库表 CONTRACT_TEMPLATE_MANAGE
+ */
 @TableName(value = "CONTRACT_TEMPLATE_MANAGE")
 @Data
 @EqualsAndHashCode(callSuper = false)
@@ -25,63 +29,83 @@ public class ContractTemplateManage implements Serializable {
     @TableId(value = "ID", type = IdType.INPUT)
     private Long id;
 
+    /** 模板编号（自动生成，如 TPL-MM-20260522-128） */
     @TableField("TEMPLATE_CODE")
     private String templateCode;
 
+    /** 模板名称 */
     @TableField("TEMPLATE_NAME")
     private String templateName;
 
+    /** 范本类型 */
     @TableField("SOURCE")
     private String source;
 
+    /** 合同类型 */
     @TableField("CONTRACT_TYPE")
     private String contractType;
 
+    /** 我方地位：甲方/乙方/丙方 */
     @TableField("SELF_PARTY_ROLE")
     private String selfPartyRole;
 
+    /** 版本号 */
     @TableField("VERSION")
     private String version;
 
+    /** 状态：draft/published/disabled */
     @TableField("STATUS")
     private String status;
 
+    /** 变量数量 */
     @TableField("VARIABLE_COUNT")
     private Integer variableCount;
 
+    /** 模板描述 */
     @TableField("DESCRIPTION")
     private String description;
 
+    /** 使用提示 */
     @TableField("USAGE_TIP")
     private String usageTip;
 
+    /** 模板文件名 */
     @TableField("TEMPLATE_FILE_NAME")
     private String templateFileName;
 
+    /** 模板文件路径 */
     @TableField("TEMPLATE_FILE_PATH")
     private String templateFilePath;
 
+    /** 发布范围 orgId 集合（JSON 文本） */
     @TableField("PUBLISH_ORG_IDS_JSON")
     private String publishOrgIdsJson;
 
+    /** 发布范围 orgName 集合（JSON 文本） */
     @TableField("PUBLISH_ORG_NAMES_JSON")
     private String publishOrgNamesJson;
 
+    /** 变量映射集合（JSON 文本） */
     @TableField("VARIABLE_MAPPINGS_JSON")
     private String variableMappingsJson;
 
+    /** 创建人 */
     @TableField("CREATE_BY")
     private String createBy;
 
+    /** 创建时间 */
     @TableField("CREATED_TIME")
     private LocalDateTime createdTime;
 
+    /** 更新人 */
     @TableField("UPDATED_BY")
     private String updatedBy;
 
+    /** 更新时间 */
     @TableField("UPDATED_TIME")
     private LocalDateTime updatedTime;
 
+    /** 删除标记 */
     @TableField("DEL_FLAG")
     private String delFlag;
 }

src/main/java/com/nbport/zgwl/manifest/dto/ContractTemplateDto.java

@@ -26,6 +26,7 @@ public class ContractTemplateDto implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** 主键ID */
     private Long id;
 
     /**
@@ -33,6 +34,7 @@ public class ContractTemplateDto implements Serializable {
      */
     private String templateCode;
 
+    /** 模板名称 */
     private String templateName;
 
     /**
@@ -40,6 +42,7 @@ public class ContractTemplateDto implements Serializable {
      */
     private String source;
 
+    /** 合同类型（如 买卖合同、服务合同 等） */
     private String contractType;
 
     /**
@@ -47,6 +50,7 @@ public class ContractTemplateDto implements Serializable {
      */
     private String selfPartyRole;
 
+    /** 版本号 */
     private String version;
 
     /**
@@ -54,12 +58,16 @@ public class ContractTemplateDto implements Serializable {
      */
     private String status;
 
+    /** 变量数量（由 variableMappings 自动计算） */
     private Integer variableCount;
 
+    /** 模板描述 */
     private String description;
 
+    /** 使用提示 */
     private String usageTip;
 
+    /** 模板文件名（上传时的原始文件名） */
     private String templateFileName;
 
     /**
@@ -84,30 +92,40 @@ public class ContractTemplateDto implements Serializable {
      */
     private String publishScopeText;
 
+    /** 变量映射列表（Word 模板变量 → 业务字段的绑定关系） */
     @Builder.Default
     private List<TemplateVariableMappingDto> variableMappings = new ArrayList<>();
 
+    /** 模板中用到的变量名列表（由 variableMappings 自动提取） */
     @Builder.Default
     private List<String> variables = new ArrayList<>();
 
+    /** 创建人 */
     private String createBy;
 
+    /** 创建时间 */
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
     private LocalDateTime createdTime;
 
+    /** 更新人 */
     private String updatedBy;
 
+    /** 更新时间 */
     @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
     private LocalDateTime updatedTime;
 
+    /** 删除标记 */
     private String delFlag;
 
     /**
      * 以下两个字段只在数据库层临时承接 JSON 文本，不给页面直接使用。
      */
+    /** 发布范围 orgId 的 JSON 文本 */
     private String publishOrgIdsJson;
 
+    /** 发布范围 orgName 的 JSON 文本 */
     private String publishOrgNamesJson;
 
+    /** 变量映射的 JSON 文本 */
     private String variableMappingsJson;
 }

src/main/java/com/nbport/zgwl/manifest/dto/ContractTemplateQueryDto.java

@@ -17,11 +17,15 @@ public class ContractTemplateQueryDto extends BasePageDto implements Serializabl
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** 模板名称（模糊搜索） */
     private String templateName;
 
+    /** 合同类型 */
     private String contractType;
 
+    /** 范本类型（标准模板/推荐文本/示范文本/对方文本） */
     private String source;
 
+    /** 状态（draft/published/disabled） */
     private String status;
 }

src/main/java/com/nbport/zgwl/manifest/handler/ContractTemplateDataHandler.java

@@ -24,6 +24,7 @@ import java.util.stream.Collectors;
 @Component
 public class ContractTemplateDataHandler {
 
+    /** 保存前数据清洗（去空格、去重、自动计算变量数和发布范围文本） */
     public void normalizeBeforeSave(ContractTemplateDto template) {
         template.setTemplateName(StrUtil.trim(template.getTemplateName()));
         template.setSource(StrUtil.trim(template.getSource()));
@@ -74,6 +75,7 @@ public class ContractTemplateDataHandler {
         template.setPublishScopeText(String.join("、", template.getPublishOrgNames()));
     }
 
+    /** 保存前数据校验（必填项校验、变量映射校验） */
     public void validateForSave(ContractTemplateDto template) {
         if (StrUtil.isBlank(template.getTemplateName())) {
             throw new ServiceException("范本名称不能为空");
@@ -109,6 +111,7 @@ public class ContractTemplateDataHandler {
         }
     }
 
+    /** 查询后将 JSON 文本转成前端需要的列表结构 */
     public void fillUiFields(ContractTemplateDto template) {
         if (template == null) {
             return;
@@ -133,6 +136,7 @@ public class ContractTemplateDataHandler {
         template.setPublishScopeText(String.join("、", template.getPublishOrgNames()));
     }
 
+    /** 批量填充 UI 字段 */
     public void fillUiFields(List<ContractTemplateDto> templates) {
         if (templates == null) {
             return;
@@ -140,6 +144,7 @@ public class ContractTemplateDataHandler {
         templates.forEach(this::fillUiFields);
     }
 
+    /** 根据 id 批量填充发布范围 orgName（将 id 转为对应的组织名称） */
     public void fillOrgNamesByIds(ContractTemplateDto template, List<TemplateOrgOptionDto> orgOptions) {
         if (template.getPublishOrgIds() == null) {
             template.setPublishOrgNames(new ArrayList<>());

src/main/java/com/nbport/zgwl/manifest/mapper/ContractTemplateMapper.java

@@ -14,23 +14,31 @@ import java.util.List;
  */
 public interface ContractTemplateMapper {
 
+    /** 获取模板主表序列（Oracle 主键生成） */
     Long selectTemplateSeqNextVal();
 
+    /** 分页查询模板列表 */
     IPage<ContractTemplateDto> selectTemplatePage(Page<ContractTemplateDto> page, @Param("query") ContractTemplateQueryDto queryDto);
 
+    /** 查询已发布模板列表 */
     List<ContractTemplateDto> selectPublishedTemplates();
 
+    /** 根据主键查询模板详情 */
     ContractTemplateDto selectTemplateById(@Param("id") Long id);
 
+    /** 新增模板 */
     int insertTemplate(ContractTemplateDto template);
 
+    /** 修改模板 */
     int updateTemplate(ContractTemplateDto template);
 
+    /** 更新模板状态 */
     int updateTemplateStatus(@Param("id") Long id,
                              @Param("status") String status,
                              @Param("updateBy") String updateBy,
                              @Param("updateTime") LocalDateTime updateTime);
 
+    /** 删除模板（逻辑删除） */
     int deleteTemplateById(@Param("id") Long id,
                            @Param("updateBy") String updateBy,
                            @Param("updateTime") LocalDateTime updateTime,

src/main/java/com/nbport/zgwl/manifest/service/ContractTemplateService.java

@@ -12,17 +12,24 @@ import java.util.List;
  */
 public interface ContractTemplateService {
 
+    /** 分页查询模板列表 */
     PageResult<ContractTemplateDto> queryTemplateList(ContractTemplateQueryDto queryDto);
 
+    /** 获取已发布的模板列表（用于发起合同时选择） */
     List<ContractTemplateDto> queryPublishedTemplates();
 
+    /** 根据主键查询模板详情（含 JSON 字段的解析） */
     ContractTemplateDto getTemplateDetail(Long id);
 
+    /** 新增模板 */
     ContractTemplateDto createTemplate(ContractTemplateDto template);
 
+    /** 修改模板 */
     ContractTemplateDto updateTemplate(ContractTemplateDto template);
 
+    /** 切换模板状态 */
     ContractTemplateDto changeTemplateStatus(Long id, String status);
 
+    /** 获取发布范围组织选项 */
     List<TemplateOrgOptionDto> queryOrgOptions();
 }

src/main/java/com/nbport/zgwl/manifest/service/ContractTemplateServiceImpl.java

@@ -31,6 +31,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
 
     private final ContractTemplateDataHandler contractTemplateDataHandler;
 
+    /** 分页查询模板列表 */
     @Override
     public PageResult<ContractTemplateDto> queryTemplateList(ContractTemplateQueryDto queryDto) {
         Page<ContractTemplateDto> page = new Page<>(queryDto.getPageNo(), queryDto.getPageSize());
@@ -39,6 +40,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         return pageResult;
     }
 
+    /** 已发布的模板列表 */
     @Override
     public List<ContractTemplateDto> queryPublishedTemplates() {
         List<ContractTemplateDto> templates = contractTemplateMapper.selectPublishedTemplates();
@@ -46,6 +48,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         return templates;
     }
 
+    /** 获取模板详情（含发布范围、变量映射的解析结果） */
     @Override
     public ContractTemplateDto getTemplateDetail(Long id) {
         ContractTemplateDto template = contractTemplateMapper.selectTemplateById(id);
@@ -56,6 +59,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         return template;
     }
 
+    /** 新增模板（自动生成模板编号、保存 JSON 字段） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public ContractTemplateDto createTemplate(ContractTemplateDto template) {
@@ -77,6 +81,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         return getTemplateDetail(template.getId());
     }
 
+    /** 修改模板（保留原有的 templateCode、创建人、创建时间不变） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public ContractTemplateDto updateTemplate(ContractTemplateDto template) {
@@ -105,6 +110,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         return getTemplateDetail(template.getId());
     }
 
+    /** 切换模板状态（draft / published / disabled） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public ContractTemplateDto changeTemplateStatus(Long id, String status) {
@@ -128,6 +134,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         return getTemplateDetail(id);
     }
 
+    /** 获取发布范围组织选项（当前为假数据，内网联调时替换为真实组织接口） */
     @Override
     public List<TemplateOrgOptionDto> queryOrgOptions() {
         return List.of(
@@ -138,6 +145,7 @@ public class ContractTemplateServiceImpl implements ContractTemplateService {
         );
     }
 
+    /** 将 JSON 字段转为文本存入数据库 */
     private void saveJsonFields(ContractTemplateDto template) {
         template.setPublishOrgIdsJson(ManifestJsonUtils.toJson(template.getPublishOrgIds()));
         template.setPublishOrgNamesJson(ManifestJsonUtils.toJson(template.getPublishOrgNames()));

src/main/java/com/nbport/zgwl/manifest/utils/ManifestCodeUtils.java

@@ -47,6 +47,7 @@ public final class ManifestCodeUtils {
     private ManifestCodeUtils() {
     }
 
+    /** 生成模板编号（格式：TPL-合同类型编码-yyyyMMddHHmmss-随机3位数字） */
     public static String buildTemplateCode(String contractType) {
         String typeCode = CONTRACT_TYPE_CODE_MAP.getOrDefault(contractType, "QT");
         String now = new SimpleDateFormat("yyyyMMddHHmmss").format(new Date());

src/main/java/com/nbport/zgwl/manifest/utils/ManifestJsonUtils.java

@@ -17,6 +17,7 @@ public final class ManifestJsonUtils {
     private ManifestJsonUtils() {
     }
 
+    /** 对象转 JSON 字符串 */
     public static String toJson(Object value) {
         if (value == null) {
             return null;
@@ -24,6 +25,7 @@ public final class ManifestJsonUtils {
         return JSON.toJSONString(value);
     }
 
+    /** 解析 String List 类型的 JSON */
     public static List<String> parseStringList(String json) {
         if (json == null || json.isBlank()) {
             return Collections.emptyList();
@@ -32,6 +34,7 @@ public final class ManifestJsonUtils {
         });
     }
 
+    /** 泛型解析 JSON 为 List */
     public static <T> List<T> parseList(String json, TypeReference<List<T>> typeReference) {
         if (json == null || json.isBlank()) {
             return Collections.emptyList();

src/main/java/com/nbport/zgwl/manifest/utils/ManifestManageConstants.java

@@ -10,17 +10,24 @@ public final class ManifestManageConstants {
     private ManifestManageConstants() {
     }
 
+    /** 模板管理请求前缀 */
     public static final String REQUEST_PREFIX = "/manifest/manage";
 
+    /** 默认操作人（后续内网联调时替换为真实用户） */
     public static final String DEFAULT_OPERATOR = "local_test";
 
+    /** 未删除标记 */
     public static final String DEL_FLAG_NORMAL = "0";
 
+    /** 已删除标记 */
     public static final String DEL_FLAG_DELETED = "2";
 
+    /** 草稿状态 */
     public static final String STATUS_DRAFT = "draft";
 
+    /** 已发布状态 */
     public static final String STATUS_PUBLISHED = "published";
 
+    /** 已禁用状态 */
     public static final String STATUS_DISABLED = "disabled";
 }

src/main/java/com/nbport/zgwl/partner/controller/PartnerManageController.java

@@ -30,27 +30,32 @@ public class PartnerManageController {
 
     private final PartnerManageService partnerManageService;
 
+    /** 分页查询相对方列表 */
     @PostMapping("/list")
     public R<PageResult<PartnerManageDto>> queryList(@RequestBody PartnerQueryDto queryDto) {
         return R.success(partnerManageService.queryPartnerList(queryDto));
     }
 
+    /** 查询单个相对方详情 */
     @GetMapping("/{customerSysid}")
     public R<PartnerManageDto> getInfo(@PathVariable("customerSysid") Long customerSysid) {
         return R.success(partnerManageService.selectPartnerById(customerSysid));
     }
 
+    /** 新增相对方 */
     @PostMapping
     public R<Long> add(@RequestBody PartnerManageDto partner) {
         return R.success(partnerManageService.insertPartner(partner));
     }
 
+    /** 修改相对方 */
     @PutMapping
     public R<String> edit(@RequestBody PartnerManageDto partner) {
         partnerManageService.updatePartner(partner);
         return R.success("保存成功");
     }
 
+    /** 批量删除相对方（逗号分隔多个 ID） */
     @DeleteMapping("/{customerSysids}")
     public R<String> remove(@PathVariable("customerSysids") String customerSysids) {
         List<Long> idList = Arrays.stream(customerSysids.split(","))
@@ -61,6 +66,7 @@ public class PartnerManageController {
         return R.success("删除成功");
     }
 
+    /** 模拟同步到法务系统 */
     @PostMapping("/{customerSysid}/sync")
     public R<PartnerManageDto> mockSync(@PathVariable("customerSysid") Long customerSysid) {
         return R.success(partnerManageService.mockSyncPartner(customerSysid));

src/main/java/com/nbport/zgwl/partner/domain/IldmFeeCustomerInfo.java

@@ -15,6 +15,10 @@ import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 
+/**
+ * 客户/相对方信息表 实体
+ * 对应数据库表 ILDM_FEE_CUSTOMER_INFO
+ */
 @TableName(value = "ILDM_FEE_CUSTOMER_INFO")
 @Data
 @EqualsAndHashCode(callSuper = false)
@@ -24,201 +28,267 @@ public class IldmFeeCustomerInfo implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** 客户系统ID（主键） */
     @TableId(value = "CUSTOMER_SYSID", type = IdType.INPUT)
     private Long customerSysid;
 
+    /** 客户注册号 */
     @TableField("CUSTOMER_REGNO")
     private String customerRegno;
 
+    /** 客户编号 */
     @TableField("CUSTOMER_NO")
     private String customerNo;
 
+    /** 公司全称 */
     @TableField("CUSTOMER_NAME_C")
     private String customerNameC;
 
+    /** 公司英文名称 */
     @TableField("CUSTOMER_NAME_EN")
     private String customerNameEn;
 
+    /** 公司简称 */
     @TableField("CUSTOMER_SHORT_NAME")
     private String customerShortName;
 
+    /** 公司英文简称 */
     @TableField("CUSTOMER_SHORT_NAME_EN")
     private String customerShortNameEn;
 
+    /** 统一社会信用代码 */
     @TableField("CUSTOMER_TAXNO")
     private String customerTaxno;
 
+    /** 详细地址 */
     @TableField("CUSTOMER_ADDRESS")
     private String customerAddress;
 
+    /** 联系电话 */
     @TableField("OFFICEPHONE")
     private String officephone;
 
+    /** 开户银行 */
     @TableField("CUSTOMER_BANK")
     private String customerBank;
 
+    /** 银行账户 */
     @TableField("CUSTOMER_BANKACCOUNT")
     private String customerBankaccount;
 
+    /** 客户性质 */
     @TableField("CUSTOMER_CHARACTER")
     private String customerCharacter;
 
+    /** 注册地址 */
     @TableField("CUSTOMER_REGADDR")
     private String customerRegaddr;
 
+    /** 注册日期 */
     @TableField("CUSTOMER_REGDATE")
     private LocalDate customerRegdate;
 
+    /** 客户性质分类 */
     @TableField("CUSTOMER_NATURE")
     private String customerNature;
 
+    /** 邮编 */
     @TableField("CUSTOMER_ZIP")
     private String customerZip;
 
+    /** 客户类型标识1 */
     @TableField("CUSTOMER_1_TYPEFLAG")
     private String customer1Typeflag;
 
+    /** 客户类型标识2 */
     @TableField("CUSTOMER_2_TYPEFLAG")
     private String customer2Typeflag;
 
+    /** 客户类型标识3 */
     @TableField("CUSTOMER_3_TYPEFLAG")
     private String customer3Typeflag;
 
+    /** 客户类型标识4 */
     @TableField("CUSTOMER_4_TYPEFLAG")
     private String customer4Typeflag;
 
+    /** 境内外 */
     @TableField("PLACE_TYPE")
     private String placeType;
 
+    /** 启用标识 */
     @TableField("ACTIVEFLAG")
     private String activeflag;
 
+    /** 海铁系统客户ID */
     @TableField("CUSTOMER_SYSID_HT")
     private String customerSysidHt;
 
+    /** 下载日期 */
     @TableField("DOWN_DATE")
     private LocalDate downDate;
 
+    /** 开户标识 */
     @TableField("OPEN_FLAG")
     private String openFlag;
 
+    /** 创建人 */
     @TableField("CREATE_BY")
     private String createBy;
 
+    /** 创建时间 */
     @TableField("CREATE_TIME")
     private LocalDateTime createTime;
 
+    /** 更新人 */
     @TableField("UPDATE_BY")
     private String updateBy;
 
+    /** 更新时间 */
     @TableField("UPDATE_TIME")
     private LocalDateTime updateTime;
 
+    /** 业务系统类型（ht:海铁联运系统;xg:箱管系统;qc:全程物流） */
     @TableField("SYSTEM_TYPE")
     private String systemType;
 
+    /** 备注 */
     @TableField("REMARK")
     private String remark;
 
+    /** 组织体系对应的公司编码 */
     @TableField("ORG_ID")
     private String orgId;
 
+    /** 邮箱地址 */
     @TableField("EMAIL_ADDRESS")
     private String emailAddress;
 
+    /** 法务系统相对方ID（唯一标识） */
     @TableField("OPPOSITE_ID")
     private String oppositeId;
 
+    /** 相对方性质分类（1:境内组织,2:境内个人,3:境外组织,4:境外个人） */
     @TableField("OPPOSITE_CHARACTER")
     private String oppositeCharacter;
 
+    /** 是否涉港澳台标识（Y:是,N:否，法务业务分类用） */
     @TableField("GAT_FLAG")
     private String gatFlag;
 
+    /** 是否集团内（Y:是,N:否，法务业务分类用） */
     @TableField("GROUP_FLAG")
     private String groupFlag;
 
+    /** 国家编码 */
     @TableField("COUNTRY")
     private String country;
 
+    /** 国家名称 */
     @TableField("COUNTRY_NAME")
     private String countryName;
 
+    /** 城市 */
     @TableField("CITY")
     private String city;
 
+    /** 邮编 */
     @TableField("POSTCODE")
     private String postcode;
 
+    /** 法定代表人或负责人ID */
     @TableField("LEGAL_PERSON_ID")
     private String legalPersonId;
 
+    /** 法定代表人或负责人姓名 */
     @TableField("LEGAL_PERSON_NAME")
     private String legalPersonName;
 
+    /** 法定代表人或负责人账户 */
     @TableField("LEGAL_PERSON_ACCOUNT")
     private String legalPersonAccount;
 
+    /** 法定代表人身份证号（加密存储） */
     @TableField("LEGAL_PERSON_CARD_ID")
     private String legalPersonCardId;
 
+    /** 网站地址 */
     @TableField("WEBSITE")
     private String website;
 
+    /** 自然人证件类型（idCard:身份证,passport:护照,other:其他） */
     @TableField("CERTIFICATE_TYPE")
     private String certificateType;
 
+    /** 自然人证件号码（加密存储） */
     @TableField("CERTIFICATE_NUM")
     private String certificateNum;
 
+    /** TIN码（税务识别号） */
     @TableField("TIN_CODE")
     private String tinCode;
 
+    /** 境外公司活动证明编码 */
     @TableField("ABROAD_CODE")
     private String abroadCode;
 
+    /** 注册资金（单位：元） */
     @TableField("REGISTERED_CAPITAL")
     private BigDecimal registeredCapital;
 
+    /** 注册资本（文本描述，如：1000万人民币） */
     @TableField("REG_CAPITAL")
     private String regCapital;
 
+    /** 经营范围 */
     @TableField("BUS_SCOPE")
     private String busScope;
 
+    /** 相对方编码（业务分类编码） */
     @TableField("OPPOSITE_CODE")
     private String oppositeCode;
 
+    /** 状态（EFFECTUAL:有效,INVALID:无效） */
     @TableField("OPPOSITE_STATUS")
     private String oppositeStatus;
 
+    /** 是否SGAT（1:是,0:否） */
     @TableField("IS_SGAT")
     private String isSgat;
 
+    /** 是否JTN（1:是,0:否） */
     @TableField("IS_JTN")
     private String isJtn;
 
+    /** 组织性质（ZY:政府,QY:企业,QT:其他组织） */
     @TableField("NATURE_OF_ENTERPRISE_ORG")
     private String natureOfEnterpriseOrg;
 
+    /** 组织性质子级（GNQY:国有企业,MYQY:民营企业,WZQY:外资企业等） */
     @TableField("NATURE_OF_ENTERPRISE_ORG_LEV")
     private String natureOfEnterpriseOrgLev;
 
+    /** 类型（client:客户,supplier:供应商,Partner:合作伙伴等） */
     @TableField("RELATIVE_TYPE")
     private String relativeType;
 
+    /** 法务系统删除标记（Y:是,N:否，逻辑删除） */
     @TableField("IS_DELETED")
     private String isDeleted;
 
+    /** 备注【法务】 */
     @TableField("COMMENTS")
     private String comments;
 
+    /** 同步状态：unsynced/synced/failed */
     @TableField("SYNC_STATUS")
     private String syncStatus;
 
+    /** 最后同步时间 */
     @TableField("SYNC_TIME")
     private LocalDateTime syncTime;
 
+    /** 同步说明 */
     @TableField("SYNC_MESSAGE")
     private String syncMessage;
 }

src/main/java/com/nbport/zgwl/partner/domain/SealPartnerContact.java

@@ -13,6 +13,10 @@ import java.io.Serial;
 import java.io.Serializable;
 import java.time.LocalDateTime;
 
+/**
+ * 相对方联系人表 实体
+ * 对应数据库表 SEAL_PARTNER_CONTACT
+ */
 @TableName(value = "SEAL_PARTNER_CONTACT")
 @Data
 @EqualsAndHashCode(callSuper = false)
@@ -22,42 +26,55 @@ public class SealPartnerContact implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** 主键ID */
     @TableId(value = "ID", type = IdType.INPUT)
     private Long id;
 
+    /** 关联相对方主表 CUSTOMER_SYSID */
     @TableField("PARTNER_RECORD_ID")
     private Long partnerRecordId;
 
+    /** 联系人姓名 */
     @TableField("CONTACT_NAME")
     private String contactName;
 
+    /** 联系电话 */
     @TableField("CONTACT_PHONE")
     private String contactPhone;
 
+    /** 通讯地址 */
     @TableField("POSTAL_ADDRESS")
     private String postalAddress;
 
+    /** 电子邮箱 */
     @TableField("EMAIL")
     private String email;
 
+    /** 排序号 */
     @TableField("SORT_ORDER")
     private Integer sortOrder;
 
+    /** 删除标记：0存在 2删除 */
     @TableField("DEL_FLAG")
     private String delFlag;
 
+    /** 创建人 */
     @TableField("CREATE_BY")
     private String createBy;
 
+    /** 创建时间 */
     @TableField("CREATE_TIME")
     private LocalDateTime createTime;
 
+    /** 更新人 */
     @TableField("UPDATE_BY")
     private String updateBy;
 
+    /** 更新时间 */
     @TableField("UPDATE_TIME")
     private LocalDateTime updateTime;
 
+    /** 备注 */
     @TableField("REMARK")
     private String remark;
 }

src/main/java/com/nbport/zgwl/partner/dto/PartnerContactDto.java

@@ -22,6 +22,7 @@ public class PartnerContactDto implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** 主键ID */
     private Long id;
 
     /**
@@ -29,19 +30,27 @@ public class PartnerContactDto implements Serializable {
      */
     private String uid;
 
+    /** 关联相对方主表 CUSTOMER_SYSID */
     private Long partnerRecordId;
 
+    /** 联系人姓名 */
     private String contactName;
 
+    /** 联系电话 */
     private String contactPhone;
 
+    /** 通讯地址 */
     private String postalAddress;
 
+    /** 电子邮箱 */
     private String email;
 
+    /** 排序号 */
     private Integer sortOrder;
 
+    /** 删除标记：0存在 2删除 */
     private String delFlag;
 
+    /** 备注 */
     private String remark;
 }

src/main/java/com/nbport/zgwl/partner/dto/PartnerQueryDto.java

@@ -17,13 +17,18 @@ public class PartnerQueryDto extends BasePageDto implements Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
+    /** 公司全称（模糊查询） */
     private String customerNameC;
 
+    /** 类型（client/supplier/Partner 等） */
     private String relativeType;
 
+    /** 相对方性质分类（1:境内组织,2:境内个人,3:境外组织,4:境外个人） */
     private String oppositeCharacter;
 
+    /** 是否集团内（Y/N） */
     private String groupFlag;
 
+    /** 同步状态（unsynced/synced/failed） */
     private String syncStatus;
 }

src/main/java/com/nbport/zgwl/partner/handler/PartnerDataHandler.java

@@ -20,6 +20,7 @@ import java.util.stream.Collectors;
 @Component
 public class PartnerDataHandler {
 
+    /** 保存前数据清洗（去空格、按性质清空不相关字段、设置默认值） */
     public void normalizeBeforeSave(PartnerManageDto partner) {
         partner.setCustomerNameC(StrUtil.trim(partner.getCustomerNameC()));
         partner.setCustomerTaxno(StrUtil.trim(partner.getCustomerTaxno()));
@@ -91,6 +92,7 @@ public class PartnerDataHandler {
         partner.setContacts(contacts);
     }
 
+    /** 保存前数据校验（必填项校验、格式校验、联系人校验） */
     public void validateForSave(PartnerManageDto partner) {
         if (StrUtil.isBlank(partner.getCustomerNameC())) {
             throw new ServiceException("公司名称不能为空");
@@ -140,6 +142,7 @@ public class PartnerDataHandler {
         validateContacts(partner);
     }
 
+    /** 给联系人填充前端 uid（用于列表渲染时的临时唯一标识） */
     public void fillContactUiKeys(List<PartnerContactDto> contacts) {
         if (contacts == null) {
             return;
@@ -151,6 +154,7 @@ public class PartnerDataHandler {
         });
     }
 
+    /** 校验联系人信息（姓名/电话/地址/邮箱必填，邮箱格式校验） */
     private void validateContacts(PartnerManageDto partner) {
         if (!needContacts(partner)) {
             return;
@@ -177,6 +181,7 @@ public class PartnerDataHandler {
         }
     }
 
+    /** 清洗单条联系人数据（去空格、设置默认删除标记） */
     private void normalizeContact(PartnerContactDto contact) {
         contact.setContactName(StrUtil.trim(contact.getContactName()));
         contact.setContactPhone(StrUtil.trim(contact.getContactPhone()));
@@ -186,6 +191,7 @@ public class PartnerDataHandler {
         contact.setDelFlag(PartnerManageConstants.CONTACT_DEL_FLAG_NORMAL);
     }
 
+    /** 判断联系人是否有有效数据（至少填写一个字段才保留） */
     private boolean hasAnyContactValue(PartnerContactDto contact) {
         return StrUtil.isNotBlank(contact.getContactName())
                 || StrUtil.isNotBlank(contact.getContactPhone())
@@ -193,10 +199,12 @@ public class PartnerDataHandler {
                 || StrUtil.isNotBlank(contact.getEmail());
     }
 
+    /** 是否需要维护联系人（境内组织、境外组织必须维护） */
     private boolean needContacts(PartnerManageDto partner) {
         return isDomesticOrg(partner) || isForeignOrg(partner);
     }
 
+    /** 是否显示涉港澳台标识（境内组织、境内个人才显示） */
     private boolean showGatFlag(PartnerManageDto partner) {
         return isDomesticOrg(partner) || isDomesticPerson(partner);
     }

src/main/java/com/nbport/zgwl/partner/mapper/PartnerManageMapper.java

@@ -15,35 +15,46 @@ import java.util.List;
  */
 public interface PartnerManageMapper {
 
+    /** 获取相对方主表序列（Oracle 主键生成） */
     Long selectPartnerSeqNextVal();
 
+    /** 获取联系人表序列（Oracle 主键生成） */
     Long selectPartnerContactSeqNextVal();
 
+    /** 分页查询相对方列表 */
     IPage<PartnerManageDto> selectPartnerPage(Page<PartnerManageDto> page, @Param("query") PartnerQueryDto queryDto);
 
+    /** 根据主键查询单条相对方详情 */
     PartnerManageDto selectPartnerById(@Param("customerSysid") Long customerSysid);
 
+    /** 新增相对方 */
     int insertPartner(PartnerManageDto partner);
 
+    /** 修改相对方 */
     int updatePartner(PartnerManageDto partner);
 
+    /** 批量逻辑删除相对方 */
     int deletePartnerByIds(@Param("customerSysids") List<Long> customerSysids,
                            @Param("updateBy") String updateBy,
                            @Param("updateTime") LocalDateTime updateTime,
                            @Param("isDeleted") String isDeleted);
 
+    /** 根据相对方 ID 列表批量查询联系人 */
     List<PartnerContactDto> selectPartnerContactsByPartnerIds(@Param("partnerRecordIds") List<Long> partnerRecordIds);
 
+    /** 逻辑删除某个相对方下的所有联系人 */
     int markPartnerContactsDeletedByPartnerId(@Param("partnerRecordId") Long partnerRecordId,
                                               @Param("updateBy") String updateBy,
                                               @Param("updateTime") LocalDateTime updateTime,
                                               @Param("delFlag") String delFlag);
 
+    /** 批量逻辑删除多个相对方下的所有联系人 */
     int markPartnerContactsDeletedByPartnerIds(@Param("partnerRecordIds") List<Long> partnerRecordIds,
                                                @Param("updateBy") String updateBy,
                                                @Param("updateTime") LocalDateTime updateTime,
                                                @Param("delFlag") String delFlag);
 
+    /** 批量插入联系人 */
     int batchInsertPartnerContacts(@Param("contacts") List<PartnerContactDto> contacts,
                                    @Param("createBy") String createBy,
                                    @Param("createTime") LocalDateTime createTime,
@@ -51,6 +62,7 @@ public interface PartnerManageMapper {
                                    @Param("updateTime") LocalDateTime updateTime,
                                    @Param("delFlag") String delFlag);
 
+    /** 更新同步状态（回写法务系统返回的 oppositeId） */
     int updatePartnerSyncInfo(@Param("customerSysid") Long customerSysid,
                               @Param("oppositeId") String oppositeId,
                               @Param("syncStatus") String syncStatus,

src/main/java/com/nbport/zgwl/partner/service/PartnerManageService.java

@@ -11,15 +11,21 @@ import java.util.List;
  */
 public interface PartnerManageService {
 
+    /** 分页查询相对方列表 */
     PageResult<PartnerManageDto> queryPartnerList(PartnerQueryDto queryDto);
 
+    /** 根据主键查询相对方详情 */
     PartnerManageDto selectPartnerById(Long customerSysid);
 
+    /** 新增相对方 */
     Long insertPartner(PartnerManageDto partner);
 
+    /** 修改相对方 */
     void updatePartner(PartnerManageDto partner);
 
+    /** 批量删除相对方 */
     void deletePartnerByIds(List<Long> customerSysids);
 
+    /** 模拟同步到法务系统 */
     PartnerManageDto mockSyncPartner(Long customerSysid);
 }

src/main/java/com/nbport/zgwl/partner/service/PartnerManageServiceImpl.java

@@ -36,6 +36,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
 
     private final PartnerDataHandler partnerDataHandler;
 
+    /** 分页查询相对方列表（结果中会带上联系人数据） */
     @Override
     public PageResult<PartnerManageDto> queryPartnerList(PartnerQueryDto queryDto) {
         Page<PartnerManageDto> page = new Page<>(queryDto.getPageNo(), queryDto.getPageSize());
@@ -45,6 +46,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
         return pageResult;
     }
 
+    /** 根据主键查询单个相对方详情（含联系人） */
     @Override
     public PartnerManageDto selectPartnerById(Long customerSysid) {
         PartnerManageDto partner = partnerManageMapper.selectPartnerById(customerSysid);
@@ -55,6 +57,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
         return partner;
     }
 
+    /** 新增相对方（含联系人信息保存，数据回写主键） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public Long insertPartner(PartnerManageDto partner) {
@@ -80,6 +83,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
         return partner.getCustomerSysid();
     }
 
+    /** 修改相对方（先删旧联系人，再批量插入新联系人） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public void updatePartner(PartnerManageDto partner) {
@@ -116,6 +120,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
         saveContacts(partner.getCustomerSysid(), partner.getContacts(), now);
     }
 
+    /** 批量删除相对方（逻辑删除，同时删除关联联系人） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public void deletePartnerByIds(List<Long> customerSysids) {
@@ -135,6 +140,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
                 PartnerManageConstants.PARTNER_IS_DELETED_DELETED);
     }
 
+    /** 模拟同步相对方到法务系统（本地测试用，TODO：替换为真实 collectOpposites 调用） */
     @Override
     @Transactional(rollbackFor = Exception.class)
     public PartnerManageDto mockSyncPartner(Long customerSysid) {
@@ -174,6 +180,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
         return selectPartnerById(customerSysid);
     }
 
+    /** 批量查询并填充联系人（避免 N+1，一次查完再分组赋值） */
     private void attachContacts(List<PartnerManageDto> partnerList) {
         if (partnerList == null || partnerList.isEmpty()) {
             return;
@@ -199,6 +206,7 @@ public class PartnerManageServiceImpl implements PartnerManageService {
         });
     }
 
+    /** 批量保存联系人（设置排序号、删除标记后统一插入） */
     private void saveContacts(Long customerSysid, List<PartnerContactDto> contacts, LocalDateTime now) {
         if (customerSysid == null || contacts == null || contacts.isEmpty()) {
             return;

src/main/java/com/nbport/zgwl/partner/utils/PartnerIdUtils.java

@@ -19,10 +19,12 @@ public final class PartnerIdUtils {
     private PartnerIdUtils() {
     }
 
+    /** 生成本地相对方编码（格式：OPP-yyyyMMddHHmmss-随机4位） */
     public static String buildPartnerId() {
         return PARTNER_PREFIX + "-" + formatNow("yyyyMMddHHmmss") + "-" + randomDigits(4);
     }
 
+    /** 生成集团相对方 ID（格式：JT-yyyyMMddHHmmss-随机4位，后续联调时由法务系统返回替换） */
     public static String buildGroupPartnerId() {
         return GROUP_PREFIX + "-" + formatNow("yyyyMMddHHmmss") + "-" + randomDigits(4);
     }

src/main/java/com/nbport/zgwl/partner/utils/PartnerManageConstants.java

@@ -8,35 +8,51 @@ public final class PartnerManageConstants {
     private PartnerManageConstants() {
     }
 
+    /** 相对方管理请求前缀 */
     public static final String REQUEST_PREFIX = "/partner/manage";
 
+    /** 默认操作人（后续内网联调时替换为真实用户） */
     public static final String DEFAULT_OPERATOR = "local_test";
 
+    /** 相对方未删除标记 */
     public static final String PARTNER_IS_DELETED_NORMAL = "N";
 
+    /** 相对方已删除标记 */
     public static final String PARTNER_IS_DELETED_DELETED = "Y";
 
+    /** 联系人未删除标记 */
     public static final String CONTACT_DEL_FLAG_NORMAL = "0";
 
+    /** 联系人已删除标记 */
     public static final String CONTACT_DEL_FLAG_DELETED = "2";
 
+    /** 相对方有效状态 */
     public static final String OPPOSITE_STATUS_EFFECTUAL = "EFFECTUAL";
 
+    /** 涉港澳台：是 */
     public static final String GAT_FLAG_YES = "Y";
 
+    /** 涉港澳台：否 */
     public static final String GAT_FLAG_NO = "N";
 
+    /** 集团内：是 */
     public static final String GROUP_FLAG_YES = "Y";
 
+    /** 集团内：否 */
     public static final String GROUP_FLAG_NO = "N";
 
+    /** 标识：1（是） */
     public static final String FLAG_ONE = "1";
 
+    /** 标识：0（否） */
     public static final String FLAG_ZERO = "0";
 
+    /** 同步状态：未同步 */
     public static final String SYNC_STATUS_UNSYNCED = "unsynced";
 
+    /** 同步状态：已同步 */
     public static final String SYNC_STATUS_SYNCED = "synced";
 
+    /** 同步状态：同步失败 */
     public static final String SYNC_STATUS_FAILED = "failed";
 }

src/main/java/com/nbport/zgwl/partner/utils/PartnerSyncPayloadBuilder.java

@@ -17,6 +17,7 @@ public final class PartnerSyncPayloadBuilder {
     private PartnerSyncPayloadBuilder() {
     }
 
+    /** 构建相对方信息采集报文（数据采集接口规范 V3.0 格式） */
     public static PushPayloadDTO buildCollectOppositesPayload(PartnerManageDto partner) {
         Map<String, Object> payload = new LinkedHashMap<>();
         payload.put("o_id", partner.getCustomerSysid() == null ? null : String.valueOf(partner.getCustomerSysid()));
@@ -48,6 +49,7 @@ public final class PartnerSyncPayloadBuilder {
         return requestDTO;
     }
 
+    /** 构建联系人列表报文 */
     private static List<Map<String, Object>> buildContactList(List<PartnerContactDto> contacts) {
         if (contacts == null) {
             return List.of();
@@ -62,6 +64,7 @@ public final class PartnerSyncPayloadBuilder {
         }).collect(Collectors.toList());
     }
 
+    /** 转换组织性质：系统内用 ZY（政府），法务系统用 ZF */
     private static String convertOrgNature(String natureOfEnterpriseOrg) {
         if ("ZY".equals(natureOfEnterpriseOrg)) {
             return "ZF";

src/main/resources/application.yml

@@ -15,6 +15,7 @@ mybatis-plus:
   mapper-locations: classpath*:mapper/**/*.xml
   type-aliases-package: com.nbport.zgwl.entity,com.nbport.zgwl.partner.domain,com.nbport.zgwl.manifest.domain
   configuration:
+    jdbc-type-for-null: 'NULL'
     map-underscore-to-camel-case: true
     log-impl: org.apache.ibatis.logging.stdout.StdOutImpl
   global-config: