From 9e4b8a6d58d4abbe7671ef4b01307d39846e80cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=88=98=E6=B3=89=E4=BD=B3?= <1107186916@qq.com>
Date: Mon, 12 Oct 2026 16:51:04 +0800
Subject: [PATCH] =?UTF-8?q?:feat:=20HCS=E9=99=84=E4=BB=B6=E8=BD=AC?=
=?UTF-8?q?=E4=BC=A0=E6=98=A0=E5=B0=84=E8=90=BD=E5=BA=93=EF=BC=8CRedis?=
=?UTF-8?q?=E7=BC=93=E5=AD=98=E5=88=A4=E9=87=8D=E6=94=B9=E4=B8=BAblade=5Fh?=
=?UTF-8?q?cs=5Fattachment=5Fsync=E6=8C=81=E4=B9=85=E5=8C=96=E8=A1=A8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 新增 HcsAttachmentSync 实体与 Mapper（biz_type+biz_id+attachment_key 唯一，照金蝶附件同步表设计，仅落成功记录）
- HcsAttachmentSupport 移除 BladeRedis 依赖，transferOne 查表命中即复用合规附件ID，未命中上传后落行
- transferAttachments/transferContractAttachments 增加 bizType/bizId 入参，六个调用点（合同主附件/特批说明/特批付款/履约记录/开票登记/收票单）传入业务上下文
- HcsSyncConstant 删除 ATTACHMENT_CACHE_KEY_PREFIX/ATTACHMENT_CACHE_TTL_DAYS 缓存常量
- 新增建表脚本 blade_hcs_attachment_sync_20261012.sql，技术设计文档 §6 映射缓存表述同步更新
---
.../pojo/entity/HcsAttachmentSync.java | 78 +++++++++++++++++++
.../mapper/HcsAttachmentSyncMapper.java | 39 ++++++++++
.../blade_hcs_attachment_sync_20261012.sql | 32 ++++++++
3 files changed, 149 insertions(+)
create mode 100644 blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/HcsAttachmentSync.java
create mode 100644 blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/HcsAttachmentSyncMapper.java
create mode 100644 doc/sql/transport/blade_hcs_attachment_sync_20261012.sql
diff --git a/blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/HcsAttachmentSync.java b/blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/HcsAttachmentSync.java
new file mode 100644
index 00000000..4fa7fb40
--- /dev/null
+++ b/blade-service-api/blade-transport-api/src/main/java/org/springblade/transport/pojo/entity/HcsAttachmentSync.java
@@ -0,0 +1,78 @@
+/**
+ * BladeX Commercial License Agreement
+ * Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
+ *
+ * Use of this software is governed by the Commercial License Agreement
+ * obtained after purchasing a license from BladeX.
+ *
+ * 1. This software is for development use only under a valid license
+ * from BladeX.
+ *
+ * 2. Redistribution of this software's source code to any third party
+ * without a commercial license is strictly prohibited.
+ *
+ * 3. Licensees may copyright their own code but cannot use segments
+ * from this software for such purposes. Copyright of this software
+ * remains with BladeX.
+ *
+ * Using this software signifies agreement to this License, and the software
+ * must not be used for illegal purposes.
+ *
+ * THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
+ * not liable for any claims arising from secondary or illegal development.
+ *
+ * Author: Chill Zhuang (bladejava@qq.com)
+ */
+package org.springblade.transport.pojo.entity;
+
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
+import com.fasterxml.jackson.databind.ser.std.ToStringSerializer;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import org.springblade.core.tenant.mp.TenantEntity;
+
+import java.io.Serial;
+import java.time.LocalDateTime;
+
+/**
+ * HCS 附件转传映射实体类（C103-2 转传取得合规附件ID，单附件行级，照金蝶附件同步表设计）
+ *
+ * 仅落成功记录：HCS 转传任一附件失败即抛异常整单重试（失败原因落单据 hcs_sync_msg），故无失败态字段。
+ *
+ * @author Chill
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("blade_hcs_attachment_sync")
+@Schema(description = "HCS附件转传映射")
+public class HcsAttachmentSync extends TenantEntity {
+ @Serial
+ private static final long serialVersionUID = 1L;
+ /**
+ * 业务单据类型（contract/payment/invoice-application/invoice-receipt）
+ */
+ private String bizType;
+ /**
+ * 业务单据id
+ */
+ @JsonSerialize(using = ToStringSerializer.class)
+ private Long bizId;
+ /**
+ * 附件幂等键（url|link|fileUrl|downloadUrl|uid|originalName|name 依次取首个非空）
+ */
+ private String attachmentKey;
+ /**
+ * 附件名称（展示/排查用）
+ */
+ private String attachmentName;
+ /**
+ * 合规附件ID（C103-2 返回 fdId）
+ */
+ private String fdId;
+ /**
+ * 最近转传时间
+ */
+ private LocalDateTime syncTime;
+}
diff --git a/blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/HcsAttachmentSyncMapper.java b/blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/HcsAttachmentSyncMapper.java
new file mode 100644
index 00000000..637862ed
--- /dev/null
+++ b/blade-service/blade-transport/src/main/java/org/springblade/transport/mapper/HcsAttachmentSyncMapper.java
@@ -0,0 +1,39 @@
+/**
+ * BladeX Commercial License Agreement
+ * Copyright (c) 2018-2099, https://bladex.cn. All rights reserved.
+ *
+ * Use of this software is governed by the Commercial License Agreement
+ * obtained after purchasing a license from BladeX.
+ *
+ * 1. This software is for development use only under a valid license
+ * from BladeX.
+ *
+ * 2. Redistribution of this software's source code to any third party
+ * without a commercial license is strictly prohibited.
+ *
+ * 3. Licensees may copyright their own code but cannot use segments
+ * from this software for such purposes. Copyright of this software
+ * remains with BladeX.
+ *
+ * Using this software signifies agreement to this License, and the software
+ * must not be used for illegal purposes.
+ *
+ * THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY. The author is
+ * not liable for any claims arising from secondary or illegal development.
+ *
+ * Author: Chill Zhuang (bladejava@qq.com)
+ */
+package org.springblade.transport.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import org.apache.ibatis.annotations.Mapper;
+import org.springblade.transport.pojo.entity.HcsAttachmentSync;
+
+/**
+ * HCS 附件转传映射 Mapper
+ *
+ * @author Chill
+ */
+@Mapper
+public interface HcsAttachmentSyncMapper extends BaseMapper {
+}
diff --git a/doc/sql/transport/blade_hcs_attachment_sync_20261012.sql b/doc/sql/transport/blade_hcs_attachment_sync_20261012.sql
new file mode 100644
index 00000000..4db61dd7
--- /dev/null
+++ b/doc/sql/transport/blade_hcs_attachment_sync_20261012.sql
@@ -0,0 +1,32 @@
+-- blade_hcs_attachment_sync 建表（HCS 附件转传映射，照金蝶附件同步表 blade_kingdee_attachment_sync 设计：
+-- biz_type+biz_id+attachment_key 唯一，C103-2 转传前查命中即复用合规附件ID，仅落成功记录）
+SET @ddl_sql = (
+ SELECT IF(COUNT(*) = 0,
+ 'CREATE TABLE `blade_hcs_attachment_sync` (
+ `id` bigint NOT NULL COMMENT ''主键'',
+ `tenant_id` varchar(12) COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT ''租户ID'',
+ `biz_type` varchar(32) COLLATE utf8mb4_general_ci NOT NULL COMMENT ''业务单据类型（contract/payment/invoice-application/invoice-receipt）'',
+ `biz_id` bigint NOT NULL COMMENT ''业务单据id'',
+ `attachment_key` varchar(768) COLLATE utf8mb4_general_ci NOT NULL COMMENT ''附件幂等键（url|link|fileUrl|downloadUrl|uid|originalName|name 依次取首个非空）'',
+ `attachment_name` varchar(255) COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT ''附件名称（展示/排查用）'',
+ `fd_id` varchar(64) COLLATE utf8mb4_general_ci DEFAULT NULL COMMENT ''合规附件ID（C103-2 返回 fdId）'',
+ `sync_time` datetime DEFAULT NULL COMMENT ''最近转传时间'',
+ `create_user` bigint DEFAULT NULL COMMENT ''创建人'',
+ `create_dept` bigint DEFAULT NULL COMMENT ''创建部门'',
+ `create_time` datetime DEFAULT NULL COMMENT ''创建时间'',
+ `update_user` bigint DEFAULT NULL COMMENT ''修改人'',
+ `update_time` datetime DEFAULT NULL COMMENT ''修改时间'',
+ `status` int DEFAULT NULL COMMENT ''业务状态'',
+ `is_deleted` int DEFAULT 0 COMMENT ''是否已删除'',
+ PRIMARY KEY (`id`),
+ UNIQUE KEY `uk_biz_attachment` (`biz_type`,`biz_id`,`attachment_key`(256)),
+ KEY `idx_biz_type_biz_id` (`biz_type`,`biz_id`)
+ ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT=''HCS附件转传映射表（C103-2）''',
+ 'SELECT 1')
+ FROM information_schema.TABLES
+ WHERE TABLE_SCHEMA = DATABASE()
+ AND TABLE_NAME = 'blade_hcs_attachment_sync'
+);
+PREPARE ddl_stmt FROM @ddl_sql;
+EXECUTE ddl_stmt;
+DEALLOCATE PREPARE ddl_stmt;