From 757b058697fde3dc5ebde2578036c4d097038f83 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 17 Nov 2026 10:02:50 +0800 Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E4=B8=8A=E4=BC=A0=E9=99=84=E4=BB=B6=20/v1/saleOrder/c?= =?UTF-8?q?reateAttachment?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 HengjianOrderAttachmentDtos,在 OutboundCapable 上加 uploadAttachments()(default 拒绝),恒健覆盖 - 门面新增 outbound().attachment(ref, list):写操作走幂等守卫, 业务键是「单号 + 附件名 + attachment」——同附件重传幂等、 不同附件各自一次(只用单号做键会让第二次附件被判成重复) - 请求平铺;type 在这个接口是 INTEGER 0~6(创建订单那边标 STRING, 两页不一致),认不出即拒绝,不猜 - 给了 contentBase64 时忽略 url 并剥掉 data: 前缀(仓方语义) - 真机无 token 时直接 403、不做参数校验,必填项按文档实现: orderNo + 非空列表,每行 name/type 必填、url 与 file 二选一 - 响应无 data,只有 code/message 验证:mvn test 全量通过,恒健 305 个用例(+12)通过。 Co-Authored-By: Claude Code --- README.md | 4 +- docs-warehouse/hengjian/README.md | 10 +- .../warehouse/capability/OutboundCapable.java | 19 ++ .../warehouse/sdk/WarehouseOutbounds.java | 56 ++++++ .../ecommerce/hengjian/HengjianConstants.java | 8 + .../hengjian/adapter/HengjianAdapter.java | 97 ++++++++++ .../hengjian/dto/HengjianOrderAttachmentDtos.java | 58 ++++++ .../adapter/HengjianOrderAttachmentTest.java | 208 +++++++++++++++++++++ 8 files changed, 454 insertions(+), 6 deletions(-) create mode 100644 warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderAttachmentDtos.java create mode 100644 warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderAttachmentTest.java diff --git a/README.md b/README.md index eadb675..11f76ff 100644 --- a/README.md +++ b/README.md @@ -141,7 +141,7 @@ sequenceDiagram | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | | `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) | -| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货计划创建查询处理) | +| `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件) | 依赖方向: ``` @@ -395,7 +395,7 @@ common.ecommerce │ HengjianInboundCreateDtos / HengjianInboundQueryDtos / │ HengjianTransferDtos / HengjianReturnPlanCreateDtos / │ HengjianReturnDetailDtos / HengjianReturnListDtos / - │ HengjianReturnHandleDtos + │ HengjianReturnHandleDtos / HengjianOrderAttachmentDtos ├── enums HengjianOrderStatus(orderStatusEnum → OutboundStatus); │ 其余状态枚举约定见 package-info,待建 ├── http HengjianRequestFactory / HengjianEnvelope / HengjianRateLimiter diff --git a/docs-warehouse/hengjian/README.md b/docs-warehouse/hengjian/README.md index 1ce6e27..96e33ef 100644 --- a/docs-warehouse/hengjian/README.md +++ b/docs-warehouse/hengjian/README.md @@ -89,7 +89,8 @@ | 27 | 退货计划列表 | `POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage` | `RETURN` | ✅ | | 28 | 退货处理单列表 | `POST /v1/saleReturn/getReturnPlanHandlePage` | `RETURN` | ✅ | | 29 | 填写退货处理方式 | `POST /v1/saleReturn/handlingMethod` | `RETURN` | ✅ | -| 30 | 回调 | — | — | ❌ 文档无回调页 | +| 30 | 订单上传附件 | `POST /v1/saleOrder/createAttachment` | `OUTBOUND` | ✅ | +| 31 | 回调 | — | — | ❌ 文档无回调页 | 前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, @@ -201,7 +202,7 @@ `orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()` 落库;拿不到就报错,**不当创建成功**。 -**未接入**:订单上传附件、物流异动单取消。调用这些方法会显式抛异常,不返回 null—— +**未接入**:物流异动单取消。调用会显式抛异常,不返回 null—— 静默返回空会让调用方以为「仓说没有这单」。 ## 3. 未接入(文档已有,按需排期) @@ -256,7 +257,7 @@ **未能确认**:`handleType` 文档标 STRING、示例给数字。真机字符串和数字都试过, 两种都能过(都走到后续业务校验),**区分不出**类型要求,按示例发 Integer。 -**未接入**:订单上传附件、物流异动单取消。调用这些方法会显式抛异常,不返回 null—— +**未接入**:物流异动单取消。调用会显式抛异常,不返回 null—— 静默返回空会让调用方以为「仓说没有这单」。 #### 订单详情(`/v1/saleOrder/findOne`) @@ -846,13 +847,14 @@ warehouse-sdk-hengjian/ ├── adapter/HengjianTransferTest.java 21 个:必填 / 字符串数量 / 外部仓 / 13 状态 / 取消 ├── adapter/HengjianReturnCreateTest.java 16 个:params 包裹 / 行级四项 / 跟踪号回退 / 8 状态 ├── adapter/HengjianReturnQueryTest.java 18 个:两套形态 / 三套码表 / 四项定位 / 处理方式映射 + ├── adapter/HengjianOrderAttachmentTest.java 12 个:平铺 / 类型整数 / base64 优先 / 本地校验 ├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举 ├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径 ├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性 └── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true ``` -已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(293 个 + 4 个跳过)。 +已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(305 个 + 4 个跳过)。 ## 5. 探针用法 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java index 3b9f696..be40020 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java @@ -46,4 +46,23 @@ public interface OutboundCapable extends WarehouseAdapter { /** 拆单结果:多包裹时返回多条,带跟踪号与面单引用。 */ List packages(WarehouseContext ctx, OutboundRef ref); + + /** + * 给已下发的订单补传附件(面单 / 装箱单 / BOL / 箱标等)。写操作, + * 幂等键 {@code warehouseCode + outboundRequestNo + "attachment"}。 + * + *

