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);