Browse Source

Merge branch 'feature/supplier-lingxing' of http://124.222.6.97:3000/chencc/common-ecommerce into feature/supplier-lingxing

feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
8d76933a8d
  1. 2
      docs-warehouse/README.md
  2. 251
      docs-warehouse/xincang/README.md
  3. 94
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  4. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java
  5. 423
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
  6. 97
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java
  7. 24
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java
  8. 23
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
  9. 372
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
  10. 20
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
  11. 579
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  12. 58
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java
  13. 4
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java
  14. 42
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
  15. 7
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
  16. 8
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
  17. 54
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
  18. 169
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
  19. 4
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java
  20. 20
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java
  21. 76
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java
  22. 21
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
  23. 26
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
  24. 19
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
  25. 293
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java
  26. 307
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java
  27. 338
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java
  28. 5
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  29. 33
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  30. 22
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
  31. 29
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java

2
docs-warehouse/README.md

@ -7,6 +7,7 @@ @@ -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 @@ @@ -14,4 +15,5 @@
- 想知道**能力有哪些** → `architecture.md` 的「能力矩阵」
- 想知道**回调怎么接** → `callback.md` 的「宿主要做什么」
- 想知道**运去哪对接了什么** → `yqn/README.md` 的「接口清单」
- 想知道**信仓对接了什么** → `xincang/README.md` 的「接口清单」
- 想知道**踩过什么坑** → `notes.md`

251
docs-warehouse/xincang/README.md

