Browse Source

feat(xincang): 对接头程预报,并修正必填字段静默兜底

四个预报接口(信仓把入库拆成「建空单 → 补明细 → 提交」三步):
- POST forecast.do_forecast         → InboundCapable.create,只建单头
- POST forecast.do_improve_forecast → InboundCapable.improve,补明细(整段覆盖)
- POST forecast.done_forecast       → InboundCapable.submit,query 与 body 都带单号
- GET  forecast.forecast_detail     → InboundCapable.get,state 映射到 InboundStatus

core 只新增:InboundCapable 的 default improve / submit、
InboundView 的对应方法(走幂等守卫)、InboundCommand 的预报头字段。

同时修正字段必填性与代码不一致的问题:
- InboundCommand / TransferCommand 上「null 表示不传」的注释与信仓实际必填不符,
  改为标注「信仓必填」,不再误导调用方传 null 后再吃运行期异常
- XincangProductMapper:declaredValue 缺失时不再按 0.00 建档(金额影响计费与清关),
  改为下发前直接拒绝
- XincangChannelRecommendMapper:仓库代码缺失的报价行直接跳过,
  不再编一个 "-" 占位

Co-Authored-By: Claude Code <noreply@anthropic.com>
feature/supplier-lingxing
lml 1 week ago
parent
commit
b360b73df2
  1. 5
      README.md
  2. 24
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java
  3. 157
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java
  4. 23
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
  5. 38
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  6. 12
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
  7. 130
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  8. 6
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java
  9. 213
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java
  10. 10
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
  11. 318
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
  12. 21
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
  13. 4
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
  14. 249
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java
  15. 30
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java

5
README.md

@ -135,7 +135,7 @@ sequenceDiagram @@ -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 @@ -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

24
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InboundCapable.java

@ -30,4 +30,28 @@ public interface InboundCapable extends WarehouseAdapter { @@ -30,4 +30,28 @@ public interface InboundCapable extends WarehouseAdapter {
default List<String> bols(WarehouseContext ctx, String inboundRef) {
return Collections.emptyList();
}
/**
* 补充 / 完善入库单资料(明细、柜号、时间等)。<b>写操作</b>,
* 幂等键 {@code warehouseCode + inboundRef + "improve"}。
*
* <p>信仓叫「完善资料」({@code forecast.do_improve_forecast}),入库单创建后
* 才能补商品明细;不支持的仓默认拒绝。</p>
*/
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);
}
/**
* 提交入库单(从草稿进入仓方流程)。<b>写操作</b>,
* 幂等键 {@code warehouseCode + inboundRef + "submit"}。
*
* <p>信仓叫「预报提交」({@code forecast.done_forecast});不支持的仓默认拒绝。</p>
*/
default void submit(WarehouseContext ctx, String inboundRef) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.INBOUND);
}
}

157
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java

