diff --git a/docs-warehouse/README.md b/docs-warehouse/README.md
index 45d2d5f..e75ff01 100644
--- a/docs-warehouse/README.md
+++ b/docs-warehouse/README.md
@@ -7,6 +7,7 @@
| [architecture.md](architecture.md) | 三方仓架构:分层、模块依赖、门面/能力/适配器/SPI |
| [callback.md](callback.md) | 回调(Webhook)链路:验签、分派、出参模型、宿主怎么接 |
| [yqn/README.md](yqn/README.md) | 运去哪:接口汇总、联调结论、平台限制 |
+| [xincang/README.md](xincang/README.md) | 信仓:接口汇总、枚举码表、协议待核对、联调探针 |
| [notes.md](notes.md) | 通用注意事项:写操作、幂等、时区、单位、字段口径 |
## 快速定位
@@ -14,4 +15,5 @@
- 想知道**能力有哪些** → `architecture.md` 的「能力矩阵」
- 想知道**回调怎么接** → `callback.md` 的「宿主要做什么」
- 想知道**运去哪对接了什么** → `yqn/README.md` 的「接口清单」
+- 想知道**信仓对接了什么** → `xincang/README.md` 的「接口清单」
- 想知道**踩过什么坑** → `notes.md`
diff --git a/docs-warehouse/xincang/README.md b/docs-warehouse/xincang/README.md
new file mode 100644
index 0000000..93784af
--- /dev/null
+++ b/docs-warehouse/xincang/README.md
@@ -0,0 +1,251 @@
+# 信仓(XinCang)接入汇总
+
+## 1. 基本信息
+
+| 项 | 值 |
+|---|---|
+| 适配器 ID | `xincang` |
+| 测试 / 联调环境 | `http://test.api.oms.13u3.com/oms` |
+| 生产环境 | `https://oms.xincang-tech.com/oms/` |
+| 鉴权 | 先 `GET /api.login?appkey=&secret=` 换 token;业务请求把 token 放 **query 参数 `token`**,不是 `Authorization` 头 |
+| token 有效期 | 2 小时,**没有 refresh 接口**,到期只能重新登录 |
+| token 维度 | 客户级(同一 appkey 下多仓共用一个 token) |
+| 限流 | 保守默认 2 req/s(仓方未公开) |
+| 成功判定 | 顶层 `errno=0`;业务接口还要 `rst.code="0"`(登录响应没有 `rst.code`) |
+| 时间口径 | 北京时间(`yyyy-MM-dd HH:mm:ss` / 日期 `yyyy-MM-dd`) |
+| 单位 | 金额美元、尺寸英寸、重量磅(统一模型是 cm/g,适配器内换算) |
+
+## 2. 接口清单(19 个已对接)
+
+| # | 接口 | 路径 | 能力位 |
+|---|---|---|---|
+| 1 | 登录 | `GET /api.login` | — |
+| 2 | 新增产品 | `POST /api.add_product` | `PRODUCT` |
+| 3 | 更新产品 | `POST /api.update_product` | `PRODUCT` |
+| 4 | 产品列表(查重用) | `GET /api.productlist` | `PRODUCT` |
+| 5 | 新增订单一单多件 | `POST /api.add_order_multiple` | `OUTBOUND` |
+| 6 | 订单详情 | `GET /api.get_order` | `OUTBOUND` |
+| 7 | 删除订单 | `POST /api.delete_order` | `OUTBOUND` |
+| 8 | 新增转运 | `POST /fba.do_fba` | `TRANSFER` |
+| 9 | 转运审核 | `POST /fba.do_approve` | `TRANSFER` |
+| 10 | 转运详情 | `GET /fba.fba_detail` | `TRANSFER` |
+| 11 | 删除转运 | `POST /fba.delete_fba` | `TRANSFER` |
+| 12 | 新增预报 | `POST /forecast.do_forecast` | `INBOUND` |
+| 13 | 完善资料 | `POST /forecast.do_improve_forecast` | `INBOUND` |
+| 14 | 预报提交 | `POST /forecast.done_forecast` | `INBOUND` |
+| 15 | 预报详情 | `GET /forecast.forecast_detail` | `INBOUND` |
+| 16 | 实时库存 | `GET /api.stocklist` | `INVENTORY_QUERY` |
+| 17 | 库龄列表 | `GET /api.stockagelist` | `INVENTORY_QUERY` |
+| 18 | 最优渠道 | `POST /api.calculate_order_v3` | `CHANNEL_RECOMMEND` |
+| 19 | 客户仓库 / 承运商 | `GET /api.get_customer_warehouses`、`/api.get_customer_logistics` | `DIRECTORY` |
+
+### 已声明但未接入
+
+| 常量 | 说明 |
+|---|---|
+| `PATH_PRODUCT_PUBLISH`(`/api.pub_product`) | 临时产品 → 正式产品,未接;建档结果仍是临时产品 |
+| `PATH_TRANSFER_LIST`(`/fba.fbalist`) | 转运列表,未接 |
+| `api.orderlist` / `forecast.forecastlist` | 列表查询均未接 |
+
+## 3. 业务流程
+
+### 出库
+
+```
+① 查仓库 / 承运商(拿 warehouse_code、logistics_type)
+ GET /api.get_customer_warehouses
+ GET /api.get_customer_logistics
+② 可选:最优渠道询价
+ POST /api.calculate_order_v3
+③ 下单(multipart/form-data)
+ POST /api.add_order_multiple
+④ 查详情 / 回读状态
+ GET /api.get_order?order_no= (或 ckh=)
+⑤ 删除(按状态分流:待审核→删除、待发货→已取消、拣货/已拣货→已拦截)
+ POST /api.delete_order
+```
+
+### 转运(仓 → 平台仓)
+
+```
+① 建转运(application/json) POST /fba.do_fba → order_no
+② 查详情 GET /fba.fba_detail?order_no=
+③ 审核 POST /fba.do_approve?order_no=
+④ 删除(仅待审核可删) POST /fba.delete_fba?order_no=
+```
+
+### 头程入库(预报)
+
+```
+① 建空单(只给单头) POST /forecast.do_forecast → order_no
+② 补明细(整段覆盖) POST /forecast.do_improve_forecast
+③ 提交 POST /forecast.done_forecast (query + body 都带 forecast_no)
+④ 查详情 GET /forecast.forecast_detail
+```
+
+> ①②③ 是三步,不是一次调用。① 不需要商品明细(`referenceSkuCount` 必填)。
+
+### 商品
+
+```
+① 查临时产品(决定 add 还是 update)
+ GET /api.productlist?state=0&key=
+② 新增(临时产品) POST /api.add_product
+ 或 更新(仅临时产品可更新) POST /api.update_product
+```
+
+## 4. 枚举映射(信仓是两套码表,core 是第三套)
+
+### 订单状态 `state`
+
+| 信仓码 | 含义 | core `OutboundStatus` |
+|---|---|---|
+| 0 | 待审核 | `PENDING_REVIEW` |
+| 1 | 待发货 | `PENDING_SHIPMENT` |
+| 2 | 拣货中 | `PICKING` |
+| 3 | 已拣货 | `PICKED` |
+| 4 | 已贴单 | `LABEL_READY` |
+| 5 | 已发货 | `SHIPPED` |
+| 6 | 已拦截 | `INTERCEPTED` |
+| 7 | 缺货 | `OUT_OF_STOCK` |
+| 8 | 已取消 | `CANCELLED` |
+| 10 | 已删除 | `DELETED` |
+| 11 | 审核中 | `REVIEWING` |
+| 12 | 审核失败 | `REVIEW_FAILED` |
+| 其他 | — | `UNKNOWN`(不猜) |
+
+### 转运状态 `state`
+
+| 信仓码 | 含义 | core `TransferStatus` |
+|---|---|---|
+| 0 | 待审核 | `PENDING_REVIEW` |
+| 1 | 待处理 | `PENDING_PROCESSING` |
+| 2 | 待拣货 | `PENDING_PICK` |
+| 3 | 待贴标 | `PENDING_LABELING` |
+| 4 | 待打托 | `PENDING_PALLETIZING` |
+| 5 | 待发货 | `PENDING_OUTBOUND` |
+| 6 | 已发货 | `SHIPPED`(**不是** `COMPLETED`)|
+| 7 | 已取消 | `CANCELLED` |
+
+> **列表接口与详情接口的码表不一致**:列表写的是「0 待审核 1 待处理 2 带拣货 3 待打托 4 待发货 5 已发货 9 取消」(少「待贴标」、后续前移)。适配器以**详情码表**为准,原始值仍保存在 `rawStatus`。
+
+### 预报状态 `state`
+
+| 信仓码 | 含义 | core `InboundStatus` |
+|---|---|---|
+| 0 | 建仓中 | `DRAFT` |
+| 1 | 出运中 | `IN_TRANSIT` |
+| 2 | 预报完成 | `PENDING_SHIPMENT` |
+| 3 | 在海上 | `IN_TRANSIT` |
+| 4 | 送仓中 | `IN_TRANSIT` |
+| 5 | 卸柜中 | `RECEIVING` |
+| 6 | 清点中 | `RECEIVING` |
+| 7 | 上架中 | `STORING` |
+| 8 | 上架完成 | `COMPLETED` |
+| 9 | 已驳回 | `REJECTED` |
+
+### 订单类型 `order_type`
+
+| 值 | 含义 | 对应 core |
+|---|---|---|
+| `common` | 非自供面单 | `LabelMode.WAREHOUSE_LABEL` |
+| `wayfair` | 自供面单 | `LabelMode.PLATFORM_LABEL`(`gzh` + `face_base64` 必填)|
+
+> 转运接口的 `order_type` 是**另一套字典**(FBA / LTL 等),与下单接口无关。
+
+## 5. 字段口径(容易传错的)
+
+| 字段 | 要传什么 |
+|---|---|
+| 下单 `ckh` | **参考号,唯一不可重复**;适配器用 `outboundRequestNo`,重推同一单号会被拒 |
+| 下单 `logistics_type` | 承运商字典值(`api.get_customer_logistics` 返回的原值) |
+| 下单 `is_sign` | `是` / `否`;模型 `OutboundCommand.signatureRequired`,未给时兜底「否」 |
+| 下单 `is_split` | `1` 拆单 / `0` 打包;未给时仓方默认 `1` |
+| 商品 `amount` | **必填且美元**;取 `declaredValue`,缺失直接拒绝(不再兜底 0.00) |
+| 商品 `bar_code` | 必填且**查重**;`WarehouseProduct.barcode` 未给时退回 SKU |
+| 商品 `ckm` | 仓库码,取 `customItemNo` |
+| 转运 `po` | 必填;未给时退回 `transferRequestNo` |
+| 转运 `delivery_mode` / `delivery_way` | 必填,只认仓方字典原值;先调字典接口 |
+| 转运 `is_pallet` | 必填 `是` / `否`;模型映射 `palletRequired` |
+| 预报 `rfc_sku_count` | 必填;取 `referenceSkuCount`,没有退回明细行数 |
+| 预报 `ref_no` | 完善资料必填,**长度上限 32** |
+| 库存 `warehouse_code` | **必填且只能单个**;传多个显式拒绝 |
+| 库存 `is_show_zero` | 默认不传时只返回库存 > 0 的 SKU;模型 `includeZeroStock` |
+| 库龄 `bill_date` | 单值字符串 `起 - 止` |
+
+## 6. 单位与时区
+
+| 字段 | 单位 |
+|---|---|
+| 商品 `weight_lbs` / `size_*_ln` | 磅 / 英寸(适配器从 cm、g 换算,保留 4 位) |
+| 商品 `amount` | 美元,2 位小数 |
+| 库存 `volume_cm` | 立方厘米 |
+| 库龄 `total_volume_cbm` | 立方米 |
+
+时间字段全部是**北京时间**,适配器解析成 UTC 后存入模型(`Instant`)。空串一律转 `null`,不猜。
+
+## 7. 平台限制(已知且无法解决)
+
+| 接口 | 字段 | 情况 |
+|---|---|---|
+| 订单详情 `get_order` | `order_no` | 只回系统单号;业务侧单号在 `ckh` |
+| 订单详情 `get_order` | 面单 | 只给 `face_url`(OSS 签名链接,有时效) |
+| 转运详情 | `dest_warehouse` | 可能是占位 `"0"` |
+| 产品建档 | `state` | 新建的是**临时产品**(`state=0`),没有上架接口就下不了单 |
+| 预报 | 明细 | 建单时没有明细,必须先建头再补 |
+| 列表查询 | 订单 / 转运 / 预报 | 均无列表接口;`query(cursor)` 用单号取详情代替 |
+| 错误信息 | `err` | 只有一句话(如「产品参数有误」),无法细分原因 |
+
+## 8. 协议待核对(联调时必看)
+
+| 项 | 现状 |
+|---|---|
+| 生产域名 | 文档未给,常量写的是 `"待核对"` |
+| 限流 | 未公开,按 2 req/s |
+| **最优渠道 `calculate_order_v3`** | 文档标 `GET` + JSON body,**OkHttp 不支持 GET 带 body**;适配器按 **POST + JSON body** 下发 |
+
+## 9. 联调探针
+
+三个探针,默认全部跳过:
+
+```bash
+# ① 登录
+mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ -Dxincang.probe=true \
+ -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \
+ -Dtest=XincangLoginProbeTest test
+
+# ② 只读(9 个查询接口)
+mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ -Dxincang.probe=true \
+ -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \
+ -Dxincang.probe.sku=<有库存的SKU> -Dxincang.probe.postcode=<美国邮编> \
+ -Dtest=XincangReadProbeTest test
+
+# ③ 写(会留下真实数据,需二次确认)
+mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ -Dxincang.probe=true -Dxincang.probe.write=true \
+ -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \
+ -Dxincang.probe.sku= -Dxincang.probe.postcode=<邮编> \
+ -Dxincang.probe.destWarehouse=<目的仓> \
+ -Dtest=XincangWriteProbeTest test
+```
+
+可选属性:`warehouseCode` / `carrier` / `orderNo` / `transferNo` / `forecastNo` / `qty` /
+`destWarehouse` / `deliveryMode` / `deliveryWay` / `orderType` / `shipmentType` /
+`cabinetType` / `deliveryRequirements` / `otherNeed` / `transferApprove`。
+
+**会留下数据的探针**:商品建档(无删除接口)、预报(`delete_forecast` 未接)、
+转运审核(审核后不可删,需 `-Dxincang.probe.transferApprove=true`)。
+出库与转运创建可以自清理。
+
+## 10. 未接入
+
+| 项 | 原因 |
+|---|---|
+| 上架正式产品 | 统一模型没有「上架」语义 |
+| 订单 / 转运 / 预报列表 | 仓方虽提供,但统一模型暂未接列表能力 |
+| 文件上传 `upload.files` | 需要 multipart 文件流;商品图片与转运附件因此传不了 |
+| 修改订单 `api.update_order` | 文档建议停止使用 |
+| 费用测算 `api.calculate_order` / `_v2` | 只接了最优渠道 `_v3` |
+| 库龄费率以外的费用明细 | `is_need_fee_rate` 已支持,但结算账单未接 |
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
index 80989bd..bef8302 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
@@ -9,9 +9,12 @@ import java.util.Objects;
/**
* 仓商品建档入参。
*
- * 单位写进字段名(cm / g),避免适配器之间靠注释约定换算。
- * 运去哪 API 115 的必填项(sku / 中英文名 / 包装方式 / 长宽高 / 重量 / SN)
- * 在这里都是必填,缺了在构造期就失败,而不是等平台报错。
+ * 单位写进字段名(cm / g),避免适配器之间靠注释约定换算。
+ *
+ * 构造期只校验所有仓都必须给的字段:{@code omsSku}、{@code name}、
+ * 长宽高与重量为正。其余字段({@code nameEn} / {@code packingType} / 海关三项 /
+ * 品类等)的必填性与组合约束都由各适配器在拼报文时校验——
+ * 否则接第二家仓时会被第一家的约束卡住。
*/
public final class WarehouseProduct {
@@ -20,11 +23,21 @@ public final class WarehouseProduct {
private final String customItemNo;
private final String barcode;
private final String name;
+ /**
+ * 英文名。
+ *
+ * 运去哪必填(适配器会拒绝缺失);信仓接口只有中文名({@code chn_name}),
+ * 未给即不传。
+ */
private final String nameEn;
private final String description;
/** 产品类型:1 成品 / 2 配件 / 3 耗材;0 表示未指定(平台默认成品)。 */
private final int productType;
- /** 发货包装:0 原包装发货 / 1 重新打包。 */
+ /**
+ * 发货包装:0 原包装发货 / 1 重新打包;-1 表示未给。
+ *
+ * 运去哪必填(适配器会拒绝缺失);信仓接口没有该字段,未给即不传。
+ */
private final int packingType;
private final double lengthCm;
private final double widthCm;
@@ -124,18 +137,37 @@ public final class WarehouseProduct {
*/
private final List lotAttributeCodes;
+ // ==================== 仓方原始字段 ====================
+
+ /**
+ * 产品品类;null 表示不传。
+ *
+ * 信仓 {@code product_category}:0 其它 / 1 家具 / 2 食品 / 3 汽配 / 4 服饰 /
+ * 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。取值由仓方字典定义,适配器不归一。
+ */
+ private final Integer productCategory;
+
+ /**
+ * 产品图片地址;null 表示不传。
+ *
+ * 信仓走「先上传文件、再回传 OSS 元数据」的两步流程({@code upload.files}),
+ * 这里只承载最终可访问的 URL;适配器拿不到 OSS 元数据时不发送该字段。
+ */
+ private final String imageUrl;
+
private WarehouseProduct(Builder b) {
this.omsSku = require(b.omsSku, "omsSku");
this.providerSku = b.providerSku;
this.customItemNo = b.customItemNo;
this.barcode = b.barcode;
this.name = require(b.name, "name");
- this.nameEn = require(b.nameEn, "nameEn");
+ // nameEn 是运去哪的必填项;信仓只有 chn_name(取 name),没有英文名。
+ // 必填性由 YqnProductMapper 校验,这里不做构造期强制。
+ this.nameEn = b.nameEn;
this.description = b.description;
this.productType = b.productType;
- if (b.packingType < 0) {
- throw new IllegalArgumentException("packingType is required (0 原包装发货 / 1 重新打包)");
- }
+ // 不在构造期强制:这是运去哪的必填项,信仓不需要。必填性由各适配器按自己的
+ // 协议校验,见 YqnProductMapper;未给时保持 -1 表示「不传」。
this.packingType = b.packingType;
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
@@ -155,6 +187,8 @@ public final class WarehouseProduct {
this.cost = b.cost;
this.link = b.link;
this.remark = b.remark;
+ this.productCategory = b.productCategory;
+ this.imageUrl = b.imageUrl;
this.expirationControl = b.expirationControl;
this.expirationDays = b.expirationDays;
this.packedQuantity = b.packedQuantity;
@@ -169,21 +203,9 @@ public final class WarehouseProduct {
this.lotAttributeCodes = java.util.Collections.unmodifiableList(
new java.util.ArrayList(b.lotAttributeCodes));
- // 海关信息要么整组给、要么整组不给:国家编码 / HS Code / 申报价值缺一即失败
- int customsFields = 0;
- if (hasText(hsCode)) {
- customsFields++;
- }
- if (hasText(countryOfOrigin)) {
- customsFields++;
- }
- if (declaredValue != null) {
- customsFields++;
- }
- if (customsFields != 0 && customsFields != 3) {
- throw new IllegalArgumentException(
- "hsCode / countryOfOrigin / declaredValue must be set together for customs");
- }
+ // 海关信息「三项整组给」原本在这里校验。但信仓只用 declaredValue 当 amount(必填),
+ // 不需要 hsCode / countryOfOrigin;在模型层强制整组会把信仓卡死。
+ // 整组校验移到需要海关信息的适配器(见 YqnProductMapper.toCustoms)。
}
public static Builder builder() {
@@ -364,6 +386,16 @@ public final class WarehouseProduct {
return remark;
}
+ /** 产品品类(仓方字典值);null 表示不传。 */
+ public Integer productCategory() {
+ return productCategory;
+ }
+
+ /** 产品图片地址;null 表示不传。 */
+ public String imageUrl() {
+ return imageUrl;
+ }
+
/** 是否给了任何海关信息。 */
public boolean hasCustoms() {
return declaredValue != null;
@@ -416,6 +448,8 @@ public final class WarehouseProduct {
private Money cost;
private String link;
private String remark;
+ private Integer productCategory;
+ private String imageUrl;
private Boolean expirationControl;
private Integer expirationDays;
private Integer packedQuantity;
@@ -469,7 +503,7 @@ public final class WarehouseProduct {
return this;
}
- /** 0 原包装发货 / 1 重新打包;必填。 */
+ /** 0 原包装发货 / 1 重新打包;运去哪必填,信仓不用。 */
public Builder packingType(int v) {
this.packingType = v;
return this;
@@ -626,6 +660,18 @@ public final class WarehouseProduct {
return this;
}
+ /** 产品品类(信仓 {@code product_category} 等字典值);null 表示不传。 */
+ public Builder productCategory(Integer v) {
+ this.productCategory = v;
+ return this;
+ }
+
+ /** 产品图片地址;null 表示不传。 */
+ public Builder imageUrl(String v) {
+ this.imageUrl = v;
+ return this;
+ }
+
/**
* @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐
*/
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 70af166..78c76b6 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
@@ -8,8 +8,10 @@ import java.util.List;
/**
* 入库计划创建命令。写操作,幂等键是 {@link #inboundRequestNo()}(仓方的来源单号)。
*
- * 必填:单号、仓、库存类型、至少一条商品行。装箱、批次、附件都是可选的——
- * 仓会在收货时按实际情况清点,但给了就必须自洽(一箱多 SKU 要用 sid 归并)。
+ * 构造期只校验所有仓都必须给的:单号、库存类型取值。仓 / 商品行 / 日期等
+ * 各家要求不同(信仓「新增预报」只建单头、明细走「完善资料」),
+ * 必填性由各适配器在拼报文时校验;装箱、批次、附件的自洽性仍由模型保证
+ * (一箱多 SKU 要用 sid 归并)。
*/
public final class InboundCommand {
@@ -133,6 +135,14 @@ public final class InboundCommand {
/** 中文名称(信仓 {@code chn_name});null 表示不传。 */
private final String chnName;
+ /**
+ * 参考 SKU 种类数;null 表示不传。
+ *
+ * 信仓 {@code rfc_sku_count}(新增预报必填)。与 {@link #lines()} 行数无关:
+ * 报的是「预计有多少种 SKU」,建单时明细还没给。
+ */
+ private final Integer referenceSkuCount;
+
private InboundCommand(Builder b) {
if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) {
throw new IllegalArgumentException("inboundRequestNo must not be blank");
@@ -160,9 +170,8 @@ public final class InboundCommand {
this.shipperPhone = b.shipperPhone;
this.containerNo = b.containerNo;
this.remark = b.remark;
- if (b.lines.isEmpty()) {
- throw new IllegalArgumentException("lines must not be empty");
- }
+ // lines 不在构造期强制:信仓的入库是「先建单头 → 再完善资料补明细」两步,
+ // 第一步本来就没有明细。需要明细的仓(运去哪、信仓的完善资料)由适配器校验。
this.lines = Collections.unmodifiableList(new ArrayList(b.lines));
this.cartons = Collections.unmodifiableList(new ArrayList(b.cartons));
this.batches = Collections.unmodifiableList(new ArrayList(b.batches));
@@ -189,6 +198,7 @@ public final class InboundCommand {
this.oversize = b.oversize;
this.oversizeNote = b.oversizeNote;
this.chnName = b.chnName;
+ this.referenceSkuCount = b.referenceSkuCount;
}
public static Builder builder() {
@@ -377,6 +387,11 @@ public final class InboundCommand {
return chnName;
}
+ /** 参考 SKU 种类数;null 表示不传(信仓 {@code rfc_sku_count})。 */
+ public Integer referenceSkuCount() {
+ return referenceSkuCount;
+ }
+
public static final class Builder {
private String inboundRequestNo;
@@ -418,6 +433,7 @@ public final class InboundCommand {
private Boolean oversize;
private String oversizeNote;
private String chnName;
+ private Integer referenceSkuCount;
public Builder inboundRequestNo(String v) {
this.inboundRequestNo = v;
@@ -632,6 +648,12 @@ public final class InboundCommand {
return this;
}
+ /** 参考 SKU 种类数(信仓 {@code rfc_sku_count},新增预报必填)。 */
+ public Builder referenceSkuCount(Integer v) {
+ this.referenceSkuCount = v;
+ return this;
+ }
+
public InboundCommand build() {
return new InboundCommand(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
index 9bfdbfe..75e66ac 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
@@ -121,6 +121,65 @@ public final class InboundOrder {
*/
private final List containers;
+ // ==================== 仓方原始字段(信仓预报详情提供)====================
+
+ /** 仓方内部预报单 id;信仓 {@code id}。 */
+ private final String providerId;
+ /** 中文名称 / 联系人;信仓 {@code chn_name}。 */
+ private final String chnName;
+ /** 客户 id;信仓 {@code customer_id}。 */
+ private final String customerId;
+ /** 客户代码;信仓 {@code customer_name}。 */
+ private final String customerNo;
+ /** 目的仓 id(仓方内部);信仓 {@code dest_warehouse},与 {@link #warehouseCode()}(仓代码)不同。 */
+ private final String destWarehouseId;
+ /** 仓方状态原文(可读名);信仓 {@code state_name},如「预报完成」。 */
+ private final String rawStatusName;
+ /** 出运类型;信仓 {@code shipment_type}(1 空运 / 2 海运)。 */
+ private final String shipmentType;
+ /** 柜型;信仓 {@code cabinet_type}(0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库)。 */
+ private final String cabinetType;
+ /** 柜号;信仓 {@code cabinet_no}。 */
+ private final String cabinetNo;
+ /** 预计发货时间(UTC);信仓 {@code rfc_etd}。 */
+ private final Instant estimatedShipAt;
+ /** 实际发货时间(UTC);信仓 {@code etd}。 */
+ private final Instant shippedAt;
+ /** 是否超 120cm;信仓 {@code is_oversize}({@code "1"} / {@code "0"})。 */
+ private final String isOversize;
+ /** 超尺寸备注;信仓 {@code oversize_val}。 */
+ private final String oversizeNote;
+ /** 发货需求;信仓 {@code delivery_requirements}(1 一件代发 / 2 FBA 中转)。 */
+ private final String deliveryRequirements;
+ /** 预报时间(UTC);信仓 {@code forecast_time}。 */
+ private final Instant forecastAt;
+ /** 参考 SKU 种类数;信仓 {@code rfc_sku_count}。 */
+ private final Integer referenceSkuCount;
+ /** 预报托盘数;信仓 {@code forecast_pallet_qty}(柜型为托盘入库时才有)。 */
+ private final Integer forecastPalletQty;
+ /** 实收托盘数;信仓 {@code receive_pallet_qty}。 */
+ private final Integer receivedPalletQty;
+ /** 上架托盘数;信仓 {@code shelf_pallet_qty}。 */
+ private final Integer storedPalletQty;
+ /** 计费托盘数;信仓 {@code bill_pallet_qty}。 */
+ private final Integer billedPalletQty;
+ /** 卸柜清点时间(UTC);信仓 {@code unlade_time}。 */
+ private final Instant unladeAt;
+ /** 清点完成时间(UTC);信仓 {@code check_time}。 */
+ private final Instant checkedAt;
+ /** 上架时间(UTC);信仓 {@code putaway_time}。 */
+ private final Instant putawayAt;
+ /** 还柜时间(UTC);信仓 {@code leave_time}。 */
+ private final Instant leftAt;
+ /** 是否需要内箱贴;信仓 {@code is_inner_box_sticker}({@code "1"} / {@code "0"})。 */
+ private final String isInnerBoxSticker;
+ /** 是否需要外箱贴;信仓 {@code is_outer_box_sticker}。 */
+ private final String isOuterBoxSticker;
+ /** 其他需求(仓方原值,逗号分隔);信仓 {@code other_need},如「内箱贴,外箱贴」。 */
+ private final String otherNeed;
+ /** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */
+ private final Instant modifiedAt;
+
private InboundOrder(Builder b) {
this.inboundRequestNo = require(b.inboundRequestNo, "inboundRequestNo");
this.providerInboundId = b.providerInboundId;
@@ -158,6 +217,34 @@ public final class InboundOrder {
this.cartonTotalWeightKg = b.cartonTotalWeightKg;
this.cartonTotalVolumeCbm = b.cartonTotalVolumeCbm;
this.containers = Collections.unmodifiableList(new ArrayList(b.containers));
+ this.providerId = b.providerId;
+ this.chnName = b.chnName;
+ this.customerId = b.customerId;
+ this.customerNo = b.customerNo;
+ this.destWarehouseId = b.destWarehouseId;
+ this.rawStatusName = b.rawStatusName;
+ this.shipmentType = b.shipmentType;
+ this.cabinetType = b.cabinetType;
+ this.cabinetNo = b.cabinetNo;
+ this.estimatedShipAt = b.estimatedShipAt;
+ this.shippedAt = b.shippedAt;
+ this.isOversize = b.isOversize;
+ this.oversizeNote = b.oversizeNote;
+ this.deliveryRequirements = b.deliveryRequirements;
+ this.forecastAt = b.forecastAt;
+ this.referenceSkuCount = b.referenceSkuCount;
+ this.forecastPalletQty = b.forecastPalletQty;
+ this.receivedPalletQty = b.receivedPalletQty;
+ this.storedPalletQty = b.storedPalletQty;
+ this.billedPalletQty = b.billedPalletQty;
+ this.unladeAt = b.unladeAt;
+ this.checkedAt = b.checkedAt;
+ this.putawayAt = b.putawayAt;
+ this.leftAt = b.leftAt;
+ this.isInnerBoxSticker = b.isInnerBoxSticker;
+ this.isOuterBoxSticker = b.isOuterBoxSticker;
+ this.otherNeed = b.otherNeed;
+ this.modifiedAt = b.modifiedAt;
}
public static Builder builder() {
@@ -273,6 +360,146 @@ public final class InboundOrder {
return lines;
}
+ /** 仓方内部预报单 id。 */
+ public String providerId() {
+ return providerId;
+ }
+
+ /** 中文名称 / 联系人。 */
+ public String chnName() {
+ return chnName;
+ }
+
+ /** 客户 id。 */
+ public String customerId() {
+ return customerId;
+ }
+
+ /** 客户代码。 */
+ public String customerNo() {
+ return customerNo;
+ }
+
+ /** 目的仓 id(仓方内部)。 */
+ public String destWarehouseId() {
+ return destWarehouseId;
+ }
+
+ /** 仓方状态原文(可读名)。 */
+ public String rawStatusName() {
+ return rawStatusName;
+ }
+
+ /** 出运类型(1 空运 / 2 海运)。 */
+ public String shipmentType() {
+ return shipmentType;
+ }
+
+ /** 柜型。 */
+ public String cabinetType() {
+ return cabinetType;
+ }
+
+ /** 柜号。 */
+ public String cabinetNo() {
+ return cabinetNo;
+ }
+
+ /** 预计发货时间(UTC)。 */
+ public Instant estimatedShipAt() {
+ return estimatedShipAt;
+ }
+
+ /** 实际发货时间(UTC)。 */
+ public Instant shippedAt() {
+ return shippedAt;
+ }
+
+ /** 是否超 120cm(仓方原值)。 */
+ public String isOversize() {
+ return isOversize;
+ }
+
+ /** 超尺寸备注。 */
+ public String oversizeNote() {
+ return oversizeNote;
+ }
+
+ /** 发货需求(1 一件代发 / 2 FBA 中转)。 */
+ public String deliveryRequirements() {
+ return deliveryRequirements;
+ }
+
+ /** 预报时间(UTC)。 */
+ public Instant forecastAt() {
+ return forecastAt;
+ }
+
+ /** 参考 SKU 种类数。 */
+ public Integer referenceSkuCount() {
+ return referenceSkuCount;
+ }
+
+ /** 预报托盘数。 */
+ public Integer forecastPalletQty() {
+ return forecastPalletQty;
+ }
+
+ /** 实收托盘数。 */
+ public Integer receivedPalletQty() {
+ return receivedPalletQty;
+ }
+
+ /** 上架托盘数。 */
+ public Integer storedPalletQty() {
+ return storedPalletQty;
+ }
+
+ /** 计费托盘数。 */
+ public Integer billedPalletQty() {
+ return billedPalletQty;
+ }
+
+ /** 卸柜清点时间(UTC)。 */
+ public Instant unladeAt() {
+ return unladeAt;
+ }
+
+ /** 清点完成时间(UTC)。 */
+ public Instant checkedAt() {
+ return checkedAt;
+ }
+
+ /** 上架时间(UTC)。 */
+ public Instant putawayAt() {
+ return putawayAt;
+ }
+
+ /** 还柜时间(UTC)。 */
+ public Instant leftAt() {
+ return leftAt;
+ }
+
+ /** 是否需要内箱贴(仓方原值)。 */
+ public String isInnerBoxSticker() {
+ return isInnerBoxSticker;
+ }
+
+ /** 是否需要外箱贴(仓方原值)。 */
+ public String isOuterBoxSticker() {
+ return isOuterBoxSticker;
+ }
+
+ /** 其他需求(仓方原值)。 */
+ public String otherNeed() {
+ return otherNeed;
+ }
+
+ /** 最后修改时间(UTC)。 */
+ public Instant modifiedAt() {
+ return modifiedAt;
+ }
+
/** 是否整体完成入库。 */
public boolean completed() {
return status == InboundStatus.COMPLETED;
@@ -452,6 +679,34 @@ public final class InboundOrder {
private Double cartonTotalWeightKg;
private Double cartonTotalVolumeCbm;
private final List containers = new ArrayList();
+ private String providerId;
+ private String chnName;
+ private String customerId;
+ private String customerNo;
+ private String destWarehouseId;
+ private String rawStatusName;
+ private String shipmentType;
+ private String cabinetType;
+ private String cabinetNo;
+ private Instant estimatedShipAt;
+ private Instant shippedAt;
+ private String isOversize;
+ private String oversizeNote;
+ private String deliveryRequirements;
+ private Instant forecastAt;
+ private Integer referenceSkuCount;
+ private Integer forecastPalletQty;
+ private Integer receivedPalletQty;
+ private Integer storedPalletQty;
+ private Integer billedPalletQty;
+ private Instant unladeAt;
+ private Instant checkedAt;
+ private Instant putawayAt;
+ private Instant leftAt;
+ private String isInnerBoxSticker;
+ private String isOuterBoxSticker;
+ private String otherNeed;
+ private Instant modifiedAt;
public Builder inboundRequestNo(String v) {
this.inboundRequestNo = v;
@@ -628,6 +883,174 @@ public final class InboundOrder {
return this;
}
+ /** 仓方内部预报单 id(信仓 {@code id})。 */
+ public Builder providerId(String v) {
+ this.providerId = v;
+ return this;
+ }
+
+ /** 中文名称 / 联系人(信仓 {@code chn_name})。 */
+ public Builder chnName(String v) {
+ this.chnName = v;
+ return this;
+ }
+
+ /** 客户 id(信仓 {@code customer_id})。 */
+ public Builder customerId(String v) {
+ this.customerId = v;
+ return this;
+ }
+
+ /** 客户代码(信仓 {@code customer_name})。 */
+ public Builder customerNo(String v) {
+ this.customerNo = v;
+ return this;
+ }
+
+ /** 目的仓 id(信仓 {@code dest_warehouse})。 */
+ public Builder destWarehouseId(String v) {
+ this.destWarehouseId = v;
+ return this;
+ }
+
+ /** 仓方状态原文(信仓 {@code state_name})。 */
+ public Builder rawStatusName(String v) {
+ this.rawStatusName = v;
+ return this;
+ }
+
+ /** 出运类型(信仓 {@code shipment_type})。 */
+ public Builder shipmentType(String v) {
+ this.shipmentType = v;
+ return this;
+ }
+
+ /** 柜型(信仓 {@code cabinet_type})。 */
+ public Builder cabinetType(String v) {
+ this.cabinetType = v;
+ return this;
+ }
+
+ /** 柜号(信仓 {@code cabinet_no})。 */
+ public Builder cabinetNo(String v) {
+ this.cabinetNo = v;
+ return this;
+ }
+
+ /** 预计发货时间(信仓 {@code rfc_etd})。 */
+ public Builder estimatedShipAt(Instant v) {
+ this.estimatedShipAt = v;
+ return this;
+ }
+
+ /** 实际发货时间(信仓 {@code etd})。 */
+ public Builder shippedAt(Instant v) {
+ this.shippedAt = v;
+ return this;
+ }
+
+ /** 是否超 120cm(信仓 {@code is_oversize})。 */
+ public Builder isOversize(String v) {
+ this.isOversize = v;
+ return this;
+ }
+
+ /** 超尺寸备注(信仓 {@code oversize_val})。 */
+ public Builder oversizeNote(String v) {
+ this.oversizeNote = v;
+ return this;
+ }
+
+ /** 发货需求(信仓 {@code delivery_requirements})。 */
+ public Builder deliveryRequirements(String v) {
+ this.deliveryRequirements = v;
+ return this;
+ }
+
+ /** 预报时间(信仓 {@code forecast_time})。 */
+ public Builder forecastAt(Instant v) {
+ this.forecastAt = v;
+ return this;
+ }
+
+ /** 参考 SKU 种类数(信仓 {@code rfc_sku_count})。 */
+ public Builder referenceSkuCount(Integer v) {
+ this.referenceSkuCount = v;
+ return this;
+ }
+
+ /** 预报托盘数(信仓 {@code forecast_pallet_qty})。 */
+ public Builder forecastPalletQty(Integer v) {
+ this.forecastPalletQty = v;
+ return this;
+ }
+
+ /** 实收托盘数(信仓 {@code receive_pallet_qty})。 */
+ public Builder receivedPalletQty(Integer v) {
+ this.receivedPalletQty = v;
+ return this;
+ }
+
+ /** 上架托盘数(信仓 {@code shelf_pallet_qty})。 */
+ public Builder storedPalletQty(Integer v) {
+ this.storedPalletQty = v;
+ return this;
+ }
+
+ /** 计费托盘数(信仓 {@code bill_pallet_qty})。 */
+ public Builder billedPalletQty(Integer v) {
+ this.billedPalletQty = v;
+ return this;
+ }
+
+ /** 卸柜清点时间(信仓 {@code unlade_time})。 */
+ public Builder unladeAt(Instant v) {
+ this.unladeAt = v;
+ return this;
+ }
+
+ /** 清点完成时间(信仓 {@code check_time})。 */
+ public Builder checkedAt(Instant v) {
+ this.checkedAt = v;
+ return this;
+ }
+
+ /** 上架时间(信仓 {@code putaway_time})。 */
+ public Builder putawayAt(Instant v) {
+ this.putawayAt = v;
+ return this;
+ }
+
+ /** 还柜时间(信仓 {@code leave_time})。 */
+ public Builder leftAt(Instant v) {
+ this.leftAt = v;
+ return this;
+ }
+
+ /** 是否需要内箱贴(信仓 {@code is_inner_box_sticker})。 */
+ public Builder isInnerBoxSticker(String v) {
+ this.isInnerBoxSticker = v;
+ return this;
+ }
+
+ /** 是否需要外箱贴(信仓 {@code is_outer_box_sticker})。 */
+ public Builder isOuterBoxSticker(String v) {
+ this.isOuterBoxSticker = v;
+ return this;
+ }
+
+ /** 其他需求(信仓 {@code other_need})。 */
+ public Builder otherNeed(String v) {
+ this.otherNeed = v;
+ return this;
+ }
+
+ /** 最后修改时间(信仓 {@code gmt_modify})。 */
+ public Builder modifiedAt(Instant v) {
+ this.modifiedAt = v;
+ return this;
+ }
+
public InboundOrder build() {
return new InboundOrder(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java
index 5e22717..7b00770 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java
@@ -23,6 +23,25 @@ public final class InboundOrderLine {
/** 最近上架时间(备货完成时间)。 */
private final Instant receivedAt;
+ // ==================== 仓方原始字段(信仓预报详情提供)====================
+
+ /** 产品名;信仓 {@code product_name}。 */
+ private final String productName;
+ /** 中文名;信仓 {@code chn_name}。 */
+ private final String productNameCn;
+ /**
+ * 清点箱数;信仓 {@code check_box_qty}。
+ *
+ * 与 {@link #packedQuantity()}(预报箱数)不同:这个是仓方清点后实际确认的箱数。
+ */
+ private final int checkedBoxCount;
+ /** 打托件数;信仓 {@code pallet_sku_count}。 */
+ private final int palletizedQuantity;
+ /** 装箱率;信仓 {@code packing_rate}。 */
+ private final String packingRate;
+ /** 体积(立方厘米);信仓 {@code volume_cm}。 */
+ private final String volumeCm;
+
private InboundOrderLine(Builder b) {
this.providerSku = require(b.providerSku, "providerSku");
this.plannedQuantity = b.plannedQuantity;
@@ -31,6 +50,12 @@ public final class InboundOrderLine {
this.receivedSaleableQuantity = b.receivedSaleableQuantity;
this.receivedUnsaleableQuantity = b.receivedUnsaleableQuantity;
this.receivedAt = b.receivedAt;
+ this.productName = b.productName;
+ this.productNameCn = b.productNameCn;
+ this.checkedBoxCount = b.checkedBoxCount;
+ this.palletizedQuantity = b.palletizedQuantity;
+ this.packingRate = b.packingRate;
+ this.volumeCm = b.volumeCm;
}
public static Builder builder() {
@@ -65,6 +90,36 @@ public final class InboundOrderLine {
return receivedAt;
}
+ /** 产品名。 */
+ public String productName() {
+ return productName;
+ }
+
+ /** 中文名。 */
+ public String productNameCn() {
+ return productNameCn;
+ }
+
+ /** 清点箱数;与 {@link #packedQuantity()}(预报箱数)不同。 */
+ public int checkedBoxCount() {
+ return checkedBoxCount;
+ }
+
+ /** 打托件数。 */
+ public int palletizedQuantity() {
+ return palletizedQuantity;
+ }
+
+ /** 装箱率(仓方原值)。 */
+ public String packingRate() {
+ return packingRate;
+ }
+
+ /** 体积(立方厘米,仓方原值)。 */
+ public String volumeCm() {
+ return volumeCm;
+ }
+
/** 实收与计划是否一致;不一致说明短少或溢装,需要人工核对。 */
public boolean quantityMatchesPlan() {
return receivedQuantity == plannedQuantity;
@@ -85,6 +140,12 @@ public final class InboundOrderLine {
private int receivedSaleableQuantity;
private int receivedUnsaleableQuantity;
private Instant receivedAt;
+ private String productName;
+ private String productNameCn;
+ private int checkedBoxCount;
+ private int palletizedQuantity;
+ private String packingRate;
+ private String volumeCm;
public Builder providerSku(String v) {
this.providerSku = v;
@@ -121,6 +182,42 @@ public final class InboundOrderLine {
return this;
}
+ /** 产品名(信仓 {@code product_name})。 */
+ public Builder productName(String v) {
+ this.productName = v;
+ return this;
+ }
+
+ /** 中文名(信仓 {@code chn_name})。 */
+ public Builder productNameCn(String v) {
+ this.productNameCn = v;
+ return this;
+ }
+
+ /** 清点箱数(信仓 {@code check_box_qty})。 */
+ public Builder checkedBoxCount(int v) {
+ this.checkedBoxCount = v;
+ return this;
+ }
+
+ /** 打托件数(信仓 {@code pallet_sku_count})。 */
+ public Builder palletizedQuantity(int v) {
+ this.palletizedQuantity = v;
+ return this;
+ }
+
+ /** 装箱率(信仓 {@code packing_rate})。 */
+ public Builder packingRate(String v) {
+ this.packingRate = v;
+ return this;
+ }
+
+ /** 体积(信仓 {@code volume_cm})。 */
+ public Builder volumeCm(String v) {
+ this.volumeCm = v;
+ return this;
+ }
+
public InboundOrderLine build() {
return new InboundOrderLine(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
index a53cbc5..1d74310 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
@@ -15,6 +15,13 @@ public final class InventoryQuery {
private final Instant updatedAfter;
private final int pageSize;
private final String cursor;
+ /**
+ * 是否包含零库存的 SKU;null 表示不传,由仓方按默认处理。
+ *
+ * 部分仓(信仓 {@code is_show_zero})默认只返回库存大于 0 的数据;
+ * 需要做全量对账时显式传 {@code true}。不支持的仓忽略该字段。
+ */
+ private final Boolean includeZeroStock;
private InventoryQuery(Builder b) {
this.providerSkus = Collections.unmodifiableList(new ArrayList(b.providerSkus));
@@ -23,6 +30,7 @@ public final class InventoryQuery {
this.updatedAfter = b.updatedAfter;
this.pageSize = b.pageSize;
this.cursor = b.cursor;
+ this.includeZeroStock = b.includeZeroStock;
}
public static Builder builder() {
@@ -56,6 +64,11 @@ public final class InventoryQuery {
return cursor;
}
+ /** 是否包含零库存 SKU;null 表示不传。 */
+ public Boolean includeZeroStock() {
+ return includeZeroStock;
+ }
+
public static final class Builder {
private final List providerSkus = new ArrayList();
private final List warehouseCodes = new ArrayList();
@@ -63,6 +76,7 @@ public final class InventoryQuery {
private Instant updatedAfter;
private int pageSize = 100;
private String cursor;
+ private Boolean includeZeroStock;
public Builder sku(String sku) {
if (sku != null) {
@@ -113,6 +127,16 @@ public final class InventoryQuery {
return this;
}
+ /**
+ * 是否包含零库存 SKU;null 表示不传(仓方默认)。
+ *
+ * 信仓对应 {@code is_show_zero}:默认只返回库存大于 0 的产品。
+ */
+ public Builder includeZeroStock(Boolean v) {
+ this.includeZeroStock = v;
+ return this;
+ }
+
public InventoryQuery build() {
return new InventoryQuery(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
index 15fde17..d9dd244 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
@@ -67,6 +67,16 @@ public final class OutboundCommand {
/** 是否 SFP(Seller Fulfilled Prime);null 表示不传,由仓按默认否处理。 */
private final Boolean sfp;
+ // ==================== 仓方原始字段(下单时用)====================
+
+ /**
+ * 是否需要签名签收;null 表示不传,由仓方按默认处理。
+ *
+ * 信仓 {@code is_sign}({@code "1"} / {@code "0"})。适配器不会替你猜:
+ * 不传就不发,仓方默认值与业务要求未必一致。
+ */
+ private final Boolean signatureRequired;
+
private OutboundCommand(Builder b) {
if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) {
throw new IllegalArgumentException("outboundRequestNo must not be blank");
@@ -96,6 +106,7 @@ public final class OutboundCommand {
this.labelContentBase64 = b.labelContentBase64;
this.shopName = b.shopName;
this.sfp = b.sfp;
+ this.signatureRequired = b.signatureRequired;
}
public static Builder builder() {
@@ -207,6 +218,11 @@ public final class OutboundCommand {
return sfp;
}
+ /** 是否需要签名签收;null 表示不传(信仓 {@code is_sign})。 */
+ public Boolean signatureRequired() {
+ return signatureRequired;
+ }
+
public static final class Builder {
private String outboundRequestNo;
@@ -230,6 +246,7 @@ public final class OutboundCommand {
private String labelContentBase64;
private String shopName;
private Boolean sfp;
+ private Boolean signatureRequired;
public Builder outboundRequestNo(String outboundRequestNo) {
this.outboundRequestNo = outboundRequestNo;
@@ -353,6 +370,12 @@ public final class OutboundCommand {
return this;
}
+ /** 是否需要签名签收;null 表示不传(信仓 {@code is_sign})。 */
+ public Builder signatureRequired(Boolean v) {
+ this.signatureRequired = v;
+ return this;
+ }
+
public OutboundCommand build() {
return new OutboundCommand(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
index 73da5c3..57de083 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
@@ -99,6 +99,66 @@ public final class OutboundOrder {
*/
private final String thirdPartyAccount;
+ // ==================== 仓方原始字段(部分是某家仓特有,见每项说明)====================
+
+ /** 仓方内部订单 id;信仓 {@code id}。其他仓未提供时为 null。 */
+ private final String providerId;
+ /** 仓方状态原文(可读名);信仓 {@code state_name},如「已发货」。其他仓未提供时为 null。 */
+ private final String rawStatusName;
+ /**
+ * 物流面单下载地址。
+ *
+ * 信仓 {@code face_url}(OSS 签名 URL,有时效);运去哪通过 packages 返回。可能为 null。
+ */
+ private final String labelUrl;
+ /** 店铺名;信仓 {@code shop_name},如 {@code XC001-shop}。其他仓未提供时为 null。 */
+ private final String shopName;
+ /** 订单件数合计;信仓 {@code sku_count}。其他仓未提供时为 null。 */
+ private final Integer skuCount;
+ /** 产品 SKU(单件订单的便捷字段);信仓 {@code product_sku}。多件订单请看 {@link #lines()}。 */
+ private final String productSku;
+ /** 产品名(单件订单的便捷字段);信仓 {@code product_name}。 */
+ private final String productName;
+ /** 来源 SKU;信仓 {@code source_sku}。与 {@link #productSku()} 在信仓通常相同。 */
+ private final String sourceSku;
+ /** 仓方内部仓库 id;信仓 {@code warehouse_id}。与 {@link #warehouseCode()}(仓代码)不同。 */
+ private final String providerWarehouseId;
+ /** 是否需要签名签收;信仓 {@code is_sign}({@code "1"} / {@code "0"})。 */
+ private final String isSign;
+ /** 计费分区;信仓 {@code zone},承运商分区号。 */
+ private final String zone;
+ /** 包裹长(英寸,仓方原值);信仓 {@code dim_length}。 */
+ private final String dimLength;
+ /** 包裹宽(英寸,仓方原值);信仓 {@code dim_width}。 */
+ private final String dimWidth;
+ /** 包裹高(英寸,仓方原值);信仓 {@code dim_height}。 */
+ private final String dimHeight;
+ /** 计抛系数;信仓 {@code dim_divisor}。 */
+ private final String dimDivisor;
+ /** 实重(磅,字符串原值);信仓 {@code weight_lbs}。 */
+ private final String weightLbs;
+ /** 计费重(磅,字符串原值);信仓 {@code billing_weight_lbs}。 */
+ private final String billingWeightLbs;
+ /** 体积重(磅,字符串原值);信仓 {@code volume_weight_lbs}。 */
+ private final String volumeWeightLbs;
+ /**
+ * 订单总费用(仓方原值字符串)。
+ *
+ * 信仓 {@code total_amount}:总费用,含运费与操作费等,不等于
+ * {@link #estimatedShippingFee()}(预估运费)。两者不互相覆盖。
+ */
+ private final Money totalAmount;
+ /** 修复 / 补收金额;信仓 {@code repair_amount}。 */
+ private final Money repairAmount;
+ /** 审核时间(UTC);信仓 {@code approve_time}。 */
+ private final Instant approvedAt;
+ /** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */
+ private final Instant modifiedAt;
+ /** 取消时间(UTC);信仓 {@code gmt_cancel},未取消为 null。 */
+ private final Instant cancelledAt;
+ /** 截单时间(UTC);信仓 {@code intercept_time}。 */
+ private final Instant interceptedAt;
+
private OutboundOrder(Builder b) {
this.warehouseCode = requireText(b.warehouseCode, "warehouseCode");
this.outboundRequestNo = requireText(b.outboundRequestNo, "outboundRequestNo");
@@ -127,6 +187,30 @@ public final class OutboundOrder {
this.signatureRequired = b.signatureRequired;
this.insured = b.insured;
this.thirdPartyAccount = b.thirdPartyAccount;
+ this.providerId = b.providerId;
+ this.rawStatusName = b.rawStatusName;
+ this.labelUrl = b.labelUrl;
+ this.shopName = b.shopName;
+ this.skuCount = b.skuCount;
+ this.productSku = b.productSku;
+ this.productName = b.productName;
+ this.sourceSku = b.sourceSku;
+ this.providerWarehouseId = b.providerWarehouseId;
+ this.isSign = b.isSign;
+ this.zone = b.zone;
+ this.dimLength = b.dimLength;
+ this.dimWidth = b.dimWidth;
+ this.dimHeight = b.dimHeight;
+ this.dimDivisor = b.dimDivisor;
+ this.weightLbs = b.weightLbs;
+ this.billingWeightLbs = b.billingWeightLbs;
+ this.volumeWeightLbs = b.volumeWeightLbs;
+ this.totalAmount = b.totalAmount;
+ this.repairAmount = b.repairAmount;
+ this.approvedAt = b.approvedAt;
+ this.modifiedAt = b.modifiedAt;
+ this.cancelledAt = b.cancelledAt;
+ this.interceptedAt = b.interceptedAt;
}
public static Builder builder() {
@@ -241,6 +325,126 @@ public final class OutboundOrder {
return thirdPartyAccount;
}
+ /** 仓方内部订单 id。 */
+ public String providerId() {
+ return providerId;
+ }
+
+ /** 仓方状态原文(可读名)。 */
+ public String rawStatusName() {
+ return rawStatusName;
+ }
+
+ /** 物流面单下载地址;可能为 null。 */
+ public String labelUrl() {
+ return labelUrl;
+ }
+
+ /** 店铺名。 */
+ public String shopName() {
+ return shopName;
+ }
+
+ /** 订单件数合计。 */
+ public Integer skuCount() {
+ return skuCount;
+ }
+
+ /** 单件订单的便捷字段:产品 SKU。 */
+ public String productSku() {
+ return productSku;
+ }
+
+ /** 单件订单的便捷字段:产品名。 */
+ public String productName() {
+ return productName;
+ }
+
+ /** 来源 SKU。 */
+ public String sourceSku() {
+ return sourceSku;
+ }
+
+ /** 仓方内部仓库 id。 */
+ public String providerWarehouseId() {
+ return providerWarehouseId;
+ }
+
+ /** 是否需要签名签收(仓方原值)。 */
+ public String isSign() {
+ return isSign;
+ }
+
+ /** 计费分区。 */
+ public String zone() {
+ return zone;
+ }
+
+ /** 包裹长(英寸,仓方原值)。 */
+ public String dimLength() {
+ return dimLength;
+ }
+
+ /** 包裹宽(英寸,仓方原值)。 */
+ public String dimWidth() {
+ return dimWidth;
+ }
+
+ /** 包裹高(英寸,仓方原值)。 */
+ public String dimHeight() {
+ return dimHeight;
+ }
+
+ /** 计抛系数。 */
+ public String dimDivisor() {
+ return dimDivisor;
+ }
+
+ /** 实重(磅,仓方原值)。 */
+ public String weightLbs() {
+ return weightLbs;
+ }
+
+ /** 计费重(磅,仓方原值)。 */
+ public String billingWeightLbs() {
+ return billingWeightLbs;
+ }
+
+ /** 体积重(磅,仓方原值)。 */
+ public String volumeWeightLbs() {
+ return volumeWeightLbs;
+ }
+
+ /** 订单总费用;与 {@link #estimatedShippingFee()} 不同,不要互相覆盖。 */
+ public Money totalAmount() {
+ return totalAmount;
+ }
+
+ /** 修复 / 补收金额。 */
+ public Money repairAmount() {
+ return repairAmount;
+ }
+
+ /** 审核时间(UTC)。 */
+ public Instant approvedAt() {
+ return approvedAt;
+ }
+
+ /** 最后修改时间(UTC)。 */
+ public Instant modifiedAt() {
+ return modifiedAt;
+ }
+
+ /** 取消时间(UTC);未取消为 null。 */
+ public Instant cancelledAt() {
+ return cancelledAt;
+ }
+
+ /** 截单时间(UTC)。 */
+ public Instant interceptedAt() {
+ return interceptedAt;
+ }
+
/** 是否带仓方异常。 */
public boolean hasException() {
return exceptionCode != null && !exceptionCode.trim().isEmpty();
@@ -274,6 +478,30 @@ public final class OutboundOrder {
private Instant paidAt;
private String carrierCode;
private String currency;
+ private String providerId;
+ private String rawStatusName;
+ private String labelUrl;
+ private String shopName;
+ private Integer skuCount;
+ private String productSku;
+ private String productName;
+ private String sourceSku;
+ private String providerWarehouseId;
+ private String isSign;
+ private String zone;
+ private String dimLength;
+ private String dimWidth;
+ private String dimHeight;
+ private String dimDivisor;
+ private String weightLbs;
+ private String billingWeightLbs;
+ private String volumeWeightLbs;
+ private Money totalAmount;
+ private Money repairAmount;
+ private Instant approvedAt;
+ private Instant modifiedAt;
+ private Instant cancelledAt;
+ private Instant interceptedAt;
private List attachments = new ArrayList();
private List serialNumbers = new ArrayList();
private Boolean signatureRequired;
@@ -400,6 +628,150 @@ public final class OutboundOrder {
return this;
}
+ /** 仓方内部订单 id(信仓 {@code id})。 */
+ public Builder providerId(String v) {
+ this.providerId = v;
+ return this;
+ }
+
+ /** 仓方状态原文(信仓 {@code state_name})。 */
+ public Builder rawStatusName(String v) {
+ this.rawStatusName = v;
+ return this;
+ }
+
+ /** 物流面单下载地址(信仓 {@code face_url})。 */
+ public Builder labelUrl(String v) {
+ this.labelUrl = v;
+ return this;
+ }
+
+ /** 店铺名(信仓 {@code shop_name})。 */
+ public Builder shopName(String v) {
+ this.shopName = v;
+ return this;
+ }
+
+ /** 订单件数合计(信仓 {@code sku_count})。 */
+ public Builder skuCount(Integer v) {
+ this.skuCount = v;
+ return this;
+ }
+
+ /** 单件订单的产品 SKU(信仓 {@code product_sku})。 */
+ public Builder productSku(String v) {
+ this.productSku = v;
+ return this;
+ }
+
+ /** 单件订单的产品名(信仓 {@code product_name})。 */
+ public Builder productName(String v) {
+ this.productName = v;
+ return this;
+ }
+
+ /** 来源 SKU(信仓 {@code source_sku})。 */
+ public Builder sourceSku(String v) {
+ this.sourceSku = v;
+ return this;
+ }
+
+ /** 仓方内部仓库 id(信仓 {@code warehouse_id})。 */
+ public Builder providerWarehouseId(String v) {
+ this.providerWarehouseId = v;
+ return this;
+ }
+
+ /** 是否需要签名签收(信仓 {@code is_sign})。 */
+ public Builder isSign(String v) {
+ this.isSign = v;
+ return this;
+ }
+
+ /** 计费分区(信仓 {@code zone})。 */
+ public Builder zone(String v) {
+ this.zone = v;
+ return this;
+ }
+
+ /** 包裹长(信仓 {@code dim_length})。 */
+ public Builder dimLength(String v) {
+ this.dimLength = v;
+ return this;
+ }
+
+ /** 包裹宽(信仓 {@code dim_width})。 */
+ public Builder dimWidth(String v) {
+ this.dimWidth = v;
+ return this;
+ }
+
+ /** 包裹高(信仓 {@code dim_height})。 */
+ public Builder dimHeight(String v) {
+ this.dimHeight = v;
+ return this;
+ }
+
+ /** 计抛系数(信仓 {@code dim_divisor})。 */
+ public Builder dimDivisor(String v) {
+ this.dimDivisor = v;
+ return this;
+ }
+
+ /** 实重(信仓 {@code weight_lbs})。 */
+ public Builder weightLbs(String v) {
+ this.weightLbs = v;
+ return this;
+ }
+
+ /** 计费重(信仓 {@code billing_weight_lbs})。 */
+ public Builder billingWeightLbs(String v) {
+ this.billingWeightLbs = v;
+ return this;
+ }
+
+ /** 体积重(信仓 {@code volume_weight_lbs})。 */
+ public Builder volumeWeightLbs(String v) {
+ this.volumeWeightLbs = v;
+ return this;
+ }
+
+ /** 订单总费用(信仓 {@code total_amount})。 */
+ public Builder totalAmount(Money v) {
+ this.totalAmount = v;
+ return this;
+ }
+
+ /** 修复 / 补收金额(信仓 {@code repair_amount})。 */
+ public Builder repairAmount(Money v) {
+ this.repairAmount = v;
+ return this;
+ }
+
+ /** 审核时间(信仓 {@code approve_time})。 */
+ public Builder approvedAt(Instant v) {
+ this.approvedAt = v;
+ return this;
+ }
+
+ /** 最后修改时间(信仓 {@code gmt_modify})。 */
+ public Builder modifiedAt(Instant v) {
+ this.modifiedAt = v;
+ return this;
+ }
+
+ /** 取消时间(信仓 {@code gmt_cancel})。 */
+ public Builder cancelledAt(Instant v) {
+ this.cancelledAt = v;
+ return this;
+ }
+
+ /** 截单时间(信仓 {@code intercept_time})。 */
+ public Builder interceptedAt(Instant v) {
+ this.interceptedAt = v;
+ return this;
+ }
+
public OutboundOrder build() {
return new OutboundOrder(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 bcfa8a5..e73aca8 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
@@ -8,6 +8,9 @@ import java.util.List;
* 调拨单创建命令。写操作,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。
*
* 运去哪对 {@code sourceNo} 有唯一约束,查询与取消都靠它,所以它同时是业务主键。
+ *
+ * 构造期只校验跨仓共识的必填项;某一家仓特有的必填项(运去哪的日期与收货地址、
+ * 信仓的转运类型 / 方式 / 是否打托)由各适配器在拼报文时校验。
*/
public final class TransferCommand {
@@ -29,7 +32,7 @@ public final class TransferCommand {
private final String removeOrderId;
/** 目的地地址 code(FBA 地址 code)。 */
private final String receiveStore;
- /** 目的地地址;{@code TransferType.OUTBOUND} 时构造期必填。 */
+ /** 目的地地址;调拨出库时部分仓必填(运去哪),必填性由适配器校验。 */
private final ShipTo shipTo;
private final String remark;
/** 增值服务:1 贴产品标 / 2 贴箱标 / 3 贴托盘标。 */
@@ -101,11 +104,10 @@ public final class TransferCommand {
this.inventoryType = b.inventoryType;
this.carrierType = b.carrierType;
this.transportationType = b.transportationType;
- if (b.estimateOutboundDate == null || b.estimateInboundDate == null) {
- throw new IllegalArgumentException(
- "estimateOutboundDate and estimateInboundDate are required");
- }
- if (b.estimateInboundDate.isBefore(b.estimateOutboundDate)) {
+ // 日期必填是运去哪的要求,信仓转运只需要发货日期(pre_send_time)。
+ // 必填性与先后顺序由各适配器校验;这里只保证「给了两个才比较先后」的自洽。
+ if (b.estimateOutboundDate != null && b.estimateInboundDate != null
+ && b.estimateInboundDate.isBefore(b.estimateOutboundDate)) {
throw new IllegalArgumentException(
"estimateInboundDate must not be earlier than estimateOutboundDate");
}
@@ -115,10 +117,8 @@ public final class TransferCommand {
this.removeOrderId = b.removeOrderId;
this.receiveStore = b.receiveStore;
this.shipTo = b.shipTo;
- // 调拨出库必须给收货地址;仓到仓由仓自己处理
- if (type == TransferType.OUTBOUND && shipTo == null) {
- throw new IllegalArgumentException("shipTo is required when transfer type is OUTBOUND");
- }
+ // 收货地址在调拨出库时是否必填由各仓协议决定:
+ // 运去哪要求 shipTo;信仓用 other_warehouse(仓库名)代替,见对应适配器。
this.remark = b.remark;
this.serviceTypes = java.util.Collections.unmodifiableList(
new java.util.ArrayList(b.serviceTypes));
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
index c03fe41..755c665 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
@@ -1,10 +1,12 @@
package common.ecommerce.warehouse.model;
+import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.TransferStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.enums.TransferType;
import java.time.Instant;
+import java.util.List;
/**
* 调拨单(查询 / 创建结果)。
@@ -59,6 +61,66 @@ public final class TransferOrder {
/** 仓方异常原因;无异常时为 null。 */
private final String errorReason;
+ // ==================== 仓方原始字段(信仓转运详情提供)====================
+
+ /** 仓方内部转运单 id;信仓 {@code id}。 */
+ private final String providerId;
+ /** 采购 / 调拨单号;信仓 {@code po}。{@link #transferRequestNo()} 是来源单号,两者不同。 */
+ private final String po;
+ /** 客户 id;信仓 {@code customer_id}。 */
+ private final String customerId;
+ /** 客户代码;信仓 {@code customer_no}。 */
+ private final String customerNo;
+ /** 发货仓 id(仓方内部);信仓 {@code from_warehouse},与 {@link #fromWarehouseCode()}(仓代码)不同。 */
+ private final String fromWarehouseId;
+ /** 目的仓 id(仓方内部);信仓 {@code dest_warehouse}。 */
+ private final String destWarehouseId;
+ /** 仓方状态原文(可读名);信仓 {@code state_name},如「待审核」。 */
+ private final String rawStatusName;
+ /** 转运类型(仓方字典值);信仓 {@code delivery_mode},取值见「转运类型」字典接口。 */
+ private final String deliveryMode;
+ /** 转运方式 / 配送方式(仓方字典值);信仓 {@code delivery_way}。 */
+ private final String deliveryWay;
+ /**
+ * 订单类型(仓方字典值);信仓 {@code order_type}。
+ *
+ * 注意与下单接口的 {@code order_type}(common / wayfair)语义不同,
+ * 这里取的是「订单类型」字典(FBA / LTL 等)。
+ */
+ private final String orderType;
+ /** 目的仓不在字典里时的自填仓库名;信仓 {@code other_warehouse}。 */
+ private final String otherWarehouse;
+ /** 标签需求(仓方原值,逗号分隔);信仓 {@code label_requirement},如「产品贴,外箱标签」。 */
+ private final String labelRequirement;
+ /** 是否需要产品贴;信仓 {@code is_product_label}({@code "1"} / {@code "0"})。 */
+ private final String isProductLabel;
+ /** 是否需要外箱贴;信仓 {@code is_ctn_label}。 */
+ private final String isCtnLabel;
+ /** 是否需要托盘贴;信仓 {@code is_pallet_label}。 */
+ private final String isPalletLabel;
+ /** 是否打托(仓方原值);信仓 {@code is_pallet}。 */
+ private final String isPallet;
+ /** 拣货开始时间(UTC);信仓 {@code picking_time}。 */
+ private final Instant pickingStartedAt;
+ /** 拣货结束时间(UTC);信仓 {@code picked_time}。 */
+ private final Instant pickedAt;
+ /** 打托时间(UTC);信仓 {@code palleted_time}。 */
+ private final Instant palletizedAt;
+ /** 发货时间(UTC);信仓 {@code send_time}。 */
+ private final Instant sentAt;
+ /** 审核时间(UTC);信仓 {@code approve_time}。 */
+ private final Instant approvedAt;
+ /** 仓方运输 / 发货单 id;信仓 {@code shipping_id}。 */
+ private final String shippingId;
+ /** 订单总费用(仓方原值);信仓 {@code total_amount}。 */
+ private final Money totalAmount;
+ /** 创建时间(UTC);信仓 {@code gmt_create}。 */
+ private final Instant createdAt;
+ /** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */
+ private final Instant modifiedAt;
+ /** 商品明细;查询详情时回填,创建返回时通常为空。 */
+ private final List lines;
+
private TransferOrder(Builder b) {
this.transferRequestNo = require(b.transferRequestNo, "transferRequestNo");
this.providerTransferNo = b.providerTransferNo;
@@ -80,6 +142,33 @@ public final class TransferOrder {
this.totalVolumeCbm = b.totalVolumeCbm;
this.errorCode = b.errorCode;
this.errorReason = b.errorReason;
+ this.providerId = b.providerId;
+ this.po = b.po;
+ this.customerId = b.customerId;
+ this.customerNo = b.customerNo;
+ this.fromWarehouseId = b.fromWarehouseId;
+ this.destWarehouseId = b.destWarehouseId;
+ this.rawStatusName = b.rawStatusName;
+ this.deliveryMode = b.deliveryMode;
+ this.deliveryWay = b.deliveryWay;
+ this.orderType = b.orderType;
+ this.otherWarehouse = b.otherWarehouse;
+ this.labelRequirement = b.labelRequirement;
+ this.isProductLabel = b.isProductLabel;
+ this.isCtnLabel = b.isCtnLabel;
+ this.isPalletLabel = b.isPalletLabel;
+ this.isPallet = b.isPallet;
+ this.pickingStartedAt = b.pickingStartedAt;
+ this.pickedAt = b.pickedAt;
+ this.palletizedAt = b.palletizedAt;
+ this.sentAt = b.sentAt;
+ this.approvedAt = b.approvedAt;
+ this.shippingId = b.shippingId;
+ this.totalAmount = b.totalAmount;
+ this.createdAt = b.createdAt;
+ this.modifiedAt = b.modifiedAt;
+ this.lines = b.lines == null ? java.util.Collections.emptyList()
+ : java.util.Collections.unmodifiableList(new java.util.ArrayList(b.lines));
}
public static Builder builder() {
@@ -187,6 +276,305 @@ public final class TransferOrder {
return sourceProvider;
}
+ /** 仓方内部转运单 id。 */
+ public String providerId() {
+ return providerId;
+ }
+
+ /** 采购 / 调拨单号;与 {@link #transferRequestNo()} 不是一回事。 */
+ public String po() {
+ return po;
+ }
+
+ /** 客户 id。 */
+ public String customerId() {
+ return customerId;
+ }
+
+ /** 客户代码。 */
+ public String customerNo() {
+ return customerNo;
+ }
+
+ /** 发货仓 id(仓方内部)。 */
+ public String fromWarehouseId() {
+ return fromWarehouseId;
+ }
+
+ /** 目的仓 id(仓方内部)。 */
+ public String destWarehouseId() {
+ return destWarehouseId;
+ }
+
+ /** 仓方状态原文(可读名)。 */
+ public String rawStatusName() {
+ return rawStatusName;
+ }
+
+ /** 转运类型(仓方字典值)。 */
+ public String deliveryMode() {
+ return deliveryMode;
+ }
+
+ /** 转运方式 / 配送方式(仓方字典值)。 */
+ public String deliveryWay() {
+ return deliveryWay;
+ }
+
+ /** 订单类型(仓方字典值,FBA / LTL 等);与下单接口的 common / wayfair 无关。 */
+ public String orderType() {
+ return orderType;
+ }
+
+ /** 目的仓不在字典里时的自填仓库名。 */
+ public String otherWarehouse() {
+ return otherWarehouse;
+ }
+
+ /** 标签需求(仓方原值,逗号分隔)。 */
+ public String labelRequirement() {
+ return labelRequirement;
+ }
+
+ /** 是否需要产品贴(仓方原值)。 */
+ public String isProductLabel() {
+ return isProductLabel;
+ }
+
+ /** 是否需要外箱贴(仓方原值)。 */
+ public String isCtnLabel() {
+ return isCtnLabel;
+ }
+
+ /** 是否需要托盘贴(仓方原值)。 */
+ public String isPalletLabel() {
+ return isPalletLabel;
+ }
+
+ /** 是否打托(仓方原值)。 */
+ public String isPallet() {
+ return isPallet;
+ }
+
+ /** 拣货开始时间(UTC)。 */
+ public Instant pickingStartedAt() {
+ return pickingStartedAt;
+ }
+
+ /** 拣货结束时间(UTC)。 */
+ public Instant pickedAt() {
+ return pickedAt;
+ }
+
+ /** 打托时间(UTC)。 */
+ public Instant palletizedAt() {
+ return palletizedAt;
+ }
+
+ /** 发货时间(UTC)。 */
+ public Instant sentAt() {
+ return sentAt;
+ }
+
+ /** 审核时间(UTC)。 */
+ public Instant approvedAt() {
+ return approvedAt;
+ }
+
+ /** 仓方运输 / 发货单 id。 */
+ public String shippingId() {
+ return shippingId;
+ }
+
+ /** 订单总费用。 */
+ public Money totalAmount() {
+ return totalAmount;
+ }
+
+ /** 创建时间(UTC)。 */
+ public Instant createdAt() {
+ return createdAt;
+ }
+
+ /** 最后修改时间(UTC)。 */
+ public Instant modifiedAt() {
+ return modifiedAt;
+ }
+
+ /** 商品明细;未查询详情时为空列表。 */
+ public List lines() {
+ return lines;
+ }
+
+ /**
+ * 转运商品明细(查询详情时回填)。
+ *
+ * 数量分三层:预报件数、清点箱数、上架件数。对账时要一起看。
+ */
+ public static final class TransferLine {
+
+ /** 产品 SKU;信仓 {@code product_no}。 */
+ private final String providerSku;
+ /** 产品名;信仓 {@code product_name}。 */
+ private final String productName;
+ /** 中文名;信仓 {@code chn_name}。 */
+ private final String productNameCn;
+ /** 预报件数;信仓 {@code sku_count}。 */
+ private final int plannedQuantity;
+ /** 预报箱数;信仓 {@code box_count}。 */
+ private final int boxCount;
+ /** 清点箱数;信仓 {@code check_box_qty}。 */
+ private final int checkedBoxCount;
+ /** 打托件数;信仓 {@code pallet_sku_count}。 */
+ private final int palletizedQuantity;
+ /** 上架件数;信仓 {@code put_on_sku_count}。 */
+ private final int storedQuantity;
+ /** 装箱率;信仓 {@code packing_rate}。 */
+ private final String packingRate;
+ /** 备注;信仓 {@code remark}。 */
+ private final String remark;
+
+ private TransferLine(Builder b) {
+ this.providerSku = require(b.providerSku, "providerSku");
+ this.productName = b.productName;
+ this.productNameCn = b.productNameCn;
+ this.plannedQuantity = b.plannedQuantity;
+ this.boxCount = b.boxCount;
+ this.checkedBoxCount = b.checkedBoxCount;
+ this.palletizedQuantity = b.palletizedQuantity;
+ this.storedQuantity = b.storedQuantity;
+ this.packingRate = b.packingRate;
+ this.remark = b.remark;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ public String providerSku() {
+ return providerSku;
+ }
+
+ public String productName() {
+ return productName;
+ }
+
+ public String productNameCn() {
+ return productNameCn;
+ }
+
+ /** 预报件数。 */
+ public int plannedQuantity() {
+ return plannedQuantity;
+ }
+
+ /** 预报箱数。 */
+ public int boxCount() {
+ return boxCount;
+ }
+
+ /** 清点箱数。 */
+ public int checkedBoxCount() {
+ return checkedBoxCount;
+ }
+
+ /** 打托件数。 */
+ public int palletizedQuantity() {
+ return palletizedQuantity;
+ }
+
+ /** 上架件数。 */
+ public int storedQuantity() {
+ return storedQuantity;
+ }
+
+ /** 装箱率(仓方原值)。 */
+ public String packingRate() {
+ return packingRate;
+ }
+
+ public String remark() {
+ return remark;
+ }
+
+ public static final class Builder {
+ private String providerSku;
+ private String productName;
+ private String productNameCn;
+ private int plannedQuantity;
+ private int boxCount;
+ private int checkedBoxCount;
+ private int palletizedQuantity;
+ private int storedQuantity;
+ private String packingRate;
+ private String remark;
+
+ /** 产品 SKU(信仓 {@code product_no});必填。 */
+ public Builder providerSku(String v) {
+ this.providerSku = v;
+ return this;
+ }
+
+ /** 产品名(信仓 {@code product_name})。 */
+ public Builder productName(String v) {
+ this.productName = v;
+ return this;
+ }
+
+ /** 中文名(信仓 {@code chn_name})。 */
+ public Builder productNameCn(String v) {
+ this.productNameCn = v;
+ return this;
+ }
+
+ /** 预报件数(信仓 {@code sku_count})。 */
+ public Builder plannedQuantity(int v) {
+ this.plannedQuantity = v;
+ return this;
+ }
+
+ /** 预报箱数(信仓 {@code box_count})。 */
+ public Builder boxCount(int v) {
+ this.boxCount = v;
+ return this;
+ }
+
+ /** 清点箱数(信仓 {@code check_box_qty})。 */
+ public Builder checkedBoxCount(int v) {
+ this.checkedBoxCount = v;
+ return this;
+ }
+
+ /** 打托件数(信仓 {@code pallet_sku_count})。 */
+ public Builder palletizedQuantity(int v) {
+ this.palletizedQuantity = v;
+ return this;
+ }
+
+ /** 上架件数(信仓 {@code put_on_sku_count})。 */
+ public Builder storedQuantity(int v) {
+ this.storedQuantity = v;
+ return this;
+ }
+
+ /** 装箱率(信仓 {@code packing_rate})。 */
+ public Builder packingRate(String v) {
+ this.packingRate = v;
+ return this;
+ }
+
+ /** 备注(信仓 {@code remark})。 */
+ public Builder remark(String v) {
+ this.remark = v;
+ return this;
+ }
+
+ public TransferLine build() {
+ return new TransferLine(this);
+ }
+ }
+ }
+
private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank");
@@ -215,6 +603,32 @@ public final class TransferOrder {
private Double totalVolumeCbm;
private String errorCode;
private String errorReason;
+ private String providerId;
+ private String po;
+ private String customerId;
+ private String customerNo;
+ private String fromWarehouseId;
+ private String destWarehouseId;
+ private String rawStatusName;
+ private String deliveryMode;
+ private String deliveryWay;
+ private String orderType;
+ private String otherWarehouse;
+ private String labelRequirement;
+ private String isProductLabel;
+ private String isCtnLabel;
+ private String isPalletLabel;
+ private String isPallet;
+ private Instant pickingStartedAt;
+ private Instant pickedAt;
+ private Instant palletizedAt;
+ private Instant sentAt;
+ private Instant approvedAt;
+ private String shippingId;
+ private Money totalAmount;
+ private Instant createdAt;
+ private Instant modifiedAt;
+ private List lines;
public Builder transferRequestNo(String v) {
this.transferRequestNo = v;
@@ -316,6 +730,171 @@ public final class TransferOrder {
return this;
}
+ /** 仓方内部转运单 id(信仓 {@code id})。 */
+ public Builder providerId(String v) {
+ this.providerId = v;
+ return this;
+ }
+
+ /** 采购 / 调拨单号(信仓 {@code po})。 */
+ public Builder po(String v) {
+ this.po = v;
+ return this;
+ }
+
+ /** 客户 id(信仓 {@code customer_id})。 */
+ public Builder customerId(String v) {
+ this.customerId = v;
+ return this;
+ }
+
+ /** 客户代码(信仓 {@code customer_no})。 */
+ public Builder customerNo(String v) {
+ this.customerNo = v;
+ return this;
+ }
+
+ /** 发货仓 id(信仓 {@code from_warehouse})。 */
+ public Builder fromWarehouseId(String v) {
+ this.fromWarehouseId = v;
+ return this;
+ }
+
+ /** 目的仓 id(信仓 {@code dest_warehouse})。 */
+ public Builder destWarehouseId(String v) {
+ this.destWarehouseId = v;
+ return this;
+ }
+
+ /** 仓方状态原文(信仓 {@code state_name})。 */
+ public Builder rawStatusName(String v) {
+ this.rawStatusName = v;
+ return this;
+ }
+
+ /** 转运类型(信仓 {@code delivery_mode})。 */
+ public Builder deliveryMode(String v) {
+ this.deliveryMode = v;
+ return this;
+ }
+
+ /** 转运方式 / 配送方式(信仓 {@code delivery_way})。 */
+ public Builder deliveryWay(String v) {
+ this.deliveryWay = v;
+ return this;
+ }
+
+ /** 订单类型(信仓 {@code order_type})。 */
+ public Builder orderType(String v) {
+ this.orderType = v;
+ return this;
+ }
+
+ /** 目的仓不在字典里时的自填仓库名(信仓 {@code other_warehouse})。 */
+ public Builder otherWarehouse(String v) {
+ this.otherWarehouse = v;
+ return this;
+ }
+
+ /** 标签需求(信仓 {@code label_requirement})。 */
+ public Builder labelRequirement(String v) {
+ this.labelRequirement = v;
+ return this;
+ }
+
+ /** 是否需要产品贴(信仓 {@code is_product_label})。 */
+ public Builder isProductLabel(String v) {
+ this.isProductLabel = v;
+ return this;
+ }
+
+ /** 是否需要外箱贴(信仓 {@code is_ctn_label})。 */
+ public Builder isCtnLabel(String v) {
+ this.isCtnLabel = v;
+ return this;
+ }
+
+ /** 是否需要托盘贴(信仓 {@code is_pallet_label})。 */
+ public Builder isPalletLabel(String v) {
+ this.isPalletLabel = v;
+ return this;
+ }
+
+ /** 是否打托(信仓 {@code is_pallet})。 */
+ public Builder isPallet(String v) {
+ this.isPallet = v;
+ return this;
+ }
+
+ /** 拣货开始时间(信仓 {@code picking_time})。 */
+ public Builder pickingStartedAt(Instant v) {
+ this.pickingStartedAt = v;
+ return this;
+ }
+
+ /** 拣货结束时间(信仓 {@code picked_time})。 */
+ public Builder pickedAt(Instant v) {
+ this.pickedAt = v;
+ return this;
+ }
+
+ /** 打托时间(信仓 {@code palleted_time})。 */
+ public Builder palletizedAt(Instant v) {
+ this.palletizedAt = v;
+ return this;
+ }
+
+ /** 发货时间(信仓 {@code send_time})。 */
+ public Builder sentAt(Instant v) {
+ this.sentAt = v;
+ return this;
+ }
+
+ /** 审核时间(信仓 {@code approve_time})。 */
+ public Builder approvedAt(Instant v) {
+ this.approvedAt = v;
+ return this;
+ }
+
+ /** 仓方运输 / 发货单 id(信仓 {@code shipping_id})。 */
+ public Builder shippingId(String v) {
+ this.shippingId = v;
+ return this;
+ }
+
+ /** 订单总费用(信仓 {@code total_amount})。 */
+ public Builder totalAmount(Money v) {
+ this.totalAmount = v;
+ return this;
+ }
+
+ /** 创建时间(信仓 {@code gmt_create})。 */
+ public Builder createdAt(Instant v) {
+ this.createdAt = v;
+ return this;
+ }
+
+ /** 最后修改时间(信仓 {@code gmt_modify})。 */
+ public Builder modifiedAt(Instant v) {
+ this.modifiedAt = v;
+ return this;
+ }
+
+ /** 商品明细(查询详情时回填)。 */
+ public Builder lines(List v) {
+ this.lines = v;
+ return this;
+ }
+
+ /** 追加一条商品明细。 */
+ public Builder line(TransferLine v) {
+ if (this.lines == null) {
+ this.lines = new java.util.ArrayList();
+ }
+ this.lines.add(v);
+ return this;
+ }
+
public TransferOrder build() {
return new TransferOrder(this);
}
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
index c96754f..ff5f0d7 100644
--- 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
@@ -50,8 +50,15 @@ public final class XincangForecastMapper {
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());
+ if (cmd.referenceSkuCount() == null && cmd.lines().isEmpty()) {
+ throw validation(ctx,
+ "referenceSkuCount is required for xincang forecast (信仓 rfc_sku_count 必填)");
+ }
+ // 参考 SKU 种类数:优先用调用方显式给的值(信仓必填),
+ // 没有再退回明细行数——建单时明细通常还没有,不能只依赖行数
+ req.rfcSkuCount = cmd.referenceSkuCount() != null
+ ? String.valueOf(cmd.referenceSkuCount())
+ : 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());
@@ -72,6 +79,9 @@ public final class XincangForecastMapper {
String forecastNo,
String productsJson,
WarehouseContext ctx) {
+ if (cmd.lines().isEmpty()) {
+ throw validation(ctx, "xincang improve_forecast requires at least one product line");
+ }
XincangDtos.ForecastImproveRequest req = new XincangDtos.ForecastImproveRequest();
req.forecastNo = require(forecastNo, "forecastNo", ctx);
req.destWarehouse = require(cmd.warehouseId(), "warehouseId (dest_warehouse)", ctx);
@@ -128,11 +138,19 @@ public final class XincangForecastMapper {
if (product == null || blank(product.productNo)) {
continue;
}
+ // 歧义说明:信仓的 box_count 是「预报箱数」,而统一模型
+ // packedQuantity 的语义是「装箱时实际装进去的件数」,两者不是一回事,
+ // 所以 box_count 不映射到 packedQuantity,只放仓方原始字段。
lines.add(InboundOrderLine.builder()
.providerSku(product.productNo.trim())
.plannedQuantity(intOf(product.skuCount))
- .packedQuantity(intOf(product.boxCount))
.receivedQuantity(intOf(product.putOnSkuCount))
+ .productName(blankToNull(product.productName))
+ .productNameCn(blankToNull(product.chnName))
+ .checkedBoxCount(intOf(product.checkBoxQty))
+ .palletizedQuantity(intOf(product.palletSkuCount))
+ .packingRate(blankToNull(product.packingRate))
+ .volumeCm(blankToNull(product.volumeCm))
.build());
}
}
@@ -150,6 +168,35 @@ public final class XincangForecastMapper {
.actualArrivalAt(parseTime(detail.eta))
.remark(blankToNull(detail.remark))
.lines(lines)
+ // ---- 仓方原始字段 ----
+ .providerId(blankToNull(detail.id))
+ .chnName(blankToNull(detail.chnName))
+ .customerId(blankToNull(detail.customerId))
+ .customerNo(blankToNull(detail.customerName))
+ .destWarehouseId(blankToNull(detail.destWarehouseId))
+ .rawStatusName(blankToNull(detail.stateName))
+ .shipmentType(blankToNull(detail.shipmentType))
+ .cabinetType(blankToNull(detail.cabinetType))
+ .cabinetNo(blankToNull(detail.cabinetNo))
+ .estimatedShipAt(parseTime(detail.rfcEtd))
+ .shippedAt(parseTime(detail.etd))
+ .isOversize(blankToNull(detail.isOversize))
+ .oversizeNote(blankToNull(detail.oversizeVal))
+ .deliveryRequirements(blankToNull(detail.deliveryRequirements))
+ .forecastAt(parseTime(detail.forecastTime))
+ .referenceSkuCount(parseInteger(detail.rfcSkuCount))
+ .forecastPalletQty(parseInteger(detail.forecastPalletQty))
+ .receivedPalletQty(parseInteger(detail.receivePalletQty))
+ .storedPalletQty(parseInteger(detail.shelfPalletQty))
+ .billedPalletQty(parseInteger(detail.billPalletQty))
+ .unladeAt(parseTime(detail.unladeTime))
+ .checkedAt(parseTime(detail.checkTime))
+ .putawayAt(parseTime(detail.putawayTime))
+ .leftAt(parseTime(detail.leaveTime))
+ .isInnerBoxSticker(blankToNull(detail.isInnerBoxSticker))
+ .isOuterBoxSticker(blankToNull(detail.isOuterBoxSticker))
+ .otherNeed(blankToNull(detail.otherNeed))
+ .modifiedAt(parseTime(detail.gmtModify))
.build();
}
@@ -171,6 +218,11 @@ public final class XincangForecastMapper {
return XincangOrderDetailMapper.parseTime(raw);
}
+ /** 整数原值:空值 / 非法返回 null(与 {@link #intOf} 的区别是保留「仓方没给」)。 */
+ static Integer parseInteger(String raw) {
+ return XincangOrderDetailMapper.parseInteger(raw);
+ }
+
static int intOf(String raw) {
return XincangOrderDetailMapper.parsePositiveInt(raw);
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
index 10c6bd4..d6c54d7 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
@@ -71,6 +71,10 @@ public final class XincangInventoryMapper {
}
params.put("page", pageNumber(query.cursor()));
params.put("limit", pageSize(query.pageSize()));
+ // 信仓默认只返回库存 > 0 的产品;需要零库存数据时显式传 1
+ if (query.includeZeroStock() != null) {
+ params.put("is_show_zero", query.includeZeroStock() ? 1 : 0);
+ }
return params;
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
index 6583e83..a48dd37 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
@@ -64,6 +64,31 @@ public final class XincangOrderDetailMapper {
.exceptionCode(blankToNull(detail.apiError))
.estimatedShippingFee(parseMoney(detail.totalAmount))
.currency(CURRENCY_USD)
+ // ---- 仓方原始字段 ----
+ .providerId(blankToNull(detail.id))
+ .rawStatusName(blankToNull(detail.stateName))
+ .labelUrl(blankToNull(detail.faceUrl))
+ .shopName(blankToNull(detail.shopName))
+ .skuCount(parseInteger(detail.skuCount))
+ .productSku(blankToNull(detail.productSku))
+ .productName(blankToNull(detail.productName))
+ .sourceSku(blankToNull(detail.sourceSku))
+ .providerWarehouseId(blankToNull(detail.warehouseId))
+ .isSign(blankToNull(detail.isSign))
+ .zone(blankToNull(detail.zone))
+ .dimLength(blankToNull(detail.dimLength))
+ .dimWidth(blankToNull(detail.dimWidth))
+ .dimHeight(blankToNull(detail.dimHeight))
+ .dimDivisor(blankToNull(detail.dimDivisor))
+ .weightLbs(blankToNull(detail.weightLbs))
+ .billingWeightLbs(blankToNull(detail.billingWeightLbs))
+ .volumeWeightLbs(blankToNull(detail.volumeWeightLbs))
+ .totalAmount(parseMoney(detail.totalAmount))
+ .repairAmount(parseMoney(detail.repairAmount))
+ .approvedAt(parseTime(detail.approveTime))
+ .modifiedAt(parseTime(detail.gmtModify))
+ .cancelledAt(parseTime(detail.gmtCancel))
+ .interceptedAt(parseTime(detail.interceptTime))
.build();
}
@@ -174,6 +199,23 @@ public final class XincangOrderDetailMapper {
}
}
+ /**
+ * 整数原值:空值 / 非法返回 null。
+ *
+ * 与 {@link #parsePositiveInt} 的区别:这个把 null 与 0 区分开,
+ * 用于「仓方没给」与「仓方给了 0」要分开的字段(如件数合计)。
+ */
+ static Integer parseInteger(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return Integer.valueOf(raw.trim());
+ } catch (NumberFormatException e) {
+ return null;
+ }
+ }
+
static int parsePositiveInt(String raw) {
if (blank(raw)) {
return 0;
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
index e39c422..fabc8b3 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
@@ -40,7 +40,7 @@ public final class XincangOrderMapper {
/** 信仓布尔字段统一用「是 / 否」。 */
private static final String YES = "是";
private static final String NO = "否";
- /** 签名服务:模型无对应字段,固定否。 */
+ /** 签名服务未指定时的兜底值:文档把它列为必填,只能给「否」。 */
private static final String SIGN_NOT_REQUIRED = NO;
private XincangOrderMapper() {
@@ -87,7 +87,10 @@ public final class XincangOrderMapper {
form.put("phone", shipTo.phone().trim());
putIfPresent(form, "email", shipTo.email());
form.put("logistics_type", cmd.carrierCode().trim());
- form.put("is_sign", SIGN_NOT_REQUIRED);
+ // is_sign 是必填项:调用方给值就按值发,没给才退回「否」并说明原因
+ form.put("is_sign", cmd.signatureRequired() == null
+ ? SIGN_NOT_REQUIRED
+ : (cmd.signatureRequired() ? YES : NO));
form.put("products", productsJson(cmd.lines(), json));
putIfPresent(form, "shop_name", cmd.shopName());
if (cmd.sfp() != null) {
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 8a3764f..326ec70 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
@@ -17,6 +17,9 @@ import java.math.RoundingMode;
*
* 文档未定义「包装方式 / 是否 SN / 客退处理 / 海关信息」等字段,这些统一模型字段
* 不发送,避免自行编造平台不认的键。
+ *
+ * 文档里标「已废弃」的 {@code ahs_weight} / {@code ahs_dimensions} / {@code oversize}
+ * 只在 DTO 里占位,一律不填——仓方已改为按服务商参数自动计算。
*/
public final class XincangProductMapper {
@@ -54,6 +57,11 @@ public final class XincangProductMapper {
req.remark = trimToNull(product.remark());
req.ckm = trimToNull(product.customItemNo());
req.productType = product.productType() > 0 ? product.productType() : null;
+ // product_category 由调用方按仓方字典显式给,适配器不猜
+ req.productCategory = product.productCategory();
+ // product_image 需要 upload.files 返回的 OSS 元数据;只有 URL 时无法组装,
+ // 因此这里不填 —— 明确不发送,避免被仓方当成无效图片
+ req.productImage = null;
return req;
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
index 1347435..bc67f3e 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
@@ -38,9 +38,63 @@ public final class XincangTransferDetailMapper {
.totalQuantity(totalQuantityOf(detail))
.estimatedOutboundAt(XincangOrderDetailMapper.parseDate(detail.preSendTime))
.remark(XincangOrderDetailMapper.blankToNull(detail.remark))
+ // ---- 仓方原始字段 ----
+ .providerId(XincangOrderDetailMapper.blankToNull(detail.id))
+ .po(XincangOrderDetailMapper.blankToNull(detail.po))
+ .customerId(XincangOrderDetailMapper.blankToNull(detail.customerId))
+ .customerNo(XincangOrderDetailMapper.blankToNull(detail.customerNo))
+ .fromWarehouseId(XincangOrderDetailMapper.blankToNull(detail.fromWarehouseId))
+ .destWarehouseId(XincangOrderDetailMapper.blankToNull(detail.destWarehouseId))
+ .rawStatusName(XincangOrderDetailMapper.blankToNull(detail.stateName))
+ .deliveryMode(XincangOrderDetailMapper.blankToNull(detail.deliveryMode))
+ .deliveryWay(XincangOrderDetailMapper.blankToNull(detail.deliveryWay))
+ .orderType(XincangOrderDetailMapper.blankToNull(detail.orderType))
+ .otherWarehouse(XincangOrderDetailMapper.blankToNull(detail.otherWarehouse))
+ .labelRequirement(XincangOrderDetailMapper.blankToNull(detail.labelRequirement))
+ .isProductLabel(XincangOrderDetailMapper.blankToNull(detail.isProductLabel))
+ .isCtnLabel(XincangOrderDetailMapper.blankToNull(detail.isCtnLabel))
+ .isPalletLabel(XincangOrderDetailMapper.blankToNull(detail.isPalletLabel))
+ .isPallet(XincangOrderDetailMapper.blankToNull(detail.isPallet))
+ .pickingStartedAt(XincangOrderDetailMapper.parseTime(detail.pickingTime))
+ .pickedAt(XincangOrderDetailMapper.parseTime(detail.pickedTime))
+ .palletizedAt(XincangOrderDetailMapper.parseTime(detail.palletedTime))
+ .sentAt(XincangOrderDetailMapper.parseTime(detail.sendTime))
+ .approvedAt(XincangOrderDetailMapper.parseTime(detail.approveTime))
+ .shippingId(XincangOrderDetailMapper.blankToNull(detail.shippingId))
+ .totalAmount(XincangOrderDetailMapper.parseMoney(detail.totalAmount))
+ .createdAt(XincangOrderDetailMapper.parseTime(detail.gmtCreate))
+ .modifiedAt(XincangOrderDetailMapper.parseTime(detail.gmtModify))
+ .lines(toLines(detail))
.build();
}
+ /** 转运明细行 → 统一模型。 */
+ static java.util.List toLines(XincangDtos.TransferDetail detail) {
+ if (detail.products == null || detail.products.isEmpty()) {
+ return java.util.Collections.emptyList();
+ }
+ java.util.List out =
+ new java.util.ArrayList(detail.products.size());
+ for (XincangDtos.TransferDetailProduct product : detail.products) {
+ if (product == null || XincangOrderDetailMapper.blank(product.productNo)) {
+ continue;
+ }
+ out.add(TransferOrder.TransferLine.builder()
+ .providerSku(product.productNo.trim())
+ .productName(XincangOrderDetailMapper.blankToNull(product.productName))
+ .productNameCn(XincangOrderDetailMapper.blankToNull(product.chnName))
+ .plannedQuantity(XincangOrderDetailMapper.parsePositiveInt(product.skuCount))
+ .boxCount(XincangOrderDetailMapper.parsePositiveInt(product.boxCount))
+ .checkedBoxCount(XincangOrderDetailMapper.parsePositiveInt(product.checkBoxQty))
+ .palletizedQuantity(XincangOrderDetailMapper.parsePositiveInt(product.palletSkuCount))
+ .storedQuantity(XincangOrderDetailMapper.parsePositiveInt(product.putOnSkuCount))
+ .packingRate(XincangOrderDetailMapper.blankToNull(product.packingRate))
+ .remark(XincangOrderDetailMapper.blankToNull(product.remark))
+ .build());
+ }
+ return out;
+ }
+
/** 明细件数合计;明细缺失时返回 0(未知,不猜)。 */
static int totalQuantityOf(XincangDtos.TransferDetail detail) {
if (detail.products == null || detail.products.isEmpty()) {
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 2439a53..36850fc 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
@@ -141,6 +141,34 @@ public final class XincangDtos {
/** 产品图片;需先调 {@code upload.files}。统一模型暂不承载图片,通常为 null。 */
@JsonProperty("product_image")
public ProductImage productImage;
+
+ /**
+ * AHS 计费重量。
+ *
+ * 文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填,
+ * 保留占位只为与文档字段表对齐。
+ */
+ @JsonProperty("ahs_weight")
+ @Deprecated
+ public String ahsWeight;
+
+ /**
+ * AHS 计费尺寸。
+ *
+ * 文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。
+ */
+ @JsonProperty("ahs_dimensions")
+ @Deprecated
+ public String ahsDimensions;
+
+ /**
+ * 是否超尺寸。
+ *
+ * 文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。
+ */
+ @JsonProperty("oversize")
+ @Deprecated
+ public String oversize;
}
/** 产品图片(OSS 元数据)。 */
@@ -428,6 +456,14 @@ public final class XincangDtos {
@JsonProperty("po")
public String po;
+ /** 客户 id。 */
+ @JsonProperty("customer_id")
+ public String customerId;
+
+ /** 客户代码。 */
+ @JsonProperty("customer_no")
+ public String customerNo;
+
/** 发货仓 id / 代码。 */
@JsonProperty("from_warehouse")
public String fromWarehouseId;
@@ -558,6 +594,22 @@ public final class XincangDtos {
public String weightLbs;
@JsonProperty("weight_kg")
public String weightKg;
+
+ /** 产品中文名(文档字段 {@code chn_name} 的语义;与 {@link #chnName} 同值来源)。 */
+ @JsonProperty("product_name")
+ public String productName;
+
+ /** 清点箱数。 */
+ @JsonProperty("check_box_qty")
+ public String checkBoxQty;
+
+ /** 打托件数。 */
+ @JsonProperty("pallet_sku_count")
+ public String palletSkuCount;
+
+ /** 上架件数。 */
+ @JsonProperty("put_on_sku_count")
+ public String putOnSkuCount;
}
/** 转运详情响应外层。 */
@@ -1017,6 +1069,15 @@ public final class XincangDtos {
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastCreateRequest {
+ /**
+ * 客户 id。
+ *
+ * 文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。
+ */
+ @JsonProperty("customer_id")
+ @Deprecated
+ public String customerId;
+
/** 目的地仓。 */
@JsonProperty("dest_warehouse")
public String destWarehouse;
@@ -1081,6 +1142,24 @@ public final class XincangDtos {
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastImproveRequest {
+ /**
+ * 预报单 id。
+ *
+ * 文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。
+ */
+ @JsonProperty("id")
+ @Deprecated
+ public String id;
+
+ /**
+ * 客户 id。
+ *
+ * 文档标注已舍弃,SDK 不填。
+ */
+ @JsonProperty("customer_id")
+ @Deprecated
+ public String customerId;
+
@JsonProperty("forecast_no")
public String forecastNo;
@@ -1094,9 +1173,20 @@ public final class XincangDtos {
@JsonProperty("ref_no")
public String refNo;
+ /**
+ * 新增预报柜号。
+ *
+ * 文档标注已舍弃,SDK 不填。
+ */
+ @JsonProperty("old_cabinet_no")
+ @Deprecated
+ public String oldCabinetNo;
+
+ /** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。 */
@JsonProperty("cabinet_type")
public String cabinetType;
+ /** 柜号。 */
@JsonProperty("cabinet_no")
public String cabinetNo;
@@ -1108,6 +1198,15 @@ public final class XincangDtos {
@JsonProperty("eta")
public String eta;
+ /**
+ * 最晚免费时间(提柜)。
+ *
+ * 文档标注已舍弃,SDK 不填。
+ */
+ @JsonProperty("lfd")
+ @Deprecated
+ public String lfd;
+
@JsonProperty("delivery_requirements")
public String deliveryRequirements;
@@ -1118,13 +1217,33 @@ public final class XincangDtos {
@JsonProperty("other_need")
public String otherNeed;
+ /**
+ * 总件数。
+ *
+ * 文档标注已舍弃(由 {@code products} 汇总),SDK 不填。
+ */
+ @JsonProperty("sku_count_sum")
+ @Deprecated
+ public String skuCountSum;
+
+ /**
+ * 总箱数。
+ *
+ * 文档标注已舍弃(由 {@code products} 汇总),SDK 不填。
+ */
+ @JsonProperty("box_count_sum")
+ @Deprecated
+ public String boxCountSum;
+
/** 产品明细 JSON 字符串。 */
@JsonProperty("products")
public String products;
+ /** 船务公司 id;通过【获取船务公司】接口取得。 */
@JsonProperty("shipping_company_id")
public String shippingCompanyId;
+ /** 预报托盘数;柜型为托盘入库时填写。 */
@JsonProperty("forecast_pallet_qty")
public String forecastPalletQty;
}
@@ -1160,6 +1279,10 @@ public final class XincangDtos {
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ForecastDetail {
+ /** 预报单 id。 */
+ @JsonProperty("id")
+ public String id;
+
@JsonProperty("forecast_no")
public String forecastNo;
@@ -1167,6 +1290,14 @@ public final class XincangDtos {
@JsonProperty("chn_name")
public String chnName;
+ /** 客户 id。 */
+ @JsonProperty("customer_id")
+ public String customerId;
+
+ /** 客户代码。 */
+ @JsonProperty("customer_name")
+ public String customerName;
+
/** 目的仓 id / 代码。 */
@JsonProperty("dest_warehouse")
public String destWarehouseId;
@@ -1300,6 +1431,44 @@ public final class XincangDtos {
/** 体积(立方厘米)。 */
@JsonProperty("volume_cm")
public String volumeCm;
+
+ /** 中文名。 */
+ @JsonProperty("chn_name")
+ public String chnName;
+
+ /** 英文名。 */
+ @JsonProperty("en_name")
+ public String enName;
+
+ /** 体积(立方英寸)。 */
+ @JsonProperty("volume_ln")
+ public String volumeLn;
+
+ /** 长(厘米)。 */
+ @JsonProperty("size_l_cm")
+ public String sizeLCm;
+ /** 宽(厘米)。 */
+ @JsonProperty("size_w_cm")
+ public String sizeWCm;
+ /** 高(厘米)。 */
+ @JsonProperty("size_h_cm")
+ public String sizeHCm;
+ /** 长(英寸)。 */
+ @JsonProperty("size_l_ln")
+ public String sizeLLn;
+ /** 宽(英寸)。 */
+ @JsonProperty("size_w_ln")
+ public String sizeWLn;
+ /** 高(英寸)。 */
+ @JsonProperty("size_h_ln")
+ public String sizeHLn;
+
+ /** 预报产品创建时间。 */
+ @JsonProperty("gmt_create")
+ public String gmtCreate;
+ /** 预报产品最后修改时间。 */
+ @JsonProperty("gmt_modify")
+ public String gmtModify;
}
/** 预报详情响应外层。 */
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
index bb47f38..4fa8817 100644
--- 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
@@ -223,7 +223,9 @@ class XincangForecastTest {
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());
+ // box_count(预报箱数)语义不同于 packedQuantity(实际装箱件数),不再互相映射
+ assertEquals(0, order.lines().get(0).packedQuantity(),
+ "box_count 不再冒充 packedQuantity");
assertEquals(80, order.lines().get(0).receivedQuantity());
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
index 3f295f9..8fd887d 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
@@ -131,6 +131,26 @@ class XincangInventoryTest {
}
@Test
+ void stockSendsShowZeroWhenRequested() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ adapter.query(ctx(), InventoryQuery.builder().includeZeroStock(true).build());
+
+ assertTrue(transport.lastDataRequest().url().contains("is_show_zero=1"),
+ transport.lastDataRequest().url());
+ }
+
+ @Test
+ void stockOmitsShowZeroWhenUnset() {
+ transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY));
+
+ adapter.query(ctx(), InventoryQuery.builder().build());
+
+ assertFalse(transport.lastDataRequest().url().contains("is_show_zero"),
+ "未指定时不传,交给仓方默认");
+ }
+
+ @Test
void ageQuerySendsBillDateRangeAndMapsRecord() {
transport.route(XincangConstants.PATH_STOCK_AGE_LIST, req -> Responses.ok(AGE_BODY));
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java
new file mode 100644
index 0000000..2537ac8
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java
@@ -0,0 +1,76 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.model.InboundCommand;
+import common.ecommerce.warehouse.model.InboundLine;
+import org.junit.jupiter.api.Test;
+
+import java.time.LocalDate;
+
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+
+/**
+ * 统一模型里「某家仓必填、其他仓不需要」的字段不再在构造期拦截。
+ *
+ * 这些用例守护的是:信仓可以只给它认识的字段就构造出命令,
+ * 不会因为运去哪的必填项(nameEn / packingType / 海关三项 / 入库商品行)
+ * 被迫塞无意义的值。
+ */
+class XincangModelRelaxTest {
+
+ /** 商品:不给 nameEn / packingType / 海关三项也能构造(信仓都收不到这些字段)。 */
+ @Test
+ void productBuildsWithoutYqnOnlyFields() {
+ WarehouseProduct product = WarehouseProduct.builder()
+ .omsSku("SKU-1")
+ .name("中文名")
+ .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
+ .build();
+ assertNotNull(product);
+ }
+
+ /**
+ * 商品:信仓 amount 必填,但只需要 declaredValue,不需要 hsCode / countryOfOrigin。
+ *
+ * 改前「海关三项必须整组给」在构造期强制,信仓调用方被迫填两个用不上的字段。
+ */
+ @Test
+ void productCustomsValueAloneIsAccepted() {
+ WarehouseProduct product = WarehouseProduct.builder()
+ .omsSku("SKU-2")
+ .name("中文名")
+ .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
+ .declaredValue(Money.of("1.00", "USD"))
+ .build();
+ assertNotNull(product);
+ }
+
+ /** 入库:信仓「新增预报」只建单头,可以没有商品行(明细走「完善资料」)。 */
+ @Test
+ void inboundHeaderOnlyIsEnoughForForecastCreate() {
+ InboundCommand head = InboundCommand.builder()
+ .inboundRequestNo("FC-1")
+ .warehouseId("NJ-2605")
+ .shipmentType("2")
+ .cabinetType("1")
+ .containerNo("CAB-1")
+ .predictionShipDate(LocalDate.now().plusDays(1))
+ .estimateArriveDate(LocalDate.now().plusDays(30))
+ .deliveryRequirements("1")
+ .referenceSkuCount(3)
+ .build();
+ assertNotNull(head);
+ }
+
+ /** 入库:完善资料阶段要明细,这时才加行,模型允许。 */
+ @Test
+ void inboundWithLinesStillWorks() {
+ InboundCommand withLines = InboundCommand.builder()
+ .inboundRequestNo("FC-2")
+ .warehouseId("NJ-2605")
+ .line(InboundLine.builder().omsSku("SKU-1").quantity(1).build())
+ .build();
+ assertNotNull(withLines);
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
index 711f01f..1e42797 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
@@ -168,6 +168,27 @@ class XincangOrderTest {
}
@Test
+ void signatureFlagFollowsCaller() {
+ transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok(
+ "{\"rst\":{\"order_no\":\"DS-SIG\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}"));
+ OutboundCommand signed = OutboundCommand.builder()
+ .outboundRequestNo("OB-SIG")
+ .salesPlatform(Platform.AMAZON_SC)
+ .carrierCode("FEDEX-G")
+ .warehouseId("CA-3790")
+ .signatureRequired(true)
+ .shipTo(ShipTo.builder().name("R").phone("1").countryCode("US").stateOrProvince("CA")
+ .city("Fontana").addressLine1("1 A St").postalCode("92337").build())
+ .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(1).build())
+ .build();
+
+ adapter.create(ctx(), signed);
+
+ assertTrue(transport.lastDataRequest().body().contains("name=\"is_sign\"\r\n\r\n是"),
+ transport.lastDataRequest().body());
+ }
+
+ @Test
void splitFlagIsOmittedWhenCallerDidNotSetIt() {
transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok(
"{\"rst\":{\"order_no\":\"DS-1\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}"));
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 cfe3182..836425b 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
@@ -207,6 +207,32 @@ class XincangProductTest {
}
@Test
+ void productWithoutEnglishNameIsAccepted() {
+ // 信仓只有中文名(chn_name),没有 english name 字段;
+ // nameEn 是运去哪的必填项,不应在统一模型构造期强制
+ routeProductList("[]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\"}"));
+ WarehouseProduct noEnglishName = WarehouseProduct.builder()
+ .omsSku("APITEST008")
+ .name("测试商品")
+ .barcode("B-8")
+ .packingType(0)
+ .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
+ .declaredValue(Money.of("1.00", "USD"))
+ .hsCode("9403600000")
+ .countryOfOrigin("US")
+ .build();
+
+ assertNotNull(adapter.createOrUpdate(ctx(), noEnglishName),
+ "缺 nameEn 时信仓应能正常建档");
+
+ String body = Objects.requireNonNull(transport.lastDataRequest()).body();
+ assertTrue(body.contains("\"chn_name\":\"测试商品\""), body);
+ assertFalse(body.contains("nameEn"), "信仓不发送英文名");
+ }
+
+ @Test
void missingDeclaredValueIsRejectedInsteadOfSendingZero() {
routeProductList("[]");
WarehouseProduct noValue = WarehouseProduct.builder()
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
index 9904c47..0240ae0 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
@@ -192,6 +192,25 @@ class XincangTransferTest {
}
@Test
+ void modelNoLongerRequiresInboundDateOrShipTo() {
+ // 信仓转运只用 pre_send_time,也不用收件地址;模型不再强制这两个字段
+ TransferCommand minimal = TransferCommand.builder()
+ .transferRequestNo("TR-MIN")
+ .type(TransferType.OUTBOUND)
+ .fromWarehouseCode("CA-3790").toWarehouseCode("ONT8")
+ .estimateOutboundDate(LocalDate.parse("2026-11-20"))
+ .deliveryMode("FBA").deliveryWay("Amazon(亚马逊卡车自提)")
+ .palletRequired(false)
+ .line("SKU-1", 1)
+ .build();
+
+ transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok(
+ "{\"rst\":{\"order_no\":\"LTL-MIN\"},\"errno\":0,\"err\":\"\"}"));
+
+ assertNotNull(adapter.create(ctx(), minimal));
+ }
+
+ @Test
void nonOutboundTransferTypeIsRejected() {
TransferCommand cmd = TransferCommand.builder()
.transferRequestNo("TR-2")
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java
new file mode 100644
index 0000000..7588b77
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java
@@ -0,0 +1,293 @@
+package common.ecommerce.xincang.probe;
+
+import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.HttpResponse;
+import common.ecommerce.http.HttpTransport;
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.http.OkHttpTransport;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.WarehouseFacility;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.adapter.XincangAdapter;
+import org.junit.jupiter.api.Assumptions;
+
+import java.time.Clock;
+import java.util.List;
+import java.util.function.Supplier;
+
+/**
+ * 信仓联网探针的公共基座。
+ *
+ * 默认全部跳过,用 {@code -Dxincang.probe=true} 显式开启;写接口还要再加
+ * {@code -Dxincang.probe.write=true} 二次确认。凭据与业务数据一律走系统属性,
+ * 真实值不入库。
+ *
+ *
+ * mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ * -Dxincang.probe=true \
+ * -Dxincang.probe.appKey=你的appkey -Dxincang.probe.appSecret=你的secret \
+ * -Dtest=XincangReadProbeTest test
+ *
+ *
+ * 可选属性:{@code baseUrl}、{@code warehouseCode}、{@code sku}、{@code postcode}、
+ * {@code qty}、{@code orderNo}、{@code transferNo}、{@code forecastNo}。
+ *
+ * 设计约束:
+ *
+ * - 每个探针独立执行,单个失败只打印不抛出,保证一次能跑完全部接口;
+ * - 请求 / 响应都打印(截断 + 脱敏),便于和文档逐字段对照;
+ * - 不硬编码任何业务数据:仓代码与承运商从目录接口现取。
+ *
+ */
+final class XincangProbeSupport {
+
+ /** 通用开关。 */
+ static final String PROBE = "xincang.probe";
+ /** 写接口二次确认。 */
+ static final String PROBE_WRITE = "xincang.probe.write";
+
+ static final String APP_KEY = System.getProperty("xincang.probe.appKey", "");
+ static final String APP_SECRET = System.getProperty("xincang.probe.appSecret", "");
+ static final String BASE_URL = opt("xincang.probe.baseUrl", XincangConstants.TEST_BASE_URL);
+
+ /** 业务输入:没有默认值,必须由调用方显式传入。 */
+ static final String WAREHOUSE_CODE = opt("xincang.probe.warehouseCode", "");
+ static final String SKU = opt("xincang.probe.sku", "");
+ static final String POSTCODE = opt("xincang.probe.postcode", "");
+ static final String ORDER_NO = opt("xincang.probe.orderNo", "");
+ static final String TRANSFER_NO = opt("xincang.probe.transferNo", "");
+ static final String FORECAST_NO = opt("xincang.probe.forecastNo", "");
+
+ private static final JacksonJsonCodec JSON = new JacksonJsonCodec();
+
+ /** 目录接口发现结果缓存,避免每个探针都列一遍。 */
+ private static String discoveredWarehouseCode;
+ private static boolean warehouseDiscoveryAttempted;
+ private static String discoveredCarrier;
+ private static boolean carrierDiscoveryAttempted;
+
+ private XincangProbeSupport() {
+ }
+
+ // ---------------------------------------------------------------- 装配
+
+ /** 真实联网传输 + 报文打印;token 等敏感头在这里脱敏。 */
+ static HttpTransport transport() {
+ return new LoggingTransport(new OkHttpTransport("common-ecommerce-xincang-probe"));
+ }
+
+ /** 装配真实适配器;令牌只存在内存里,不落盘。 */
+ static XincangAdapter adapter() {
+ return new XincangAdapter(transport(), JSON, new InMemoryTokenStore(),
+ new InMemoryLockProvider(), Clock.systemUTC());
+ }
+
+ /** 用指定传输装配,便于需要复用连接的对象。 */
+ static XincangAdapter adapter(HttpTransport transport) {
+ return new XincangAdapter(transport, JSON, new InMemoryTokenStore(),
+ new InMemoryLockProvider(), Clock.systemUTC());
+ }
+
+ static WarehouseContext ctx() {
+ return ctx(WAREHOUSE_CODE.isEmpty() ? null : WAREHOUSE_CODE);
+ }
+
+ static WarehouseContext ctx(String providerWarehouseId) {
+ return WarehouseContext.of("XC-PROBE", WarehouseProvider.XINCANG, providerWarehouseId,
+ WarehouseConnection.of(BASE_URL, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret(APP_SECRET).build()),
+ "probe-" + System.currentTimeMillis(), Clock.systemUTC());
+ }
+
+ // ---------------------------------------------------------------- 前置检查
+
+ /** 凭据齐全才继续,否则整个探针 skip(不算失败)。 */
+ static void requireCredentials() {
+ Assumptions.assumeTrue(!APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(),
+ "未提供 -Dxincang.probe.appKey / -Dxincang.probe.appSecret,跳过探针");
+ }
+
+ /** 需要某个业务输入时用它:缺了就跳过当前用例并说明缺哪个属性。 */
+ static void requireProperty(String name) {
+ Assumptions.assumeTrue(System.getProperty(name, "").trim().length() > 0,
+ "未提供 -D" + name + ",跳过该探针");
+ }
+
+ // ---------------------------------------------------------------- 执行 & 打印
+
+ /** 执行一步并打印结果;异常只打印不抛出,返回 null。 */
+ static T step(String label, Supplier action) {
+ System.out.println(" [probe] " + label);
+ try {
+ T value = action.get();
+ System.out.println(" [ok] " + label + " → " + describe(value));
+ return value;
+ } catch (RuntimeException e) {
+ printError(e);
+ return null;
+ }
+ }
+
+ static void step(String label, Runnable action) {
+ step(label, () -> {
+ action.run();
+ return Boolean.TRUE;
+ });
+ }
+
+ /** 异常打印:类型 + 截断消息 + 平台错误字段。 */
+ static void printError(RuntimeException e) {
+ String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage();
+ System.out.println(" [ERROR] " + e.getClass().getSimpleName() + ": "
+ + (msg.length() <= 400 ? msg : msg.substring(0, 400) + "…"));
+ if (e instanceof common.ecommerce.shared.error.ChannelException) {
+ common.ecommerce.shared.error.ChannelException ce =
+ (common.ecommerce.shared.error.ChannelException) e;
+ System.out.println(" operation=" + ce.operation()
+ + " platformCode=" + ce.platformCode()
+ + " platformRequestId=" + ce.platformRequestId()
+ + " retryable=" + ce.retryable());
+ }
+ }
+
+ private static String describe(Object value) {
+ if (value == null) {
+ return "null";
+ }
+ if (value instanceof List) {
+ return ((List>) value).size() + " items";
+ }
+ return String.valueOf(value);
+ }
+
+ // ---------------------------------------------------------------- 依赖发现
+
+ /**
+ * 仓代码:优先 {@code -Dxincang.probe.warehouseCode},否则从客户仓库接口取第一家。
+ *
+ * @return 没有可用仓时返回 null,调用方打印跳过
+ */
+ static String warehouseCode(XincangAdapter adapter) {
+ if (!WAREHOUSE_CODE.isEmpty()) {
+ return WAREHOUSE_CODE;
+ }
+ if (warehouseDiscoveryAttempted) {
+ return discoveredWarehouseCode;
+ }
+ warehouseDiscoveryAttempted = true;
+ try {
+ List facilities = adapter.warehouses(ctx());
+ if (!facilities.isEmpty()) {
+ discoveredWarehouseCode = facilities.get(0).warehouseCode();
+ System.out.println(" [discovery] 自动使用仓 " + discoveredWarehouseCode);
+ }
+ } catch (RuntimeException e) {
+ printError(e);
+ }
+ return discoveredWarehouseCode;
+ }
+
+ /**
+ * 承运商 / 物流方式:优先 {@code -Dxincang.probe.carrier},否则从客户承运商接口取第一个。
+ */
+ static String carrier(XincangAdapter adapter) {
+ String configured = System.getProperty("xincang.probe.carrier", "").trim();
+ if (!configured.isEmpty()) {
+ return configured;
+ }
+ if (carrierDiscoveryAttempted) {
+ return discoveredCarrier;
+ }
+ carrierDiscoveryAttempted = true;
+ try {
+ List carriers = adapter.carriers(ctx());
+ if (!carriers.isEmpty()) {
+ discoveredCarrier = carriers.get(0);
+ System.out.println(" [discovery] 自动使用承运商 " + discoveredCarrier);
+ }
+ } catch (RuntimeException e) {
+ printError(e);
+ }
+ return discoveredCarrier;
+ }
+
+ /** 业务单号后缀:保证重跑不会撞「参考号已存在」这类唯一约束。 */
+ static String uniqueSuffix() {
+ return new java.text.SimpleDateFormat("yyyyMMdd-HHmmss")
+ .format(new java.util.Date());
+ }
+
+ static int qty() {
+ String raw = System.getProperty("xincang.probe.qty", "1").trim();
+ try {
+ int v = Integer.parseInt(raw);
+ return v > 0 ? v : 1;
+ } catch (NumberFormatException e) {
+ return 1;
+ }
+ }
+
+ static String opt(String name, String fallback) {
+ String value = System.getProperty(name, "");
+ if (value == null) {
+ return fallback;
+ }
+ String trimmed = value.trim();
+ return trimmed.isEmpty() ? fallback : trimmed;
+ }
+
+ // ---------------------------------------------------------------- 报文打印
+
+ /**
+ * 请求 / 响应打印。
+ *
+ * 脱敏规则:鉴权头与 URL 里的 token / secret 一律替换成 {@code ***};
+ * 打印体截断到 2000 字符,避免大段 base64 或明细刷屏。
+ */
+ static final class LoggingTransport implements HttpTransport {
+
+ private static final int MAX_BODY = 2000;
+
+ private final HttpTransport delegate;
+
+ LoggingTransport(HttpTransport delegate) {
+ this.delegate = delegate;
+ }
+
+ @Override
+ public HttpResponse execute(HttpRequest request) {
+ System.out.println(" --> " + request.method() + " " + maskUrl(request.url()));
+ System.out.println(" body " + truncate(request.body()));
+ long start = System.nanoTime();
+ HttpResponse response = delegate.execute(request);
+ long millis = (System.nanoTime() - start) / 1_000_000L;
+ System.out.println(" <-- " + response.statusCode() + " (" + millis + "ms) "
+ + truncate(response.body()));
+ return response;
+ }
+
+ /** 去掉 scheme+host,并把 query 里的敏感参数打码。 */
+ private static String maskUrl(String url) {
+ if (url == null) {
+ return "null";
+ }
+ int pathStart = url.indexOf('/', url.indexOf("://") + 3);
+ String path = pathStart < 0 ? url : url.substring(pathStart);
+ return path.replaceAll("(?i)((?:token|secret|appkey)=)[^&]*", "$1***");
+ }
+
+ private static String truncate(String body) {
+ if (body == null) {
+ return "null";
+ }
+ return body.length() <= MAX_BODY
+ ? body
+ : body.substring(0, MAX_BODY) + "...(" + body.length() + " chars)";
+ }
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java
new file mode 100644
index 0000000..d3cc360
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java
@@ -0,0 +1,307 @@
+package common.ecommerce.xincang.probe;
+
+import common.ecommerce.warehouse.model.ChannelRecommendQuery;
+import common.ecommerce.warehouse.model.ChannelRecommendResult;
+import common.ecommerce.warehouse.model.InventoryAgeQuery;
+import common.ecommerce.warehouse.model.InventoryAgeRecord;
+import common.ecommerce.warehouse.model.InventoryQuery;
+import common.ecommerce.warehouse.model.InventorySnapshot;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.OutboundRef;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.model.WarehouseFacility;
+import common.ecommerce.shared.support.Page;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.adapter.XincangAdapter;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
+
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * 信仓只读接口的联网探针:核对真实出入参。
+ *
+ * 默认跳过,用 {@code -Dxincang.probe=true} 开启。凭据与业务数据走系统属性,
+ * 真实值不入库;缺某个业务输入时只跳过依赖它的用例,不影响其他用例。
+ *
+ *
+ * mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ * -Dxincang.probe=true \
+ * -Dxincang.probe.appKey=... -Dxincang.probe.appSecret=... \
+ * -Dxincang.probe.sku=... -Dxincang.probe.postcode=... \
+ * -Dtest=XincangReadProbeTest test
+ *
+ *
+ * 可选属性:{@code warehouseCode} / {@code sku} / {@code postcode} / {@code orderNo} /
+ * {@code transferNo} / {@code forecastNo} / {@code productPageSize}。
+ *
+ * 只做查询,不调用任何写接口;异常只打印不抛出,一次能跑完全部段落。
+ */
+@EnabledIfSystemProperty(named = XincangProbeSupport.PROBE, matches = "true")
+class XincangReadProbeTest {
+
+ // ================================================================ 公共资料
+
+ /** 客户所有仓库:拿到仓代码,同时验证目录接口。 */
+ @Test
+ void probeCustomerWarehouses() {
+ XincangProbeSupport.requireCredentials();
+ System.out.println("\n================ xincang / api.get_customer_warehouses ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ List warehouses =
+ XincangProbeSupport.step("warehouses", () -> adapter.warehouses(XincangProbeSupport.ctx()));
+ if (warehouses == null) {
+ return;
+ }
+ for (WarehouseFacility w : warehouses) {
+ System.out.println(" warehouse_code=" + w.warehouseCode()
+ + " id=" + w.providerWarehouseId()
+ + " " + w.city() + "/" + w.province() + "/" + w.country()
+ + " " + w.postcode());
+ }
+ if (warehouses.isEmpty()) {
+ System.out.println(" [warn] 该账户下没有任何仓库,后续依赖仓代码的探针会跳过");
+ }
+ }
+
+ /** 客户所有承运商:拿到 logistics_type,用于下单与报价。 */
+ @Test
+ void probeCustomerLogistics() {
+ XincangProbeSupport.requireCredentials();
+ System.out.println("\n================ xincang / api.get_customer_logistics ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ List carriers =
+ XincangProbeSupport.step("carriers", () -> adapter.carriers(XincangProbeSupport.ctx()));
+ if (carriers != null) {
+ System.out.println(" carriers=" + carriers);
+ }
+ }
+
+ // ================================================================ 库存 / 库龄
+
+ /** 实时库存:核对手上数量字段口径。 */
+ @Test
+ void probeStockList() {
+ XincangProbeSupport.requireCredentials();
+ System.out.println("\n================ xincang / api.stocklist ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ String warehouseCode = XincangProbeSupport.warehouseCode(adapter);
+ if (warehouseCode == null) {
+ System.out.println(" [skip] 没有可用仓代码,跳过");
+ return;
+ }
+ InventoryQuery.Builder query = InventoryQuery.builder()
+ .warehouseCode(warehouseCode)
+ .pageSize(10);
+ if (!XincangProbeSupport.SKU.isEmpty()) {
+ query.sku(XincangProbeSupport.SKU);
+ }
+ Page page = XincangProbeSupport.step(
+ "stocklist warehouse=" + warehouseCode,
+ () -> adapter.query(XincangProbeSupport.ctx(warehouseCode), query.build()));
+ if (page == null) {
+ return;
+ }
+ System.out.println(" items=" + page.size() + " nextCursor=" + page.nextCursor());
+ for (InventorySnapshot s : page.items()) {
+ System.out.println(" sku=" + s.providerSku()
+ + " onHand=" + s.onHand()
+ + " available=" + s.available()
+ + " reserved=" + s.reserved()
+ + " pending=" + s.pendingOutbound()
+ + " inTransit=" + s.inTransit()
+ + " alert=" + s.alertQuantity()
+ + " name=" + s.productName()
+ + " volumeCm=" + s.volumeCbm());
+ }
+ }
+
+ /** 库龄列表:默认查最近 7 天,核对计费字段。 */
+ @Test
+ void probeStockAgeList() {
+ XincangProbeSupport.requireCredentials();
+ System.out.println("\n================ xincang / api.stockagelist ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ LocalDate end = LocalDate.now();
+ LocalDate start = end.minusDays(7);
+ InventoryAgeQuery query = InventoryAgeQuery.builder()
+ .dateRange(start, end)
+ .pageSize(10)
+ .includeFeeRate(true)
+ .build();
+ Page page = XincangProbeSupport.step(
+ "stockagelist " + start + " ~ " + end,
+ () -> adapter.queryAges(XincangProbeSupport.ctx(), query));
+ if (page == null) {
+ return;
+ }
+ System.out.println(" items=" + page.size() + " nextCursor=" + page.nextCursor());
+ for (InventoryAgeRecord r : page.items()) {
+ System.out.println(" sku=" + r.providerSku()
+ + " warehouse=" + r.warehouseCode()
+ + " billingDate=" + r.billingDate()
+ + " inStockAt=" + r.inStockAt()
+ + " ageDays=" + r.ageDays()
+ + " qty=" + r.quantity()
+ + " billingQty=" + r.billingQuantity()
+ + " feeRate=" + r.feeRate()
+ + " fee=" + r.fee()
+ + " cabinet=" + r.cabinetNo());
+ }
+ }
+
+ // ================================================================ 详情
+
+ /** 订单详情:按 -Dxincang.probe.orderNo 查。 */
+ @Test
+ void probeOrderDetail() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.orderNo");
+ System.out.println("\n================ xincang / api.get_order ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ OutboundOrder order = XincangProbeSupport.step(
+ "get_order " + XincangProbeSupport.ORDER_NO,
+ () -> adapter.get(XincangProbeSupport.ctx(),
+ OutboundRef.ofProviderOrderId(XincangProbeSupport.ORDER_NO)));
+ if (order == null) {
+ return;
+ }
+ System.out.println(" orderNo=" + order.outboundRequestNo()
+ + " providerOrderId=" + order.providerOrderId()
+ + " ref=" + order.orderRef()
+ + " status=" + order.status() + "(raw=" + order.rawStatus() + ")"
+ + " labelMode=" + order.labelMode()
+ + " carrier=" + order.carrierCode()
+ + " tracking=" + order.trackingNumber()
+ + " exception=" + order.exceptionCode()
+ + " requestedAt=" + order.requestedAt()
+ + " shippedAt=" + order.shippedAt()
+ + " fee=" + order.estimatedShippingFee());
+ System.out.println(" shipTo=" + order.shipTo());
+ for (common.ecommerce.warehouse.model.OutboundLine line : order.lines()) {
+ System.out.println(" sku=" + line.providerSku()
+ + " qty=" + line.quantity()
+ + " name=" + line.declareName());
+ }
+ }
+
+ /** 转运详情:按 -Dxincang.probe.transferNo 查。 */
+ @Test
+ void probeTransferDetail() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.transferNo");
+ System.out.println("\n================ xincang / fba.fba_detail ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ TransferOrder order = XincangProbeSupport.step(
+ "fba_detail " + XincangProbeSupport.TRANSFER_NO,
+ () -> adapter.getTransfer(XincangProbeSupport.ctx(), XincangProbeSupport.TRANSFER_NO));
+ if (order == null) {
+ return;
+ }
+ System.out.println(" transferRequestNo=" + order.transferRequestNo()
+ + " providerTransferNo=" + order.providerTransferNo()
+ + " from=" + order.fromWarehouseCode()
+ + " to=" + order.toWarehouseCode()
+ + " type=" + order.type()
+ + " status=" + order.status() + "(raw=" + order.rawStatus() + ")"
+ + " totalQty=" + order.totalQuantity()
+ + " estimatedOutboundAt=" + order.estimatedOutboundAt()
+ + " remark=" + order.remark());
+ }
+
+ /** 预报详情:按 -Dxincang.probe.forecastNo 查。 */
+ @Test
+ void probeForecastDetail() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.forecastNo");
+ System.out.println("\n================ xincang / forecast.forecast_detail ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ common.ecommerce.warehouse.model.InboundOrder order = XincangProbeSupport.step(
+ "forecast_detail " + XincangProbeSupport.FORECAST_NO,
+ () -> adapter.get(XincangProbeSupport.ctx(), XincangProbeSupport.FORECAST_NO));
+ if (order == null) {
+ return;
+ }
+ System.out.println(" inboundRequestNo=" + order.inboundRequestNo()
+ + " providerInboundId=" + order.providerInboundId()
+ + " warehouse=" + order.warehouseCode()
+ + " status=" + order.status() + "(raw=" + order.rawStatus() + ")"
+ + " boxCount=" + order.boxCount()
+ + " createdAt=" + order.createdAt()
+ + " receivedAt=" + order.receivedAt()
+ + " estimatedArrivalAt=" + order.estimatedArrivalAt()
+ + " actualArrivalAt=" + order.actualArrivalAt()
+ + " remark=" + order.remark());
+ for (common.ecommerce.warehouse.model.InboundOrderLine line : order.lines()) {
+ System.out.println(" sku=" + line.providerSku()
+ + " planned=" + line.plannedQuantity()
+ + " packed=" + line.packedQuantity()
+ + " received=" + line.receivedQuantity());
+ }
+ }
+
+ // ================================================================ 报价
+
+ /**
+ * 最优渠道:需要 SKU 与邮编。
+ *
+ * 协议待核对:文档写 GET + JSON body,OkHttp 不支持 GET 带 body,
+ * 适配器按 POST + JSON body 下发。这里重点看仓方是否接受。
+ */
+ @Test
+ void probeChannelRecommend() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ XincangProbeSupport.requireProperty("xincang.probe.postcode");
+ System.out.println("\n================ xincang / api.calculate_order_v3 ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ ChannelRecommendQuery query = ChannelRecommendQuery.builder()
+ .product(XincangProbeSupport.SKU, XincangProbeSupport.qty())
+ .postalCode(XincangProbeSupport.POSTCODE)
+ .signatureRequired(false)
+ .build();
+ ChannelRecommendResult result = XincangProbeSupport.step(
+ "calculate_order_v3 sku=" + XincangProbeSupport.SKU
+ + " postcode=" + XincangProbeSupport.POSTCODE,
+ () -> adapter.recommend(XincangProbeSupport.ctx(), query));
+ if (result == null) {
+ return;
+ }
+ if (result.optimalPlan() == null) {
+ System.out.println(" optimalPlan=null(该城无可用渠道,属合法结果)");
+ } else {
+ System.out.println(" optimalPlan: warehouse=" + result.optimalPlan().warehouseCode()
+ + " service=" + result.optimalPlan().serviceCode()
+ + " total=" + result.optimalPlan().total());
+ }
+ System.out.println(" warehouseQuotes=" + result.warehouseQuotes().size());
+ for (ChannelRecommendResult.WarehouseQuote q : result.warehouseQuotes()) {
+ System.out.println(" warehouse=" + q.warehouseCode()
+ + " inventoryEnough=" + q.inventoryEnough()
+ + " insufficient=" + q.insufficientStockError());
+ for (ChannelRecommendResult.ServiceQuote s : q.services()) {
+ System.out.println(" service=" + s.serviceCode() + " total=" + s.total());
+ for (ChannelRecommendResult.FeeItem f : s.fees()) {
+ System.out.println(" " + f.bigFeeType() + "/" + f.feeType()
+ + " = " + f.fee());
+ }
+ }
+ }
+ }
+
+ // ================================================================ 商品列表
+
+ /** 产品列表:通过 createOrUpdate 的查重路径顺带验证(只读部分)。 */
+ @Test
+ void probeProductLookup() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ System.out.println("\n================ xincang / api.productlist ================");
+ System.out.println(" [说明] 产品列表接口只在建档查重时调用,这里直接查一次核对字段:");
+ System.out.println(" sku=" + XincangProbeSupport.SKU
+ + ",请对照下方接口返回的 rst.data[].state(0 临时 / 1 正式)");
+ System.out.println(" [提示] 走 api.add_product 会真实建档,请用 XincangWriteProbeTest。");
+ System.out.println(" endpoint=" + XincangConstants.PATH_PRODUCT_LIST);
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java
new file mode 100644
index 0000000..cbd6226
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java
@@ -0,0 +1,338 @@
+package common.ecommerce.xincang.probe;
+
+import common.ecommerce.shared.model.Platform;
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.capability.WarehouseProductCapable;
+import common.ecommerce.warehouse.enums.LabelMode;
+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.model.OutboundCommand;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.OutboundReceipt;
+import common.ecommerce.warehouse.model.OutboundRef;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.enums.TransferType;
+import common.ecommerce.xincang.adapter.XincangAdapter;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
+
+import java.time.LocalDate;
+
+/**
+ * 信仓写接口的联网探针:真实下单 / 建转运 / 建预报,用于核对报文。
+ *
+ * 默认整类跳过,需要两个开关同时打开:
+ *
+ * -Dxincang.probe=true -Dxincang.probe.write=true
+ *
+ *
+ * 运行示例:
+ *
+ * mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ * -Dxincang.probe=true -Dxincang.probe.write=true \
+ * -Dxincang.probe.appKey=... -Dxincang.probe.appSecret=... \
+ * -Dxincang.probe.sku=... -Dxincang.probe.postcode=... \
+ * -Dtest=XincangWriteProbeTest test
+ *
+ *
+ * 注意:会在仓方测试环境留下真实数据。能自清理的链路(订单、转运)会尽量删掉;
+ * 商品建档与预报没有删除接口,跑完需要人工清理。所有单号都带时间戳后缀,
+ * 重跑不会撞唯一约束。
+ */
+@EnabledIfSystemProperty(named = XincangProbeSupport.PROBE_WRITE, matches = "true")
+class XincangWriteProbeTest {
+
+ // ================================================================ 商品
+
+ /**
+ * 商品建档 / 更新:走 add_product 或 update_product(先查临时产品决定)。
+ *
+ * 需要 {@code -Dxincang.probe.sku};金额按 1.00 USD 下发,
+ * 因为信仓把 amount 列为必填且我们不再兜底 0。
+ */
+ @Test
+ void probeProductUpsert() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ System.out.println("\n================ xincang / api.add_product | api.update_product ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+
+ WarehouseProduct product = WarehouseProduct.builder()
+ .omsSku(XincangProbeSupport.SKU)
+ .name("探针商品")
+ .nameEn("Probe Product")
+ .barcode("PROBE-" + XincangProbeSupport.uniqueSuffix())
+ .packingType(0)
+ .lengthCm(30)
+ .widthCm(20)
+ .heightCm(10)
+ .weightGrams(500)
+ .declaredValue(Money.of("1.00", "USD"))
+ .hsCode("9403600000")
+ .countryOfOrigin("US")
+ .build();
+
+ WarehouseProductCapable.ProductResult result = XincangProbeSupport.step(
+ "createOrUpdate sku=" + XincangProbeSupport.SKU,
+ () -> adapter.createOrUpdate(XincangProbeSupport.ctx(), product));
+ if (result != null) {
+ System.out.println(" providerSku=" + result.providerSku()
+ + " status=" + result.status()
+ + " rawStatus=" + result.rawStatus());
+ System.out.println(" [注意] 没有删除产品接口,跑完需人工清理或复用该 SKU。");
+ }
+ }
+
+ // ================================================================ 出库
+
+ /**
+ * 出库闭环:下单 → 详情回读 → 删除。
+ *
+ * 需要 sku + postcode;承运商从目录接口自动取(或 {@code -Dxincang.probe.carrier})。
+ */
+ @Test
+ void probeOutboundRoundTrip() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ XincangProbeSupport.requireProperty("xincang.probe.postcode");
+ System.out.println("\n================ xincang / api.add_order_multiple → get_order → delete_order ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ String warehouseCode = XincangProbeSupport.warehouseCode(adapter);
+ String carrier = XincangProbeSupport.carrier(adapter);
+ if (warehouseCode == null || carrier == null) {
+ System.out.println(" [skip] 缺少仓代码或承运商,跳过");
+ return;
+ }
+ String requestNo = "PROBE-" + XincangProbeSupport.uniqueSuffix();
+
+ OutboundCommand command = OutboundCommand.builder()
+ .outboundRequestNo(requestNo)
+ .orderRef(requestNo)
+ .labelMode(LabelMode.WAREHOUSE_LABEL)
+ .salesPlatform(Platform.CUSTOM)
+ .carrierCode(carrier)
+ .warehouseId(warehouseCode)
+ .splitOrder(true)
+ .shipTo(ShipTo.builder()
+ .name("Probe Receiver")
+ .phone("5550000000")
+ .countryCode("US")
+ .stateOrProvince("CA")
+ .city("Fontana")
+ .addressLine1("1 Probe Street")
+ .postalCode(XincangProbeSupport.POSTCODE)
+ .build())
+ .line(OutboundLine.builder()
+ .lineNo("1")
+ .omsSku(XincangProbeSupport.SKU)
+ .quantity(XincangProbeSupport.qty())
+ .declareName("Probe Item")
+ .build())
+ .build();
+
+ OutboundReceipt receipt = XincangProbeSupport.step("add_order_multiple ckh=" + requestNo,
+ () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), command));
+ if (receipt == null || receipt.providerOrderId() == null) {
+ return;
+ }
+ System.out.println(" providerOrderId=" + receipt.providerOrderId());
+
+ OutboundOrder order = XincangProbeSupport.step("get_order 回读",
+ () -> adapter.get(XincangProbeSupport.ctx(warehouseCode),
+ OutboundRef.ofProviderOrderId(receipt.providerOrderId())));
+ if (order != null) {
+ System.out.println(" status=" + order.status() + "(raw=" + order.rawStatus() + ")"
+ + " ref=" + order.orderRef()
+ + " lines=" + order.lines().size());
+ System.out.println(" checkCancel=" + XincangProbeSupport.step("checkCancel",
+ () -> adapter.checkCancel(XincangProbeSupport.ctx(warehouseCode),
+ OutboundRef.ofProviderOrderId(receipt.providerOrderId()))));
+ }
+
+ XincangProbeSupport.step("delete_order 自清理",
+ () -> adapter.cancel(XincangProbeSupport.ctx(warehouseCode),
+ common.ecommerce.warehouse.model.CancelCommand.builder()
+ .providerOrderId(receipt.providerOrderId())
+ .build()));
+ }
+
+ // ================================================================ 转运
+
+ /**
+ * 转运闭环:建转运 → 详情回读 → 删除(仅待审核可删)。
+ */
+ @Test
+ void probeTransferRoundTrip() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ XincangProbeSupport.requireProperty("xincang.probe.destWarehouse");
+ System.out.println("\n================ xincang / fba.do_fba → fba_detail → fba.delete_fba ================");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ String warehouseCode = XincangProbeSupport.warehouseCode(adapter);
+ if (warehouseCode == null) {
+ System.out.println(" [skip] 缺少仓代码,跳过");
+ return;
+ }
+ String transferNo = "PROBE-" + XincangProbeSupport.uniqueSuffix();
+ String destWarehouse = XincangProbeSupport.opt("xincang.probe.destWarehouse", "");
+
+ TransferCommand command = TransferCommand.builder()
+ .transferRequestNo(transferNo)
+ .type(TransferType.OUTBOUND)
+ .fromWarehouseCode(warehouseCode)
+ .toWarehouseCode(destWarehouse)
+ .po(transferNo)
+ // 信仓只用 pre_send_time;到仓日期与收件地址它都不收,
+ // 这里不传,顺便验证模型已不再强制这两个字段
+ .estimateOutboundDate(LocalDate.now().plusDays(1))
+ .deliveryMode(XincangProbeSupport.opt("xincang.probe.deliveryMode", ""))
+ .deliveryWay(XincangProbeSupport.opt("xincang.probe.deliveryWay", ""))
+ .orderType(XincangProbeSupport.opt("xincang.probe.orderType", ""))
+ .palletRequired(Boolean.FALSE)
+ .line(XincangProbeSupport.SKU, XincangProbeSupport.qty())
+ .build();
+
+ TransferOrder created = XincangProbeSupport.step("do_fba fba_no=" + transferNo,
+ () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), command));
+ if (created == null || created.providerTransferNo() == null) {
+ return;
+ }
+ String providerNo = created.providerTransferNo();
+ System.out.println(" providerTransferNo=" + providerNo + " status=" + created.status());
+
+ XincangProbeSupport.step("fba_detail 回读",
+ () -> adapter.getTransfer(XincangProbeSupport.ctx(warehouseCode), providerNo));
+
+ XincangProbeSupport.step("fba.delete_fba 自清理",
+ () -> adapter.deleteTransfer(XincangProbeSupport.ctx(warehouseCode), providerNo));
+ }
+
+ /**
+ * 转运审核:建转运 → 审核。
+ *
+ * 审核之后不能删除,会在测试环境留下数据,默认不跑;
+ * 需要显式加 {@code -Dxincang.probe.transferApprove=true}。
+ */
+ @Test
+ void probeTransferApprove() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.transferApprove");
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ XincangProbeSupport.requireProperty("xincang.probe.destWarehouse");
+ System.out.println("\n================ xincang / fba.do_approve ================");
+ System.out.println(" [注意] 审核后的转运单无法删除,会留下数据。");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ String warehouseCode = XincangProbeSupport.warehouseCode(adapter);
+ if (warehouseCode == null) {
+ System.out.println(" [skip] 缺少仓代码,跳过");
+ return;
+ }
+ String transferNo = "PROBE-APPROVE-" + XincangProbeSupport.uniqueSuffix();
+ TransferCommand command = TransferCommand.builder()
+ .transferRequestNo(transferNo)
+ .type(TransferType.OUTBOUND)
+ .fromWarehouseCode(warehouseCode)
+ .toWarehouseCode(XincangProbeSupport.opt("xincang.probe.destWarehouse", ""))
+ .po(transferNo)
+ .estimateOutboundDate(LocalDate.now().plusDays(1))
+ .deliveryMode(XincangProbeSupport.opt("xincang.probe.deliveryMode", ""))
+ .deliveryWay(XincangProbeSupport.opt("xincang.probe.deliveryWay", ""))
+ .orderType(XincangProbeSupport.opt("xincang.probe.orderType", ""))
+ .palletRequired(Boolean.FALSE)
+ .line(XincangProbeSupport.SKU, XincangProbeSupport.qty())
+ .build();
+
+ TransferOrder created = XincangProbeSupport.step("do_fba",
+ () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), command));
+ if (created == null || created.providerTransferNo() == null) {
+ return;
+ }
+ XincangProbeSupport.step("do_approve " + created.providerTransferNo(),
+ () -> adapter.approve(XincangProbeSupport.ctx(warehouseCode),
+ created.providerTransferNo()));
+ }
+
+ // ================================================================ 预报
+
+ /**
+ * 预报闭环:新增 → 完善资料 → 提交 → 详情回读。
+ *
+ * 没有删除接口,跑完会在测试环境留下预报单。
+ */
+ @Test
+ void probeForecastRoundTrip() {
+ XincangProbeSupport.requireCredentials();
+ XincangProbeSupport.requireProperty("xincang.probe.sku");
+ System.out.println("\n================ xincang / forecast.do_forecast → improve → done → detail ================");
+ System.out.println(" [注意] 预报没有删除接口,会留下数据。");
+ XincangAdapter adapter = XincangProbeSupport.adapter();
+ String warehouseCode = XincangProbeSupport.warehouseCode(adapter);
+ if (warehouseCode == null) {
+ System.out.println(" [skip] 缺少仓代码,跳过");
+ return;
+ }
+ String suffix = XincangProbeSupport.uniqueSuffix();
+ String requestNo = "PROBE-FC-" + suffix;
+
+ InboundCommand head = InboundCommand.builder()
+ .inboundRequestNo(requestNo)
+ .warehouseId(warehouseCode)
+ .shipmentType(XincangProbeSupport.opt("xincang.probe.shipmentType", "2"))
+ .cabinetType(XincangProbeSupport.opt("xincang.probe.cabinetType", "1"))
+ .containerNo("PROBE-CAB-" + suffix)
+ .predictionShipDate(LocalDate.now().plusDays(1))
+ .estimateArriveDate(LocalDate.now().plusDays(30))
+ .deliveryRequirements(XincangProbeSupport.opt("xincang.probe.deliveryRequirements", "1"))
+ .line(InboundLine.builder()
+ .omsSku(XincangProbeSupport.SKU)
+ .providerSku(XincangProbeSupport.SKU)
+ .quantity(XincangProbeSupport.qty())
+ .build())
+ .build();
+
+ InboundReceipt receipt = XincangProbeSupport.step("do_forecast fba_no=" + requestNo,
+ () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), head));
+ if (receipt == null || receipt.providerInboundId() == null) {
+ return;
+ }
+ String forecastNo = receipt.providerInboundId();
+ System.out.println(" forecast_no=" + forecastNo);
+
+ InboundCommand improve = InboundCommand.builder()
+ .inboundRequestNo(requestNo)
+ .warehouseId(warehouseCode)
+ .shipmentType(XincangProbeSupport.opt("xincang.probe.shipmentType", "2"))
+ .cabinetType(XincangProbeSupport.opt("xincang.probe.cabinetType", "1"))
+ .containerNo("PROBE-CAB-" + suffix)
+ .predictionShipDate(LocalDate.now().plusDays(1))
+ .estimateArriveDate(LocalDate.now().plusDays(30))
+ .deliveryRequirements(XincangProbeSupport.opt("xincang.probe.deliveryRequirements", "1"))
+ .referenceNo("REF-" + suffix)
+ .otherNeed(XincangProbeSupport.opt("xincang.probe.otherNeed", ""))
+ .line(InboundLine.builder()
+ .omsSku(XincangProbeSupport.SKU)
+ .providerSku(XincangProbeSupport.SKU)
+ .quantity(XincangProbeSupport.qty())
+ .build())
+ .build();
+
+ XincangProbeSupport.step("do_improve_forecast",
+ () -> adapter.improve(XincangProbeSupport.ctx(warehouseCode), forecastNo, improve));
+ XincangProbeSupport.step("done_forecast",
+ () -> adapter.submit(XincangProbeSupport.ctx(warehouseCode), forecastNo));
+
+ InboundOrder detail = XincangProbeSupport.step("forecast_detail 回读",
+ () -> adapter.get(XincangProbeSupport.ctx(warehouseCode), forecastNo));
+ if (detail != null) {
+ System.out.println(" status=" + detail.status() + "(raw=" + detail.rawStatus() + ")"
+ + " boxCount=" + detail.boxCount()
+ + " lines=" + detail.lines().size());
+ }
+ }
+}
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
index d7195df..240cc31 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
@@ -37,6 +37,11 @@ public final class YqnInboundMapper {
/** 统一命令 → 运去哪创建入库计划请求。 */
public static YqnCreateInboundDtos.CreateInboundPlanRequest toRequest(InboundCommand cmd, String warehouseCode) {
+ // 运去哪要求至少一条商品行;信仓「新增预报」不需要(明细走完善资料),
+ // 所以这条校验从 InboundCommand 构造期移到这里
+ if (cmd.lines().isEmpty()) {
+ throw new IllegalArgumentException("yqn inbound plan requires at least one product line");
+ }
requireContainerNo(cmd.containerNo());
YqnCreateInboundDtos.CreateInboundPlanRequest req = new YqnCreateInboundDtos.CreateInboundPlanRequest();
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
index de5409e..0f261cb 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
@@ -29,6 +29,15 @@ public final class YqnProductMapper {
* 这里只做字段搬运与单位对齐(cm / g 与平台一致,不换算)。
*/
public static YqnProductDtos.SaveProductRequest toRequest(WarehouseProduct product) {
+ // 运去哪 API 115 把 packingType 列为必填;统一模型不再在构造期强制
+ // (信仓没有该字段),所以在这里按运去哪的协议校验。
+ if (product.packingType() < 0) {
+ throw new IllegalArgumentException(
+ "yqn product requires packingType (0 原包装发货 / 1 重新打包)");
+ }
+ if (product.nameEn() == null || product.nameEn().trim().isEmpty()) {
+ throw new IllegalArgumentException("yqn product requires nameEn");
+ }
YqnProductDtos.SaveProductRequest req = new YqnProductDtos.SaveProductRequest();
req.sku = skuOf(product);
req.customItemNo = product.customItemNo();
@@ -71,7 +80,8 @@ public final class YqnProductMapper {
req.cost = cost.amount().doubleValue();
req.currency = cost.currencyCode();
}
- req.customs = toCustoms(product.declaredValue(), product.hsCode(), product.countryOfOrigin());
+ req.customs = toCustoms(product.declaredValue(), product.hsCode(), product.countryOfOrigin(),
+ product.omsSku());
return req;
}
@@ -115,8 +125,25 @@ public final class YqnProductMapper {
}
static List toCustoms(Money declaredValue,
- String hsCode, String countryCode) {
- if (declaredValue == null || isBlank(hsCode) || isBlank(countryCode)) {
+ String hsCode, String countryCode,
+ String sku) {
+ // 「三项整组给」的校验从 WarehouseProduct 构造期移到这里:
+ // 信仓只用 declaredValue 当 amount,不要求另外两项,模型层不能强制。
+ int given = 0;
+ if (declaredValue != null) {
+ given++;
+ }
+ if (!isBlank(hsCode)) {
+ given++;
+ }
+ if (!isBlank(countryCode)) {
+ given++;
+ }
+ if (given != 0 && given != 3) {
+ throw new IllegalArgumentException(
+ "yqn product " + sku + " requires hsCode / countryOfOrigin / declaredValue together");
+ }
+ if (given == 0) {
return null;
}
// 运去哪海关只接受 USD。之前无脑把申报额贴成 USD,非美元申报会被静默算错,
diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
index f3a03d7..d735864 100644
--- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
+++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
@@ -30,8 +30,28 @@ public final class YqnTransferMapper {
private YqnTransferMapper() {
}
- /** 统一命令 → 运去哪创建调拨单请求。 */
+ /**
+ * 统一命令 → 运去哪创建调拨单请求。
+ *
+ * 运去哪要求两个预计日期都给,且调拨出库必须带收货地址。这两条原本写在
+ * {@link TransferCommand} 的构造期,会把运去哪的约束强加给其它仓(信仓转运只有
+ * 发货日期、用仓库名代替地址),现在改到这里按运去哪的协议校验。
+ *
+ * @throws IllegalArgumentException 缺日期,或调拨出库缺收货地址
+ */
public static YqnTransferDtos.CreateTransferPlanRequest toRequest(TransferCommand cmd) {
+ if (cmd.estimateOutboundDate() == null || cmd.estimateInboundDate() == null) {
+ throw new IllegalArgumentException(
+ "yqn transfer requires estimateOutboundDate and estimateInboundDate");
+ }
+ if (cmd.estimateInboundDate().isBefore(cmd.estimateOutboundDate())) {
+ throw new IllegalArgumentException(
+ "estimateInboundDate must not be earlier than estimateOutboundDate");
+ }
+ if (cmd.type() == common.ecommerce.warehouse.enums.TransferType.OUTBOUND
+ && cmd.shipTo() == null) {
+ throw new IllegalArgumentException("yqn transfer requires shipTo when type is OUTBOUND");
+ }
YqnTransferDtos.CreateTransferPlanRequest req = new YqnTransferDtos.CreateTransferPlanRequest();
req.type = YqnTransferType.codeOf(cmd.type());
req.orgWarehouseCode = cmd.fromWarehouseCode();
diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java
index 7707a9a..3bb6b81 100644
--- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java
+++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java
@@ -123,21 +123,38 @@ class YqnProductTest {
}
@Test
- void halfCustomsIsRejectedAtBuildTime() {
- assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder()
+ void halfCustomsIsRejectedByMapper() {
+ // 海关三项整组给原本在构造期校验,信仓只用 declaredValue 当 amount,
+ // 所以校验移到运去哪 mapper
+ WarehouseProduct halfCustoms = WarehouseProduct.builder()
.omsSku("X").name("n").nameEn("n").packingType(0)
.lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)
.hsCode("123")
- .build());
+ .build();
+ assertThrows(IllegalArgumentException.class,
+ () -> YqnProductMapper.toRequest(halfCustoms));
}
@Test
void requiredFieldsAreEnforced() {
- assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder()
+ // packingType 是运去哪的必填项,但统一模型里是可选(信仓没有该字段),
+ // 所以校验发生在 mapper,不是在构造期
+ WarehouseProduct missingPackingType = WarehouseProduct.builder()
.omsSku("X").name("n").nameEn("n")
- // 缺 packingType
.lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)
- .build());
+ .build();
+ assertThrows(IllegalArgumentException.class,
+ () -> YqnProductMapper.toRequest(missingPackingType));
+
+ // nameEn 也是运去哪的必填项,同样在 mapper 校验
+ WarehouseProduct missingNameEn = WarehouseProduct.builder()
+ .omsSku("X").name("n").packingType(0)
+ .lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)
+ .build();
+ assertThrows(IllegalArgumentException.class,
+ () -> YqnProductMapper.toRequest(missingNameEn));
+
+ // 跨仓共识的必填项(长宽高 / 重量为正)仍在构造期校验
assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder()
.omsSku("X").name("n").nameEn("n").packingType(0)
.lengthCm(0).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)