@ -0,0 +1,251 @@ @@ -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=<sku>
② 新增(临时产品) 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=<appkey> -Dxincang.probe.appSecret=<secret> \
-Dtest=XincangLoginProbeTest test
# ② 只读(9 个查询接口)
mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
-Dxincang.probe=true \
-Dxincang.probe.appKey=<appkey> -Dxincang.probe.appSecret=<secret> \
-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=<appkey> -Dxincang.probe.appSecret=<secret> \
-Dxincang.probe.sku=<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` 已支持,但结算账单未接 |

94
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java

@ -9,9 +9,12 @@ import java.util.Objects; @@ -9,9 +9,12 @@ import java.util.Objects;
/**
* 仓商品建档入参。
*
* <p>单位写进字段名(cm / g),避免适配器之间靠注释约定换算。
* 运去哪 API 115 的必填项(sku / 中英文名 / 包装方式 / 长宽高 / 重量 / SN)
* 在这里都是必填,缺了在构造期就失败,而不是等平台报错。</p>
* <p>单位写进字段名(cm / g),避免适配器之间靠注释约定换算。</p>
*
* <p>构造期只校验<b>所有仓都必须给</b>的字段:{@code omsSku}、{@code name}、
* 长宽高与重量为正。其余字段({@code nameEn} / {@code packingType} / 海关三项 /
* 品类等)的必填性与组合约束都由各适配器在拼报文时校验——
* 否则接第二家仓时会被第一家的约束卡住。</p>
*/
public final class WarehouseProduct {
@ -20,11 +23,21 @@ public final class WarehouseProduct { @@ -20,11 +23,21 @@ public final class WarehouseProduct {
private final String customItemNo;
private final String barcode;
private final String name;
/**
* 英文名。
*
* <p>运去哪必填(适配器会拒绝缺失);信仓接口只有中文名({@code chn_name}),
* 未给即不传。</p>
*/
private final String nameEn;
private final String description;
/** 产品类型:1 成品 / 2 配件 / 3 耗材;0 表示未指定(平台默认成品)。 */
private final int productType;
/** 发货包装:0 原包装发货 / 1 重新打包。 */
/**
* 发货包装:0 原包装发货 / 1 重新打包;<b>-1 表示未给</b>。
*
* <p>运去哪必填(适配器会拒绝缺失);信仓接口没有该字段,未给即不传。</p>
*/
private final int packingType;
private final double lengthCm;
private final double widthCm;
@ -124,18 +137,37 @@ public final class WarehouseProduct { @@ -124,18 +137,37 @@ public final class WarehouseProduct {
*/
private final List<String> lotAttributeCodes;
// ==================== 仓方原始字段 ====================
/**
* 产品品类;null 表示不传。
*
* <p>信仓 {@code product_category}:0 其它 / 1 家具 / 2 食品 / 3 汽配 / 4 服饰 /
* 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。取值由仓方字典定义,适配器不归一。</p>
*/
private final Integer productCategory;
/**
* 产品图片地址;null 表示不传。
*
* <p>信仓走「先上传文件、再回传 OSS 元数据」的两步流程({@code upload.files}),
* 这里只承载最终可访问的 URL;适配器拿不到 OSS 元数据时不发送该字段。</p>
*/
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 { @@ -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 { @@ -169,21 +203,9 @@ public final class WarehouseProduct {
this.lotAttributeCodes = java.util.Collections.unmodifiableList(
new java.util.ArrayList<String>(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 { @@ -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 { @@ -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 { @@ -469,7 +503,7 @@ public final class WarehouseProduct {
return this;
}
/** 0 原包装发货 / 1 重新打包;<b>必填</b>。 */
/** 0 原包装发货 / 1 重新打包;运去哪必填,信仓不用。 */
public Builder packingType(int v) {
this.packingType = v;
return this;
@ -626,6 +660,18 @@ public final class WarehouseProduct { @@ -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 必填项缺失、尺寸/重量非正、海关三项不齐
*/

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

@ -8,8 +8,10 @@ import java.util.List; @@ -8,8 +8,10 @@ import java.util.List;
/**
* 入库计划创建命令。<b>写操作</b>,幂等键是 {@link #inboundRequestNo()}(仓方的来源单号)。
*
* <p>必填:单号、仓、库存类型、至少一条商品行。装箱、批次、附件都是可选的——
* 仓会在收货时按实际情况清点,但<b>给了就必须自洽</b>(一箱多 SKU 要用 sid 归并)。</p>
* <p>构造期只校验所有仓都必须给的:单号、库存类型取值。仓 / 商品行 / 日期等
* 各家要求不同(信仓「新增预报」只建单头、明细走「完善资料」),
* 必填性由各适配器在拼报文时校验;装箱、批次、附件的自洽性仍由模型保证
* (一箱多 SKU 要用 sid 归并)。</p>
*/
public final class InboundCommand {
@ -133,6 +135,14 @@ public final class InboundCommand { @@ -133,6 +135,14 @@ public final class InboundCommand {
/** 中文名称(信仓 {@code chn_name});null 表示不传。 */
private final String chnName;
/**
* 参考 SKU 种类数;null 表示不传。
*
* <p>信仓 {@code rfc_sku_count}(新增预报必填)。与 {@link #lines()} 行数无关:
* 报的是「预计有多少种 SKU」,建单时明细还没给。</p>
*/
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 { @@ -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<InboundLine>(b.lines));
this.cartons = Collections.unmodifiableList(new ArrayList<InboundCarton>(b.cartons));
this.batches = Collections.unmodifiableList(new ArrayList<InboundBatch>(b.batches));
@ -189,6 +198,7 @@ public final class InboundCommand { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

423
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java

@ -121,6 +121,65 @@ public final class InboundOrder { @@ -121,6 +121,65 @@ public final class InboundOrder {
*/
private final List<ContainerInfo> 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 { @@ -158,6 +217,34 @@ public final class InboundOrder {
this.cartonTotalWeightKg = b.cartonTotalWeightKg;
this.cartonTotalVolumeCbm = b.cartonTotalVolumeCbm;
this.containers = Collections.unmodifiableList(new ArrayList<ContainerInfo>(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 { @@ -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 { @@ -452,6 +679,34 @@ public final class InboundOrder {
private Double cartonTotalWeightKg;
private Double cartonTotalVolumeCbm;
private final List<ContainerInfo> containers = new ArrayList<ContainerInfo>();
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 { @@ -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);
}

97
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java

@ -23,6 +23,25 @@ public final class InboundOrderLine { @@ -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}。
*
* <p>与 {@link #packedQuantity()}(预报箱数)不同:这个是仓方清点后实际确认的箱数。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

24
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java

@ -15,6 +15,13 @@ public final class InventoryQuery { @@ -15,6 +15,13 @@ public final class InventoryQuery {
private final Instant updatedAfter;
private final int pageSize;
private final String cursor;
/**
* 是否包含零库存的 SKU;null 表示不传,由仓方按默认处理。
*
* <p>部分仓(信仓 {@code is_show_zero})默认只返回库存大于 0 的数据;
* 需要做全量对账时显式传 {@code true}。不支持的仓忽略该字段。</p>
*/
private final Boolean includeZeroStock;
private InventoryQuery(Builder b) {
this.providerSkus = Collections.unmodifiableList(new ArrayList<String>(b.providerSkus));
@ -23,6 +30,7 @@ public final class InventoryQuery { @@ -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 { @@ -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<String> providerSkus = new ArrayList<String>();
private final List<String> warehouseCodes = new ArrayList<String>();
@ -63,6 +76,7 @@ public final class InventoryQuery { @@ -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 { @@ -113,6 +127,16 @@ public final class InventoryQuery {
return this;
}
/**
* 是否包含零库存 SKU;null 表示不传(仓方默认)。
*
* <p>信仓对应 {@code is_show_zero}:默认只返回库存大于 0 的产品。</p>
*/
public Builder includeZeroStock(Boolean v) {
this.includeZeroStock = v;
return this;
}
public InventoryQuery build() {
return new InventoryQuery(this);
}

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

@ -67,6 +67,16 @@ public final class OutboundCommand { @@ -67,6 +67,16 @@ public final class OutboundCommand {
/** 是否 SFP(Seller Fulfilled Prime);null 表示不传,由仓按默认否处理。 */
private final Boolean sfp;
// ==================== 仓方原始字段(下单时用)====================
/**
* 是否需要签名签收;null 表示不传,由仓方按默认处理。
*
* <p>信仓 {@code is_sign}({@code "1"} / {@code "0"})。适配器不会替你猜:
* 不传就不发,仓方默认值与业务要求未必一致。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

372
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java

@ -99,6 +99,66 @@ public final class OutboundOrder { @@ -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;
/**
* 物流面单下载地址。
*
* <p>信仓 {@code face_url}(OSS 签名 URL,有时效);运去哪通过 packages 返回。可能为 null。</p>
*/
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;
/**
* 订单总费用(仓方原值字符串)。
*
* <p>信仓 {@code total_amount}:<b>总费用</b>,含运费与操作费等,不等于
* {@link #estimatedShippingFee()}(预估运费)。两者不互相覆盖。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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<WarehouseAttachment> attachments = new ArrayList<WarehouseAttachment>();
private List<SerialNumber> serialNumbers = new ArrayList<SerialNumber>();
private Boolean signatureRequired;
@ -400,6 +628,150 @@ public final class OutboundOrder { @@ -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);
}

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

@ -8,6 +8,9 @@ import java.util.List; @@ -8,6 +8,9 @@ import java.util.List;
* 调拨单创建命令。<b>写操作</b>,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。
*
* <p>运去哪对 {@code sourceNo} 有唯一约束,查询与取消都靠它,所以它同时是业务主键。</p>
*
* <p>构造期只校验跨仓共识的必填项;某一家仓特有的必填项(运去哪的日期与收货地址、
* 信仓的转运类型 / 方式 / 是否打托)由各适配器在拼报文时校验。</p>
*/
public final class TransferCommand {
@ -29,7 +32,7 @@ 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 { @@ -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 { @@ -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<Integer>(b.serviceTypes));

579
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java

@ -1,10 +1,12 @@ @@ -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 { @@ -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}。
*
* <p>注意与下单接口的 {@code order_type}(common / wayfair)语义不同,
* 这里取的是「订单类型」字典(FBA / LTL 等)。</p>
*/
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<TransferLine> lines;
private TransferOrder(Builder b) {
this.transferRequestNo = require(b.transferRequestNo, "transferRequestNo");
this.providerTransferNo = b.providerTransferNo;
@ -80,6 +142,33 @@ public final class TransferOrder { @@ -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.<TransferLine>emptyList()
: java.util.Collections.unmodifiableList(new java.util.ArrayList<TransferLine>(b.lines));
}
public static Builder builder() {
@ -187,6 +276,305 @@ public final class TransferOrder { @@ -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<TransferLine> lines() {
return lines;
}
/**
* 转运商品明细(查询详情时回填)。
*
* <p>数量分三层:预报件数、清点箱数、上架件数。对账时要一起看。</p>
*/
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 { @@ -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<TransferLine> lines;
public Builder transferRequestNo(String v) {
this.transferRequestNo = v;
@ -316,6 +730,171 @@ public final class TransferOrder { @@ -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<TransferLine> v) {
this.lines = v;
return this;
}
/** 追加一条商品明细。 */
public Builder line(TransferLine v) {
if (this.lines == null) {
this.lines = new java.util.ArrayList<TransferLine>();
}
this.lines.add(v);
return this;
}
public TransferOrder build() {
return new TransferOrder(this);
}

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

@ -50,8 +50,15 @@ public final class XincangForecastMapper { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

4
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java

@ -71,6 +71,10 @@ public final class XincangInventoryMapper { @@ -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;
}

42
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java

@ -64,6 +64,31 @@ public final class XincangOrderDetailMapper { @@ -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 { @@ -174,6 +199,23 @@ public final class XincangOrderDetailMapper {
}
}
/**
* 整数原值:空值 / 非法返回 null。
*
* <p>与 {@link #parsePositiveInt} 的区别:这个把 null 与 0 区分开,
* 用于「仓方没给」与「仓方给了 0」要分开的字段(如件数合计)。</p>
*/
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;

7
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java

@ -40,7 +40,7 @@ public final class XincangOrderMapper { @@ -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 { @@ -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) {

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

@ -17,6 +17,9 @@ import java.math.RoundingMode; @@ -17,6 +17,9 @@ import java.math.RoundingMode;
*
* <p>文档未定义「包装方式 / 是否 SN / 客退处理 / 海关信息」等字段,这些统一模型字段
* <b>不发送</b>,避免自行编造平台不认的键。</p>
*
* <p>文档里标「已废弃」的 {@code ahs_weight} / {@code ahs_dimensions} / {@code oversize}
* 只在 DTO 里占位,<b>一律不填</b>——仓方已改为按服务商参数自动计算。</p>
*/
public final class XincangProductMapper {
@ -54,6 +57,11 @@ 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;
}

54
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java

@ -38,9 +38,63 @@ public final class XincangTransferDetailMapper { @@ -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<TransferOrder.TransferLine> toLines(XincangDtos.TransferDetail detail) {
if (detail.products == null || detail.products.isEmpty()) {
return java.util.Collections.emptyList();
}
java.util.List<TransferOrder.TransferLine> out =
new java.util.ArrayList<TransferOrder.TransferLine>(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()) {

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

@ -141,6 +141,34 @@ public final class XincangDtos { @@ -141,6 +141,34 @@ public final class XincangDtos {
/** 产品图片;需先调 {@code upload.files}。统一模型暂不承载图片,通常为 null。 */
@JsonProperty("product_image")
public ProductImage productImage;
/**
* AHS 计费重量。
*
* <p>文档标注<b>已废弃</b>:具体值由各服务商参数自动计算。SDK 不填,
* 保留占位只为与文档字段表对齐。</p>
*/
@JsonProperty("ahs_weight")
@Deprecated
public String ahsWeight;
/**
* AHS 计费尺寸。
*
* <p>文档标注<b>已废弃</b>:具体值由各服务商参数自动计算。SDK 不填。</p>
*/
@JsonProperty("ahs_dimensions")
@Deprecated
public String ahsDimensions;
/**
* 是否超尺寸。
*
* <p>文档标注<b>已废弃</b>:具体值由各服务商参数自动计算。SDK 不填。</p>
*/
@JsonProperty("oversize")
@Deprecated
public String oversize;
}
/** 产品图片(OSS 元数据)。 */
@ -428,6 +456,14 @@ public final class XincangDtos { @@ -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 { @@ -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 { @@ -1017,6 +1069,15 @@ public final class XincangDtos {
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastCreateRequest {
/**
* 客户 id。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填;保留占位以与文档字段表对齐。</p>
*/
@JsonProperty("customer_id")
@Deprecated
public String customerId;
/** 目的地仓。 */
@JsonProperty("dest_warehouse")
public String destWarehouse;
@ -1081,6 +1142,24 @@ public final class XincangDtos { @@ -1081,6 +1142,24 @@ public final class XincangDtos {
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ForecastImproveRequest {
/**
* 预报单 id。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填;保留占位以与文档字段表对齐。</p>
*/
@JsonProperty("id")
@Deprecated
public String id;
/**
* 客户 id。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填。</p>
*/
@JsonProperty("customer_id")
@Deprecated
public String customerId;
@JsonProperty("forecast_no")
public String forecastNo;
@ -1094,9 +1173,20 @@ public final class XincangDtos { @@ -1094,9 +1173,20 @@ public final class XincangDtos {
@JsonProperty("ref_no")
public String refNo;
/**
* 新增预报柜号。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填。</p>
*/
@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 { @@ -1108,6 +1198,15 @@ public final class XincangDtos {
@JsonProperty("eta")
public String eta;
/**
* 最晚免费时间(提柜)。
*
* <p>文档标注<b>已舍弃</b>,SDK 不填。</p>
*/
@JsonProperty("lfd")
@Deprecated
public String lfd;
@JsonProperty("delivery_requirements")
public String deliveryRequirements;
@ -1118,13 +1217,33 @@ public final class XincangDtos { @@ -1118,13 +1217,33 @@ public final class XincangDtos {
@JsonProperty("other_need")
public String otherNeed;
/**
* 总件数。
*
* <p>文档标注<b>已舍弃</b>(由 {@code products} 汇总),SDK 不填。</p>
*/
@JsonProperty("sku_count_sum")
@Deprecated
public String skuCountSum;
/**
* 总箱数。
*
* <p>文档标注<b>已舍弃</b>(由 {@code products} 汇总),SDK 不填。</p>
*/
@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 { @@ -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 { @@ -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 { @@ -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;
}
/** 预报详情响应外层。 */

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

@ -223,7 +223,9 @@ class XincangForecastTest { @@ -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());
}

20
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java

@ -131,6 +131,26 @@ class XincangInventoryTest { @@ -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));

76
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java

@ -0,0 +1,76 @@ @@ -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;
/**
* 统一模型里「某家仓必填、其他仓不需要」的字段不再在构造期拦截。
*
* <p>这些用例守护的是:信仓可以只给它认识的字段就构造出命令,
* 不会因为运去哪的必填项(nameEn / packingType / 海关三项 / 入库商品行)
* 被迫塞无意义的值。</p>
*/
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。
*
* <p>改前「海关三项必须整组给」在构造期强制,信仓调用方被迫填两个用不上的字段。</p>
*/
@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);
}
}

21
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java

@ -168,6 +168,27 @@ class XincangOrderTest { @@ -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\":\"\"}"));

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

@ -207,6 +207,32 @@ class XincangProductTest { @@ -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()

19
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java

@ -192,6 +192,25 @@ class XincangTransferTest { @@ -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")

293
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java

@ -0,0 +1,293 @@ @@ -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;
/**
* 信仓联网探针的公共基座。
*
* <p><b>默认全部跳过</b>,用 {@code -Dxincang.probe=true} 显式开启;写接口还要再加
* {@code -Dxincang.probe.write=true} 二次确认。凭据与业务数据一律走系统属性,
* <b>真实值不入库</b>。</p>
*
* <pre>
* mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
* -Dxincang.probe=true \
* -Dxincang.probe.appKey=你的appkey -Dxincang.probe.appSecret=你的secret \
* -Dtest=XincangReadProbeTest test
* </pre>
*
* <p>可选属性:{@code baseUrl}、{@code warehouseCode}、{@code sku}、{@code postcode}、
* {@code qty}、{@code orderNo}、{@code transferNo}、{@code forecastNo}。</p>
*
* <p>设计约束:</p>
* <ul>
* <li>每个探针独立执行,单个失败只打印不抛出,保证一次能跑完全部接口;</li>
* <li>请求 / 响应都打印(截断 + 脱敏),便于和文档逐字段对照;</li>
* <li>不硬编码任何业务数据:仓代码与承运商从目录接口现取。</li>
* </ul>
*/
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> T step(String label, Supplier<T> 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<WarehouseFacility> 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<String> 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;
}
// ---------------------------------------------------------------- 报文打印
/**
* 请求 / 响应打印。
*
* <p>脱敏规则:鉴权头与 URL 里的 token / secret 一律替换成 {@code ***};
* 打印体截断到 2000 字符,避免大段 base64 或明细刷屏。</p>
*/
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)";
}
}
}

307
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java

@ -0,0 +1,307 @@ @@ -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;
/**
* 信仓只读接口的联网探针:核对真实出入参。
*
* <p><b>默认跳过</b>,用 {@code -Dxincang.probe=true} 开启。凭据与业务数据走系统属性,
* 真实值不入库;缺某个业务输入时只跳过依赖它的用例,不影响其他用例。</p>
*
* <pre>
* 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
* </pre>
*
* <p>可选属性:{@code warehouseCode} / {@code sku} / {@code postcode} / {@code orderNo} /
* {@code transferNo} / {@code forecastNo} / {@code productPageSize}。</p>
*
* <p><b>只做查询</b>,不调用任何写接口;异常只打印不抛出,一次能跑完全部段落。</p>
*/
@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<WarehouseFacility> 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<String> 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<InventorySnapshot> 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<InventoryAgeRecord> 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 与邮编。
*
* <p>协议待核对:文档写 GET + JSON body,OkHttp 不支持 GET 带 body,
* 适配器按 POST + JSON body 下发。这里重点看仓方是否接受。</p>
*/
@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);
}
}

338
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java

@ -0,0 +1,338 @@ @@ -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;
/**
* 信仓写接口的联网探针:真实下单 / 建转运 / 建预报,用于核对报文。
*
* <p><b>默认整类跳过</b>,需要两个开关同时打开:</p>
* <pre>
* -Dxincang.probe=true -Dxincang.probe.write=true
* </pre>
*
* <p>运行示例:</p>
* <pre>
* 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
* </pre>
*
* <p><b>注意:会在仓方测试环境留下真实数据。</b>能自清理的链路(订单、转运)会尽量删掉;
* 商品建档与预报没有删除接口,跑完需要人工清理。所有单号都带时间戳后缀,
* 重跑不会撞唯一约束。</p>
*/
@EnabledIfSystemProperty(named = XincangProbeSupport.PROBE_WRITE, matches = "true")
class XincangWriteProbeTest {
// ================================================================ 商品
/**
* 商品建档 / 更新:走 add_product 或 update_product(先查临时产品决定)。
*
* <p>需要 {@code -Dxincang.probe.sku};金额按 1.00 USD 下发,
* 因为信仓把 amount 列为必填且我们不再兜底 0。</p>
*/
@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。");
}
}
// ================================================================ 出库
/**
* 出库闭环:下单 → 详情回读 → 删除。
*
* <p>需要 sku + postcode;承运商从目录接口自动取(或 {@code -Dxincang.probe.carrier})。</p>
*/
@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));
}
/**
* 转运审核:建转运 → 审核。
*
* <p><b>审核之后不能删除</b>,会在测试环境留下数据,默认不跑;
* 需要显式加 {@code -Dxincang.probe.transferApprove=true}。</p>
*/
@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()));
}
// ================================================================ 预报
/**
* 预报闭环:新增 → 完善资料 → 提交 → 详情回读。
*
* <p><b>没有删除接口</b>,跑完会在测试环境留下预报单。</p>
*/
@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());
}
}
}

5
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java

@ -37,6 +37,11 @@ public final class YqnInboundMapper { @@ -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();

33
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java

@ -29,6 +29,15 @@ public final class YqnProductMapper { @@ -29,6 +29,15 @@ public final class YqnProductMapper {
* 这里只做字段搬运与单位对齐(cm / g 与平台一致,不换算)。</p>
*/
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 { @@ -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 { @@ -115,8 +125,25 @@ public final class YqnProductMapper {
}
static List<YqnProductDtos.SaveProductRequest.Customs> 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,非美元申报会被静默算错,

22
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java

@ -30,8 +30,28 @@ public final class YqnTransferMapper { @@ -30,8 +30,28 @@ public final class YqnTransferMapper {
private YqnTransferMapper() {
}
/** 统一命令 → 运去哪创建调拨单请求。 */
/**
* 统一命令 → 运去哪创建调拨单请求。
*
* <p>运去哪要求两个预计日期都给,且调拨出库必须带收货地址。这两条原本写在
* {@link TransferCommand} 的构造期,会把运去哪的约束强加给其它仓(信仓转运只有
* 发货日期、用仓库名代替地址),现在改到这里按运去哪的协议校验。</p>
*
* @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();

29
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java

@ -123,21 +123,38 @@ class YqnProductTest { @@ -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)

Loading…
Cancel
Save