From b360b73df2ca4c6acc5c1d183f905303d5060911 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Wed, 11 Nov 2026 11:13:34 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E5=A4=B4=E7=A8=8B=E9=A2=84=E6=8A=A5=EF=BC=8C=E5=B9=B6=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3=E5=BF=85=E5=A1=AB=E5=AD=97=E6=AE=B5=E9=9D=99=E9=BB=98?= =?UTF-8?q?=E5=85=9C=E5=BA=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 四个预报接口(信仓把入库拆成「建空单 → 补明细 → 提交」三步): - POST forecast.do_forecast → InboundCapable.create,只建单头 - POST forecast.do_improve_forecast → InboundCapable.improve,补明细(整段覆盖) - POST forecast.done_forecast → InboundCapable.submit,query 与 body 都带单号 - GET forecast.forecast_detail → InboundCapable.get,state 映射到 InboundStatus core 只新增:InboundCapable 的 default improve / submit、 InboundView 的对应方法(走幂等守卫)、InboundCommand 的预报头字段。 同时修正字段必填性与代码不一致的问题: - InboundCommand / TransferCommand 上「null 表示不传」的注释与信仓实际必填不符, 改为标注「信仓必填」,不再误导调用方传 null 后再吃运行期异常 - XincangProductMapper:declaredValue 缺失时不再按 0.00 建档(金额影响计费与清关), 改为下发前直接拒绝 - XincangChannelRecommendMapper:仓库代码缺失的报价行直接跳过, 不再编一个 "-" 占位 Co-Authored-By: Claude Code --- README.md | 5 +- .../warehouse/capability/InboundCapable.java | 24 ++ .../ecommerce/warehouse/model/InboundCommand.java | 157 ++++++++++ .../ecommerce/warehouse/model/TransferCommand.java | 23 +- .../warehouse/sdk/WarehouseOperations.java | 38 +++ .../common/ecommerce/xincang/XincangConstants.java | 12 + .../ecommerce/xincang/adapter/XincangAdapter.java | 130 ++++++++- .../adapter/XincangChannelRecommendMapper.java | 6 +- .../xincang/adapter/XincangForecastMapper.java | 213 ++++++++++++++ .../xincang/adapter/XincangProductMapper.java | 10 +- .../common/ecommerce/xincang/dto/XincangDtos.java | 318 +++++++++++++++++++++ .../xincang/http/XincangRequestFactory.java | 21 ++ .../xincang/adapter/XincangAdapterTest.java | 4 +- .../xincang/adapter/XincangForecastTest.java | 249 ++++++++++++++++ .../xincang/adapter/XincangProductTest.java | 30 +- 15 files changed, 1216 insertions(+), 24 deletions(-) create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java diff --git a/README.md b/README.md index a9abd08..02bedff 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、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报) | 依赖方向: ``` @@ -334,7 +334,8 @@ common.ecommerce ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper / │ XincangOrderMapper / XincangOrderDetailMapper / │ XincangTransferMapper / XincangTransferDetailMapper / - │ XincangChannelRecommendMapper / XincangInventoryMapper + │ XincangChannelRecommendMapper / XincangInventoryMapper / + │ XincangForecastMapper ├── dto XincangDtos(登录 / 商品) ├── enums XincangOrderStatus / XincangTransferState / │ XincangForecastStatus / XincangOrderType diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java index 0686174..632e207 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java @@ -30,4 +30,28 @@ public interface InboundCapable extends WarehouseAdapter { default List bols(WarehouseContext ctx, String inboundRef) { return Collections.emptyList(); } + + /** + * 补充 / 完善入库单资料(明细、柜号、时间等)。写操作, + * 幂等键 {@code warehouseCode + inboundRef + "improve"}。 + * + *

信仓叫「完善资料」({@code forecast.do_improve_forecast}),入库单创建后 + * 才能补商品明细;不支持的仓默认拒绝。

+ */ + default void improve(WarehouseContext ctx, String inboundRef, + common.ecommerce.warehouse.model.InboundCommand cmd) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND); + } + + /** + * 提交入库单(从草稿进入仓方流程)。写操作, + * 幂等键 {@code warehouseCode + inboundRef + "submit"}。 + * + *

信仓叫「预报提交」({@code forecast.done_forecast});不支持的仓默认拒绝。

+ */ + default void submit(WarehouseContext ctx, String inboundRef) { + throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( + common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND); + } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java index 92bae1f..c0cfc67 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java @@ -40,6 +40,33 @@ public final class InboundCommand { private final List cartons; private final List batches; + // ---- 头程预报的仓方协议字段(运去哪不用,信仓预报接口要求)---- + + /** 出运类型:1 空运 / 2 海运。信仓预报必填,缺了适配器会拒绝。 */ + private final String shipmentType; + /** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。信仓预报必填。 */ + private final String cabinetType; + /** 发货需求:1 一件代发 / 2 FBA 中转。信仓预报必填。 */ + private final String deliveryRequirements; + /** + * 业务参考号(信仓 {@code ref_no},长度上限 32)。 + * + *

信仓「完善资料」必填、「新增预报」不需要;适配器按调用的是哪一步分别校验。

+ */ + private final String referenceNo; + /** 其他需求,如 {@code 内箱贴,外箱贴};信仓可选,null 表示不传。 */ + private final String otherNeed; + /** 船务公司 id;null 表示不传。 */ + private final String shippingCompanyId; + /** 预报托盘数;柜型为托盘入库时才有意义。 */ + private final Integer forecastPalletQty; + /** 是否超 120cm;null 表示不传。 */ + private final Boolean oversize; + /** 超尺寸备注;null 表示不传。 */ + private final String oversizeNote; + /** 中文名称(信仓 {@code chn_name});null 表示不传。 */ + private final String chnName; + private InboundCommand(Builder b) { if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("inboundRequestNo must not be blank"); @@ -73,6 +100,16 @@ public final class InboundCommand { this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); this.cartons = Collections.unmodifiableList(new ArrayList(b.cartons)); this.batches = Collections.unmodifiableList(new ArrayList(b.batches)); + this.shipmentType = b.shipmentType; + this.cabinetType = b.cabinetType; + this.deliveryRequirements = b.deliveryRequirements; + this.referenceNo = b.referenceNo; + this.otherNeed = b.otherNeed; + this.shippingCompanyId = b.shippingCompanyId; + this.forecastPalletQty = b.forecastPalletQty; + this.oversize = b.oversize; + this.oversizeNote = b.oversizeNote; + this.chnName = b.chnName; } public static Builder builder() { @@ -156,6 +193,56 @@ public final class InboundCommand { return batches; } + /** 出运类型:1 空运 / 2 海运;信仓预报必填。 */ + public String shipmentType() { + return shipmentType; + } + + /** 柜型;信仓预报必填。 */ + public String cabinetType() { + return cabinetType; + } + + /** 发货需求:1 一件代发 / 2 FBA 中转;信仓预报必填。 */ + public String deliveryRequirements() { + return deliveryRequirements; + } + + /** 业务参考号;信仓「完善资料」必填。 */ + public String referenceNo() { + return referenceNo; + } + + /** 其他需求,如 {@code 内箱贴,外箱贴};可选。 */ + public String otherNeed() { + return otherNeed; + } + + /** 船务公司 id;null 表示不传。 */ + public String shippingCompanyId() { + return shippingCompanyId; + } + + /** 预报托盘数;null 表示不传。 */ + public Integer forecastPalletQty() { + return forecastPalletQty; + } + + /** 是否超 120cm;null 表示不传。 */ + public Boolean oversize() { + return oversize; + } + + /** 超尺寸备注;null 表示不传。 */ + public String oversizeNote() { + return oversizeNote; + } + + /** 中文名称;null 表示不传。 */ + public String chnName() { + return chnName; + } + public static final class Builder { private String inboundRequestNo; @@ -176,6 +263,16 @@ public final class InboundCommand { private final List lines = new ArrayList(); private final List cartons = new ArrayList(); private final List batches = new ArrayList(); + private String shipmentType; + private String cabinetType; + private String deliveryRequirements; + private String referenceNo; + private String otherNeed; + private String shippingCompanyId; + private Integer forecastPalletQty; + private Boolean oversize; + private String oversizeNote; + private String chnName; public Builder inboundRequestNo(String v) { this.inboundRequestNo = v; @@ -275,6 +372,66 @@ public final class InboundCommand { return this; } + /** 出运类型:1 空运 / 2 海运。 */ + public Builder shipmentType(String v) { + this.shipmentType = v; + return this; + } + + /** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。 */ + public Builder cabinetType(String v) { + this.cabinetType = v; + return this; + } + + /** 发货需求:1 一件代发 / 2 FBA 中转。 */ + public Builder deliveryRequirements(String v) { + this.deliveryRequirements = v; + return this; + } + + /** 业务参考号(仓方 {@code ref_no})。 */ + public Builder referenceNo(String v) { + this.referenceNo = v; + return this; + } + + /** 其他需求,如 {@code 内箱贴,外箱贴}。 */ + public Builder otherNeed(String v) { + this.otherNeed = v; + return this; + } + + /** 船务公司 id。 */ + public Builder shippingCompanyId(String v) { + this.shippingCompanyId = v; + return this; + } + + /** 预报托盘数。 */ + public Builder forecastPalletQty(Integer v) { + this.forecastPalletQty = v; + return this; + } + + /** 是否超 120cm;null 表示不传。 */ + public Builder oversize(Boolean v) { + this.oversize = v; + return this; + } + + /** 超尺寸备注。 */ + public Builder oversizeNote(String v) { + this.oversizeNote = v; + return this; + } + + /** 中文名称。 */ + public Builder chnName(String v) { + this.chnName = v; + return this; + } + public InboundCommand build() { return new InboundCommand(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 6252087..bcfa8a5 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 @@ -29,7 +29,7 @@ public final class TransferCommand { private final String removeOrderId; /** 目的地地址 code(FBA 地址 code)。 */ private final String receiveStore; - /** 目的地地址;仓到仓调拨可为 null,调拨出库必填。 */ + /** 目的地地址;{@code TransferType.OUTBOUND} 时构造期必填。 */ private final ShipTo shipTo; private final String remark; /** 增值服务:1 贴产品标 / 2 贴箱标 / 3 贴托盘标。 */ @@ -48,7 +48,7 @@ public final class TransferCommand { * SDK 不做枚举归一,免得联想出仓方不认的标签名。

*/ private final List labelRequirements; - /** 是否需要打托;null 表示不传(仓按默认规则)。 */ + /** 是否需要打托;信仓转运必填({@code is_pallet}),缺了适配器会拒绝。 */ private final Boolean palletRequired; /** 产品贴打印份数;null 表示不传。 */ private final Integer productLabelCopies; @@ -56,15 +56,18 @@ public final class TransferCommand { private final Integer cartonLabelCopies; /** 托盘贴打印份数;null 表示不传。 */ private final Integer palletLabelCopies; - /** PO 号;部分仓(信仓)要求,其余为 null。 */ + /** + * PO 号。信仓转运必填;未给时信仓适配器退回 {@code transferRequestNo}, + * 其余仓为 null。 + */ private final String po; - /** 订单类型(仓方字典值,如信仓 FBA / LTL);null 表示不传。 */ + /** 订单类型(仓方字典值,如信仓 FBA / LTL);可选,null 表示不传。 */ private final String orderType; - /** 转运类型(仓方字典值);null 表示不传。 */ + /** 转运类型(仓方字典值);信仓转运必填,缺了适配器会拒绝。 */ private final String deliveryMode; - /** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */ + /** 转运方式 / 配送方式(仓方字典值);信仓转运必填,缺了适配器会拒绝。 */ private final String deliveryWay; - /** 目的仓不在仓方字典时的自填仓库名;null 表示不传。 */ + /** 目的仓不在仓方字典时的自填仓库名;可选,null 表示不传。 */ private final String otherWarehouseName; /** @@ -243,7 +246,7 @@ public final class TransferCommand { return labelRequirements; } - /** 是否需要打托;null 表示不传。 */ + /** 是否需要打托;信仓转运必填。 */ public Boolean palletRequired() { return palletRequired; } @@ -273,12 +276,12 @@ public final class TransferCommand { return orderType; } - /** 转运类型(仓方字典值);null 表示不传。 */ + /** 转运类型(仓方字典值);信仓转运必填。 */ public String deliveryMode() { return deliveryMode; } - /** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */ + /** 转运方式 / 配送方式(仓方字典值);信仓转运必填。 */ public String deliveryWay() { return deliveryWay; } 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 aabf511..1b62f7f 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 @@ -327,6 +327,44 @@ public final class WarehouseOperations { () -> ((InboundCapable) adapter).query(ctx, cursor)); } + /** + * 完善入库单资料。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + inboundRef + improve}。 + */ + public void improve(final String inboundRef, final InboundCommand cmd) { + require(WarehouseCapability.INBOUND, InboundCapable.class); + if (guard == null) { + throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); + } + final InboundCapable capable = (InboundCapable) adapter; + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), inboundRef, "improve"), + () -> { + capable.improve(ctx, inboundRef, cmd); + return inboundRef; + }, + ref -> ref); + } + + /** + * 提交入库单。写操作:强制经幂等守卫,幂等键 + * {@code warehouseCode + inboundRef + submit}。 + */ + public void submit(final String inboundRef) { + require(WarehouseCapability.INBOUND, InboundCapable.class); + if (guard == null) { + throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations"); + } + final InboundCapable capable = (InboundCapable) adapter; + guard.execute( + WarehouseWriteScope.of(provider.name(), account.warehouseCode(), inboundRef, "submit"), + () -> { + capable.submit(ctx, inboundRef); + return inboundRef; + }, + ref -> ref); + } + /** BOL 文档。 */ public List bols(String inboundRef) { require(WarehouseCapability.INBOUND, InboundCapable.class); 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 d465259..f2b1952 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 @@ -65,6 +65,18 @@ public final class XincangConstants { /** 库龄列表;必填 {@code bill_date}({@code 起 - 止})。 */ public static final String PATH_STOCK_AGE_LIST = "/api.stockagelist"; + /** 新增预报(创建入库单,空明细)。 */ + public static final String PATH_FORECAST_CREATE = "/forecast.do_forecast"; + + /** 完善预报资料(补明细 / 柜号 / 时间);新数据覆盖旧数据。 */ + public static final String PATH_FORECAST_IMPROVE = "/forecast.do_improve_forecast"; + + /** 预报提交(草稿进入仓方流程);forecast_no 必填。 */ + public static final String PATH_FORECAST_SUBMIT = "/forecast.done_forecast"; + + /** 预报详情;forecast_no 必填。 */ + public static final String PATH_FORECAST_DETAIL = "/forecast.forecast_detail"; + /** * 最优渠道。 * 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 4b9285b..ed6dbfe 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 @@ -11,6 +11,7 @@ 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.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable; @@ -28,6 +29,9 @@ import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.ChannelRecommendQuery; import common.ecommerce.warehouse.model.InventoryAgeQuery; import common.ecommerce.warehouse.model.InventoryAgeRecord; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.ChannelRecommendResult; @@ -71,7 +75,7 @@ import java.util.Map; * {@code WarehouseConnection} 传入。

*/ public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable, - TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable { + TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable, InboundCapable { private static final String OP_PRODUCT_QUERY = "warehouse.product.query"; private static final String OP_PRODUCT_ADD = "warehouse.product.add"; @@ -121,7 +125,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa public EnumSet capabilities() { return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT, - WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.INVENTORY_QUERY); + WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.INVENTORY_QUERY, + WarehouseCapability.INBOUND); } /** @@ -427,6 +432,107 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa "warehouse.transfer.delete"); } + // ------------------------------------------------------------------ 头程预报 + + /** + * 创建入库单(信仓「新增预报」,{@code POST forecast.do_forecast})。 + * + *

信仓把入库拆成两步:这里只建空单,商品明细要再调 {@link #improve} 补; + * 两条命令共用 {@link InboundCommand},所以这里只取单头字段。

+ */ + @Override + public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { + XincangDtos.ForecastCreateRequest body = XincangForecastMapper.toCreateRequest(cmd, ctx); + String raw = execute(ctx, XincangConstants.PATH_FORECAST_CREATE, body, login(ctx), + "warehouse.inbound.create"); + XincangDtos.ForecastCreateResult result = + json.fromJson(raw, XincangDtos.ForecastCreateResponse.class).rst; + if (result == null || blank(result.orderNo)) { + throw WarehouseException.builder() + .message("xincang forecast returned no rst.order_no: " + safeRelay(raw)) + .operation("warehouse.inbound.create") + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .rawResponse(safeRelay(raw)) + .build(); + } + return InboundReceipt.of(cmd.inboundRequestNo(), result.orderNo); + } + + /** + * 完善资料({@code POST forecast.do_improve_forecast})。 + * + *

商品明细是 JSON 字符串,新数据直接覆盖旧数据。

+ */ + @Override + public void improve(WarehouseContext ctx, String inboundRef, InboundCommand cmd) { + String productsJson = json.toJson(XincangForecastMapper.products(cmd)); + XincangDtos.ForecastImproveRequest body = + XincangForecastMapper.toImproveRequest(cmd, inboundRef, productsJson, ctx); + execute(ctx, XincangConstants.PATH_FORECAST_IMPROVE, body, login(ctx), + "warehouse.inbound.improve"); + } + + /** + * 预报提交({@code POST forecast.done_forecast})。 + * + *

文档同时要求 query 与 body 里都有 {@code forecast_no},这里两处都带。

+ */ + @Override + public void submit(WarehouseContext ctx, String inboundRef) { + if (blank(inboundRef)) { + throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.submit", + "forecast_no must not be blank"); + } + Map params = new LinkedHashMap(); + params.put("forecast_no", inboundRef); + Map body = new LinkedHashMap(); + body.put("forecast_no", inboundRef); + executePostQueryWithBody(ctx, XincangConstants.PATH_FORECAST_SUBMIT, params, body, + "warehouse.inbound.submit"); + } + + /** + * 预报详情({@code GET forecast.forecast_detail})。 + * + * @param inboundRef 预报单号({@code forecast_no}) + */ + @Override + public InboundOrder get(WarehouseContext ctx, String inboundRef) { + if (blank(inboundRef)) { + throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.get", + "forecast_no must not be blank"); + } + Map params = new LinkedHashMap(); + params.put("forecast_no", inboundRef); + String raw = executeGet(ctx, XincangConstants.PATH_FORECAST_DETAIL, params, login(ctx), + "warehouse.inbound.get"); + XincangDtos.ForecastDetail detail = + json.fromJson(raw, XincangDtos.ForecastDetailResponse.class).rst; + if (detail == null) { + throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.get", + "xincang forecast_detail returned no rst"); + } + return XincangForecastMapper.toOrder(detail, ctx); + } + + /** + * 分页查入库单:信仓只有「按单号取详情」,没有列表接口。 + * + *

因此 {@code cursor} 按预报单号解释,返回 0 或 1 条;不传单号直接拒绝, + * 避免被误当成增量同步入口。

+ */ + @Override + public Page query(WarehouseContext ctx, String cursor) { + if (blank(cursor)) { + throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.query", + "xincang has no forecast list API; pass forecast_no as cursor"); + } + return XincangForecastMapper.singlePage(get(ctx, cursor)); + } + // ------------------------------------------------------------------ 库存 /** @@ -530,6 +636,26 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } + /** POST:query 与 JSON body 各放一份参数(预报提交要求两处都有)。 */ + private String executePostQueryWithBody(WarehouseContext ctx, String path, + Map params, Map body, + String operation) { + rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); + Map query = new LinkedHashMap(); + if (params != null) { + query.putAll(params); + } + String token = login(ctx).value(); + query.put(XincangConstants.QUERY_TOKEN, token); + HttpRequest req = requestFactory.postJsonWithToken(ctx.endpointBaseUrl(), path, + json.toJson(body), token, operation); + HttpRequest withQuery = req.toBuilder() + .url(ctx.endpointBaseUrl() + path + "?" + XincangRequestFactory.queryString(query)) + .build(); + HttpResponse resp = transport.execute(withQuery); + return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); + } + /** POST 但无请求体:参数全在 query(转运审核)。 */ private String executePostQuery(WarehouseContext ctx, String path, Map params, String operation) { diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java index 3005fe2..5cf1cea 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java @@ -66,7 +66,8 @@ public final class XincangChannelRecommendMapper { } if (rst.warehouseFeeList != null) { for (XincangDtos.CalculateV3Result.WarehouseFee warehouse : rst.warehouseFeeList) { - if (warehouse == null) { + // 仓代码是必填主键,缺了这条报价无法归属,直接跳过而不是编一个 "-" + if (warehouse == null || blankToNull(warehouse.warehouse) == null) { continue; } builder.warehouseQuote(toQuote(warehouse)); @@ -79,8 +80,7 @@ public final class XincangChannelRecommendMapper { XincangDtos.CalculateV3Result.WarehouseFee warehouse) { ChannelRecommendResult.WarehouseQuote.Builder builder = ChannelRecommendResult.WarehouseQuote.builder() - .warehouseCode(blankToNull(warehouse.warehouse) == null - ? "-" : warehouse.warehouse.trim()) + .warehouseCode(warehouse.warehouse.trim()) .inventoryEnough(parseFlag(warehouse.isInventoryEnough)) .insufficientStockError(blankToNull(warehouse.insufficientStockError)); if (warehouse.logisticsService != null) { diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java new file mode 100644 index 0000000..c96754f --- /dev/null +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java @@ -0,0 +1,213 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.error.ValidationException; +import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.enums.InboundStatus; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundLine; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundOrderLine; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.xincang.XincangConstants; +import common.ecommerce.xincang.dto.XincangDtos; +import common.ecommerce.xincang.enums.XincangForecastStatus; + +import java.time.Instant; +import java.util.ArrayList; +import java.util.List; + +/** + * 头程预报报文映射(信仓 {@code forecast.*} 系列)。 + * + *

信仓把入库拆成两步:{@code do_forecast} 先建空单,{@code do_improve_forecast} + * 再补商品明细;统一模型里对应 {@code InboundCommand} 的 {@code create} 与 {@code improve}。

+ * + *

时间字段按北京时间解析成 UTC。

+ */ +public final class XincangForecastMapper { + + private static final String YES = "1"; + private static final String NO = "0"; + + private XincangForecastMapper() { + } + + /** + * 统一命令 → 新增预报请求。 + * + *

信仓必填:目的仓、出运类型、柜型、柜号、参考发货 / 到港时间、发货需求、 + * 参考 SKU 种类数。缺一项在下发前就拒绝,避免仓返回难懂的 err。

+ */ + public static XincangDtos.ForecastCreateRequest toCreateRequest(InboundCommand cmd, + WarehouseContext ctx) { + XincangDtos.ForecastCreateRequest req = new XincangDtos.ForecastCreateRequest(); + req.destWarehouse = require(cmd.warehouseId(), "warehouseId (dest_warehouse)", ctx); + req.shipmentType = require(cmd.shipmentType(), "shipmentType", ctx); + req.cabinetType = require(cmd.cabinetType(), "cabinetType", ctx); + req.cabinetNo = require(cmd.containerNo(), "containerNo (cabinet_no)", ctx); + req.rfcEtd = requireDate(cmd.predictionShipDate(), "predictionShipDate (rfc_etd)", ctx); + req.rfcEta = requireDate(cmd.estimateArriveDate(), "estimateArriveDate (rfc_eta)", ctx); + req.deliveryRequirements = require(cmd.deliveryRequirements(), "deliveryRequirements", ctx); + // 参考 SKU 种类数:没有明细时按行数给,有明细时也按行数(信仓只要求一个估计值) + req.rfcSkuCount = String.valueOf(cmd.lines().size()); + req.chnName = blankToNull(cmd.chnName()); + req.isOversize = cmd.oversize() == null ? null : (cmd.oversize() ? YES : NO); + req.oversizeVal = blankToNull(cmd.oversizeNote()); + req.remark = blankToNull(cmd.remark()); + req.shippingCompanyId = blankToNull(cmd.shippingCompanyId()); + req.forecastPalletQty = cmd.forecastPalletQty() == null + ? null : String.valueOf(cmd.forecastPalletQty()); + return req; + } + + /** + * 统一命令 → 完善资料请求。 + * + * @param forecastNo 新增预报返回的 {@code order_no} + * @param productsJson 商品明细 JSON 字符串 + */ + public static XincangDtos.ForecastImproveRequest toImproveRequest(InboundCommand cmd, + String forecastNo, + String productsJson, + WarehouseContext ctx) { + XincangDtos.ForecastImproveRequest req = new XincangDtos.ForecastImproveRequest(); + req.forecastNo = require(forecastNo, "forecastNo", ctx); + req.destWarehouse = require(cmd.warehouseId(), "warehouseId (dest_warehouse)", ctx); + req.shipmentType = require(cmd.shipmentType(), "shipmentType", ctx); + req.refNo = require(cmd.referenceNo(), "referenceNo (ref_no)", ctx); + if (req.refNo.length() > 32) { + throw validation(ctx, "referenceNo must not exceed 32 chars (信仓 ref_no)"); + } + req.cabinetType = require(cmd.cabinetType(), "cabinetType", ctx); + req.cabinetNo = require(cmd.containerNo(), "containerNo (cabinet_no)", ctx); + req.etd = requireDate(cmd.predictionShipDate(), "predictionShipDate (etd)", ctx); + req.eta = requireDate(cmd.estimateArriveDate(), "estimateArriveDate (eta)", ctx); + req.deliveryRequirements = require(cmd.deliveryRequirements(), "deliveryRequirements", ctx); + req.remark = blankToNull(cmd.remark()); + req.otherNeed = blankToNull(cmd.otherNeed()); + req.products = productsJson; + req.shippingCompanyId = blankToNull(cmd.shippingCompanyId()); + req.forecastPalletQty = cmd.forecastPalletQty() == null + ? null : String.valueOf(cmd.forecastPalletQty()); + return req; + } + + /** + * 入库行 → 完善资料的产品明细。 + * + *

信仓要求 {@code box_count} 必填,统一模型没有独立箱数字段, + * 按「一箱一件」兜底({@code box_count = sku_count});装箱率不同的场景 + * 需要调用方在 {@code InboundCarton} 里显式给出,本轮不做更细的拆分。

+ */ + public static List products(InboundCommand cmd) { + List products = + new ArrayList(cmd.lines().size()); + for (InboundLine line : cmd.lines()) { + XincangDtos.ForecastProduct product = new XincangDtos.ForecastProduct(); + product.productNo = line.providerSku() == null ? line.omsSku() : line.providerSku(); + product.skuCount = String.valueOf(line.quantity()); + product.boxCount = String.valueOf(line.quantity()); + products.add(product); + } + return products; + } + + /** + * 预报详情 → {@link InboundOrder}。 + * + *

双号:{@code forecast_no} 既作仓侧单号也作业务单号兜底—— + * 信仓的 {@code ref_no} 可能为空。

+ */ + public static InboundOrder toOrder(XincangDtos.ForecastDetail detail, WarehouseContext ctx) { + InboundStatus status = XincangForecastStatus.toCore(detail.state); + List lines = new ArrayList(); + if (detail.products != null) { + for (XincangDtos.ForecastDetailProduct product : detail.products) { + if (product == null || blank(product.productNo)) { + continue; + } + lines.add(InboundOrderLine.builder() + .providerSku(product.productNo.trim()) + .plannedQuantity(intOf(product.skuCount)) + .packedQuantity(intOf(product.boxCount)) + .receivedQuantity(intOf(product.putOnSkuCount)) + .build()); + } + } + return InboundOrder.builder() + .inboundRequestNo(firstNonBlank(detail.refNo, detail.forecastNo)) + .providerInboundId(detail.forecastNo) + .warehouseCode(firstNonBlank(detail.destWarehouseName, ctx.providerWarehouseId())) + .status(status) + .rawStatus(detail.state) + .sourceProvider(WarehouseProvider.XINCANG) + .boxCount(intOf(detail.rfcSkuCount)) + .createdAt(parseTime(detail.gmtCreate)) + .receivedAt(parseTime(detail.receiveTime)) + .estimatedArrivalAt(parseTime(detail.rfcEta)) + .actualArrivalAt(parseTime(detail.eta)) + .remark(blankToNull(detail.remark)) + .lines(lines) + .build(); + } + + /** + * 详情分页:信仓详情是单条查询,没有列表接口。 + * + *

入参是单号,返回 0 或 1 条;{@code cursor} 恒为 null。

+ */ + public static Page singlePage(InboundOrder order) { + if (order == null) { + return Page.empty(); + } + return Page.last(java.util.Collections.singletonList(order)); + } + + // ---------------------------------------------------------------- internals + + static Instant parseTime(String raw) { + return XincangOrderDetailMapper.parseTime(raw); + } + + static int intOf(String raw) { + return XincangOrderDetailMapper.parsePositiveInt(raw); + } + + private static String requireDate(java.time.LocalDate date, String field, WarehouseContext ctx) { + if (date == null) { + throw validation(ctx, field + " is required for xincang forecast"); + } + return date.format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd")); + } + + private static String require(String value, String field, WarehouseContext ctx) { + if (blank(value)) { + throw validation(ctx, field + " is required for xincang forecast"); + } + return value.trim(); + } + + private static ValidationException validation(WarehouseContext ctx, String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation("warehouse.inbound.create") + .provider(WarehouseProvider.XINCANG.name()) + .requestId(ctx.requestId()) + .retryable(false)); + } + + static String firstNonBlank(String a, String b) { + return XincangOrderDetailMapper.firstNonBlank(a, b); + } + + static String blankToNull(String v) { + return XincangOrderDetailMapper.blankToNull(v); + } + + static boolean blank(String v) { + return XincangOrderDetailMapper.blank(v); + } + +} diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java index e89aadc..8a3764f 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java @@ -46,6 +46,7 @@ public final class XincangProductMapper { req.barCode = barcodeOf(product); req.weightLbs = decimal(product.weightGrams()) .divide(decimal(XincangConstants.GRAMS_PER_POUND), SCALE, RoundingMode.HALF_UP); + // 信仓把 packing_rate 列为必填;统一模型没有装箱率字段,按「一箱一件」下发 req.packingRate = DEFAULT_PACKING_RATE; req.sizeLLn = inches(product.lengthCm()); req.sizeWLn = inches(product.widthCm()); @@ -82,12 +83,15 @@ public final class XincangProductMapper { /** * 金额:取申报价值。 * - *

信仓 {@code amount} 固定美元且最多两位小数,其他币种直接拒绝,避免静默按美元记错价。 - * 未给申报价值时按 0.00 发送(文档必填项)。

+ *

信仓 {@code amount} 是必填项且固定美元。申报价值缺失时直接拒绝, + * 不按 0.00 兜底——按 0 美元建档会让后续计费与清关金额全错,比建档失败更难发现。

+ * + * @throws IllegalArgumentException 申报价值缺失或不是美元 */ private static BigDecimal amount(Money declaredValue) { if (declaredValue == null) { - return BigDecimal.ZERO.setScale(AMOUNT_SCALE, RoundingMode.UNNECESSARY); + throw new IllegalArgumentException( + "xincang product requires declaredValue (amount is mandatory, USD)"); } if (!"USD".equalsIgnoreCase(declaredValue.currencyCode())) { throw new IllegalArgumentException( 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 e4323f0..22b04ac 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 @@ -1009,6 +1009,324 @@ public final class XincangDtos { public StockAgeListResult rst; } + /** + * 新增预报请求({@code POST forecast.do_forecast})。 + * + *

只建单,不带商品明细;明细走「完善资料」。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ForecastCreateRequest { + + /** 目的地仓。 */ + @JsonProperty("dest_warehouse") + public String destWarehouse; + + /** 出运类型:1 空运 / 2 海运。 */ + @JsonProperty("shipment_type") + public String shipmentType; + + /** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。 */ + @JsonProperty("cabinet_type") + public String cabinetType; + + /** 柜号。 */ + @JsonProperty("cabinet_no") + public String cabinetNo; + + /** 参考发货时间。 */ + @JsonProperty("rfc_etd") + public String rfcEtd; + + /** 参考到港时间。 */ + @JsonProperty("rfc_eta") + public String rfcEta; + + /** 发货需求:1 一件代发 / 2 FBA 中转。 */ + @JsonProperty("delivery_requirements") + public String deliveryRequirements; + + /** 参考 SKU 种类数量。 */ + @JsonProperty("rfc_sku_count") + public String rfcSkuCount; + + /** 中文名称。 */ + @JsonProperty("chn_name") + public String chnName; + + /** 是否超 120cm:1 是 / 0 否。 */ + @JsonProperty("is_oversize") + public String isOversize; + + /** 超尺寸备注。 */ + @JsonProperty("oversize_val") + public String oversizeVal; + + @JsonProperty("remark") + public String remark; + + /** 船务公司 id。 */ + @JsonProperty("shipping_company_id") + public String shippingCompanyId; + + /** 预报托盘数;柜型为托盘入库时填。 */ + @JsonProperty("forecast_pallet_qty") + public String forecastPalletQty; + } + + /** + * 完善预报资料请求({@code POST forecast.do_improve_forecast})。 + * + *

{@code products} 是一段 JSON 字符串,新数据直接覆盖旧数据。

+ */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ForecastImproveRequest { + + @JsonProperty("forecast_no") + public String forecastNo; + + @JsonProperty("dest_warehouse") + public String destWarehouse; + + @JsonProperty("shipment_type") + public String shipmentType; + + /** 参考编号,长度上限 32。 */ + @JsonProperty("ref_no") + public String refNo; + + @JsonProperty("cabinet_type") + public String cabinetType; + + @JsonProperty("cabinet_no") + public String cabinetNo; + + /** 发货时间。 */ + @JsonProperty("etd") + public String etd; + + /** 到港时间。 */ + @JsonProperty("eta") + public String eta; + + @JsonProperty("delivery_requirements") + public String deliveryRequirements; + + @JsonProperty("remark") + public String remark; + + /** 其他需求,如 内箱贴,外箱贴。 */ + @JsonProperty("other_need") + public String otherNeed; + + /** 产品明细 JSON 字符串。 */ + @JsonProperty("products") + public String products; + + @JsonProperty("shipping_company_id") + public String shippingCompanyId; + + @JsonProperty("forecast_pallet_qty") + public String forecastPalletQty; + } + + /** 完善资料里的产品行(序列化进 {@code products} 字符串)。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class ForecastProduct { + + @JsonProperty("product_no") + public String productNo; + + /** 件数。 */ + @JsonProperty("sku_count") + public String skuCount; + + /** 箱数。 */ + @JsonProperty("box_count") + public String boxCount; + + /** 批次号;可选。 */ + @JsonProperty("batch_no") + public String batchNo; + + @JsonProperty("remark") + public String remark; + } + + /** + * 预报详情({@code GET forecast.forecast_detail})的 {@code rst}。 + * + *

时间字段是北京时间。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ForecastDetail { + + @JsonProperty("forecast_no") + public String forecastNo; + + /** 中文名称。 */ + @JsonProperty("chn_name") + public String chnName; + + /** 目的仓 id / 代码。 */ + @JsonProperty("dest_warehouse") + public String destWarehouseId; + @JsonProperty("dest_warehouse_name") + public String destWarehouseName; + + /** 出运类型。 */ + @JsonProperty("shipment_type") + public String shipmentType; + + /** 参考编号。 */ + @JsonProperty("ref_no") + public String refNo; + + /** 柜型 / 柜号。 */ + @JsonProperty("cabinet_type") + public String cabinetType; + @JsonProperty("cabinet_no") + public String cabinetNo; + + /** 预计发货 / 到港时间。 */ + @JsonProperty("rfc_etd") + public String rfcEtd; + @JsonProperty("rfc_eta") + public String rfcEta; + /** 实际发货 / 到港时间。 */ + @JsonProperty("etd") + public String etd; + @JsonProperty("eta") + public String eta; + + /** 是否超 120cm。 */ + @JsonProperty("is_oversize") + public String isOversize; + @JsonProperty("oversize_val") + public String oversizeVal; + + /** 发货需求。 */ + @JsonProperty("delivery_requirements") + public String deliveryRequirements; + + /** 预报时间。 */ + @JsonProperty("forecast_time") + public String forecastTime; + + /** 参考 SKU 种类数。 */ + @JsonProperty("rfc_sku_count") + public String rfcSkuCount; + + @JsonProperty("remark") + public String remark; + + /** 托盘数:预报 / 实收 / 上架 / 计费。 */ + @JsonProperty("forecast_pallet_qty") + public String forecastPalletQty; + @JsonProperty("receive_pallet_qty") + public String receivePalletQty; + @JsonProperty("shelf_pallet_qty") + public String shelfPalletQty; + @JsonProperty("bill_pallet_qty") + public String billPalletQty; + + /** 到仓 / 卸柜清点 / 清点完成 / 上架 / 还柜时间。 */ + @JsonProperty("receive_time") + public String receiveTime; + @JsonProperty("unlade_time") + public String unladeTime; + @JsonProperty("check_time") + public String checkTime; + @JsonProperty("putaway_time") + public String putawayTime; + @JsonProperty("leave_time") + public String leaveTime; + + /** 是否需要内箱贴 / 外箱贴:1 是 / 0 否。 */ + @JsonProperty("is_inner_box_sticker") + public String isInnerBoxSticker; + @JsonProperty("is_outer_box_sticker") + public String isOuterBoxSticker; + + @JsonProperty("other_need") + public String otherNeed; + + @JsonProperty("gmt_create") + public String gmtCreate; + @JsonProperty("gmt_modify") + public String gmtModify; + + /** 预报状态码,见 {@code XincangForecastStatus}。 */ + @JsonProperty("state") + public String state; + @JsonProperty("state_name") + public String stateName; + + @JsonProperty("products") + public List products; + } + + /** 预报详情里的产品行。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ForecastDetailProduct { + + @JsonProperty("product_no") + public String productNo; + + @JsonProperty("product_name") + public String productName; + + /** 件数。 */ + @JsonProperty("sku_count") + public String skuCount; + + /** 箱数。 */ + @JsonProperty("box_count") + public String boxCount; + + /** 清点箱数。 */ + @JsonProperty("check_box_qty") + public String checkBoxQty; + + /** 打托件数 / 上架件数。 */ + @JsonProperty("pallet_sku_count") + public String palletSkuCount; + @JsonProperty("put_on_sku_count") + public String putOnSkuCount; + + /** 装箱率。 */ + @JsonProperty("packing_rate") + public String packingRate; + + /** 体积(立方厘米)。 */ + @JsonProperty("volume_cm") + public String volumeCm; + } + + /** 预报详情响应外层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ForecastDetailResponse { + + @JsonProperty("rst") + public ForecastDetail rst; + } + + /** 新增预报响应 {@code rst}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ForecastCreateResult { + + /** 预报单号;完善资料与提交都用它。 */ + @JsonProperty("order_no") + public String orderNo; + } + + /** 新增预报响应外层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ForecastCreateResponse { + + @JsonProperty("rst") + public ForecastCreateResult rst; + } + /** 新增订单响应外层,用于取 {@code rst}。 */ @JsonIgnoreProperties(ignoreUnknown = true) public static final class OrderResponse { 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 aea6eb8..210f46e 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 @@ -66,6 +66,27 @@ public final class XincangRequestFactory { .build(); } + /** + * 把参数拼成 query 串(不含前导 {@code ?})。 + * + *

供「query 与 body 都要带同一批参数」的接口复用,如预报提交。

+ */ + public static String queryString(Map params) { + StringBuilder sb = new StringBuilder(); + if (params != null) { + for (Map.Entry e : params.entrySet()) { + if (e.getValue() == null) { + continue; + } + if (sb.length() > 0) { + sb.append('&'); + } + sb.append(urlEncode(e.getKey())).append('=').append(urlEncode(String.valueOf(e.getValue()))); + } + } + return sb.toString(); + } + /** 拼 {@code base + path?k=v},null 值跳过。 */ private String urlWithQuery(String baseUrl, String path, Map params) { StringBuilder url = new StringBuilder(trimTrailingSlash(baseUrl)).append(path); 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 db6fa23..15d2f21 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 @@ -121,8 +121,8 @@ class XincangAdapterTest { assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId()); assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.TRANSFER, - WarehouseCapability.SPLIT, WarehouseCapability.CHANNEL_RECOMMEND), - adapter.capabilities()); + WarehouseCapability.INBOUND, WarehouseCapability.SPLIT, + WarehouseCapability.CHANNEL_RECOMMEND), adapter.capabilities()); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT)); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND)); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY)); diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java new file mode 100644 index 0000000..bb47f38 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java @@ -0,0 +1,249 @@ +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.enums.InboundStatus; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundLine; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundReceipt; +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.Instant; +import java.time.LocalDate; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * 头程预报四个接口(新增 / 完善资料 / 提交 / 详情)契约测试。 + */ +class XincangForecastTest { + + private static final String BASE = XincangConstants.TEST_BASE_URL; + private static final String APP_KEY = "ak-1"; + + private static final String DETAIL_BODY = "{\"rst\":{" + + "\"forecast_no\":\"OFCS2610150000325\"," + + "\"dest_warehouse\":\"84047962479824\"," + + "\"dest_warehouse_name\":\"NJ-2605\"," + + "\"shipment_type\":\"1\"," + + "\"ref_no\":\"ref-api-test-0002\"," + + "\"cabinet_type\":\"40GP\"," + + "\"cabinet_no\":\"cabinet-api-test-0002\"," + + "\"rfc_etd\":\"2026-09-16 08:00:00\"," + + "\"rfc_eta\":\"2026-10-14 08:00:00\"," + + "\"etd\":\"2026-09-21 08:00:00\"," + + "\"eta\":\"2026-10-22 08:00:00\"," + + "\"rfc_sku_count\":\"3\"," + + "\"remark\":\"kkkkkkksss\"," + + "\"receive_time\":\"\"," + + "\"gmt_create\":\"2026-10-15 15:40:33\"," + + "\"state\":\"2\"," + + "\"state_name\":\"预报完成\"," + + "\"products\":[" + + "{\"product_no\":\"HB-B2060-RED\",\"sku_count\":\"100\",\"box_count\":\"100\"," + + "\"put_on_sku_count\":\"80\"}" + + "]},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-detail\"}"; + + private RecordingTransport transport; + private XincangAdapter adapter; + + @BeforeEach + void setUp() { + transport = RecordingTransport.create(); + MutableClock clock = MutableClock.atUtc("2026-11-11T00: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-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605", + WarehouseConnection.of(BASE, ChannelSecret.builder() + .appKey(APP_KEY).appSecret("sk").build()), + "req-1", Clock.systemUTC()); + } + + /** 信仓预报要求单头字段齐全。 */ + private static InboundCommand command() { + return InboundCommand.builder() + .inboundRequestNo("IN-20261111-001") + .warehouseId("NJ-2605") + // 出运类型 1 空运 / 2 海运 + .shipmentType("2") + // 柜型 1 = 40GP + .cabinetType("1") + .containerNo("CAB-0001") + // 参考发货 / 到港 + .predictionShipDate(LocalDate.parse("2026-11-20")) + .estimateArriveDate(LocalDate.parse("2026-12-10")) + // 发货需求 1 一件代发 + .deliveryRequirements("1") + .referenceNo("ref-001") + .remark("备注") + .line(InboundLine.builder().omsSku("SKU-A").providerSku("SKU-A").quantity(100).build()) + .build(); + } + + @Test + void createSendsHeadOnlyAndReturnsForecastNo() { + transport.route(XincangConstants.PATH_FORECAST_CREATE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"OFCS2610150000325\"},\"errno\":0,\"err\":\"\"}")); + + InboundReceipt receipt = adapter.create(ctx(), command()); + + common.ecommerce.http.HttpRequest req = transport.lastDataRequest(); + assertTrue(req.url().contains("/forecast.do_forecast?token=%7BT-1%7D"), req.url()); + String body = req.body(); + assertTrue(body.contains("\"dest_warehouse\":\"NJ-2605\""), body); + assertTrue(body.contains("\"shipment_type\":\"2\""), body); + assertTrue(body.contains("\"cabinet_type\":\"1\""), body); + assertTrue(body.contains("\"cabinet_no\":\"CAB-0001\""), body); + assertTrue(body.contains("\"rfc_etd\":\"2026-11-20\""), body); + assertTrue(body.contains("\"rfc_eta\":\"2026-12-10\""), body); + assertTrue(body.contains("\"delivery_requirements\":\"1\""), body); + assertTrue(body.contains("\"rfc_sku_count\":\"1\""), body); + // 创建阶段不带明细 + assertFalse(body.contains("products"), body); + + assertEquals("IN-20261111-001", receipt.inboundRequestNo()); + assertEquals("OFCS2610150000325", receipt.providerInboundId()); + } + + @Test + void createRejectsMissingHeadFieldBeforeSending() { + InboundCommand incomplete = InboundCommand.builder() + .inboundRequestNo("IN-2").warehouseId("NJ-2605") + .line(InboundLine.builder().omsSku("SKU-A").quantity(1).build()) + .build(); + + ValidationException e = assertThrows(ValidationException.class, + () -> adapter.create(ctx(), incomplete)); + assertTrue(e.getMessage().contains("shipmentType"), e.getMessage()); + assertFalse(transport.recorded().stream() + .anyMatch(r -> r.url().contains(XincangConstants.PATH_FORECAST_CREATE))); + } + + @Test + void improveSendsProductsAsJsonString() { + transport.route(XincangConstants.PATH_FORECAST_IMPROVE, req -> Responses.ok( + "{\"rst\":true,\"errno\":0,\"err\":\"\"}")); + + adapter.improve(ctx(), "OFCS2610150000325", command()); + + common.ecommerce.http.HttpRequest req = transport.lastDataRequest(); + assertTrue(req.url().contains("/forecast.do_improve_forecast?"), req.url()); + String body = req.body(); + assertTrue(body.contains("\"forecast_no\":\"OFCS2610150000325\""), body); + assertTrue(body.contains("\"ref_no\":\"ref-001\""), body); + assertTrue(body.contains("\"etd\":\"2026-11-20\""), body); + assertTrue(body.contains("\"eta\":\"2026-12-10\""), body); + // products 是 JSON 字符串 + assertTrue(body.contains("\\\"product_no\\\":\\\"SKU-A\\\""), body); + assertTrue(body.contains("\\\"sku_count\\\":\\\"100\\\""), body); + assertTrue(body.contains("\\\"box_count\\\":\\\"100\\\""), body); + } + + @Test + void improveRejectsTooLongReferenceNo() { + InboundCommand longRef = InboundCommand.builder() + .inboundRequestNo("IN-3").warehouseId("NJ-2605") + .shipmentType("2").cabinetType("1").containerNo("C") + .predictionShipDate(LocalDate.parse("2026-11-20")) + .estimateArriveDate(LocalDate.parse("2026-12-10")) + .deliveryRequirements("1") + .referenceNo("ref-ref-ref-ref-ref-ref-ref-ref-1234") + .line(InboundLine.builder().omsSku("SKU-A").quantity(1).build()) + .build(); + + ValidationException e = assertThrows(ValidationException.class, + () -> adapter.improve(ctx(), "OFCS-1", longRef)); + assertTrue(e.getMessage().contains("32"), e.getMessage()); + } + + @Test + void submitSendsForecastNoInBothQueryAndBody() { + transport.route(XincangConstants.PATH_FORECAST_SUBMIT, req -> Responses.ok( + "{\"rst\":true,\"errno\":0,\"err\":\"\"}")); + + adapter.submit(ctx(), "OFCS2610150000325"); + + common.ecommerce.http.HttpRequest req = transport.lastDataRequest(); + assertEquals("POST", req.method()); + assertTrue(req.url().contains("forecast_no=OFCS2610150000325"), req.url()); + assertTrue(req.url().contains("token=%7BT-1%7D"), req.url()); + assertTrue(req.body().contains("\"forecast_no\":\"OFCS2610150000325\""), req.body()); + } + + @Test + void submitRejectsBlankForecastNo() { + ValidationException e = assertThrows(ValidationException.class, + () -> adapter.submit(ctx(), " ")); + assertTrue(e.getMessage().contains("forecast_no"), e.getMessage()); + } + + @Test + void detailMapsToInboundOrder() { + transport.route(XincangConstants.PATH_FORECAST_DETAIL, req -> Responses.ok(DETAIL_BODY)); + + InboundOrder order = adapter.get(ctx(), "OFCS2610150000325"); + + String url = transport.lastDataRequest().url(); + assertTrue(url.contains("/forecast.forecast_detail?"), url); + assertTrue(url.contains("forecast_no=OFCS2610150000325"), url); + + assertEquals("ref-api-test-0002", order.inboundRequestNo()); + assertEquals("OFCS2610150000325", order.providerInboundId()); + assertEquals("NJ-2605", order.warehouseCode()); + assertEquals(InboundStatus.PENDING_SHIPMENT, order.status()); + assertEquals("2", order.rawStatus()); + assertEquals(WarehouseProvider.XINCANG, order.sourceProvider()); + // 北京时间 2026-10-15 15:40:33 → UTC 07:40:33 + assertEquals(Instant.parse("2026-10-15T07:40:33Z"), order.createdAt()); + assertNull(order.receivedAt(), "空串时间应为 null"); + + assertEquals(1, order.lines().size()); + assertEquals("HB-B2060-RED", order.lines().get(0).providerSku()); + assertEquals(100, order.lines().get(0).plannedQuantity()); + assertEquals(100, order.lines().get(0).packedQuantity()); + assertEquals(80, order.lines().get(0).receivedQuantity()); + } + + @Test + void queryWithoutCursorIsRejected() { + ValidationException e = assertThrows(ValidationException.class, + () -> adapter.query(ctx(), (String) null)); + assertTrue(e.getMessage().contains("no forecast list API"), e.getMessage()); + } + + @Test + void queryByCursorReturnsSinglePage() { + transport.route(XincangConstants.PATH_FORECAST_DETAIL, req -> Responses.ok(DETAIL_BODY)); + + assertEquals(1, adapter.query(ctx(), "OFCS2610150000325").size()); + } + + @Test + void inboundCapabilityDeclared() { + assertTrue(adapter.capabilities().contains(WarehouseCapability.INBOUND)); + assertTrue(adapter.supports("XC-NJ-2605", WarehouseCapability.INBOUND)); + } +} 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 eea8b23..cfe3182 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 @@ -182,7 +182,7 @@ class XincangProductTest { } @Test - void barcodeFallsBackToSkuAndAmountToZeroWhenMissing() { + void barcodeFallsBackToSku() { routeProductList("[]"); transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok( "{\"rst\":true,\"errno\":0,\"err\":\"\"}")); @@ -192,18 +192,41 @@ class XincangProductTest { .nameEn("Test") .packingType(0) .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100) + .declaredValue(Money.of("1.00", "USD")) + .hsCode("9403600000") + .countryOfOrigin("US") .build(); adapter.createOrUpdate(ctx(), noBarcode); String body = Objects.requireNonNull(transport.lastDataRequest()).body(); assertTrue(body.contains("\"bar_code\":\"APITEST005\""), body); - assertTrue(body.contains("\"amount\":0.00"), body); + assertTrue(body.contains("\"amount\":1.00"), body); // 未指定产品类型时不发该字段 assertFalse(body.contains("product_type"), body); } @Test + void missingDeclaredValueIsRejectedInsteadOfSendingZero() { + routeProductList("[]"); + WarehouseProduct noValue = WarehouseProduct.builder() + .omsSku("APITEST007") + .name("测试商品") + .nameEn("Test") + .barcode("B-7") + .packingType(0) + .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100) + .build(); + + IllegalArgumentException e = assertThrows(IllegalArgumentException.class, + () -> adapter.createOrUpdate(ctx(), noValue)); + assertTrue(e.getMessage().contains("declaredValue"), e.getMessage()); + assertFalse(transport.recorded().stream() + .anyMatch(r -> r.url().contains(XincangConstants.PATH_PRODUCT_ADD)), + "缺金额应在下发前失败,不按 0 美元建档"); + } + + @Test void nonUsdDeclaredValueIsRejectedBeforeSending() { WarehouseProduct eur = WarehouseProduct.builder() .omsSku("APITEST006") @@ -235,6 +258,9 @@ class XincangProductTest { .barcode("B-1") .packingType(0) .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100) + .declaredValue(Money.of("1.00", "USD")) + .hsCode("9403600000") + .countryOfOrigin("US") .build(); ProductResult result = adapter.createOrUpdate(ctx(), mapped); From 19405c553b944a5e515c4e07667c774ebaea05c5 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Wed, 11 Nov 2026 11:19:57 +0800 Subject: [PATCH 2/2] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5?= =?UTF-8?q?=E5=AE=A2=E6=88=B7=E4=BB=93=E5=BA=93=E4=B8=8E=E6=89=BF=E8=BF=90?= =?UTF-8?q?=E5=95=86=E6=9F=A5=E8=AF=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - GET api.get_customer_warehouses → WarehouseDirectoryCapable.warehouses() - GET api.get_customer_logistics → WarehouseDirectoryCapable.carriers() core 只新增: - WarehouseDirectoryCapable(warehouses / carriers) - WarehouseFacility 模型:仓代码 + 国家 / 省 / 市 / 街道 / 邮编 - WarehouseCapability 追加 DIRECTORY(210) - WarehouseOperations 增加 warehouses() / carriers(),只读带埋点 未并入 WarehouseRepository:那是宿主维护的 OMS 仓编码 → 账户映射, 这两个接口是仓方返回的可选仓库清单,数据源不同,混用会让宿主分不清信谁。 空 data 返回空列表;只有 rst 缺失(报文结构变化)才抛 ValidationException。 Co-Authored-By: Claude Code --- README.md | 2 +- .../capability/WarehouseDirectoryCapable.java | 34 +++++ .../warehouse/enums/WarehouseCapability.java | 2 + .../warehouse/model/WarehouseFacility.java | 120 +++++++++++++++++ .../warehouse/sdk/WarehouseOperations.java | 27 ++++ .../common/ecommerce/xincang/XincangConstants.java | 6 + .../ecommerce/xincang/adapter/XincangAdapter.java | 71 +++++++++- .../common/ecommerce/xincang/dto/XincangDtos.java | 85 ++++++++++++ .../xincang/adapter/XincangAdapterTest.java | 3 +- .../xincang/adapter/XincangDirectoryTest.java | 144 +++++++++++++++++++++ 10 files changed, 490 insertions(+), 4 deletions(-) create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java diff --git a/README.md b/README.md index 02bedff..4e6ba58 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、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) | 依赖方向: ``` diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java new file mode 100644 index 0000000..b43906d --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java @@ -0,0 +1,34 @@ +package common.ecommerce.warehouse.capability; + +import common.ecommerce.warehouse.model.WarehouseFacility; +import common.ecommerce.warehouse.sdk.WarehouseAdapter; +import common.ecommerce.warehouse.sdk.WarehouseContext; + +import java.util.List; + +/** + * 仓方基础资料能力:列出账户下可用的仓库与承运商。 + * + *

用途是让宿主在下单前拿到仓代码 / 物流方式,而不是把取值写死在配置里。 + * 只读,无幂等要求。

+ */ +public interface WarehouseDirectoryCapable extends WarehouseAdapter { + + /** + * 客户名下所有仓库。 + * + * @return 仓库列表;仓方返回空时为 empty list + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code DIRECTORY} + */ + List warehouses(WarehouseContext ctx); + + /** + * 客户可用的承运商 / 物流方式代码。 + * + * @return 物流方式码列表,如 {@code FEDEX-G};未配置时为空列表 + * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException + * 该仓不声明 {@code DIRECTORY} + */ + List carriers(WarehouseContext ctx); +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java index f6e0652..00751c8 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java @@ -46,6 +46,8 @@ public enum WarehouseCapability { FEE_ESTIMATE(180, "费用试算"), /** 最优渠道推荐(按 SKU + 邮编由仓择优) */ CHANNEL_RECOMMEND(200, "最优渠道推荐"), + /** 仓方基础资料(仓库列表 / 承运商列表) */ + DIRECTORY(210, "基础资料"), /** 状态回调推送 */ WEBHOOK(190, "状态回调"); diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java new file mode 100644 index 0000000..4c0d64a --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFacility.java @@ -0,0 +1,120 @@ +package common.ecommerce.warehouse.model; + +/** + * 仓方的基础资料:一个可发货的仓库及其地址。 + * + *

用于下单前让宿主拿到「这家仓有哪些仓、仓代码是什么」,而不是把仓代码写死在配置里。 + * 只读数据,不含库存与能力。

+ */ +public final class WarehouseFacility { + + /** 仓方内部 id(信仓 {@code id});可能为 null。 */ + private final String providerWarehouseId; + /** 仓代码(下单时用的 {@code warehouse_code})。 */ + private final String warehouseCode; + private final String country; + private final String province; + private final String city; + private final String street; + private final String postcode; + + private WarehouseFacility(Builder b) { + this.providerWarehouseId = b.providerWarehouseId; + this.warehouseCode = require(b.warehouseCode, "warehouseCode"); + this.country = b.country; + this.province = b.province; + this.city = b.city; + this.street = b.street; + this.postcode = b.postcode; + } + + public static Builder builder() { + return new Builder(); + } + + /** 仓方内部 id;可能为 null。 */ + public String providerWarehouseId() { + return providerWarehouseId; + } + + /** 仓代码。 */ + public String warehouseCode() { + return warehouseCode; + } + + public String country() { + return country; + } + + public String province() { + return province; + } + + public String city() { + return city; + } + + public String street() { + return street; + } + + public String postcode() { + return postcode; + } + + private static String require(String v, String n) { + if (v == null || v.trim().isEmpty()) { + throw new IllegalArgumentException(n + " must not be blank"); + } + return v.trim(); + } + + public static final class Builder { + private String providerWarehouseId; + private String warehouseCode; + private String country; + private String province; + private String city; + private String street; + private String postcode; + + public Builder providerWarehouseId(String v) { + this.providerWarehouseId = v; + return this; + } + + public Builder warehouseCode(String v) { + this.warehouseCode = v; + return this; + } + + public Builder country(String v) { + this.country = v; + return this; + } + + public Builder province(String v) { + this.province = v; + return this; + } + + public Builder city(String v) { + this.city = v; + return this; + } + + public Builder street(String v) { + this.street = v; + return this; + } + + public Builder postcode(String v) { + this.postcode = v; + return this; + } + + public WarehouseFacility build() { + return new WarehouseFacility(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 1b62f7f..f1968f1 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 @@ -11,6 +11,7 @@ import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable; +import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; import common.ecommerce.warehouse.model.FeeEstimateQuery; @@ -212,6 +213,32 @@ public final class WarehouseOperations { () -> ((TrackingCapable) adapter).trackShipment(ctx, trackingNumber)); } + /** + * 仓方基础资料:客户名下的仓库列表。 + * + *

只读。用于下单前取仓代码,避免把仓代码写死在配置里。

+ */ + public List warehouses() { + require(WarehouseCapability.DIRECTORY, WarehouseDirectoryCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.directory.warehouses", + CallSupport.params(), + List::size, + () -> ((WarehouseDirectoryCapable) adapter).warehouses(ctx)); + } + + /** + * 仓方基础资料:客户可用的承运商 / 物流方式代码。 + * + *

只读。返回的是仓方字典值,可直接传给下单的 {@code carrierCode}。

+ */ + public List carriers() { + require(WarehouseCapability.DIRECTORY, WarehouseDirectoryCapable.class); + return CallSupport.observe(observer, ctx, "warehouse.directory.carriers", + CallSupport.params(), + List::size, + () -> ((WarehouseDirectoryCapable) adapter).carriers(ctx)); + } + /** 费用视图。 */ public FeeView fees() { return new FeeView(); 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 f2b1952..48ba29c 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 @@ -65,6 +65,12 @@ public final class XincangConstants { /** 库龄列表;必填 {@code bill_date}({@code 起 - 止})。 */ public static final String PATH_STOCK_AGE_LIST = "/api.stockagelist"; + /** 获取客户所有仓库。 */ + public static final String PATH_CUSTOMER_WAREHOUSES = "/api.get_customer_warehouses"; + + /** 获取客户所有承运商。 */ + public static final String PATH_CUSTOMER_LOGISTICS = "/api.get_customer_logistics"; + /** 新增预报(创建入库单,空明细)。 */ public static final String PATH_FORECAST_CREATE = "/forecast.do_forecast"; 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 ed6dbfe..b016b7d 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 @@ -14,6 +14,7 @@ import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.OutboundCapable; +import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; @@ -33,6 +34,7 @@ import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryQuery; +import common.ecommerce.warehouse.model.WarehouseFacility; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.ChannelRecommendResult; import common.ecommerce.warehouse.model.CancelResult; @@ -55,6 +57,7 @@ import common.ecommerce.xincang.http.XincangRequestFactory; import java.time.Clock; import java.time.Instant; +import java.util.ArrayList; import java.util.EnumSet; import java.util.LinkedHashMap; import java.util.List; @@ -75,7 +78,8 @@ import java.util.Map; * {@code WarehouseConnection} 传入。

*/ public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable, - TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable, InboundCapable { + TransferCapable, WarehouseChannelRecommendCapable, InventoryCapable, InboundCapable, + WarehouseDirectoryCapable { private static final String OP_PRODUCT_QUERY = "warehouse.product.query"; private static final String OP_PRODUCT_ADD = "warehouse.product.add"; @@ -126,7 +130,7 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT, WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.INVENTORY_QUERY, - WarehouseCapability.INBOUND); + WarehouseCapability.INBOUND, WarehouseCapability.DIRECTORY); } /** @@ -432,6 +436,69 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa "warehouse.transfer.delete"); } + // ------------------------------------------------------------------ 基础资料 + + /** + * 客户名下所有仓库({@code GET api.get_customer_warehouses})。 + * + *

返回的 {@code warehouse_code} 可直接用于下单、库存查询等接口。

+ */ + @Override + public List warehouses(WarehouseContext ctx) { + String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_WAREHOUSES, + new LinkedHashMap(), login(ctx), "warehouse.directory.warehouses"); + XincangDtos.WarehouseListResult rst = + json.fromJson(raw, XincangDtos.WarehouseListResponse.class).rst; + if (rst == null) { + throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.warehouses", + "xincang get_customer_warehouses returned no rst"); + } + List out = new ArrayList(); + if (rst.data != null) { + for (XincangDtos.WarehouseListResult.WarehouseRow row : rst.data) { + if (row == null || XincangForecastMapper.blank(row.warehouseCode)) { + continue; + } + out.add(WarehouseFacility.builder() + .providerWarehouseId(XincangForecastMapper.blankToNull(row.id)) + .warehouseCode(row.warehouseCode.trim()) + .country(XincangForecastMapper.blankToNull(row.country)) + .province(XincangForecastMapper.blankToNull(row.province)) + .city(XincangForecastMapper.blankToNull(row.city)) + .street(XincangForecastMapper.blankToNull(row.street)) + .postcode(XincangForecastMapper.blankToNull(row.postcode)) + .build()); + } + } + return out; + } + + /** + * 客户可用的承运商({@code GET api.get_customer_logistics})。 + * + *

返回的 {@code logistics_type} 可直接作为下单的 {@code carrierCode}。

+ */ + @Override + public List carriers(WarehouseContext ctx) { + String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_LOGISTICS, + new LinkedHashMap(), login(ctx), "warehouse.directory.carriers"); + XincangDtos.LogisticsListResult rst = + json.fromJson(raw, XincangDtos.LogisticsListResponse.class).rst; + if (rst == null) { + throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.carriers", + "xincang get_customer_logistics returned no rst"); + } + List out = new ArrayList(); + if (rst.data != null) { + for (XincangDtos.LogisticsListResult.LogisticsRow row : rst.data) { + if (row != null && !XincangForecastMapper.blank(row.logisticsType)) { + out.add(row.logisticsType.trim()); + } + } + } + return out; + } + // ------------------------------------------------------------------ 头程预报 /** 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 22b04ac..2439a53 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 @@ -1327,6 +1327,91 @@ public final class XincangDtos { public ForecastCreateResult rst; } + /** 客户仓库列表响应 {@code rst}({@code GET api.get_customer_warehouses})。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class WarehouseListResult { + + @JsonProperty("code") + public String code; + + @JsonProperty("msg") + public String msg; + + @JsonProperty("data") + public List data; + + /** 总条数(字符串)。 */ + @JsonProperty("count") + public String count; + + /** 一行仓库。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class WarehouseRow { + + /** 仓方内部 id。 */ + @JsonProperty("id") + public String id; + + /** 仓代码。 */ + @JsonProperty("warehouse_code") + public String warehouseCode; + + @JsonProperty("country") + public String country; + @JsonProperty("province") + public String province; + @JsonProperty("city") + public String city; + @JsonProperty("street") + public String street; + @JsonProperty("postcode") + public String postcode; + } + } + + /** 客户仓库列表响应外层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class WarehouseListResponse { + + @JsonProperty("rst") + public WarehouseListResult rst; + } + + /** 客户承运商列表响应 {@code rst}({@code GET api.get_customer_logistics})。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class LogisticsListResult { + + @JsonProperty("code") + public String code; + + @JsonProperty("msg") + public String msg; + + @JsonProperty("data") + public List data; + + /** 总条数(字符串)。 */ + @JsonProperty("count") + public String count; + + /** 一行承运商。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class LogisticsRow { + + /** 物流方式代码,如 {@code FEDEX-G}。 */ + @JsonProperty("logistics_type") + public String logisticsType; + } + } + + /** 客户承运商列表响应外层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class LogisticsListResponse { + + @JsonProperty("rst") + public LogisticsListResult rst; + } + /** 新增订单响应外层,用于取 {@code rst}。 */ @JsonIgnoreProperties(ignoreUnknown = true) public static final class OrderResponse { 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 15d2f21..f9feaad 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 @@ -122,7 +122,8 @@ class XincangAdapterTest { assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.TRANSFER, WarehouseCapability.INBOUND, WarehouseCapability.SPLIT, - WarehouseCapability.CHANNEL_RECOMMEND), adapter.capabilities()); + WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.DIRECTORY), + adapter.capabilities()); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT)); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND)); assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY)); diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java new file mode 100644 index 0000000..47734e2 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangDirectoryTest.java @@ -0,0 +1,144 @@ +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.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.WarehouseFacility; +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.util.List; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * 基础资料(客户仓库 / 承运商)契约测试。 + */ +class XincangDirectoryTest { + + private static final String BASE = XincangConstants.TEST_BASE_URL; + private static final String APP_KEY = "ak-1"; + + private static final String WAREHOUSES = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[" + + "{\"id\":\"84047962214173\",\"warehouse_code\":\"CA-3790\",\"country\":\"US\"," + + "\"province\":\"CA\",\"city\":\"JURUPA VALLEY\"," + + "\"street\":\"3790 DE FOREST CIRCLE, UNIT B\",\"postcode\":\"91752\"}," + + "{\"id\":\"84047962479824\",\"warehouse_code\":\"NJ-2605\",\"country\":\"US\"," + + "\"province\":\"NJ\",\"city\":\"Burlington Township\"," + + "\"street\":\"2605 Rancocas Road\",\"postcode\":\"08016\"}" + + "],\"count\":\"2\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-wh\"}"; + + private static final String LOGISTICS = "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[" + + "{\"logistics_type\":\"FEDEX-HD\"},{\"logistics_type\":\"FEDEX-G\"}" + + "],\"count\":\"2\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-lg\"}"; + + private RecordingTransport transport; + private XincangAdapter adapter; + + @BeforeEach + void setUp() { + transport = RecordingTransport.create(); + MutableClock clock = MutableClock.atUtc("2026-11-11T00: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-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605", + WarehouseConnection.of(BASE, ChannelSecret.builder() + .appKey(APP_KEY).appSecret("sk").build()), + "req-1", Clock.systemUTC()); + } + + @Test + void listsWarehousesWithAddress() { + transport.route(XincangConstants.PATH_CUSTOMER_WAREHOUSES, req -> Responses.ok(WAREHOUSES)); + + List warehouses = adapter.warehouses(ctx()); + + String url = transport.lastDataRequest().url(); + assertTrue(url.contains("/api.get_customer_warehouses?token=%7BT-1%7D"), url); + + assertEquals(2, warehouses.size()); + WarehouseFacility first = warehouses.get(0); + assertEquals("CA-3790", first.warehouseCode()); + assertEquals("84047962214173", first.providerWarehouseId()); + assertEquals("US", first.country()); + assertEquals("CA", first.province()); + assertEquals("JURUPA VALLEY", first.city()); + assertEquals("3790 DE FOREST CIRCLE, UNIT B", first.street()); + assertEquals("91752", first.postcode()); + assertEquals("NJ-2605", warehouses.get(1).warehouseCode()); + } + + @Test + void listsCarriers() { + transport.route(XincangConstants.PATH_CUSTOMER_LOGISTICS, req -> Responses.ok(LOGISTICS)); + + List carriers = adapter.carriers(ctx()); + + assertTrue(transport.lastDataRequest().url() + .contains("/api.get_customer_logistics?"), transport.lastDataRequest().url()); + assertEquals(2, carriers.size()); + assertEquals("FEDEX-HD", carriers.get(0)); + assertEquals("FEDEX-G", carriers.get(1)); + } + + @Test + void emptyDataYieldsEmptyListNotError() { + transport.route(XincangConstants.PATH_CUSTOMER_WAREHOUSES, req -> Responses.ok( + "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[],\"count\":\"0\"}," + + "\"errno\":0,\"err\":\"\"}")); + transport.route(XincangConstants.PATH_CUSTOMER_LOGISTICS, req -> Responses.ok( + "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[],\"count\":\"0\"}," + + "\"errno\":0,\"err\":\"\"}")); + + assertTrue(adapter.warehouses(ctx()).isEmpty()); + assertTrue(adapter.carriers(ctx()).isEmpty()); + } + + @Test + void rowsWithoutWarehouseCodeAreSkipped() { + transport.route(XincangConstants.PATH_CUSTOMER_WAREHOUSES, req -> Responses.ok( + "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":[" + + "{\"id\":\"1\",\"warehouse_code\":\"\",\"country\":\"US\"}," + + "{\"id\":\"2\",\"warehouse_code\":\"CA-3790\",\"country\":\"US\"}" + + "],\"count\":\"2\"},\"errno\":0,\"err\":\"\"}")); + + List warehouses = adapter.warehouses(ctx()); + + assertEquals(1, warehouses.size()); + assertEquals("CA-3790", warehouses.get(0).warehouseCode()); + } + + @Test + void missingRstIsNotSilentEmpty() { + transport.route(XincangConstants.PATH_CUSTOMER_LOGISTICS, req -> Responses.ok( + "{\"rst\":null,\"errno\":0,\"err\":\"\"}")); + + assertThrows(ValidationException.class, () -> adapter.carriers(ctx())); + } + + @Test + void directoryCapabilityDeclared() { + assertTrue(adapter.capabilities().contains(WarehouseCapability.DIRECTORY)); + assertTrue(adapter.supports("XC-NJ-2605", WarehouseCapability.DIRECTORY)); + } +}