From cde4bac44a633f659c00c19aedbf63e5534bed47 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Tue, 10 Nov 2026 11:09:52 +0800 Subject: [PATCH] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5=E4=B8=80?= =?UTF-8?q?=E5=8D=95=E5=A4=9A=E4=BB=B6=E4=B8=8B=E5=8D=95=E4=B8=8E=E8=BD=AC?= =?UTF-8?q?=E8=BF=90=E5=88=9B=E5=BB=BA=20/=20=E5=AE=A1=E6=A0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增订单一单多件:POST api.add_order_multiple,multipart/form-data, products 字段是 JSON 字符串;返回 rst.order_no 作为仓侧单号 - 新增转运:POST fba.do_fba,application/json,返回 rst.order_no, 创建后处于待审核 - 转运审核:POST fba.do_approve,无请求体,token 与 order_no 都在 query 仓库域内核的配套扩展(YQN 不受影响,原有测试全绿): - OutboundCommand 增加 splitOrder,仅声明了 SPLIT 的仓解释 - TransferCommand 增加 po / orderType / deliveryMode / deliveryWay / otherWarehouseName / labelRequirements / palletRequired / 各类贴标份数 - TransferCapable 增加默认 approve(不支持的仓显式拒绝), WarehouseOperations.approveTransfer 走幂等守卫,动作键 approve 字段映射的取舍: - logistics_type 用 carrierCode 承载;ckh 用 outboundRequestNo(要求唯一) - is_sign 模型无对应字段,固定发「否」 - order_type:Wayfair → wayfair,其余 → common - 地址超过 32 字符的部分自动拆到 address2 - 字典字段(orderType / deliveryMode / deliveryWay / labelRequirements) 只接受仓方字典原值,SDK 不做归一 - 信仓这版不收申报信息与包裹尺寸,统一模型里的对应字段不发送 - 转运仅支持 TransferType.OUTBOUND(信仓转运 = 仓到平台仓) --- README.md | 9 +- .../warehouse/capability/TransferCapable.java | 15 ++ .../ecommerce/warehouse/model/OutboundCommand.java | 25 +++ .../ecommerce/warehouse/model/TransferCommand.java | 164 +++++++++++++++++ .../warehouse/sdk/WarehouseOperations.java | 22 +++ .../common/ecommerce/xincang/XincangConstants.java | 12 ++ .../ecommerce/xincang/adapter/XincangAdapter.java | 164 ++++++++++++++++- .../xincang/adapter/XincangOrderMapper.java | 179 +++++++++++++++++++ .../xincang/adapter/XincangTransferMapper.java | 154 ++++++++++++++++ .../adapter/XincangUnsupportedOutbound.java | 49 ++++++ .../common/ecommerce/xincang/dto/XincangDtos.java | 150 ++++++++++++++++ .../ecommerce/xincang/http/XincangMultipart.java | 81 +++++++++ .../xincang/http/XincangRequestFactory.java | 36 +++- .../xincang/adapter/XincangAdapterTest.java | 10 +- .../xincang/adapter/XincangOrderTest.java | 178 +++++++++++++++++++ .../xincang/adapter/XincangProductTest.java | 15 +- .../xincang/adapter/XincangTransferTest.java | 195 +++++++++++++++++++++ 17 files changed, 1434 insertions(+), 24 deletions(-) create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java diff --git a/README.md b/README.md index 81b4efb..30370b8 100644 --- a/README.md +++ b/README.md @@ -135,7 +135,7 @@ sequenceDiagram | `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter | | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | -| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token + 商品建档 / 更新) | +| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、一单多件下单、转运创建 / 审核) | 依赖方向: ``` @@ -322,9 +322,10 @@ common.ecommerce └── xincang 信仓三方仓(warehouse-sdk-xincang) ├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流 ├── auth XincangTokenClient(GET /api.login,无 refresh) - ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper + ├── adapter XincangAdapter / XincangAdapterFactory / + │ XincangProductMapper / XincangOrderMapper / XincangTransferMapper ├── dto XincangDtos(登录 / 商品) - └── http XincangRequestFactory / XincangEnvelope / XincangRateLimiter + └── http XincangRequestFactory / XincangMultipart / XincangEnvelope / XincangRateLimiter ``` 包名统一前缀 `common.ecommerce.`,下表省略前缀。 @@ -914,7 +915,7 @@ mvn test # 全部 mvn -pl lingxing test # 单模块 mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试 -mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 令牌缓存 / 商品建档 +mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运 ``` --- diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java index 7c91790..b25bfcb 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java @@ -21,4 +21,19 @@ public interface TransferCapable extends WarehouseAdapter { * 仓不支持该调拨类型 */ TransferOrder create(WarehouseContext ctx, TransferCommand cmd); + + /** + * 审核通过调拨单。写操作,幂等键 + * {@code warehouseCode + transferRequestNo + "approve"}。 + * + *

信仓的「转运审核」({@code POST fba.do_approve})走这里: + * {@code transferRequestNo} 传仓侧转运单号(信仓 {@code order_no}, + * 即 {@code create} 返回的 {@code providerTransferNo})。

+ * + *

没有审核环节的仓默认拒绝,不静默当作成功。

+ */ + default void approve(WarehouseContext ctx, String transferRequestNo) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.WarehouseCapability.TRANSFER); + } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java index af0e062..2f931de 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java @@ -38,6 +38,13 @@ public final class OutboundCommand { private final Instant estimatedDeliveryTime; /** 下单币种;null 时为 USD。 */ private final String currency; + /** + * 仓侧拆单开关;null 表示按仓的默认规则。 + * + *

仅对声明了 {@code WarehouseCapability.SPLIT} 的仓有意义。 + * 信仓 {@code is_split}:true 拆成一单一品(每件一张面单),false 打包成一张面单。

+ */ + private final Boolean splitOrder; private OutboundCommand(Builder b) { if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) { @@ -63,6 +70,7 @@ public final class OutboundCommand { this.latestShipDate = b.latestShipDate; this.estimatedDeliveryTime = b.estimatedDeliveryTime; this.currency = b.currency; + this.splitOrder = b.splitOrder; } public static Builder builder() { @@ -144,6 +152,16 @@ public final class OutboundCommand { return currency; } + /** + * 仓侧拆单开关;null 表示按仓默认规则。 + * + *

只有声明了 {@code WarehouseCapability.SPLIT} 的仓会解释该值, + * 其余适配器应忽略它,不得自行编造拆单行为。

+ */ + public Boolean splitOrder() { + return splitOrder; + } + public static final class Builder { private String outboundRequestNo; @@ -162,6 +180,7 @@ public final class OutboundCommand { private Instant latestShipDate; private Instant estimatedDeliveryTime; private String currency; + private Boolean splitOrder; public Builder outboundRequestNo(String outboundRequestNo) { this.outboundRequestNo = outboundRequestNo; @@ -251,6 +270,12 @@ public final class OutboundCommand { return this; } + /** 仓侧拆单开关;null 表示按仓默认规则。 */ + public Builder splitOrder(Boolean splitOrder) { + this.splitOrder = splitOrder; + return this; + } + public OutboundCommand build() { return new OutboundCommand(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java index 33d36a1..cfbe34a 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java @@ -1,5 +1,7 @@ package common.ecommerce.warehouse.model; +import java.util.List; + /** * 调拨单创建命令。写操作,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。 * @@ -37,6 +39,32 @@ public final class TransferCommand { private final java.util.List tags; private final java.util.List batches; + /** + * 标签需求:{@code 产品贴} / {@code 外箱标签} / {@code 托盘标签},可多选。 + * + *

仓侧只接受它自己字典里的值,因此这里保存仓方原文(由调用方从仓的字典接口取), + * SDK 不做枚举归一,免得联想出仓方不认的标签名。

+ */ + private final List labelRequirements; + /** 是否需要打托;null 表示不传(仓按默认规则)。 */ + private final Boolean palletRequired; + /** 产品贴打印份数;null 表示不传。 */ + private final Integer productLabelCopies; + /** 外箱贴打印份数;null 表示不传。 */ + private final Integer cartonLabelCopies; + /** 托盘贴打印份数;null 表示不传。 */ + private final Integer palletLabelCopies; + /** PO 号;部分仓(信仓)要求,其余为 null。 */ + private final String po; + /** 订单类型(仓方字典值,如信仓 FBA / LTL);null 表示不传。 */ + private final String orderType; + /** 转运类型(仓方字典值);null 表示不传。 */ + private final String deliveryMode; + /** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */ + private final String deliveryWay; + /** 目的仓不在仓方字典时的自填仓库名;null 表示不传。 */ + private final String otherWarehouseName; + private TransferCommand(Builder b) { if (b.transferRequestNo == null || b.transferRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("transferRequestNo must not be blank"); @@ -83,6 +111,22 @@ public final class TransferCommand { new java.util.ArrayList(b.tags)); this.batches = java.util.Collections.unmodifiableList( new java.util.ArrayList(b.batches)); + java.util.List labels = new java.util.ArrayList(); + for (String label : b.labelRequirements) { + if (label != null && !label.trim().isEmpty()) { + labels.add(label.trim()); + } + } + this.labelRequirements = java.util.Collections.unmodifiableList(labels); + this.palletRequired = b.palletRequired; + this.productLabelCopies = b.productLabelCopies; + this.cartonLabelCopies = b.cartonLabelCopies; + this.palletLabelCopies = b.palletLabelCopies; + this.po = b.po; + this.orderType = b.orderType; + this.deliveryMode = b.deliveryMode; + this.deliveryWay = b.deliveryWay; + this.otherWarehouseName = b.otherWarehouseName; } public static Builder builder() { @@ -166,6 +210,56 @@ public final class TransferCommand { return tags; } + /** 标签需求原文(仓方字典值),可能为空列表。 */ + public List labelRequirements() { + return labelRequirements; + } + + /** 是否需要打托;null 表示不传。 */ + public Boolean palletRequired() { + return palletRequired; + } + + /** 产品贴打印份数;null 表示不传。 */ + public Integer productLabelCopies() { + return productLabelCopies; + } + + /** 外箱贴打印份数;null 表示不传。 */ + public Integer cartonLabelCopies() { + return cartonLabelCopies; + } + + /** 托盘贴打印份数;null 表示不传。 */ + public Integer palletLabelCopies() { + return palletLabelCopies; + } + + /** PO 号;部分仓要求,未设置为 null。 */ + public String po() { + return po; + } + + /** 订单类型(仓方字典值);null 表示不传。 */ + public String orderType() { + return orderType; + } + + /** 转运类型(仓方字典值);null 表示不传。 */ + public String deliveryMode() { + return deliveryMode; + } + + /** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */ + public String deliveryWay() { + return deliveryWay; + } + + /** 目的仓不在字典时的自填仓库名;null 表示不传。 */ + public String otherWarehouseName() { + return otherWarehouseName; + } + public java.util.List batches() { return batches; } @@ -225,6 +319,16 @@ public final class TransferCommand { private final java.util.List lines = new java.util.ArrayList(); private final java.util.List tags = new java.util.ArrayList(); private final java.util.List batches = new java.util.ArrayList(); + private final java.util.List labelRequirements = new java.util.ArrayList(); + private Boolean palletRequired; + private Integer productLabelCopies; + private Integer cartonLabelCopies; + private Integer palletLabelCopies; + private String po; + private String orderType; + private String deliveryMode; + private String deliveryWay; + private String otherWarehouseName; public Builder transferRequestNo(String v) { this.transferRequestNo = v; @@ -331,6 +435,66 @@ public final class TransferCommand { return this; } + /** 标签需求(仓方字典原文),可多次调用。 */ + public Builder labelRequirement(String v) { + this.labelRequirements.add(v); + return this; + } + + /** 是否需要打托;null 表示不传。 */ + public Builder palletRequired(Boolean v) { + this.palletRequired = v; + return this; + } + + /** 产品贴打印份数;null 表示不传。 */ + public Builder productLabelCopies(Integer v) { + this.productLabelCopies = v; + return this; + } + + /** 外箱贴打印份数;null 表示不传。 */ + public Builder cartonLabelCopies(Integer v) { + this.cartonLabelCopies = v; + return this; + } + + /** 托盘贴打印份数;null 表示不传。 */ + public Builder palletLabelCopies(Integer v) { + this.palletLabelCopies = v; + return this; + } + + /** PO 号;部分仓要求。 */ + public Builder po(String v) { + this.po = v; + return this; + } + + /** 订单类型(仓方字典值)。 */ + public Builder orderType(String v) { + this.orderType = v; + return this; + } + + /** 转运类型(仓方字典值)。 */ + public Builder deliveryMode(String v) { + this.deliveryMode = v; + return this; + } + + /** 转运方式 / 配送方式(仓方字典值)。 */ + public Builder deliveryWay(String v) { + this.deliveryWay = v; + return this; + } + + /** 目的仓不在字典时的自填仓库名。 */ + public Builder otherWarehouseName(String v) { + this.otherWarehouseName = v; + return this; + } + public TransferCommand build() { return new TransferCommand(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index e482497..769d983 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -106,6 +106,28 @@ public final class WarehouseOperations { return result.value(); } + /** + * 审核通过调拨单。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + transferRequestNo + approve}。 + * + * @param transferRequestNo 仓侧调拨单号({@code create} 返回的 {@code providerTransferNo}) + */ + public void approveTransfer(final String transferRequestNo) { + require(WarehouseCapability.TRANSFER, TransferCapable.class); + if (guard == null) { + throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); + } + final TransferCapable capable = (TransferCapable) adapter; + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), + transferRequestNo, "approve"), + () -> { + capable.approve(ctx, transferRequestNo); + return transferRequestNo; + }, + ref -> ref); + } + /** 库存视图。 */ public InventoryView inventory() { return new InventoryView(); diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java index 58f3f5f..4551b76 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java @@ -50,6 +50,18 @@ public final class XincangConstants { /** 产品列表;{@code state} 必填:0 临时产品 / 1 正式产品。 */ public static final String PATH_PRODUCT_LIST = "/api.productlist"; + /** 新增订单一单多件({@code multipart/form-data};一票一件请用 {@code api.add_order})。 */ + public static final String PATH_ORDER_ADD_MULTIPLE = "/api.add_order_multiple"; + + /** 新增转运({@code application/json})。 */ + public static final String PATH_TRANSFER_CREATE = "/fba.do_fba"; + + /** 转运审核;{@code order_no} 为转运单号,走 query。 */ + public static final String PATH_TRANSFER_APPROVE = "/fba.do_approve"; + + /** 转运列表。 */ + public static final String PATH_TRANSFER_LIST = "/fba.fbalist"; + /** 登录响应里的 token 归入哪个作用域;信仓用 query 参数传递,不是 {@code Authorization} 头。 */ public static final String TOKEN_LOCATION = "query"; diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java index 8a783d3..4a90428 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java @@ -10,15 +10,31 @@ import common.ecommerce.shared.spi.AccessToken; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.TokenStore; +import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.capability.OutboundCapable; +import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; +import common.ecommerce.warehouse.error.WarehouseException; +import common.ecommerce.warehouse.model.CancelCommand; +import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.model.CancelResult; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundOrder; +import common.ecommerce.warehouse.model.OutboundQuery; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.PackageResult; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.auth.XincangTokenClient; import common.ecommerce.xincang.dto.XincangDtos; import common.ecommerce.xincang.http.XincangEnvelope; +import common.ecommerce.xincang.http.XincangMultipart; import common.ecommerce.xincang.http.XincangRateLimiter; import common.ecommerce.xincang.http.XincangRequestFactory; @@ -35,13 +51,15 @@ import java.util.Map; * 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里 * (新增 / 更新产品的请求体 schema 里也要求一份,见 {@link XincangRequestFactory})。

* - *

已实现能力:商品建档 / 更新({@link WarehouseCapability#PRODUCT})。 - * 其余能力位不声明,门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException}。

+ *

已实现能力:商品建档 / 更新({@code PRODUCT})、出库下单({@code OUTBOUND})、 + * 转运创建 / 审核({@code TRANSFER})。出库的查询 / 取消 / 包裹字段未接入, + * 调用会显式抛不支持异常,不返回空集合。

* *

适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。

*/ -public final class XincangAdapter implements WarehouseProductCapable { +public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable, + TransferCapable { private static final String OP_PRODUCT_QUERY = "warehouse.product.query"; private static final String OP_PRODUCT_ADD = "warehouse.product.add"; @@ -89,7 +107,8 @@ public final class XincangAdapter implements WarehouseProductCapable { @Override public EnumSet capabilities() { - return EnumSet.of(WarehouseCapability.PRODUCT); + return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, + WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT); } /** @@ -159,6 +178,111 @@ public final class XincangAdapter implements WarehouseProductCapable { return null; } + // ------------------------------------------------------------------ 出库 + + /** + * 下发出库单(一单多件)。 + * + *

信仓下单有两个接口:{@code api.add_order}(一票一件)与 + * {@code api.add_order_multiple}(一单多件)。统一模型允许一单多行, + * 所以这里固定走多件接口;单行订单也走它。

+ * + *

该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON; + * 返回的 {@code rst.order_no} 是信仓系统单号({@code DS-...}), + * {@code rst.order_id} 是内部 id,优先取单号。

+ * + *

查询 / 取消 / 包裹等接口本轮未接入,调用会显式抛不支持异常。

+ */ + @Override + public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { + Map form = XincangOrderMapper.toForm(ctx, cmd, json); + String raw = executeMultipart(ctx, XincangConstants.PATH_ORDER_ADD_MULTIPLE, form, + "warehouse.outbound.create"); + XincangDtos.OrderResult result = json.fromJson(raw, XincangDtos.OrderResponse.class).rst; + if (result == null || blank(result.orderNo)) { + throw WarehouseException.builder() + .message("xincang create order returned no rst.order_no: " + safeRelay(raw)) + .operation("warehouse.outbound.create") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .rawResponse(safeRelay(raw)) + .build(); + } + return OutboundReceipt.of(cmd.outboundRequestNo(), result.orderNo, null); + } + + @Override + public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { + throw XincangUnsupportedOutbound.getUnsupported(ctx); + } + + @Override + public Page query(WarehouseContext ctx, OutboundQuery query) { + throw XincangUnsupportedOutbound.queryUnsupported(ctx); + } + + @Override + public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { + throw XincangUnsupportedOutbound.checkCancelUnsupported(ctx); + } + + @Override + public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { + throw XincangUnsupportedOutbound.cancelUnsupported(ctx); + } + + @Override + public List packages(WarehouseContext ctx, OutboundRef ref) { + throw XincangUnsupportedOutbound.packagesUnsupported(ctx); + } + + // ------------------------------------------------------------------ 调拨 / 转运 + + /** + * 新增转运({@code POST fba.do_fba})。 + * + *

信仓的转运是从信仓发往平台仓,统一模型里用 {@code TransferType.OUTBOUND}。 + * 字典字段(订单类型 / 转运类型 / 转运方式 / 标签需求)只接受信仓字典原值, + * 由调用方传入,SDK 不做归一。

+ */ + @Override + public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { + String productsJson = json.toJson(XincangTransferMapper.products(cmd)); + XincangDtos.TransferRequest body = XincangTransferMapper.toRequest(cmd, ctx, productsJson); + String raw = execute(ctx, XincangConstants.PATH_TRANSFER_CREATE, body, login(ctx), + "warehouse.transfer.create"); + XincangDtos.TransferResult result = json.fromJson(raw, XincangDtos.TransferResponse.class).rst; + if (result == null || blank(result.orderNo)) { + throw WarehouseException.builder() + .message("xincang transfer returned no rst.order_no: " + safeRelay(raw)) + .operation("warehouse.transfer.create") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .rawResponse(safeRelay(raw)) + .build(); + } + return XincangTransferMapper.toCreated(cmd, result.orderNo); + } + + /** + * 转运审核({@code POST fba.do_approve?token=&order_no=})。 + * + *

注意是 POST 但无请求体,参数全在 query。

+ * + * @param transferRequestNo 信仓转运单号,即 {@link #create} 返回的 {@code providerTransferNo} + */ + @Override + public void approve(WarehouseContext ctx, String transferRequestNo) { + Map params = new LinkedHashMap(); + params.put("order_no", transferRequestNo); + executePostQuery(ctx, XincangConstants.PATH_TRANSFER_APPROVE, params, + "warehouse.transfer.approve"); + } + // ------------------------------------------------------------------ internals /** 写接口:JSON 请求体(含 token)+ query token。 */ @@ -171,6 +295,26 @@ public final class XincangAdapter implements WarehouseProductCapable { return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } + /** 写接口:multipart 表单 + query token(信仓一单多件下单)。 */ + private String executeMultipart(WarehouseContext ctx, String path, Map form, + String operation) { + rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); + HttpRequest req = XincangMultipart.post(ctx.endpointBaseUrl(), path, form, + login(ctx).value(), operation); + HttpResponse resp = transport.execute(req); + return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); + } + + /** POST 但无请求体:参数全在 query(转运审核)。 */ + private String executePostQuery(WarehouseContext ctx, String path, Map params, + String operation) { + rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); + HttpRequest req = requestFactory.postWithoutBodyWithToken(ctx.endpointBaseUrl(), path, params, + login(ctx).value(), operation); + HttpResponse resp = transport.execute(req); + return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); + } + /** 读接口:query token。 */ private String executeGet(WarehouseContext ctx, String path, Map params, AccessToken token, String operation) { @@ -189,4 +333,16 @@ public final class XincangAdapter implements WarehouseProductCapable { static String tokenKey(ChannelSecret secret) { return XincangConstants.ADAPTER_ID + ":" + secret.appKey(); } + + private static boolean blank(String v) { + return v == null || v.trim().isEmpty(); + } + + /** 原始响应可能含收件人信息,异常里只留首段。 */ + private static String safeRelay(String raw) { + if (raw == null) { + return null; + } + return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; + } } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java new file mode 100644 index 0000000..2e1edf0 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java @@ -0,0 +1,179 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.http.JsonCodec; +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.error.ValidationException; +import common.ecommerce.shared.model.Platform; +import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.xincang.XincangConstants; +import common.ecommerce.xincang.dto.XincangDtos; + +import java.time.Instant; +import java.time.LocalDateTime; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; + +/** + * 信仓出库下单报文映射({@code POST api.add_order_multiple})。 + * + *

该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON 字符串。 + * 平台字段名只出现在本类与 {@link XincangDtos}。

+ * + *

文档没有对应字段的就不发:申报信息(HS / 原产国 / 申报价值)、包裹尺寸等 + * 统一模型里有,但信仓这版接口不收,硬塞只会被忽略或报错。

+ */ +public final class XincangOrderMapper { + + /** 信仓要求发货时间格式 {@code yyyy-MM-dd HH:mm:ss}(北京时间)。 */ + private static final DateTimeFormatter REQUIRED_DELIVERY_TIME = + DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); + /** 地址 1 上限 32 字符,超出部分走 address2。 */ + private static final int ADDRESS_MAX = 32; + /** 订单类型:信仓只接受 common / wayfair。 */ + static final String ORDER_TYPE_COMMON = "common"; + static final String ORDER_TYPE_WAYFAIR = "wayfair"; + /** 签名服务:信仓只收「是 / 否」,模型里没有该字段,默认否。 */ + private static final String SIGN_NOT_REQUIRED = "否"; + + private XincangOrderMapper() { + } + + /** + * 统一命令 → 信仓一单多件下单表单。 + * + * @param ctx 本次调用上下文(取仓编码) + * @param cmd 出库命令 + * @param json 用于序列化 {@code products} + * @throws ValidationException 缺少仓编码或收件人必填项 + */ + public static Map toForm(WarehouseContext ctx, OutboundCommand cmd, JsonCodec json) { + ShipTo shipTo = cmd.shipTo(); + requireText(shipTo.name(), "shipTo.name", ctx); + requireText(shipTo.phone(), "shipTo.phone", ctx); + requireText(shipTo.countryCode(), "shipTo.countryCode", ctx); + requireText(shipTo.stateOrProvince(), "shipTo.stateOrProvince", ctx); + requireText(shipTo.city(), "shipTo.city", ctx); + requireText(shipTo.postalCode(), "shipTo.postalCode", ctx); + requireText(shipTo.addressLine1(), "shipTo.addressLine1", ctx); + + String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); + requireText(warehouseCode, "warehouseCode", ctx); + // 信仓 logistics_type 是必填的物流方式字典值,这里用 carrierCode 承载 + requireText(cmd.carrierCode(), "carrierCode (信仓 logistics_type)", ctx); + + Map form = new LinkedHashMap(); + form.put("order_type", orderTypeOf(cmd.salesPlatform())); + form.put("warehouse_code", warehouseCode); + // ckh = 参考号,信仓要求唯一;用 OMS 出库单号,便于回查 + form.put("ckh", cmd.outboundRequestNo()); + + Address address = splitAddress(shipTo.addressLine1()); + form.put("country", shipTo.countryCode().trim()); + form.put("province", shipTo.stateOrProvince().trim()); + form.put("city", shipTo.city().trim()); + form.put("address", address.line1); + putIfPresent(form, "address2", address.line2); + form.put("postcode", shipTo.postalCode().trim()); + form.put("receive_user", shipTo.name().trim()); + form.put("phone", shipTo.phone().trim()); + putIfPresent(form, "email", shipTo.email()); + form.put("logistics_type", cmd.carrierCode().trim()); + form.put("is_sign", SIGN_NOT_REQUIRED); + form.put("products", productsJson(cmd.lines(), json)); + + // 不传 is_split 时信仓默认 1(拆单);只有调用方显式给值才下发 + if (cmd.splitOrder() != null) { + form.put("is_split", cmd.splitOrder() ? "1" : "0"); + } + Instant latest = cmd.latestShipDate(); + if (latest != null) { + form.put("required_delivery_time", REQUIRED_DELIVERY_TIME.format( + LocalDateTime.ofInstant(latest, XincangConstants.SYSTEM_ZONE))); + } + putIfPresent(form, "remark", cmd.remark()); + return form; + } + + /** 商品明细:{@code [{"product_sku":"...","sku_count":"1"}, ...]}。 */ + static String productsJson(List lines, JsonCodec json) { + List products = new ArrayList(lines.size()); + for (OutboundLine line : lines) { + XincangDtos.OrderProduct product = new XincangDtos.OrderProduct(); + product.productSku = skuOf(line); + product.skuCount = String.valueOf(line.quantity()); + products.add(product); + } + return json.toJson(products); + } + + /** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */ + static String skuOf(OutboundLine line) { + String providerSku = line.providerSku(); + if (providerSku != null && !providerSku.trim().isEmpty()) { + return providerSku.trim(); + } + return line.omsSku(); + } + + /** + * 信仓订单类型只接受 {@code common} / {@code wayfair}。 + * + *

Wayfair 渠道走 {@code wayfair};其余平台走 {@code common}。 + * 信仓不区分其它平台,不做臆造映射。

+ */ + static String orderTypeOf(Platform platform) { + return platform == Platform.WAYFAIR ? ORDER_TYPE_WAYFAIR : ORDER_TYPE_COMMON; + } + + /** 地址超过 32 字符的部分截到 address2,避免被仓侧截断丢信息。 */ + static Address splitAddress(String address) { + String trimmed = address.trim(); + if (trimmed.length() <= ADDRESS_MAX) { + return new Address(trimmed, null); + } + return new Address(trimmed.substring(0, ADDRESS_MAX), trimmed.substring(ADDRESS_MAX)); + } + + /** 拆好的地址。 */ + static final class Address { + final String line1; + final String line2; + + Address(String line1, String line2) { + this.line1 = line1; + this.line2 = line2; + } + } + + private static void putIfPresent(Map form, String key, String value) { + if (value != null && !value.trim().isEmpty()) { + form.put(key, value.trim()); + } + } + + private static String requireText(String value, String field, WarehouseContext ctx) { + if (value == null || value.trim().isEmpty()) { + throw new ValidationException(ChannelException.builder() + .message("xincang outbound requires " + field) + .operation("warehouse.outbound.create") + .provider(WarehouseProvider.XINCANG.name()) + .requestId(ctx.requestId()) + .retryable(false)); + } + return value.trim(); + } + + private static String firstNonBlank(String a, String b) { + if (a != null && !a.trim().isEmpty()) { + return a.trim(); + } + return b == null ? null : b.trim(); + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java new file mode 100644 index 0000000..6c3e4e9 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java @@ -0,0 +1,154 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.error.ValidationException; +import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.model.TransferStatus; +import common.ecommerce.warehouse.model.TransferType; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.xincang.dto.XincangDtos; + +import java.time.LocalDate; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.List; + +/** + * 信仓转运 / 调拨报文映射({@code POST fba.do_fba})。 + * + *

信仓的「转运」= 从信仓发货到平台仓(FBA / 其它),在统一模型里对应 + * {@link TransferType#OUTBOUND}:发货仓是信仓自己,目的仓是平台仓。

+ * + *

字典字段({@code order_type} / {@code delivery_mode} / {@code delivery_way} / + * {@code label_requirement})信仓只认它自己字典的原值,调用方需从字典接口取; + * SDK 不做枚举归一,也不猜测取值。

+ */ +public final class XincangTransferMapper { + + private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd"); + /** 目的仓不在字典里时的固定写法(文档要求)。 */ + static final String OTHER_WAREHOUSE_NAME = "其他仓库"; + /** 标签需求多选分隔符。 */ + private static final String LABEL_SEPARATOR = ","; + + private XincangTransferMapper() { + } + + /** 统一命令 → 信仓新增转运请求。 */ + public static XincangDtos.TransferRequest toRequest(TransferCommand cmd, WarehouseContext ctx, + String productsJson) { + if (cmd.type() != TransferType.OUTBOUND) { + throw validation(ctx, "xincang transfer only supports OUTBOUND (warehouse -> platform), got " + + cmd.type()); + } + XincangDtos.TransferRequest req = new XincangDtos.TransferRequest(); + req.fbaNo = cmd.transferRequestNo(); + req.po = firstNonBlank(cmd.po(), cmd.transferRequestNo()); + req.fromWarehouseName = require(cmd.fromWarehouseCode(), + "fromWarehouseCode (信仓 from_warehouse_name)", ctx); + req.destWarehouseName = require(cmd.toWarehouseCode(), + "toWarehouseCode (信仓 dest_warehouse_name)", ctx); + req.otherWarehouse = blankToNull(cmd.otherWarehouseName()); + req.orderType = blankToNull(cmd.orderType()); + req.deliveryMode = require(cmd.deliveryMode(), "deliveryMode (信仓转运类型字典值)", ctx); + req.deliveryWay = require(cmd.deliveryWay(), "deliveryWay (信仓转运方式字典值)", ctx); + req.preSendTime = formatDate(cmd.estimateOutboundDate()); + if (req.preSendTime == null) { + throw validation(ctx, "estimateOutboundDate is required (信仓 pre_send_time)"); + } + if (cmd.palletRequired() == null) { + throw validation(ctx, "palletRequired is required (信仓 is_pallet)"); + } + req.isPallet = booleanText(cmd.palletRequired()); + req.labelRequirement = cmd.labelRequirements().isEmpty() ? null : join(cmd.labelRequirements()); + req.products = productsJson; + req.remark = blankToNull(cmd.remark()); + req.productPrintCopies = copies(cmd.productLabelCopies()); + req.ctnPrintCopies = copies(cmd.cartonLabelCopies()); + req.palletPrintCopies = copies(cmd.palletLabelCopies()); + return req; + } + + /** 转运单创建结果 → 统一模型;信仓只回 {@code order_no},其余字段留空。 */ + public static TransferOrder toCreated(TransferCommand cmd, String providerTransferNo) { + return TransferOrder.builder() + .transferRequestNo(cmd.transferRequestNo()) + .providerTransferNo(providerTransferNo) + .fromWarehouseCode(cmd.fromWarehouseCode()) + .toWarehouseCode(cmd.toWarehouseCode()) + .type(cmd.type()) + // 新增成功后处于待审核;审核走 approve + .status(TransferStatus.PENDING_REVIEW) + .rawStatus("0") + .build(); + } + + /** 产品明细:{@code [{"product_no":"SKU","sku_count":"1"}]}。 */ + public static List products(TransferCommand cmd) { + List products = + new ArrayList(cmd.lines().size()); + for (TransferCommand.TransferLine line : cmd.lines()) { + XincangDtos.TransferProduct product = new XincangDtos.TransferProduct(); + product.productNo = line.providerSku(); + product.skuCount = String.valueOf(line.quantity()); + products.add(product); + } + return products; + } + + /** 打托:true → 是 / false → 否 / null → 不传。 */ + private static String booleanText(Boolean value) { + if (value == null) { + return null; + } + return value ? "是" : "否"; + } + + private static String copies(Integer copies) { + return copies == null ? null : String.valueOf(copies); + } + + private static String formatDate(LocalDate date) { + return date == null ? null : DATE.format(date); + } + + private static String join(List values) { + StringBuilder sb = new StringBuilder(); + for (String value : values) { + if (sb.length() > 0) { + sb.append(LABEL_SEPARATOR); + } + sb.append(value); + } + return sb.toString(); + } + + private static String require(String value, String field, WarehouseContext ctx) { + if (value == null || value.trim().isEmpty()) { + throw validation(ctx, field + " is required for xincang transfer"); + } + return value.trim(); + } + + private static String firstNonBlank(String a, String fallback) { + if (a != null && !a.trim().isEmpty()) { + return a.trim(); + } + return fallback; + } + + private static String blankToNull(String v) { + return v == null || v.trim().isEmpty() ? null : v.trim(); + } + + private static ValidationException validation(WarehouseContext ctx, String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation("warehouse.transfer.create") + .provider(WarehouseProvider.XINCANG.name()) + .requestId(ctx.requestId()) + .retryable(false)); + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java new file mode 100644 index 0000000..0de5d3b --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java @@ -0,0 +1,49 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.error.ValidationException; +import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.sdk.WarehouseContext; + + +/** + * 信仓暂时不支持的出库 / 调拨能力。 + * + *

本轮只接入「新增订单」与「转运创建 / 审核」,查询、取消、包裹都还没接。 + * 这里统一抛 {@link ValidationException}({@code retryable=false}),不返回空集合—— + * 静默返回 {@code null} / 空会让调用方以为「仓说没有这单」。

+ */ +final class XincangUnsupportedOutbound { + + private XincangUnsupportedOutbound() { + } + + static ValidationException queryUnsupported(WarehouseContext ctx) { + throw unsupported(ctx, "warehouse.outbound.query"); + } + + static ValidationException getUnsupported(WarehouseContext ctx) { + throw unsupported(ctx, "warehouse.outbound.get"); + } + + static ValidationException checkCancelUnsupported(WarehouseContext ctx) { + throw unsupported(ctx, "warehouse.outbound.checkCancel"); + } + + static ValidationException cancelUnsupported(WarehouseContext ctx) { + throw unsupported(ctx, "warehouse.outbound.cancel"); + } + + static ValidationException packagesUnsupported(WarehouseContext ctx) { + throw unsupported(ctx, "warehouse.outbound.packages"); + } + + private static ValidationException unsupported(WarehouseContext ctx, String operation) { + return new ValidationException(ChannelException.builder() + .message("xincang does not implement " + operation + " yet") + .operation(operation) + .provider(WarehouseProvider.XINCANG.name()) + .requestId(ctx.requestId()) + .retryable(false)); + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java index ad34d40..5cd7db0 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java @@ -179,4 +179,154 @@ public final class XincangDtos { @JsonProperty("state") public String state; } + + /** + * 新增订单(一单多件)请求中的一条商品。 + * + *

信仓把整组商品 JSON 序列化后放进 multipart 的 {@code products} 字段。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class OrderProduct { + + /** 产品 SKU。 */ + @JsonProperty("product_sku") + public String productSku; + + /** 数量(字符串)。 */ + @JsonProperty("sku_count") + public String skuCount; + } + + /** + * 新增订单(一单多件)响应中的 {@code rst}。 + */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderResult { + + /** 信仓系统单号(DS-...)。 */ + @JsonProperty("order_no") + public String orderNo; + + /** 信仓内部订单 id。 */ + @JsonProperty("order_id") + public String orderId; + } + + /** + * 新增转运请求({@code POST fba.do_fba})。 + * + *

附件字段(产品贴 / 外箱贴 / 托盘贴 / BOL)要求先用 {@code upload.files} 上传, + * 再把它返回的 {@code data.data} 对象原样放进来;统一模型不承载附件,本轮不发送。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class TransferRequest { + + /** 转运单号(业务侧),必填。 */ + @JsonProperty("fba_no") + public String fbaNo; + + /** PO 号,必填。 */ + @JsonProperty("po") + public String po; + + /** 发货仓(仓方字典名称),必填。 */ + @JsonProperty("from_warehouse_name") + public String fromWarehouseName; + + /** 目的仓(仓方字典名称),必填。 */ + @JsonProperty("dest_warehouse_name") + public String destWarehouseName; + + /** 其它仓库名;目的仓选「其他仓库」时填。 */ + @JsonProperty("other_warehouse") + public String otherWarehouse; + + /** 转运类型(订单类型字典值),必填。 */ + @JsonProperty("order_type") + public String orderType; + + /** 转运类型(转运类型字典值),必填。 */ + @JsonProperty("delivery_mode") + public String deliveryMode; + + /** 转运方式 / 配送方式(字典值),必填。 */ + @JsonProperty("delivery_way") + public String deliveryWay; + + /** 预约发货时间 {@code yyyy-MM-dd}。 */ + @JsonProperty("pre_send_time") + public String preSendTime; + + /** 标签需求,多选用英文逗号分隔,如 {@code 产品贴,外箱标签}。 */ + @JsonProperty("label_requirement") + public String labelRequirement; + + /** 是否需要打托:{@code 是} / {@code 否}。 */ + @JsonProperty("is_pallet") + public String isPallet; + + /** 产品明细 JSON 字符串。 */ + @JsonProperty("products") + public String products; + + /** 备注。 */ + @JsonProperty("remark") + public String remark; + + /** 产品贴打印份数。 */ + @JsonProperty("product_print_copies") + public String productPrintCopies; + + /** 外箱贴打印份数。 */ + @JsonProperty("ctn_print_copies") + public String ctnPrintCopies; + + /** 托盘贴打印份数。 */ + @JsonProperty("pallet_print_copies") + public String palletPrintCopies; + } + + /** 新增转运请求里的产品明细(序列化进 {@code products} 字符串)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class TransferProduct { + + /** 产品 SKU,必填。 */ + @JsonProperty("product_no") + public String productNo; + + /** 数量(字符串),必填。 */ + @JsonProperty("sku_count") + public String skuCount; + + /** 备注。 */ + @JsonProperty("remark") + public String remark; + } + + /** 转运单创建结果 {@code rst}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class TransferResult { + + /** 信仓转运单号(LTL...),审核时传它。 */ + @JsonProperty("order_no") + public String orderNo; + } + + /** 新增订单响应外层,用于取 {@code rst}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderResponse { + + /** 下单结果;业务失败时为 null。 */ + @JsonProperty("rst") + public OrderResult rst; + } + + /** 新增转运响应外层,用于取 {@code rst}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class TransferResponse { + + /** 转运结果;业务失败时为 null。 */ + @JsonProperty("rst") + public TransferResult rst; + } } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java new file mode 100644 index 0000000..6d942d5 --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java @@ -0,0 +1,81 @@ +package common.ecommerce.xincang.http; + +import common.ecommerce.http.HttpRequest; + +import java.io.UnsupportedEncodingException; +import java.net.URLEncoder; +import java.util.Map; +import java.util.TreeMap; + +/** + * multipart/form-data 请求体构造。 + * + *

信仓「新增订单一单多件」要求 {@code multipart/form-data},字段值里的 + * {@code products} 本身就是一段 JSON 字符串。这里用固定 boundary, + * 保证同一份入参生成的报文每次都一样,便于契约测试断言。

+ */ +public final class XincangMultipart { + + /** 固定 boundary:报文可预测。 */ + static final String BOUNDARY = "----commonEcommerceXincangBoundary"; + /** 与 boundary 配套的 Content-Type。 */ + public static final String CONTENT_TYPE = "multipart/form-data; boundary=" + BOUNDARY; + + private XincangMultipart() { + } + + /** 构造一个不带文件、只有文本字段的 multipart 请求。 */ + public static HttpRequest post(String baseUrl, String path, Map form, + String token, String operation) { + return HttpRequest.builder() + .method("POST") + .url(trimTrailingSlash(baseUrl) + path + + "?token=" + urlEncode(token)) + .contentType(CONTENT_TYPE) + .body(body(form)) + .operation(operation) + .build(); + } + + /** + * 字段按 key 升序输出(信仓文档不要求顺序,固定顺序只为可断言)。 + * + *

值为 null 的字段跳过——可选字段没给就不发,避免把空串误当成业务值。

+ */ + static String body(Map form) { + StringBuilder sb = new StringBuilder(); + Map sorted = new TreeMap(); + if (form != null) { + for (Map.Entry e : form.entrySet()) { + if (e.getValue() != null) { + sorted.put(e.getKey(), e.getValue()); + } + } + } + for (Map.Entry e : sorted.entrySet()) { + sb.append("--").append(BOUNDARY).append("\r\n") + .append("Content-Disposition: form-data; name=\"").append(e.getKey()).append("\"\r\n") + .append("\r\n") + .append(e.getValue()).append("\r\n"); + } + sb.append("--").append(BOUNDARY).append("--\r\n"); + return sb.toString(); + } + + private static String trimTrailingSlash(String url) { + String trimmed = url.trim(); + int end = trimmed.length(); + while (end > 0 && trimmed.charAt(end - 1) == '/') { + end--; + } + return trimmed.substring(0, end); + } + + private static String urlEncode(String v) { + try { + return URLEncoder.encode(v == null ? "" : v, "UTF-8"); + } catch (UnsupportedEncodingException e) { + throw new IllegalStateException(e); + } + } +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java index 8417dd4..aea6eb8 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java @@ -36,8 +36,38 @@ public final class XincangRequestFactory { return get(baseUrl, XincangConstants.PATH_LOGIN, query, operation); } + /** + * 业务 POST:参数全部放 query、无请求体。 + * + *

信仓「转运审核」({@code POST fba.do_approve?token=&order_no=})就是这种形态: + * 方法必须是 POST,但文档 body 为 none。

+ */ + public HttpRequest postWithoutBodyWithToken(String baseUrl, String path, Map params, + String token, String operation) { + Map query = new LinkedHashMap<>(); + if (params != null) { + query.putAll(params); + } + query.put(XincangConstants.QUERY_TOKEN, requireText(token, + "xincang requires a token; call login first")); + return HttpRequest.builder() + .method("POST") + .url(urlWithQuery(baseUrl, path, query)) + .operation(operation) + .build(); + } + /** GET:业务参数全部放 query。 */ public HttpRequest get(String baseUrl, String path, Map params, String operation) { + return HttpRequest.builder() + .method("GET") + .url(urlWithQuery(baseUrl, path, params)) + .operation(operation) + .build(); + } + + /** 拼 {@code base + path?k=v},null 值跳过。 */ + private String urlWithQuery(String baseUrl, String path, Map params) { StringBuilder url = new StringBuilder(trimTrailingSlash(baseUrl)).append(path); if (params != null && !params.isEmpty()) { url.append('?'); @@ -53,11 +83,7 @@ public final class XincangRequestFactory { first = false; } } - return HttpRequest.builder() - .method("GET") - .url(url.toString()) - .operation(operation) - .build(); + return url.toString(); } /** diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java index 9b7cfb5..dfb83a4 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java @@ -114,14 +114,16 @@ class XincangAdapterTest { } @Test - void declaresProductOnly() { + void declaresImplementedCapabilities() { XincangAdapter adapter = adapter(); assertEquals(WarehouseProvider.XINCANG, adapter.provider()); assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId()); - assertEquals(EnumSet.of(WarehouseCapability.PRODUCT), adapter.capabilities(), - "当前只落地商品建档,不声明其它能力位"); + assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, + WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT), adapter.capabilities()); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT)); - assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND)); + assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND)); + // 库存 / 退货等未接入,仍是 false + assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY)); } } diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java new file mode 100644 index 0000000..adda5c6 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java @@ -0,0 +1,178 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.InMemoryLockProvider; +import common.ecommerce.shared.testkit.InMemoryTokenStore; +import common.ecommerce.shared.testkit.MutableClock; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.shared.model.Platform; +import common.ecommerce.warehouse.WarehouseCapability; +import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.model.LabelMode; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.xincang.XincangConstants; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Duration; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * 信仓出库下单(一单多件)契约测试。 + */ +class XincangOrderTest { + + private static final String BASE = XincangConstants.TEST_BASE_URL; + private static final String APP_KEY = "ak-1"; + private static final String TOKEN = "{T-1}"; + + private RecordingTransport transport; + private MutableClock clock; + private XincangAdapter adapter; + + @BeforeEach + void setUp() { + transport = RecordingTransport.create(); + clock = MutableClock.atUtc("2026-11-10T00:00:00Z"); + transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok( + "{\"rst\":{\"id\":\"c-1\",\"token\":\"" + TOKEN + "\",\"token_expire_time\":\"" + + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)), + XincangConstants.SYSTEM_ZONE) + .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")) + + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}")); + adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(), + new InMemoryTokenStore(), new InMemoryLockProvider(), clock); + } + + private static WarehouseContext ctx() { + return WarehouseContext.of("XC-CA-3790", WarehouseProvider.XINCANG, "CA-3790", + WarehouseConnection.of(BASE, ChannelSecret.builder() + .appKey(APP_KEY).appSecret("sk").build()), + "req-1", Clock.systemUTC()); + } + + private static OutboundCommand command(Boolean split) { + OutboundCommand.Builder b = OutboundCommand.builder() + .outboundRequestNo("OB-20261110-001") + .orderRef("SO-1") + .labelMode(LabelMode.WAREHOUSE_LABEL) + .salesPlatform(Platform.AMAZON_SC) + .carrierCode("FEDEX-G") + .warehouseId("CA-3790") + .shipTo(ShipTo.builder() + .name("Receiver") + .phone("5550000") + .countryCode("US") + .stateOrProvince("CA") + .city("Fontana") + .addressLine1("3790 DE FOREST CIRCLE, UNIT B, EXTRA LONG SUFFIX") + .postalCode("92337") + .build()) + .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(2).build()) + .line(OutboundLine.builder().lineNo("2").omsSku("SKU-B").providerSku("SKU-B-XC") + .quantity(1).build()); + if (split != null) { + b.splitOrder(split); + } + return b.build(); + } + + @Test + void createsMultiLineOrderAsMultipart() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"DS-B001-26101300025\",\"order_id\":\"125553878740636306\"}," + + "\"errno\":0,\"err\":\"\",\"trace_id\":\"t-order\"}")); + + OutboundReceipt receipt = adapter.create(ctx(), command(true)); + + assertEquals("OB-20261110-001", receipt.outboundRequestNo()); + assertEquals("DS-B001-26101300025", receipt.providerOrderId()); + + common.ecommerce.http.HttpRequest req = transport.lastDataRequest(); + assertEquals("POST", req.method()); + assertTrue(req.url().contains("/api.add_order_multiple?token="), req.url()); + assertTrue(req.contentType().startsWith("multipart/form-data; boundary="), req.contentType()); + + String body = req.body(); + assertTrue(body.contains("name=\"ckh\"\r\n\r\nOB-20261110-001"), body); + assertTrue(body.contains("name=\"warehouse_code\"\r\n\r\nCA-3790"), body); + assertTrue(body.contains("name=\"logistics_type\"\r\n\r\nFEDEX-G"), body); + assertTrue(body.contains("name=\"order_type\"\r\n\r\ncommon"), body); + assertTrue(body.contains("name=\"is_split\"\r\n\r\n1"), body); + // 商品明细是一段 JSON 字符串 + assertTrue(body.contains("\"product_sku\":\"SKU-A\""), body); + assertTrue(body.contains("\"sku_count\":\"2\""), body); + // 仓侧 SKU 优先 + assertTrue(body.contains("\"product_sku\":\"SKU-B-XC\""), body); + // 地址超过 32 位走 address2(前 32 字符 = "3790 DE FOREST CIRCLE, UNIT B, E") + assertTrue(body.contains("name=\"address\"\r\n\r\n3790 DE FOREST CIRCLE, UNIT B, E\r\n"), body); + assertTrue(body.contains("name=\"address2\"\r\n\r\nXTRA LONG SUFFIX"), body); + } + + @Test + void splitFlagIsOmittedWhenCallerDidNotSetIt() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"DS-1\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}")); + + adapter.create(ctx(), command(null)); + + assertFalse(transport.lastDataRequest().body().contains("name=\"is_split\""), + "未显式指定时交给信仓默认(拆单)"); + } + + @Test + void missingShipToFieldFailsBeforeSending() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok("{}")); + OutboundCommand cmd = OutboundCommand.builder() + .outboundRequestNo("OB-2") + .salesPlatform(Platform.AMAZON_SC) + .carrierCode("FEDEX-G") + .warehouseId("CA-3790") + .shipTo(ShipTo.builder().name("R").countryCode("US").stateOrProvince("CA") + .city("Fontana").addressLine1("1 A St").postalCode("92337").build()) + .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(1).build()) + .build(); + + common.ecommerce.shared.error.ValidationException e = + assertThrows(common.ecommerce.shared.error.ValidationException.class, + () -> adapter.create(ctx(), cmd)); + assertTrue(e.getMessage().contains("shipTo.phone"), e.getMessage()); + // 登录后即失败,不应发出下单请求 + assertFalse(transport.recorded().stream().anyMatch( + r -> r.url().contains(XincangConstants.PATH_ORDER_ADD_MULTIPLE))); + } + + @Test + void missingProviderOrderNoIsNotSilentSuccess() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( + "{\"rst\":null,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-x\"}")); + + common.ecommerce.warehouse.error.WarehouseException e = + assertThrows(common.ecommerce.warehouse.error.WarehouseException.class, + () -> adapter.create(ctx(), command(true))); + assertTrue(e.getMessage().contains("rst.order_no"), e.getMessage()); + } + + @Test + void queryAndCancelAreExplicitlyUnsupported() { + assertThrows(common.ecommerce.shared.error.ValidationException.class, + () -> adapter.get(ctx(), null)); + assertThrows(common.ecommerce.shared.error.ValidationException.class, + () -> adapter.query(ctx(), null)); + assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); + } + + @Test + void outboundCapabilityIsDeclared() { + assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.SPLIT)); + } +} diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java index 1e50fcb..e2e33f6 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java @@ -19,6 +19,7 @@ import org.junit.jupiter.api.Test; import java.time.Clock; import java.time.Duration; +import java.util.Objects; import static org.junit.jupiter.api.Assertions.*; @@ -113,8 +114,8 @@ class XincangProductTest { assertTrue(addBody.contains("\"product_type\":1"), addBody); // token 在 body 与 query 两处 assertTrue(addBody.contains("\"token\":\"{T-1}\""), addBody); - assertTrue(transport.lastDataRequest().url().endsWith("/api.add_product?token=%7BT-1%7D"), - transport.lastDataRequest().url()); + assertTrue(Objects.requireNonNull(transport.lastDataRequest()).url().endsWith("/api.add_product?token=%7BT-1%7D"), + Objects.requireNonNull(transport.lastDataRequest()).url()); } @Test @@ -126,8 +127,8 @@ class XincangProductTest { ProductResult result = adapter.createOrUpdate(ctx(), product("APITEST001")); assertEquals("UPDATED", result.status()); - assertTrue(transport.lastDataRequest().url().contains("/api.update_product"), "应走更新接口"); - assertTrue(!transport.lastDataRequest().url().contains("/api.add_product")); + assertTrue(Objects.requireNonNull(transport.lastDataRequest()).url().contains("/api.update_product"), "应走更新接口"); + assertFalse(Objects.requireNonNull(transport.lastDataRequest()).url().contains("/api.add_product")); } @Test @@ -195,11 +196,11 @@ class XincangProductTest { adapter.createOrUpdate(ctx(), noBarcode); - String body = transport.lastDataRequest().body(); + String body = Objects.requireNonNull(transport.lastDataRequest()).body(); assertTrue(body.contains("\"bar_code\":\"APITEST005\""), body); assertTrue(body.contains("\"amount\":0.00"), body); // 未指定产品类型时不发该字段 - assertTrue(!body.contains("product_type"), body); + assertFalse(body.contains("product_type"), body); } @Test @@ -245,7 +246,7 @@ class XincangProductTest { @Test void productCapabilityIsDeclared() { assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT)); - assertFalse(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT)); } } diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java new file mode 100644 index 0000000..4315968 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java @@ -0,0 +1,195 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.shared.error.ValidationException; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.InMemoryLockProvider; +import common.ecommerce.shared.testkit.InMemoryTokenStore; +import common.ecommerce.shared.testkit.MutableClock; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.WarehouseCapability; +import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.model.TransferStatus; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.model.TransferType; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.xincang.XincangConstants; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Duration; +import java.time.LocalDate; +import java.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * 信仓转运:新增({@code fba.do_fba})与审核({@code fba.do_approve})契约测试。 + */ +class XincangTransferTest { + + private static final String BASE = XincangConstants.TEST_BASE_URL; + private static final String APP_KEY = "ak-1"; + + private RecordingTransport transport; + private XincangAdapter adapter; + + @BeforeEach + void setUp() { + transport = RecordingTransport.create(); + MutableClock clock = MutableClock.atUtc("2026-11-10T00:00:00Z"); + transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok( + "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\"" + + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)), + XincangConstants.SYSTEM_ZONE) + .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")) + + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}")); + adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(), + new InMemoryTokenStore(), new InMemoryLockProvider(), clock); + } + + private static WarehouseContext ctx() { + return WarehouseContext.of("XC-CA-3790", WarehouseProvider.XINCANG, "CA-3790", + WarehouseConnection.of(BASE, ChannelSecret.builder() + .appKey(APP_KEY).appSecret("sk").build()), + "req-1", Clock.systemUTC()); + } + + private static TransferCommand command() { + return TransferCommand.builder() + .transferRequestNo("TR-20261110-001") + .type(TransferType.OUTBOUND) + .fromWarehouseCode("CA-3790") + .toWarehouseCode("ONT8") + .po("PO-58016") + .orderType("FBA") + .deliveryMode("FBA") + .deliveryWay("Amazon(亚马逊卡车自提)") + .estimateOutboundDate(LocalDate.parse("2026-11-12")) + .estimateInboundDate(LocalDate.parse("2026-11-20")) + .shipTo(ShipTo.builder().name("FBA").countryCode("US").stateOrProvince("CA") + .city("San Bernardino").addressLine1("1 Amazon Way").postalCode("92408").build()) + .palletRequired(true) + .labelRequirement("产品贴") + .labelRequirement("外箱标签") + .productLabelCopies(4) + .cartonLabelCopies(2) + .remark("测试转运") + .line("LSS29ORANGE", 5) + .line("LSS29BLUE", 1) + .build(); + } + + @Test + void createsTransferWithJsonBody() { + transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"LTL26101500002\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-fba\"}")); + + TransferOrder order = adapter.create(ctx(), command()); + + assertEquals("TR-20261110-001", order.transferRequestNo()); + assertEquals("LTL26101500002", order.providerTransferNo()); + assertEquals(TransferStatus.PENDING_REVIEW, order.status()); + + common.ecommerce.http.HttpRequest req = transport.lastDataRequest(); + assertEquals("POST", req.method()); + assertTrue(req.url().contains("/fba.do_fba?token="), req.url()); + String body = req.body(); + assertTrue(body.contains("\"fba_no\":\"TR-20261110-001\""), body); + assertTrue(body.contains("\"po\":\"PO-58016\""), body); + assertTrue(body.contains("\"from_warehouse_name\":\"CA-3790\""), body); + assertTrue(body.contains("\"dest_warehouse_name\":\"ONT8\""), body); + assertTrue(body.contains("\"delivery_mode\":\"FBA\""), body); + assertTrue(body.contains("\"delivery_way\":\"Amazon(亚马逊卡车自提)\""), body); + assertTrue(body.contains("\"pre_send_time\":\"2026-11-12\""), body); + assertTrue(body.contains("\"is_pallet\":\"是\""), body); + assertTrue(body.contains("\"label_requirement\":\"产品贴,外箱标签\""), body); + assertTrue(body.contains("\"product_print_copies\":\"4\""), body); + assertTrue(body.contains("\"ctn_print_copies\":\"2\""), body); + // products 是 JSON 字符串 + assertTrue(body.contains("\\\"product_no\\\":\\\"LSS29ORANGE\\\""), body); + assertTrue(body.contains("\\\"sku_count\\\":\\\"5\\\""), body); + } + + @Test + void approvePostsOrderNoInQueryWithoutBody() { + transport.route(XincangConstants.PATH_TRANSFER_APPROVE, req -> Responses.ok( + "{\"rst\":true,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-approve\"}")); + + adapter.approve(ctx(), "LTL26101500002"); + + common.ecommerce.http.HttpRequest req = transport.lastDataRequest(); + assertEquals("POST", req.method()); + assertTrue(req.url().contains("/fba.do_approve?"), req.url()); + assertTrue(req.url().contains("order_no=LTL26101500002"), req.url()); + assertTrue(req.url().contains("token=%7BT-1%7D"), req.url()); + assertNull(req.body(), "转运审核无请求体"); + } + + @Test + void approveFailurePropagatesBusinessError() { + transport.route(XincangConstants.PATH_TRANSFER_APPROVE, req -> Responses.ok( + "{\"rst\":null,\"errno\":-1,\"err\":\"转运单状态不允许审核\",\"trace_id\":\"t-bad\"}")); + + common.ecommerce.shared.error.PlatformBusinessException e = + assertThrows(common.ecommerce.shared.error.PlatformBusinessException.class, + () -> adapter.approve(ctx(), "LTL1")); + assertTrue(e.getMessage().contains("不允许审核"), e.getMessage()); + } + + @Test + void nonOutboundTransferTypeIsRejected() { + TransferCommand cmd = TransferCommand.builder() + .transferRequestNo("TR-2") + .type(TransferType.WAREHOUSE_TO_WAREHOUSE) + .fromWarehouseCode("A").toWarehouseCode("B") + .estimateOutboundDate(LocalDate.now()).estimateInboundDate(LocalDate.now()) + .line("SKU", 1) + .build(); + + ValidationException e = assertThrows(ValidationException.class, + () -> adapter.create(ctx(), cmd)); + assertTrue(e.getMessage().contains("OUTBOUND"), e.getMessage()); + } + + @Test + void missingDictionaryFieldsFailBeforeSending() { + TransferCommand cmd = TransferCommand.builder() + .transferRequestNo("TR-3") + .type(TransferType.OUTBOUND) + .fromWarehouseCode("CA-3790").toWarehouseCode("ONT8") + .estimateOutboundDate(LocalDate.now()) + .estimateInboundDate(LocalDate.now().plusDays(1)) + .shipTo(ShipTo.builder().name("FBA").countryCode("US").stateOrProvince("CA") + .city("San Bernardino").addressLine1("1 Amazon Way").postalCode("92408").build()) + .line("SKU", 1) + .build(); + + ValidationException e = assertThrows(ValidationException.class, + () -> adapter.create(ctx(), cmd)); + assertTrue(e.getMessage().contains("deliveryMode"), e.getMessage()); + assertFalse(transport.recorded().stream() + .anyMatch(r -> r.url().contains(XincangConstants.PATH_TRANSFER_CREATE))); + } + + @Test + void missingTransferNoIsNotSilentSuccess() { + transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"rst\":null,\"errno\":0,\"err\":\"\"}")); + + common.ecommerce.warehouse.error.WarehouseException e = + assertThrows(common.ecommerce.warehouse.error.WarehouseException.class, + () -> adapter.create(ctx(), command())); + assertTrue(e.getMessage().contains("rst.order_no"), e.getMessage()); + } + + @Test + void transferCapabilityDeclared() { + assertTrue(adapter.capabilities().contains(WarehouseCapability.TRANSFER)); + assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.TRANSFER)); + } +}