:fix: 合同发起附件attachment上移至顶层与fdFieldJson同级并同步接口文档

2026-10-19 11:12:07 +08:00
parent 64a14875fa
commit 6e6e5913ba
3 changed files with 13 additions and 12 deletions
@@ -74,7 +74,7 @@ import java.util.Objects;
 * HCS 合同同步支撑组件（C103-1 发起 / C103-11 更新，设计文档 §5.2）
 * <p>
 * 扫描任务按序执行：⓪ 特批挂起门禁 → ① 客商风险校验（可配开关，仅留痕，高风险不再阻断）→
- * ② 附件转传（v4 挂载点 fdFieldJson.attachment，随 C103-1 挂载）→ ③ C103-3 判重（§9-U4 查询能力联调确认）→
+ * ② 附件转传（挂载点为与 fdFieldJson 同级的顶层 attachment，随 C103-1 挂载）→ ③ C103-3 判重（§9-U4 查询能力联调确认）→
 * ④ C103-1 起草 / 变更单 C103-11 更新（§9-U5 定位方式待联调）→ ⑤ 履约计划 C103-9 行级同步（{@link HcsExeStageSyncSupport}，
 * 仅依赖 hcs_fd_id，先于特批挂起执行，失败补偿不被特批门禁阻塞）→ ⑥ 高风险/黑名单挂起"特批审核"
 * （外部客商管控：报文随 fdSepcailContract=true 在合规侧走特批，{@link HcsContractSpecSyncSupport} 接收结果）。
@@ -129,7 +129,7 @@ public class HcsContractSyncSupport {
 		if (hcsProperties.getContract().isRequireRiskCheck()) {
 			risky = checkRelativeRisk(contractManage);
 		}
-		// ② 附件转传（v4 已明确挂载点：C103-1 fdFieldJson.attachment，转传取得合规附件引用后随发起报文挂载）
+		// ② 附件转传（v4 已明确挂载点：C103-1 顶层 attachment，与 fdFieldJson 同级，转传取得合规附件引用后随发起报文挂载）
 		List<HcsAttachmentRefDTO> attachmentRefs = transferAttachmentsIfEnabled(contractManage);
 		// ③④ 首推判重后起草（C103-1）；已有合规ID（变更单）走更新（C103-11）
 		String resultMessage;
@@ -307,7 +307,7 @@ public class HcsContractSyncSupport {

 	/**
 	 * 组装 C103-1/C103-11 入参（字段标注照 §3.4 规范，映射表见设计文档 §5.2）；
-	 * attachmentRefs 新建传合规附件引用列表（fdId+fdEntityKey，必填，无附件传空列表），更新传 null 不挂载
+	 * attachmentRefs 新建传合规附件引用列表（顶层 attachment，fdId+fdEntityKey，必填，无附件传空列表），更新传 null 不挂载
 	 */
 	private HcsContractDraftDTO buildDraftParam(ContractManage contractManage, List<HcsAttachmentRefDTO> attachmentRefs, boolean risky) {
 		HcsContractDraftDTO param = new HcsContractDraftDTO();
@@ -325,11 +325,11 @@ public class HcsContractSyncSupport {
 		fieldJson.setXformFields(buildXformFields(contractManage, risky));
 		// 相对方（签署方）：甲方/乙方，编号按名称反查 CustomerArchive（§9-U6）
 		fieldJson.setSigner(buildSigners(contractManage));
-		// 【必填】附件数据：C103-1 必填（无附件传空列表），fdEntityKey=特批 eopCdraftSpecial/用印 eopCdraftSign/其他 eopCdraftOther，
+		// 【必填】附件数据：与 fdFieldJson 同级的顶层 attachment，C103-1 必填（无附件传空列表），fdEntityKey=特批 eopCdraftSpecial/用印 eopCdraftSign/其他 eopCdraftOther，
 		// fdBindType=ADD；更新不挂载（传 null）
 		if (attachmentRefs != null) {
-			fieldJson.setAttachment(new ArrayList<>(attachmentRefs));
-			for (HcsAttachmentRefDTO attachment : fieldJson.getAttachment()) {
+			param.setAttachment(new ArrayList<>(attachmentRefs));
+			for (HcsAttachmentRefDTO attachment : param.getAttachment()) {
 				// 【必填】操作类型：ADD 新增
 				attachment.setFdBindType("ADD");
 			}
@@ -449,7 +449,7 @@ public class HcsContractSyncSupport {

 	/**
 	 * 附件转传（可配开关）：合同主文件 approved=true（挂 eopCdraftSign）+ 其它附件（挂 eopCdraftOther），
-	 * 返回合规附件引用列表（挂载 C103-1 fdFieldJson.attachment）
+	 * 返回合规附件引用列表（挂载 C103-1 顶层 attachment，与 fdFieldJson 同级）
 	 */
 	private List<HcsAttachmentRefDTO> transferAttachmentsIfEnabled(ContractManage contractManage) {
 		if (!hcsProperties.getAttachment().isTransferEnabled()) {
@@ -31,6 +31,7 @@ import lombok.Data;

 import java.io.Serial;
 import java.io.Serializable;
+import java.util.List;

 /**
 * 合同合规系统（HCS）C103-1 合同发起入参（C103-11 合同更新入参结构相同，复用本 DTO）
@@ -67,4 +68,8 @@ public class HcsContractDraftDTO implements Serializable {
 	 * 合同字段（模板字段 + 签署方）
 	 */
 	private HcsContractFieldJsonDTO fdFieldJson;
+	/**
+	 * 附件数据（与 fdFieldJson 同级；C103-1 必填，无附件传空列表，C103-11 更新不传；fdEntityKey 普通附件枚举待合规方给出，暂不传）
+	 */
+	private List<HcsAttachmentRefDTO> attachment;
 }
@@ -36,7 +36,7 @@ import java.util.List;
 /**
 * 合同合规系统（HCS）C103-1 合同发起 fdFieldJson 节点（C103-1 新建 / C103-11 更新共用）
 * <p>
- * v4 文档已定义 attachment 附件挂载（fdId/fdBindType 必填，fdEntityKey 仅给出特批附件枚举 eopCdraftSpecial）。
+ * 附件挂载在顶层报文 attachment（与 fdFieldJson 同级），见 HcsContractDraftDTO。
 *
 * @author Chill
 */
@@ -54,8 +54,4 @@ public class HcsContractFieldJsonDTO implements Serializable {
 	 * 签署方（相对方）列表
 	 */
 	private List<HcsSignerDTO> signer;
-	/**
-	 * 附件数据（C103-1 必填，C103-11 更新不传；fdEntityKey 普通附件枚举待合规方给出，暂不传）
-	 */
-	private List<HcsAttachmentRefDTO> attachment;
 }