增加注释

2026-05-26 15:05:44 +08:00
parent 3b70da2f0b
commit 4e1026d04a
33 changed files with 307 additions and 0 deletions
@@ -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;
    }
 }
@@ -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;
 }
@@ -12,7 +12,9 @@ public class ApproveViewUrlRequestDTO implements Serializable {

    private static final long serialVersionUID = 1L;

+    /** 合同ID（法务系统返回的 contractId） */
    private String contractId;

+    /** 查看人的用户标识，用于单点登录 ssoToken 参数 */
    private String ivUser;
 }
@@ -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<>();
 }
@@ -12,7 +12,9 @@ public class PushTokenRequestDTO implements Serializable {

    private static final long serialVersionUID = 1L;

+    /** 系统标识（覆盖配置中的默认值） */
    private String systemKey;

+    /** 密钥（覆盖配置中的默认值） */
    private String secretKey;
 }
@@ -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 不能为空");
@@ -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;
@@ -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;
@@ -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()) {
@@ -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("审批查看地址未配置");
@@ -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;
 }
@@ -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;
 }
@@ -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;
 }
@@ -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<>());
@@ -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,
@@ -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();
 }
@@ -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()));
@@ -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());
@@ -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();
@@ -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";
 }
@@ -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));
@@ -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;
 }
@@ -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;
 }
@@ -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;
 }
@@ -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;
 }
@@ -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);
    }
@@ -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,
@@ -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);
 }
@@ -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;
@@ -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);
    }
@@ -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";
 }
@@ -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";