与 {@link common.ecommerce.warehouse.model.OutboundCommand#attachments()} 的区别: + * 那个是下单时一起传,这个是下单后再补——面单常常要等渠道侧出单之后才有。

+ * + *

部分仓(恒健 {@code /v1/saleOrder/createAttachment})提供独立接口; + * 没有的仓默认拒绝,不静默当作已上传。

+ * + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不支持补传附件 + */ + default void uploadAttachments(WarehouseContext ctx, OutboundRef ref, + List attachments) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.OUTBOUND); + } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java index 46c4be3..903cbf9 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java @@ -106,6 +106,62 @@ public final class WarehouseOutbounds { () -> ((OutboundCapable) adapter).cancel(ctx, cmd)); } + /** + * 给已下发的订单补传附件。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + outboundRequestNo + attachment}。 + * + *

幂等键用单号 + 动作,不含附件内容:同一次补传重跑应该是幂等的, + * 但「先传面单、后传装箱单」是两次不同的动作——两次都走同一个键时, + * 第二次会被判成重复而不发。因此附件上传按单号 + 附件名做业务键: + * 同一附件重传幂等,不同附件各自一次。

+ */ + public void attachment(final OutboundRef ref, + final List attachments) { + require(WarehouseCapability.OUTBOUND, OutboundCapable.class); + if (guard == null) { + throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); + } + if (attachments == null || attachments.isEmpty()) { + throw new IllegalArgumentException("attachments must not be empty"); + } + final String orderNo = firstNonBlank(ref.outboundRequestNo(), ref.providerOrderId()); + if (orderNo == null) { + throw new IllegalArgumentException("either outboundRequestNo or providerOrderId is required"); + } + final OutboundCapable capable = (OutboundCapable) adapter; + common.ecommerce.shared.audit.CallSupport.observe(observer, ctx, "warehouse.outbound.attachment", + common.ecommerce.shared.audit.CallSupport.params("orderNo", orderNo, + "attachmentCount", attachments.size()), + r -> common.ecommerce.shared.audit.CallSupport.NO_COUNT, + () -> { + for (common.ecommerce.warehouse.model.WarehouseAttachment attachment : attachments) { + if (attachment == null) { + continue; + } + // 业务键:单号 + 附件名 + 动作;附件名是仓方要求的必填项, + // 也是「同一次补传」最自然的业务标识 + String scopeRef = orderNo + ":" + attachment.name(); + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + scopeRef, "attachment"), + () -> { + capable.uploadAttachments(ctx, ref, + java.util.Collections.singletonList(attachment)); + return attachment.name(); + }, + name -> name); + } + return null; + }); + } + + private static String firstNonBlank(String a, String b) { + if (a != null && !a.trim().isEmpty()) { + return a.trim(); + } + return b == null ? null : (b.trim().isEmpty() ? null : b.trim()); + } + /** 拆单结果与跟踪号。 */ public List packages(final OutboundRef ref) { require(WarehouseCapability.OUTBOUND, OutboundCapable.class); diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java index 87a5beb..3dd3b30 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/HengjianConstants.java @@ -92,6 +92,14 @@ public final class HengjianConstants { public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel"; /** + * 订单上传附件({@code POST},请求平铺)。 + * + *

无 token 时直接 403、不做参数校验,必填项按文档实现。 + * 响应无 data,只有 {@code code / message}。

+ */ + public static final String PATH_ORDER_ATTACHMENT = "/v1/saleOrder/createAttachment"; + + /** * 创建物流异动单。 * *

{@code trackingNo}、{@code orderNo}、{@code remark}、{@code handleType} 真机均为必填; diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java index 663c3fd..c109322 100644 --- a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianAdapter.java @@ -17,6 +17,7 @@ import common.ecommerce.hengjian.dto.HengjianReturnPlanCreateDtos; import common.ecommerce.hengjian.dto.HengjianTransferDtos; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; +import common.ecommerce.hengjian.dto.HengjianOrderAttachmentDtos; import common.ecommerce.hengjian.dto.HengjianOrderListDtos; import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos; @@ -79,6 +80,7 @@ import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnQuery; import common.ecommerce.warehouse.model.TransferQuery; +import common.ecommerce.warehouse.model.WarehouseAttachment; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.LogisticsProduct; import common.ecommerce.warehouse.model.OutboundCommand; @@ -125,6 +127,7 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti private static final String OP_ORDER_GET = "warehouse.outbound.get"; private static final String OP_ORDER_QUERY = "warehouse.outbound.query"; private static final String OP_ORDER_CANCEL = "warehouse.outbound.cancel"; + private static final String OP_ORDER_ATTACHMENT = "warehouse.outbound.attachment"; private static final String OP_TRACKING_CHANGE_CREATE = "warehouse.tracking.change.create"; private static final String OP_TRACKING_CHANGE_GET = "warehouse.tracking.change.get"; private static final String OP_FEE_STORAGE = "warehouse.fee.storage"; @@ -1080,6 +1083,100 @@ public final class HengjianAdapter implements WarehouseDirectoryCapable, Logisti } /** + * 给已下发的订单补传附件({@code POST /v1/saleOrder/createAttachment})。 + * + *

请求平铺(无 {@code params} 包裹)。响应无 data,只有 {@code code / message}, + * 所以本方法无返回值。

+ * + *

恒健要求每行 {@code name} / {@code type} 必填、{@code url} 与 {@code file} 二选一; + * 缺了本地拒绝,不把半成品发出去。

+ */ + @Override + public void uploadAttachments(WarehouseContext ctx, OutboundRef ref, + List attachments) { + String orderNo = trimToNull(ref.outboundRequestNo()); + if (orderNo == null) { + orderNo = trimToNull(ref.providerOrderId()); + } + if (orderNo == null) { + throw new IllegalArgumentException( + "hengjian attachment upload requires outboundRequestNo or providerOrderId"); + } + if (attachments == null || attachments.isEmpty()) { + throw new IllegalArgumentException("hengjian attachment upload requires attachments"); + } + + HengjianOrderAttachmentDtos.CreateAttachmentRequest body = + new HengjianOrderAttachmentDtos.CreateAttachmentRequest(); + body.orderNo = orderNo; + body.attachInfoItemRequestList = toAttachItems(attachments, orderNo); + execute(ctx, HengjianConstants.PATH_ORDER_ATTACHMENT, body, OP_ORDER_ATTACHMENT); + } + + /** 统一附件 → 恒健附件行;逐行校验。 */ + private static List toAttachItems( + List attachments, String orderNo) { + List out = + new ArrayList(attachments.size()); + for (WarehouseAttachment attachment : attachments) { + if (attachment == null) { + continue; + } + String name = trimToNull(attachment.name()); + if (name == null) { + throw new IllegalArgumentException( + "hengjian attachment for order " + orderNo + " requires name"); + } + String type = trimToNull(attachment.type()); + if (type == null) { + throw new IllegalArgumentException( + "hengjian attachment for order " + orderNo + " requires type (0-6)"); + } + String url = trimToNull(attachment.url()); + String content = trimToNull(attachment.contentBase64()); + if (url == null && content == null) { + throw new IllegalArgumentException( + "hengjian attachment " + name + " needs url or contentBase64"); + } + HengjianOrderAttachmentDtos.AttachInfoItem item = + new HengjianOrderAttachmentDtos.AttachInfoItem(); + item.name = name; + item.type = parseAttachType(type, name); + // file 优先于 url(仓方语义:给了 file 就忽略 url) + item.file = content == null ? null : HengjianOutboundMapper.stripDataUri(content); + item.url = content == null ? url : null; + item.remark = trimToNull(attachment.remark()); + out.add(item); + } + if (out.isEmpty()) { + throw new IllegalArgumentException( + "hengjian attachment upload for order " + orderNo + " has no usable attachment"); + } + return out; + } + + /** + * 附件类型:统一模型是仓方原值字符串,恒健这个接口要 INTEGER。 + * + *

认不出的值拒绝,不猜——发错类型会让仓方把面单当「其他」存。

+ */ + private static Integer parseAttachType(String raw, String name) { + try { + int value = Integer.parseInt(raw.trim()); + if (value < 0 || value > 6) { + throw new IllegalArgumentException( + "hengjian attachment type for " + name + " must be 0-6, got " + value); + } + return value; + } catch (NumberFormatException e) { + // 部分仓用词表(Shippinglabel / BOL 等);恒健这里只收数字 + throw new IllegalArgumentException( + "hengjian attachment type for " + name + + " must be an integer 0-6, got " + raw); + } + } + + /** * 取消资格预判:查详情按状态推断。 * *

恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款 / 已删除不再接受取消, diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderAttachmentDtos.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderAttachmentDtos.java new file mode 100644 index 0000000..622b2e6 --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/dto/HengjianOrderAttachmentDtos.java @@ -0,0 +1,58 @@ +package common.ecommerce.hengjian.dto; + +import com.fasterxml.jackson.annotation.JsonInclude; + +import java.util.List; + +/** + * 恒健报文结构:订单上传附件({@code POST /v1/saleOrder/createAttachment})。 + * + *

请求平铺(无 {@code params} 包裹),与创建订单一致。

+ * + *

真机情况:无 token 直接 403、不做参数校验,必填项按文档字段表: + * {@code orderNo}、{@code attachInfoItemRequestList}(非空),每行 {@code name} / {@code type}, + * 以及 {@code url} 与 {@code file} 二选一。

+ * + *

响应无 data:只有 {@code code / message}。

+ */ +public final class HengjianOrderAttachmentDtos { + + private HengjianOrderAttachmentDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateAttachmentRequest { + + /** 订单号(来源单号);必填。 */ + public String orderNo; + + /** 附件列表;必填。 */ + public List attachInfoItemRequestList; + } + + /** 一条附件。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class AttachInfoItem { + + /** 附件名称;必填。文档建议用 trackingNo 且不带后缀。 */ + public String name; + + /** 附件 URL;与 {@link #file} 二选一。 */ + public String url; + + /** + * 附件类型;必填。 + * + *

0 Shippinglabel / 1 Packinglist / 2 BOL / 3 Other / 4 CartonLabel / + * 5 PalletLabel / 6 itemlabel。文档标 INTEGER(创建订单那边是 STRING, + * 两页不一致)——这里按 integer 发。

+ */ + public Integer type; + + /** 备注。 */ + public String remark; + + /** base64 内容;给了就忽略 {@link #url}。 */ + public String file; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderAttachmentTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderAttachmentTest.java new file mode 100644 index 0000000..246a762 --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianOrderAttachmentTest.java @@ -0,0 +1,208 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.WarehouseAttachment; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.util.Arrays; +import java.util.Collections; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 订单上传附件({@code /v1/saleOrder/createAttachment})契约测试。 + */ +class HengjianOrderAttachmentTest { + + private static final WarehouseContext CTX = WarehouseContext.of( + "HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build()), + "req-1", Clock.fixed(Instant.parse("2026-11-17T00:00:00Z"), ZoneOffset.UTC)); + + private static final String OK_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"上传成功\"}"; + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static RecordingTransport uploading() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_ATTACHMENT, req -> Responses.ok(OK_BODY)); + } + + private static WarehouseAttachment urlAttachment() { + return WarehouseAttachment.builder() + .name("1ZXH1234567890").type("0") + .url("https://cdn/label.pdf").build(); + } + + // ---------------------------------------------------------------- 请求形状 + + @Test + void postsToCreateAttachment() { + RecordingTransport transport = uploading(); + adapter(transport).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(urlAttachment())); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleOrder/createAttachment", + transport.lastDataRequest().url()); + } + + /** 请求平铺(无 params 包裹),字段名与文档一致。 */ + @Test + void sendsFlatBody() { + RecordingTransport transport = uploading(); + adapter(transport).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(urlAttachment())); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"orderNo\":\"OB-1\""), body); + assertTrue(body.contains("\"attachInfoItemRequestList\":["), body); + assertTrue(body.contains("\"name\":\"1ZXH1234567890\""), body); + assertTrue(body.contains("\"url\":\"https://cdn/label.pdf\""), body); + // 类型按 INTEGER 下发 + assertTrue(body.contains("\"type\":0"), body); + assertFalse(body.contains("\"params\""), "这个接口是平铺的,body=" + body); + } + + /** 给了 base64 就忽略 url(仓方语义)。 */ + @Test + void contentBase64TakesPrecedence() { + RecordingTransport transport = uploading(); + adapter(transport).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(WarehouseAttachment.builder() + .name("label").type("0") + .url("https://cdn/label.pdf") + .contentBase64("data:application/pdf;base64,JVBERi0xLjQK") + .build())); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"file\":\"JVBERi0xLjQK\""), body); + assertFalse(body.contains("\"url\""), "有 file 时不发 url"); + assertFalse(body.contains("data:application/pdf"), "data: 前缀要剥掉"); + } + + /** 支持一次传多个附件(7 种类型)。 */ + @Test + void sendsMultipleAttachments() { + RecordingTransport transport = uploading(); + adapter(transport).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), Arrays.asList( + WarehouseAttachment.builder().name("label").type("0").url("https://cdn/l.pdf").build(), + WarehouseAttachment.builder().name("packing").type("1").url("https://cdn/p.pdf").build(), + WarehouseAttachment.builder().name("bol").type("2").url("https://cdn/b.pdf").build())); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"type\":0"), body); + assertTrue(body.contains("\"type\":1"), body); + assertTrue(body.contains("\"type\":2"), body); + } + + /** 只给单号(无 outboundRequestNo)时用 providerOrderId。 */ + @Test + void acceptsProviderOrderId() { + RecordingTransport transport = uploading(); + adapter(transport).uploadAttachments(CTX, OutboundRef.ofProviderOrderId("193252852"), + Collections.singletonList(urlAttachment())); + + assertTrue(transport.lastDataRequest().body().contains("\"orderNo\":\"193252852\"")); + } + + // ---------------------------------------------------------------- 本地校验 + + @Test + void rejectsMissingName() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(uploading()).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(WarehouseAttachment.builder() + .type("0").url("https://cdn/l.pdf").build()))); + assertTrue(ex.getMessage().contains("name"), ex.getMessage()); + } + + @Test + void rejectsMissingType() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(uploading()).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(WarehouseAttachment.builder() + .name("label").url("https://cdn/l.pdf").build()))); + assertTrue(ex.getMessage().contains("type"), ex.getMessage()); + } + + /** url 与 file 都没有时拒绝。 */ + @Test + void rejectsWithoutUrlOrContent() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(uploading()).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(WarehouseAttachment.builder() + .name("label").type("0").build()))); + assertTrue(ex.getMessage().contains("url or contentBase64"), ex.getMessage()); + } + + /** 类型必须是 0~6 的整数:认不出的拒绝,不猜。 */ + @Test + void rejectsUnknownType() { + RecordingTransport transport = uploading(); + HengjianAdapter adapter = adapter(transport); + + assertThrows(IllegalArgumentException.class, + () -> adapter.uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(WarehouseAttachment.builder() + .name("label").type("99").url("https://cdn/l.pdf").build()))); + assertThrows(IllegalArgumentException.class, + () -> adapter.uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(WarehouseAttachment.builder() + .name("label").type("Shippinglabel") + .url("https://cdn/l.pdf").build()))); + assertTrue(transport.dataRequests().isEmpty()); + } + + @Test + void rejectsEmptyAttachments() { + RecordingTransport transport = uploading(); + HengjianAdapter adapter = adapter(transport); + + assertThrows(IllegalArgumentException.class, + () -> adapter.uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.emptyList())); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 附件列表为 null 时拒绝。 */ + @Test + void rejectsNullAttachments() { + assertThrows(IllegalArgumentException.class, + () -> adapter(uploading()).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + null)); + } + + // ---------------------------------------------------------------- 失败路径 + + @Test + void businessErrorIsPropagated() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_ATTACHMENT, req -> Responses.ok( + "{\"statusCode\":500,\"status\":1,\"code\":999999," + + "\"message\":\"订单不存在\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).uploadAttachments(CTX, OutboundRef.ofRequestNo("OB-1"), + Collections.singletonList(urlAttachment()))); + assertTrue(ex.getMessage().contains("订单不存在"), ex.getMessage()); + } +}