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