@ -40,6 +40,33 @@ public final class InboundCommand { @@ -40,6 +40,33 @@ public final class InboundCommand {
private final List<InboundCarton> cartons;
private final List<InboundBatch> batches;
// ---- 头程预报的仓方协议字段(运去哪不用,信仓预报接口要求)----
/** 出运类型:1 空运 / 2 海运。<b>信仓预报必填</b>,缺了适配器会拒绝。 */
private final String shipmentType;
/** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。<b>信仓预报必填</b>。 */
private final String cabinetType;
/** 发货需求:1 一件代发 / 2 FBA 中转。<b>信仓预报必填</b>。 */
private final String deliveryRequirements;
/**
* 业务参考号(信仓 {@code ref_no},长度上限 32)。
*
* <p>信仓「完善资料」必填、「新增预报」不需要;适配器按调用的是哪一步分别校验。</p>
*/
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 { @@ -73,6 +100,16 @@ public final class InboundCommand {
this.lines = Collections.unmodifiableList(new ArrayList<InboundLine>(b.lines));
this.cartons = Collections.unmodifiableList(new ArrayList<InboundCarton>(b.cartons));
this.batches = Collections.unmodifiableList(new ArrayList<InboundBatch>(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 { @@ -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 { @@ -176,6 +263,16 @@ public final class InboundCommand {
private final List<InboundLine> lines = new ArrayList<InboundLine>();
private final List<InboundCarton> cartons = new ArrayList<InboundCarton>();
private final List<InboundBatch> batches = new ArrayList<InboundBatch>();
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 { @@ -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);
}

23
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java

@ -29,7 +29,7 @@ public final class TransferCommand { @@ -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 { @@ -48,7 +48,7 @@ public final class TransferCommand {
* SDK 不做枚举归一,免得联想出仓方不认的标签名。</p>
*/
private final List<String> labelRequirements;
/** 是否需要打托;null 表示不传(仓按默认规则)。 */
/** 是否需要打托;<b>信仓转运必填</b>({@code is_pallet}),缺了适配器会拒绝。 */
private final Boolean palletRequired;
/** 产品贴打印份数;null 表示不传。 */
private final Integer productLabelCopies;
@ -56,15 +56,18 @@ public final class TransferCommand { @@ -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 表示不传。 */
/** 转运类型(仓方字典值);<b>信仓转运必填</b>,缺了适配器会拒绝。 */
private final String deliveryMode;
/** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */
/** 转运方式 / 配送方式(仓方字典值);<b>信仓转运必填</b>,缺了适配器会拒绝。 */
private final String deliveryWay;
/** 目的仓不在仓方字典时的自填仓库名;null 表示不传。 */
/** 目的仓不在仓方字典时的自填仓库名;可选,null 表示不传。 */
private final String otherWarehouseName;
/**
@ -243,7 +246,7 @@ public final class TransferCommand { @@ -243,7 +246,7 @@ public final class TransferCommand {
return labelRequirements;
}
/** 是否需要打托;null 表示不传。 */
/** 是否需要打托;信仓转运必填。 */
public Boolean palletRequired() {
return palletRequired;
}
@ -273,12 +276,12 @@ public final class TransferCommand { @@ -273,12 +276,12 @@ public final class TransferCommand {
return orderType;
}
/** 转运类型(仓方字典值);null 表示不传。 */
/** 转运类型(仓方字典值);信仓转运必填。 */
public String deliveryMode() {
return deliveryMode;
}
/** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */
/** 转运方式 / 配送方式(仓方字典值);信仓转运必填。 */
public String deliveryWay() {
return deliveryWay;
}

38
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -327,6 +327,44 @@ public final class WarehouseOperations { @@ -327,6 +327,44 @@ public final class WarehouseOperations {
() -> ((InboundCapable) adapter).query(ctx, cursor));
}
/**
* 完善入库单资料。<b>写操作</b>:强制经幂等守卫,幂等键
* {@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);
}
/**
* 提交入库单。<b>写操作</b>:强制经幂等守卫,幂等键
* {@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<String> bols(String inboundRef) {
require(WarehouseCapability.INBOUND, InboundCapable.class);

12
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java

@ -65,6 +65,18 @@ public final class XincangConstants { @@ -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";
/**
* 最优渠道。
*

130
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -11,6 +11,7 @@ import common.ecommerce.shared.spi.ChannelSecret; @@ -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; @@ -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; @@ -71,7 +75,7 @@ import java.util.Map;
* {@code WarehouseConnection} 传入。</p>
*/
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 @@ -121,7 +125,8 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
public EnumSet<WarehouseCapability> 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 @@ -427,6 +432,107 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.delete");
}
// ------------------------------------------------------------------ 头程预报
/**
* 创建入库单(信仓「新增预报」,{@code POST forecast.do_forecast})。
*
* <p>信仓把入库拆成两步:这里只建空单,商品明细要再调 {@link #improve} 补;
* 两条命令共用 {@link InboundCommand},所以这里只取单头字段。</p>
*/
@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})。
*
* <p>商品明细是 JSON 字符串,新数据直接覆盖旧数据。</p>
*/
@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})。
*
* <p>文档同时要求 query 与 body 里都有 {@code forecast_no},这里两处都带。</p>
*/
@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<String, Object> params = new LinkedHashMap<String, Object>();
params.put("forecast_no", inboundRef);
Map<String, Object> body = new LinkedHashMap<String, Object>();
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<String, Object> params = new LinkedHashMap<String, Object>();
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);
}
/**
* 分页查入库单:信仓只有「按单号取详情」,没有列表接口。
*
* <p>因此 {@code cursor} 按预报单号解释,返回 0 或 1 条;不传单号直接拒绝,
* 避免被误当成增量同步入口。</p>
*/
@Override
public Page<InboundOrder> 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 @@ -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<String, Object> params, Map<String, Object> body,
String operation) {
rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND);
Map<String, Object> query = new LinkedHashMap<String, Object>();
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<String, Object> params,
String operation) {

6
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangChannelRecommendMapper.java

@ -66,7 +66,8 @@ public final class XincangChannelRecommendMapper { @@ -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 { @@ -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) {

213
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java

@ -0,0 +1,213 @@ @@ -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.*} 系列)。
*
* <p>信仓把入库拆成两步:{@code do_forecast} 先建空单,{@code do_improve_forecast}
* 再补商品明细;统一模型里对应 {@code InboundCommand} 的 {@code create} 与 {@code improve}。</p>
*
* <p>时间字段按北京时间解析成 UTC。</p>
*/
public final class XincangForecastMapper {
private static final String YES = "1";
private static final String NO = "0";
private XincangForecastMapper() {
}
/**
* 统一命令 → 新增预报请求。
*
* <p>信仓必填:目的仓、出运类型、柜型、柜号、参考发货 / 到港时间、发货需求、
* 参考 SKU 种类数。缺一项在下发前就拒绝,避免仓返回难懂的 err。</p>
*/
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;
}
/**
* 入库行 → 完善资料的产品明细。
*
* <p>信仓要求 {@code box_count} 必填,统一模型没有独立箱数字段,
* 按「一箱一件」兜底({@code box_count = sku_count});装箱率不同的场景
* 需要调用方在 {@code InboundCarton} 里显式给出,本轮不做更细的拆分。</p>
*/
public static List<XincangDtos.ForecastProduct> products(InboundCommand cmd) {
List<XincangDtos.ForecastProduct> products =
new ArrayList<XincangDtos.ForecastProduct>(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}。
*
* <p>双号:{@code forecast_no} 既作仓侧单号也作业务单号兜底——
* 信仓的 {@code ref_no} 可能为空。</p>
*/
public static InboundOrder toOrder(XincangDtos.ForecastDetail detail, WarehouseContext ctx) {
InboundStatus status = XincangForecastStatus.toCore(detail.state);
List<InboundOrderLine> lines = new ArrayList<InboundOrderLine>();
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();
}
/**
* 详情分页:信仓详情是单条查询,没有列表接口。
*
* <p>入参是单号,返回 0 或 1 条;{@code cursor} 恒为 null。</p>
*/
public static Page<InboundOrder> 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);
}
}

10
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java

@ -46,6 +46,7 @@ public final class XincangProductMapper { @@ -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 { @@ -82,12 +83,15 @@ public final class XincangProductMapper {
/**
* 金额:取申报价值。
*
* <p>信仓 {@code amount} 固定美元且最多两位小数,其他币种直接拒绝,避免静默按美元记错价。
* 未给申报价值时按 0.00 发送(文档必填项)。</p>
* <p>信仓 {@code amount} 是必填项且固定美元。申报价值缺失时<b>直接拒绝</b>,
* 不按 0.00 兜底——按 0 美元建档会让后续计费与清关金额全错,比建档失败更难发现。</p>
*
* @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(

318
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java

@ -1009,6 +1009,324 @@ public final class XincangDtos { @@ -1009,6 +1009,324 @@ public final class XincangDtos {
public StockAgeListResult rst;
}
/**
* 新增预报请求({@code POST forecast.do_forecast})。
*
* <p>只建单,不带商品明细;明细走「完善资料」。</p>
*/
@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})。
*
* <p>{@code products} 是一段 JSON 字符串,新数据直接覆盖旧数据。</p>
*/
@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}。
*
* <p>时间字段是北京时间。</p>
*/
@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<ForecastDetailProduct> 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 {

21
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java

@ -66,6 +66,27 @@ public final class XincangRequestFactory { @@ -66,6 +66,27 @@ public final class XincangRequestFactory {
.build();
}
/**
* 把参数拼成 query 串(不含前导 {@code ?})。
*
* <p>供「query 与 body 都要带同一批参数」的接口复用,如预报提交。</p>
*/
public static String queryString(Map<String, Object> params) {
StringBuilder sb = new StringBuilder();
if (params != null) {
for (Map.Entry<String, Object> 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<String, Object> params) {
StringBuilder url = new StringBuilder(trimTrailingSlash(baseUrl)).append(path);

4
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java

@ -121,8 +121,8 @@ class XincangAdapterTest { @@ -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));

249
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java

@ -0,0 +1,249 @@ @@ -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));
}
}

30
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java

@ -182,7 +182,7 @@ class XincangProductTest { @@ -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 { @@ -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 { @@ -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);

Loading…
Cancel
Save