diff --git a/docs-warehouse/README.md b/docs-warehouse/README.md index 45d2d5f..e75ff01 100644 --- a/docs-warehouse/README.md +++ b/docs-warehouse/README.md @@ -7,6 +7,7 @@ | [architecture.md](architecture.md) | 三方仓架构:分层、模块依赖、门面/能力/适配器/SPI | | [callback.md](callback.md) | 回调(Webhook)链路:验签、分派、出参模型、宿主怎么接 | | [yqn/README.md](yqn/README.md) | 运去哪:接口汇总、联调结论、平台限制 | +| [xincang/README.md](xincang/README.md) | 信仓:接口汇总、枚举码表、协议待核对、联调探针 | | [notes.md](notes.md) | 通用注意事项:写操作、幂等、时区、单位、字段口径 | ## 快速定位 @@ -14,4 +15,5 @@ - 想知道**能力有哪些** → `architecture.md` 的「能力矩阵」 - 想知道**回调怎么接** → `callback.md` 的「宿主要做什么」 - 想知道**运去哪对接了什么** → `yqn/README.md` 的「接口清单」 +- 想知道**信仓对接了什么** → `xincang/README.md` 的「接口清单」 - 想知道**踩过什么坑** → `notes.md` diff --git a/docs-warehouse/xincang/README.md b/docs-warehouse/xincang/README.md new file mode 100644 index 0000000..93784af --- /dev/null +++ b/docs-warehouse/xincang/README.md @@ -0,0 +1,251 @@ +# 信仓(XinCang)接入汇总 + +## 1. 基本信息 + +| 项 | 值 | +|---|---| +| 适配器 ID | `xincang` | +| 测试 / 联调环境 | `http://test.api.oms.13u3.com/oms` | +| 生产环境 | `https://oms.xincang-tech.com/oms/` | +| 鉴权 | 先 `GET /api.login?appkey=&secret=` 换 token;业务请求把 token 放 **query 参数 `token`**,不是 `Authorization` 头 | +| token 有效期 | 2 小时,**没有 refresh 接口**,到期只能重新登录 | +| token 维度 | 客户级(同一 appkey 下多仓共用一个 token) | +| 限流 | 保守默认 2 req/s(仓方未公开) | +| 成功判定 | 顶层 `errno=0`;业务接口还要 `rst.code="0"`(登录响应没有 `rst.code`) | +| 时间口径 | 北京时间(`yyyy-MM-dd HH:mm:ss` / 日期 `yyyy-MM-dd`) | +| 单位 | 金额美元、尺寸英寸、重量磅(统一模型是 cm/g,适配器内换算) | + +## 2. 接口清单(19 个已对接) + +| # | 接口 | 路径 | 能力位 | +|---|---|---|---| +| 1 | 登录 | `GET /api.login` | — | +| 2 | 新增产品 | `POST /api.add_product` | `PRODUCT` | +| 3 | 更新产品 | `POST /api.update_product` | `PRODUCT` | +| 4 | 产品列表(查重用) | `GET /api.productlist` | `PRODUCT` | +| 5 | 新增订单一单多件 | `POST /api.add_order_multiple` | `OUTBOUND` | +| 6 | 订单详情 | `GET /api.get_order` | `OUTBOUND` | +| 7 | 删除订单 | `POST /api.delete_order` | `OUTBOUND` | +| 8 | 新增转运 | `POST /fba.do_fba` | `TRANSFER` | +| 9 | 转运审核 | `POST /fba.do_approve` | `TRANSFER` | +| 10 | 转运详情 | `GET /fba.fba_detail` | `TRANSFER` | +| 11 | 删除转运 | `POST /fba.delete_fba` | `TRANSFER` | +| 12 | 新增预报 | `POST /forecast.do_forecast` | `INBOUND` | +| 13 | 完善资料 | `POST /forecast.do_improve_forecast` | `INBOUND` | +| 14 | 预报提交 | `POST /forecast.done_forecast` | `INBOUND` | +| 15 | 预报详情 | `GET /forecast.forecast_detail` | `INBOUND` | +| 16 | 实时库存 | `GET /api.stocklist` | `INVENTORY_QUERY` | +| 17 | 库龄列表 | `GET /api.stockagelist` | `INVENTORY_QUERY` | +| 18 | 最优渠道 | `POST /api.calculate_order_v3` | `CHANNEL_RECOMMEND` | +| 19 | 客户仓库 / 承运商 | `GET /api.get_customer_warehouses`、`/api.get_customer_logistics` | `DIRECTORY` | + +### 已声明但未接入 + +| 常量 | 说明 | +|---|---| +| `PATH_PRODUCT_PUBLISH`(`/api.pub_product`) | 临时产品 → 正式产品,未接;建档结果仍是临时产品 | +| `PATH_TRANSFER_LIST`(`/fba.fbalist`) | 转运列表,未接 | +| `api.orderlist` / `forecast.forecastlist` | 列表查询均未接 | + +## 3. 业务流程 + +### 出库 + +``` +① 查仓库 / 承运商(拿 warehouse_code、logistics_type) + GET /api.get_customer_warehouses + GET /api.get_customer_logistics +② 可选:最优渠道询价 + POST /api.calculate_order_v3 +③ 下单(multipart/form-data) + POST /api.add_order_multiple +④ 查详情 / 回读状态 + GET /api.get_order?order_no= (或 ckh=) +⑤ 删除(按状态分流:待审核→删除、待发货→已取消、拣货/已拣货→已拦截) + POST /api.delete_order +``` + +### 转运(仓 → 平台仓) + +``` +① 建转运(application/json) POST /fba.do_fba → order_no +② 查详情 GET /fba.fba_detail?order_no= +③ 审核 POST /fba.do_approve?order_no= +④ 删除(仅待审核可删) POST /fba.delete_fba?order_no= +``` + +### 头程入库(预报) + +``` +① 建空单(只给单头) POST /forecast.do_forecast → order_no +② 补明细(整段覆盖) POST /forecast.do_improve_forecast +③ 提交 POST /forecast.done_forecast (query + body 都带 forecast_no) +④ 查详情 GET /forecast.forecast_detail +``` + +> ①②③ 是三步,不是一次调用。① 不需要商品明细(`referenceSkuCount` 必填)。 + +### 商品 + +``` +① 查临时产品(决定 add 还是 update) + GET /api.productlist?state=0&key= +② 新增(临时产品) POST /api.add_product + 或 更新(仅临时产品可更新) POST /api.update_product +``` + +## 4. 枚举映射(信仓是两套码表,core 是第三套) + +### 订单状态 `state` + +| 信仓码 | 含义 | core `OutboundStatus` | +|---|---|---| +| 0 | 待审核 | `PENDING_REVIEW` | +| 1 | 待发货 | `PENDING_SHIPMENT` | +| 2 | 拣货中 | `PICKING` | +| 3 | 已拣货 | `PICKED` | +| 4 | 已贴单 | `LABEL_READY` | +| 5 | 已发货 | `SHIPPED` | +| 6 | 已拦截 | `INTERCEPTED` | +| 7 | 缺货 | `OUT_OF_STOCK` | +| 8 | 已取消 | `CANCELLED` | +| 10 | 已删除 | `DELETED` | +| 11 | 审核中 | `REVIEWING` | +| 12 | 审核失败 | `REVIEW_FAILED` | +| 其他 | — | `UNKNOWN`(不猜) | + +### 转运状态 `state` + +| 信仓码 | 含义 | core `TransferStatus` | +|---|---|---| +| 0 | 待审核 | `PENDING_REVIEW` | +| 1 | 待处理 | `PENDING_PROCESSING` | +| 2 | 待拣货 | `PENDING_PICK` | +| 3 | 待贴标 | `PENDING_LABELING` | +| 4 | 待打托 | `PENDING_PALLETIZING` | +| 5 | 待发货 | `PENDING_OUTBOUND` | +| 6 | 已发货 | `SHIPPED`(**不是** `COMPLETED`)| +| 7 | 已取消 | `CANCELLED` | + +> **列表接口与详情接口的码表不一致**:列表写的是「0 待审核 1 待处理 2 带拣货 3 待打托 4 待发货 5 已发货 9 取消」(少「待贴标」、后续前移)。适配器以**详情码表**为准,原始值仍保存在 `rawStatus`。 + +### 预报状态 `state` + +| 信仓码 | 含义 | core `InboundStatus` | +|---|---|---| +| 0 | 建仓中 | `DRAFT` | +| 1 | 出运中 | `IN_TRANSIT` | +| 2 | 预报完成 | `PENDING_SHIPMENT` | +| 3 | 在海上 | `IN_TRANSIT` | +| 4 | 送仓中 | `IN_TRANSIT` | +| 5 | 卸柜中 | `RECEIVING` | +| 6 | 清点中 | `RECEIVING` | +| 7 | 上架中 | `STORING` | +| 8 | 上架完成 | `COMPLETED` | +| 9 | 已驳回 | `REJECTED` | + +### 订单类型 `order_type` + +| 值 | 含义 | 对应 core | +|---|---|---| +| `common` | 非自供面单 | `LabelMode.WAREHOUSE_LABEL` | +| `wayfair` | 自供面单 | `LabelMode.PLATFORM_LABEL`(`gzh` + `face_base64` 必填)| + +> 转运接口的 `order_type` 是**另一套字典**(FBA / LTL 等),与下单接口无关。 + +## 5. 字段口径(容易传错的) + +| 字段 | 要传什么 | +|---|---| +| 下单 `ckh` | **参考号,唯一不可重复**;适配器用 `outboundRequestNo`,重推同一单号会被拒 | +| 下单 `logistics_type` | 承运商字典值(`api.get_customer_logistics` 返回的原值) | +| 下单 `is_sign` | `是` / `否`;模型 `OutboundCommand.signatureRequired`,未给时兜底「否」 | +| 下单 `is_split` | `1` 拆单 / `0` 打包;未给时仓方默认 `1` | +| 商品 `amount` | **必填且美元**;取 `declaredValue`,缺失直接拒绝(不再兜底 0.00) | +| 商品 `bar_code` | 必填且**查重**;`WarehouseProduct.barcode` 未给时退回 SKU | +| 商品 `ckm` | 仓库码,取 `customItemNo` | +| 转运 `po` | 必填;未给时退回 `transferRequestNo` | +| 转运 `delivery_mode` / `delivery_way` | 必填,只认仓方字典原值;先调字典接口 | +| 转运 `is_pallet` | 必填 `是` / `否`;模型映射 `palletRequired` | +| 预报 `rfc_sku_count` | 必填;取 `referenceSkuCount`,没有退回明细行数 | +| 预报 `ref_no` | 完善资料必填,**长度上限 32** | +| 库存 `warehouse_code` | **必填且只能单个**;传多个显式拒绝 | +| 库存 `is_show_zero` | 默认不传时只返回库存 > 0 的 SKU;模型 `includeZeroStock` | +| 库龄 `bill_date` | 单值字符串 `起 - 止` | + +## 6. 单位与时区 + +| 字段 | 单位 | +|---|---| +| 商品 `weight_lbs` / `size_*_ln` | 磅 / 英寸(适配器从 cm、g 换算,保留 4 位) | +| 商品 `amount` | 美元,2 位小数 | +| 库存 `volume_cm` | 立方厘米 | +| 库龄 `total_volume_cbm` | 立方米 | + +时间字段全部是**北京时间**,适配器解析成 UTC 后存入模型(`Instant`)。空串一律转 `null`,不猜。 + +## 7. 平台限制(已知且无法解决) + +| 接口 | 字段 | 情况 | +|---|---|---| +| 订单详情 `get_order` | `order_no` | 只回系统单号;业务侧单号在 `ckh` | +| 订单详情 `get_order` | 面单 | 只给 `face_url`(OSS 签名链接,有时效) | +| 转运详情 | `dest_warehouse` | 可能是占位 `"0"` | +| 产品建档 | `state` | 新建的是**临时产品**(`state=0`),没有上架接口就下不了单 | +| 预报 | 明细 | 建单时没有明细,必须先建头再补 | +| 列表查询 | 订单 / 转运 / 预报 | 均无列表接口;`query(cursor)` 用单号取详情代替 | +| 错误信息 | `err` | 只有一句话(如「产品参数有误」),无法细分原因 | + +## 8. 协议待核对(联调时必看) + +| 项 | 现状 | +|---|---| +| 生产域名 | 文档未给,常量写的是 `"待核对"` | +| 限流 | 未公开,按 2 req/s | +| **最优渠道 `calculate_order_v3`** | 文档标 `GET` + JSON body,**OkHttp 不支持 GET 带 body**;适配器按 **POST + JSON body** 下发 | + +## 9. 联调探针 + +三个探针,默认全部跳过: + +```bash +# ① 登录 +mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \ + -Dxincang.probe=true \ + -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \ + -Dtest=XincangLoginProbeTest test + +# ② 只读(9 个查询接口) +mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \ + -Dxincang.probe=true \ + -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \ + -Dxincang.probe.sku=<有库存的SKU> -Dxincang.probe.postcode=<美国邮编> \ + -Dtest=XincangReadProbeTest test + +# ③ 写(会留下真实数据,需二次确认) +mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \ + -Dxincang.probe=true -Dxincang.probe.write=true \ + -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \ + -Dxincang.probe.sku= -Dxincang.probe.postcode=<邮编> \ + -Dxincang.probe.destWarehouse=<目的仓> \ + -Dtest=XincangWriteProbeTest test +``` + +可选属性:`warehouseCode` / `carrier` / `orderNo` / `transferNo` / `forecastNo` / `qty` / +`destWarehouse` / `deliveryMode` / `deliveryWay` / `orderType` / `shipmentType` / +`cabinetType` / `deliveryRequirements` / `otherNeed` / `transferApprove`。 + +**会留下数据的探针**:商品建档(无删除接口)、预报(`delete_forecast` 未接)、 +转运审核(审核后不可删,需 `-Dxincang.probe.transferApprove=true`)。 +出库与转运创建可以自清理。 + +## 10. 未接入 + +| 项 | 原因 | +|---|---| +| 上架正式产品 | 统一模型没有「上架」语义 | +| 订单 / 转运 / 预报列表 | 仓方虽提供,但统一模型暂未接列表能力 | +| 文件上传 `upload.files` | 需要 multipart 文件流;商品图片与转运附件因此传不了 | +| 修改订单 `api.update_order` | 文档建议停止使用 | +| 费用测算 `api.calculate_order` / `_v2` | 只接了最优渠道 `_v3` | +| 库龄费率以外的费用明细 | `is_need_fee_rate` 已支持,但结算账单未接 | diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java index 80989bd..bef8302 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java @@ -9,9 +9,12 @@ import java.util.Objects; /** * 仓商品建档入参。 * - *

单位写进字段名(cm / g),避免适配器之间靠注释约定换算。 - * 运去哪 API 115 的必填项(sku / 中英文名 / 包装方式 / 长宽高 / 重量 / SN) - * 在这里都是必填,缺了在构造期就失败,而不是等平台报错。

+ *

单位写进字段名(cm / g),避免适配器之间靠注释约定换算。

+ * + *

构造期只校验所有仓都必须给的字段:{@code omsSku}、{@code name}、 + * 长宽高与重量为正。其余字段({@code nameEn} / {@code packingType} / 海关三项 / + * 品类等)的必填性与组合约束都由各适配器在拼报文时校验—— + * 否则接第二家仓时会被第一家的约束卡住。

*/ public final class WarehouseProduct { @@ -20,11 +23,21 @@ public final class WarehouseProduct { private final String customItemNo; private final String barcode; private final String name; + /** + * 英文名。 + * + *

运去哪必填(适配器会拒绝缺失);信仓接口只有中文名({@code chn_name}), + * 未给即不传。

+ */ private final String nameEn; private final String description; /** 产品类型:1 成品 / 2 配件 / 3 耗材;0 表示未指定(平台默认成品)。 */ private final int productType; - /** 发货包装:0 原包装发货 / 1 重新打包。 */ + /** + * 发货包装:0 原包装发货 / 1 重新打包;-1 表示未给。 + * + *

运去哪必填(适配器会拒绝缺失);信仓接口没有该字段,未给即不传。

+ */ private final int packingType; private final double lengthCm; private final double widthCm; @@ -124,18 +137,37 @@ public final class WarehouseProduct { */ private final List lotAttributeCodes; + // ==================== 仓方原始字段 ==================== + + /** + * 产品品类;null 表示不传。 + * + *

信仓 {@code product_category}:0 其它 / 1 家具 / 2 食品 / 3 汽配 / 4 服饰 / + * 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。取值由仓方字典定义,适配器不归一。

+ */ + private final Integer productCategory; + + /** + * 产品图片地址;null 表示不传。 + * + *

信仓走「先上传文件、再回传 OSS 元数据」的两步流程({@code upload.files}), + * 这里只承载最终可访问的 URL;适配器拿不到 OSS 元数据时不发送该字段。

+ */ + private final String imageUrl; + private WarehouseProduct(Builder b) { this.omsSku = require(b.omsSku, "omsSku"); this.providerSku = b.providerSku; this.customItemNo = b.customItemNo; this.barcode = b.barcode; this.name = require(b.name, "name"); - this.nameEn = require(b.nameEn, "nameEn"); + // nameEn 是运去哪的必填项;信仓只有 chn_name(取 name),没有英文名。 + // 必填性由 YqnProductMapper 校验,这里不做构造期强制。 + this.nameEn = b.nameEn; this.description = b.description; this.productType = b.productType; - if (b.packingType < 0) { - throw new IllegalArgumentException("packingType is required (0 原包装发货 / 1 重新打包)"); - } + // 不在构造期强制:这是运去哪的必填项,信仓不需要。必填性由各适配器按自己的 + // 协议校验,见 YqnProductMapper;未给时保持 -1 表示「不传」。 this.packingType = b.packingType; this.lengthCm = requirePositive(b.lengthCm, "lengthCm"); this.widthCm = requirePositive(b.widthCm, "widthCm"); @@ -155,6 +187,8 @@ public final class WarehouseProduct { this.cost = b.cost; this.link = b.link; this.remark = b.remark; + this.productCategory = b.productCategory; + this.imageUrl = b.imageUrl; this.expirationControl = b.expirationControl; this.expirationDays = b.expirationDays; this.packedQuantity = b.packedQuantity; @@ -169,21 +203,9 @@ public final class WarehouseProduct { this.lotAttributeCodes = java.util.Collections.unmodifiableList( new java.util.ArrayList(b.lotAttributeCodes)); - // 海关信息要么整组给、要么整组不给:国家编码 / HS Code / 申报价值缺一即失败 - int customsFields = 0; - if (hasText(hsCode)) { - customsFields++; - } - if (hasText(countryOfOrigin)) { - customsFields++; - } - if (declaredValue != null) { - customsFields++; - } - if (customsFields != 0 && customsFields != 3) { - throw new IllegalArgumentException( - "hsCode / countryOfOrigin / declaredValue must be set together for customs"); - } + // 海关信息「三项整组给」原本在这里校验。但信仓只用 declaredValue 当 amount(必填), + // 不需要 hsCode / countryOfOrigin;在模型层强制整组会把信仓卡死。 + // 整组校验移到需要海关信息的适配器(见 YqnProductMapper.toCustoms)。 } public static Builder builder() { @@ -364,6 +386,16 @@ public final class WarehouseProduct { return remark; } + /** 产品品类(仓方字典值);null 表示不传。 */ + public Integer productCategory() { + return productCategory; + } + + /** 产品图片地址;null 表示不传。 */ + public String imageUrl() { + return imageUrl; + } + /** 是否给了任何海关信息。 */ public boolean hasCustoms() { return declaredValue != null; @@ -416,6 +448,8 @@ public final class WarehouseProduct { private Money cost; private String link; private String remark; + private Integer productCategory; + private String imageUrl; private Boolean expirationControl; private Integer expirationDays; private Integer packedQuantity; @@ -469,7 +503,7 @@ public final class WarehouseProduct { return this; } - /** 0 原包装发货 / 1 重新打包;必填。 */ + /** 0 原包装发货 / 1 重新打包;运去哪必填,信仓不用。 */ public Builder packingType(int v) { this.packingType = v; return this; @@ -626,6 +660,18 @@ public final class WarehouseProduct { return this; } + /** 产品品类(信仓 {@code product_category} 等字典值);null 表示不传。 */ + public Builder productCategory(Integer v) { + this.productCategory = v; + return this; + } + + /** 产品图片地址;null 表示不传。 */ + public Builder imageUrl(String v) { + this.imageUrl = v; + return this; + } + /** * @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐 */ diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java index 70af166..78c76b6 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundCommand.java @@ -8,8 +8,10 @@ import java.util.List; /** * 入库计划创建命令。写操作,幂等键是 {@link #inboundRequestNo()}(仓方的来源单号)。 * - *

必填:单号、仓、库存类型、至少一条商品行。装箱、批次、附件都是可选的—— - * 仓会在收货时按实际情况清点,但给了就必须自洽(一箱多 SKU 要用 sid 归并)。

+ *

构造期只校验所有仓都必须给的:单号、库存类型取值。仓 / 商品行 / 日期等 + * 各家要求不同(信仓「新增预报」只建单头、明细走「完善资料」), + * 必填性由各适配器在拼报文时校验;装箱、批次、附件的自洽性仍由模型保证 + * (一箱多 SKU 要用 sid 归并)。

*/ public final class InboundCommand { @@ -133,6 +135,14 @@ public final class InboundCommand { /** 中文名称(信仓 {@code chn_name});null 表示不传。 */ private final String chnName; + /** + * 参考 SKU 种类数;null 表示不传。 + * + *

信仓 {@code rfc_sku_count}(新增预报必填)。与 {@link #lines()} 行数无关: + * 报的是「预计有多少种 SKU」,建单时明细还没给。

+ */ + private final Integer referenceSkuCount; + private InboundCommand(Builder b) { if (b.inboundRequestNo == null || b.inboundRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("inboundRequestNo must not be blank"); @@ -160,9 +170,8 @@ public final class InboundCommand { this.shipperPhone = b.shipperPhone; this.containerNo = b.containerNo; this.remark = b.remark; - if (b.lines.isEmpty()) { - throw new IllegalArgumentException("lines must not be empty"); - } + // lines 不在构造期强制:信仓的入库是「先建单头 → 再完善资料补明细」两步, + // 第一步本来就没有明细。需要明细的仓(运去哪、信仓的完善资料)由适配器校验。 this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); this.cartons = Collections.unmodifiableList(new ArrayList(b.cartons)); this.batches = Collections.unmodifiableList(new ArrayList(b.batches)); @@ -189,6 +198,7 @@ public final class InboundCommand { this.oversize = b.oversize; this.oversizeNote = b.oversizeNote; this.chnName = b.chnName; + this.referenceSkuCount = b.referenceSkuCount; } public static Builder builder() { @@ -377,6 +387,11 @@ public final class InboundCommand { return chnName; } + /** 参考 SKU 种类数;null 表示不传(信仓 {@code rfc_sku_count})。 */ + public Integer referenceSkuCount() { + return referenceSkuCount; + } + public static final class Builder { private String inboundRequestNo; @@ -418,6 +433,7 @@ public final class InboundCommand { private Boolean oversize; private String oversizeNote; private String chnName; + private Integer referenceSkuCount; public Builder inboundRequestNo(String v) { this.inboundRequestNo = v; @@ -632,6 +648,12 @@ public final class InboundCommand { return this; } + /** 参考 SKU 种类数(信仓 {@code rfc_sku_count},新增预报必填)。 */ + public Builder referenceSkuCount(Integer v) { + this.referenceSkuCount = v; + return this; + } + public InboundCommand build() { return new InboundCommand(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java index 9bfdbfe..75e66ac 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java @@ -121,6 +121,65 @@ public final class InboundOrder { */ private final List containers; + // ==================== 仓方原始字段(信仓预报详情提供)==================== + + /** 仓方内部预报单 id;信仓 {@code id}。 */ + private final String providerId; + /** 中文名称 / 联系人;信仓 {@code chn_name}。 */ + private final String chnName; + /** 客户 id;信仓 {@code customer_id}。 */ + private final String customerId; + /** 客户代码;信仓 {@code customer_name}。 */ + private final String customerNo; + /** 目的仓 id(仓方内部);信仓 {@code dest_warehouse},与 {@link #warehouseCode()}(仓代码)不同。 */ + private final String destWarehouseId; + /** 仓方状态原文(可读名);信仓 {@code state_name},如「预报完成」。 */ + private final String rawStatusName; + /** 出运类型;信仓 {@code shipment_type}(1 空运 / 2 海运)。 */ + private final String shipmentType; + /** 柜型;信仓 {@code cabinet_type}(0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库)。 */ + private final String cabinetType; + /** 柜号;信仓 {@code cabinet_no}。 */ + private final String cabinetNo; + /** 预计发货时间(UTC);信仓 {@code rfc_etd}。 */ + private final Instant estimatedShipAt; + /** 实际发货时间(UTC);信仓 {@code etd}。 */ + private final Instant shippedAt; + /** 是否超 120cm;信仓 {@code is_oversize}({@code "1"} / {@code "0"})。 */ + private final String isOversize; + /** 超尺寸备注;信仓 {@code oversize_val}。 */ + private final String oversizeNote; + /** 发货需求;信仓 {@code delivery_requirements}(1 一件代发 / 2 FBA 中转)。 */ + private final String deliveryRequirements; + /** 预报时间(UTC);信仓 {@code forecast_time}。 */ + private final Instant forecastAt; + /** 参考 SKU 种类数;信仓 {@code rfc_sku_count}。 */ + private final Integer referenceSkuCount; + /** 预报托盘数;信仓 {@code forecast_pallet_qty}(柜型为托盘入库时才有)。 */ + private final Integer forecastPalletQty; + /** 实收托盘数;信仓 {@code receive_pallet_qty}。 */ + private final Integer receivedPalletQty; + /** 上架托盘数;信仓 {@code shelf_pallet_qty}。 */ + private final Integer storedPalletQty; + /** 计费托盘数;信仓 {@code bill_pallet_qty}。 */ + private final Integer billedPalletQty; + /** 卸柜清点时间(UTC);信仓 {@code unlade_time}。 */ + private final Instant unladeAt; + /** 清点完成时间(UTC);信仓 {@code check_time}。 */ + private final Instant checkedAt; + /** 上架时间(UTC);信仓 {@code putaway_time}。 */ + private final Instant putawayAt; + /** 还柜时间(UTC);信仓 {@code leave_time}。 */ + private final Instant leftAt; + /** 是否需要内箱贴;信仓 {@code is_inner_box_sticker}({@code "1"} / {@code "0"})。 */ + private final String isInnerBoxSticker; + /** 是否需要外箱贴;信仓 {@code is_outer_box_sticker}。 */ + private final String isOuterBoxSticker; + /** 其他需求(仓方原值,逗号分隔);信仓 {@code other_need},如「内箱贴,外箱贴」。 */ + private final String otherNeed; + /** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */ + private final Instant modifiedAt; + private InboundOrder(Builder b) { this.inboundRequestNo = require(b.inboundRequestNo, "inboundRequestNo"); this.providerInboundId = b.providerInboundId; @@ -158,6 +217,34 @@ public final class InboundOrder { this.cartonTotalWeightKg = b.cartonTotalWeightKg; this.cartonTotalVolumeCbm = b.cartonTotalVolumeCbm; this.containers = Collections.unmodifiableList(new ArrayList(b.containers)); + this.providerId = b.providerId; + this.chnName = b.chnName; + this.customerId = b.customerId; + this.customerNo = b.customerNo; + this.destWarehouseId = b.destWarehouseId; + this.rawStatusName = b.rawStatusName; + this.shipmentType = b.shipmentType; + this.cabinetType = b.cabinetType; + this.cabinetNo = b.cabinetNo; + this.estimatedShipAt = b.estimatedShipAt; + this.shippedAt = b.shippedAt; + this.isOversize = b.isOversize; + this.oversizeNote = b.oversizeNote; + this.deliveryRequirements = b.deliveryRequirements; + this.forecastAt = b.forecastAt; + this.referenceSkuCount = b.referenceSkuCount; + this.forecastPalletQty = b.forecastPalletQty; + this.receivedPalletQty = b.receivedPalletQty; + this.storedPalletQty = b.storedPalletQty; + this.billedPalletQty = b.billedPalletQty; + this.unladeAt = b.unladeAt; + this.checkedAt = b.checkedAt; + this.putawayAt = b.putawayAt; + this.leftAt = b.leftAt; + this.isInnerBoxSticker = b.isInnerBoxSticker; + this.isOuterBoxSticker = b.isOuterBoxSticker; + this.otherNeed = b.otherNeed; + this.modifiedAt = b.modifiedAt; } public static Builder builder() { @@ -273,6 +360,146 @@ public final class InboundOrder { return lines; } + /** 仓方内部预报单 id。 */ + public String providerId() { + return providerId; + } + + /** 中文名称 / 联系人。 */ + public String chnName() { + return chnName; + } + + /** 客户 id。 */ + public String customerId() { + return customerId; + } + + /** 客户代码。 */ + public String customerNo() { + return customerNo; + } + + /** 目的仓 id(仓方内部)。 */ + public String destWarehouseId() { + return destWarehouseId; + } + + /** 仓方状态原文(可读名)。 */ + public String rawStatusName() { + return rawStatusName; + } + + /** 出运类型(1 空运 / 2 海运)。 */ + public String shipmentType() { + return shipmentType; + } + + /** 柜型。 */ + public String cabinetType() { + return cabinetType; + } + + /** 柜号。 */ + public String cabinetNo() { + return cabinetNo; + } + + /** 预计发货时间(UTC)。 */ + public Instant estimatedShipAt() { + return estimatedShipAt; + } + + /** 实际发货时间(UTC)。 */ + public Instant shippedAt() { + return shippedAt; + } + + /** 是否超 120cm(仓方原值)。 */ + public String isOversize() { + return isOversize; + } + + /** 超尺寸备注。 */ + public String oversizeNote() { + return oversizeNote; + } + + /** 发货需求(1 一件代发 / 2 FBA 中转)。 */ + public String deliveryRequirements() { + return deliveryRequirements; + } + + /** 预报时间(UTC)。 */ + public Instant forecastAt() { + return forecastAt; + } + + /** 参考 SKU 种类数。 */ + public Integer referenceSkuCount() { + return referenceSkuCount; + } + + /** 预报托盘数。 */ + public Integer forecastPalletQty() { + return forecastPalletQty; + } + + /** 实收托盘数。 */ + public Integer receivedPalletQty() { + return receivedPalletQty; + } + + /** 上架托盘数。 */ + public Integer storedPalletQty() { + return storedPalletQty; + } + + /** 计费托盘数。 */ + public Integer billedPalletQty() { + return billedPalletQty; + } + + /** 卸柜清点时间(UTC)。 */ + public Instant unladeAt() { + return unladeAt; + } + + /** 清点完成时间(UTC)。 */ + public Instant checkedAt() { + return checkedAt; + } + + /** 上架时间(UTC)。 */ + public Instant putawayAt() { + return putawayAt; + } + + /** 还柜时间(UTC)。 */ + public Instant leftAt() { + return leftAt; + } + + /** 是否需要内箱贴(仓方原值)。 */ + public String isInnerBoxSticker() { + return isInnerBoxSticker; + } + + /** 是否需要外箱贴(仓方原值)。 */ + public String isOuterBoxSticker() { + return isOuterBoxSticker; + } + + /** 其他需求(仓方原值)。 */ + public String otherNeed() { + return otherNeed; + } + + /** 最后修改时间(UTC)。 */ + public Instant modifiedAt() { + return modifiedAt; + } + /** 是否整体完成入库。 */ public boolean completed() { return status == InboundStatus.COMPLETED; @@ -452,6 +679,34 @@ public final class InboundOrder { private Double cartonTotalWeightKg; private Double cartonTotalVolumeCbm; private final List containers = new ArrayList(); + private String providerId; + private String chnName; + private String customerId; + private String customerNo; + private String destWarehouseId; + private String rawStatusName; + private String shipmentType; + private String cabinetType; + private String cabinetNo; + private Instant estimatedShipAt; + private Instant shippedAt; + private String isOversize; + private String oversizeNote; + private String deliveryRequirements; + private Instant forecastAt; + private Integer referenceSkuCount; + private Integer forecastPalletQty; + private Integer receivedPalletQty; + private Integer storedPalletQty; + private Integer billedPalletQty; + private Instant unladeAt; + private Instant checkedAt; + private Instant putawayAt; + private Instant leftAt; + private String isInnerBoxSticker; + private String isOuterBoxSticker; + private String otherNeed; + private Instant modifiedAt; public Builder inboundRequestNo(String v) { this.inboundRequestNo = v; @@ -628,6 +883,174 @@ public final class InboundOrder { return this; } + /** 仓方内部预报单 id(信仓 {@code id})。 */ + public Builder providerId(String v) { + this.providerId = v; + return this; + } + + /** 中文名称 / 联系人(信仓 {@code chn_name})。 */ + public Builder chnName(String v) { + this.chnName = v; + return this; + } + + /** 客户 id(信仓 {@code customer_id})。 */ + public Builder customerId(String v) { + this.customerId = v; + return this; + } + + /** 客户代码(信仓 {@code customer_name})。 */ + public Builder customerNo(String v) { + this.customerNo = v; + return this; + } + + /** 目的仓 id(信仓 {@code dest_warehouse})。 */ + public Builder destWarehouseId(String v) { + this.destWarehouseId = v; + return this; + } + + /** 仓方状态原文(信仓 {@code state_name})。 */ + public Builder rawStatusName(String v) { + this.rawStatusName = v; + return this; + } + + /** 出运类型(信仓 {@code shipment_type})。 */ + public Builder shipmentType(String v) { + this.shipmentType = v; + return this; + } + + /** 柜型(信仓 {@code cabinet_type})。 */ + public Builder cabinetType(String v) { + this.cabinetType = v; + return this; + } + + /** 柜号(信仓 {@code cabinet_no})。 */ + public Builder cabinetNo(String v) { + this.cabinetNo = v; + return this; + } + + /** 预计发货时间(信仓 {@code rfc_etd})。 */ + public Builder estimatedShipAt(Instant v) { + this.estimatedShipAt = v; + return this; + } + + /** 实际发货时间(信仓 {@code etd})。 */ + public Builder shippedAt(Instant v) { + this.shippedAt = v; + return this; + } + + /** 是否超 120cm(信仓 {@code is_oversize})。 */ + public Builder isOversize(String v) { + this.isOversize = v; + return this; + } + + /** 超尺寸备注(信仓 {@code oversize_val})。 */ + public Builder oversizeNote(String v) { + this.oversizeNote = v; + return this; + } + + /** 发货需求(信仓 {@code delivery_requirements})。 */ + public Builder deliveryRequirements(String v) { + this.deliveryRequirements = v; + return this; + } + + /** 预报时间(信仓 {@code forecast_time})。 */ + public Builder forecastAt(Instant v) { + this.forecastAt = v; + return this; + } + + /** 参考 SKU 种类数(信仓 {@code rfc_sku_count})。 */ + public Builder referenceSkuCount(Integer v) { + this.referenceSkuCount = v; + return this; + } + + /** 预报托盘数(信仓 {@code forecast_pallet_qty})。 */ + public Builder forecastPalletQty(Integer v) { + this.forecastPalletQty = v; + return this; + } + + /** 实收托盘数(信仓 {@code receive_pallet_qty})。 */ + public Builder receivedPalletQty(Integer v) { + this.receivedPalletQty = v; + return this; + } + + /** 上架托盘数(信仓 {@code shelf_pallet_qty})。 */ + public Builder storedPalletQty(Integer v) { + this.storedPalletQty = v; + return this; + } + + /** 计费托盘数(信仓 {@code bill_pallet_qty})。 */ + public Builder billedPalletQty(Integer v) { + this.billedPalletQty = v; + return this; + } + + /** 卸柜清点时间(信仓 {@code unlade_time})。 */ + public Builder unladeAt(Instant v) { + this.unladeAt = v; + return this; + } + + /** 清点完成时间(信仓 {@code check_time})。 */ + public Builder checkedAt(Instant v) { + this.checkedAt = v; + return this; + } + + /** 上架时间(信仓 {@code putaway_time})。 */ + public Builder putawayAt(Instant v) { + this.putawayAt = v; + return this; + } + + /** 还柜时间(信仓 {@code leave_time})。 */ + public Builder leftAt(Instant v) { + this.leftAt = v; + return this; + } + + /** 是否需要内箱贴(信仓 {@code is_inner_box_sticker})。 */ + public Builder isInnerBoxSticker(String v) { + this.isInnerBoxSticker = v; + return this; + } + + /** 是否需要外箱贴(信仓 {@code is_outer_box_sticker})。 */ + public Builder isOuterBoxSticker(String v) { + this.isOuterBoxSticker = v; + return this; + } + + /** 其他需求(信仓 {@code other_need})。 */ + public Builder otherNeed(String v) { + this.otherNeed = v; + return this; + } + + /** 最后修改时间(信仓 {@code gmt_modify})。 */ + public Builder modifiedAt(Instant v) { + this.modifiedAt = v; + return this; + } + public InboundOrder build() { return new InboundOrder(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java index 5e22717..7b00770 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrderLine.java @@ -23,6 +23,25 @@ public final class InboundOrderLine { /** 最近上架时间(备货完成时间)。 */ private final Instant receivedAt; + // ==================== 仓方原始字段(信仓预报详情提供)==================== + + /** 产品名;信仓 {@code product_name}。 */ + private final String productName; + /** 中文名;信仓 {@code chn_name}。 */ + private final String productNameCn; + /** + * 清点箱数;信仓 {@code check_box_qty}。 + * + *

与 {@link #packedQuantity()}(预报箱数)不同:这个是仓方清点后实际确认的箱数。

+ */ + private final int checkedBoxCount; + /** 打托件数;信仓 {@code pallet_sku_count}。 */ + private final int palletizedQuantity; + /** 装箱率;信仓 {@code packing_rate}。 */ + private final String packingRate; + /** 体积(立方厘米);信仓 {@code volume_cm}。 */ + private final String volumeCm; + private InboundOrderLine(Builder b) { this.providerSku = require(b.providerSku, "providerSku"); this.plannedQuantity = b.plannedQuantity; @@ -31,6 +50,12 @@ public final class InboundOrderLine { this.receivedSaleableQuantity = b.receivedSaleableQuantity; this.receivedUnsaleableQuantity = b.receivedUnsaleableQuantity; this.receivedAt = b.receivedAt; + this.productName = b.productName; + this.productNameCn = b.productNameCn; + this.checkedBoxCount = b.checkedBoxCount; + this.palletizedQuantity = b.palletizedQuantity; + this.packingRate = b.packingRate; + this.volumeCm = b.volumeCm; } public static Builder builder() { @@ -65,6 +90,36 @@ public final class InboundOrderLine { return receivedAt; } + /** 产品名。 */ + public String productName() { + return productName; + } + + /** 中文名。 */ + public String productNameCn() { + return productNameCn; + } + + /** 清点箱数;与 {@link #packedQuantity()}(预报箱数)不同。 */ + public int checkedBoxCount() { + return checkedBoxCount; + } + + /** 打托件数。 */ + public int palletizedQuantity() { + return palletizedQuantity; + } + + /** 装箱率(仓方原值)。 */ + public String packingRate() { + return packingRate; + } + + /** 体积(立方厘米,仓方原值)。 */ + public String volumeCm() { + return volumeCm; + } + /** 实收与计划是否一致;不一致说明短少或溢装,需要人工核对。 */ public boolean quantityMatchesPlan() { return receivedQuantity == plannedQuantity; @@ -85,6 +140,12 @@ public final class InboundOrderLine { private int receivedSaleableQuantity; private int receivedUnsaleableQuantity; private Instant receivedAt; + private String productName; + private String productNameCn; + private int checkedBoxCount; + private int palletizedQuantity; + private String packingRate; + private String volumeCm; public Builder providerSku(String v) { this.providerSku = v; @@ -121,6 +182,42 @@ public final class InboundOrderLine { return this; } + /** 产品名(信仓 {@code product_name})。 */ + public Builder productName(String v) { + this.productName = v; + return this; + } + + /** 中文名(信仓 {@code chn_name})。 */ + public Builder productNameCn(String v) { + this.productNameCn = v; + return this; + } + + /** 清点箱数(信仓 {@code check_box_qty})。 */ + public Builder checkedBoxCount(int v) { + this.checkedBoxCount = v; + return this; + } + + /** 打托件数(信仓 {@code pallet_sku_count})。 */ + public Builder palletizedQuantity(int v) { + this.palletizedQuantity = v; + return this; + } + + /** 装箱率(信仓 {@code packing_rate})。 */ + public Builder packingRate(String v) { + this.packingRate = v; + return this; + } + + /** 体积(信仓 {@code volume_cm})。 */ + public Builder volumeCm(String v) { + this.volumeCm = v; + return this; + } + public InboundOrderLine build() { return new InboundOrderLine(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java index a53cbc5..1d74310 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventoryQuery.java @@ -15,6 +15,13 @@ public final class InventoryQuery { private final Instant updatedAfter; private final int pageSize; private final String cursor; + /** + * 是否包含零库存的 SKU;null 表示不传,由仓方按默认处理。 + * + *

部分仓(信仓 {@code is_show_zero})默认只返回库存大于 0 的数据; + * 需要做全量对账时显式传 {@code true}。不支持的仓忽略该字段。

+ */ + private final Boolean includeZeroStock; private InventoryQuery(Builder b) { this.providerSkus = Collections.unmodifiableList(new ArrayList(b.providerSkus)); @@ -23,6 +30,7 @@ public final class InventoryQuery { this.updatedAfter = b.updatedAfter; this.pageSize = b.pageSize; this.cursor = b.cursor; + this.includeZeroStock = b.includeZeroStock; } public static Builder builder() { @@ -56,6 +64,11 @@ public final class InventoryQuery { return cursor; } + /** 是否包含零库存 SKU;null 表示不传。 */ + public Boolean includeZeroStock() { + return includeZeroStock; + } + public static final class Builder { private final List providerSkus = new ArrayList(); private final List warehouseCodes = new ArrayList(); @@ -63,6 +76,7 @@ public final class InventoryQuery { private Instant updatedAfter; private int pageSize = 100; private String cursor; + private Boolean includeZeroStock; public Builder sku(String sku) { if (sku != null) { @@ -113,6 +127,16 @@ public final class InventoryQuery { return this; } + /** + * 是否包含零库存 SKU;null 表示不传(仓方默认)。 + * + *

信仓对应 {@code is_show_zero}:默认只返回库存大于 0 的产品。

+ */ + public Builder includeZeroStock(Boolean v) { + this.includeZeroStock = v; + return this; + } + public InventoryQuery build() { return new InventoryQuery(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java index 15fde17..d9dd244 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java @@ -67,6 +67,16 @@ public final class OutboundCommand { /** 是否 SFP(Seller Fulfilled Prime);null 表示不传,由仓按默认否处理。 */ private final Boolean sfp; + // ==================== 仓方原始字段(下单时用)==================== + + /** + * 是否需要签名签收;null 表示不传,由仓方按默认处理。 + * + *

信仓 {@code is_sign}({@code "1"} / {@code "0"})。适配器不会替你猜: + * 不传就不发,仓方默认值与业务要求未必一致。

+ */ + private final Boolean signatureRequired; + private OutboundCommand(Builder b) { if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) { throw new IllegalArgumentException("outboundRequestNo must not be blank"); @@ -96,6 +106,7 @@ public final class OutboundCommand { this.labelContentBase64 = b.labelContentBase64; this.shopName = b.shopName; this.sfp = b.sfp; + this.signatureRequired = b.signatureRequired; } public static Builder builder() { @@ -207,6 +218,11 @@ public final class OutboundCommand { return sfp; } + /** 是否需要签名签收;null 表示不传(信仓 {@code is_sign})。 */ + public Boolean signatureRequired() { + return signatureRequired; + } + public static final class Builder { private String outboundRequestNo; @@ -230,6 +246,7 @@ public final class OutboundCommand { private String labelContentBase64; private String shopName; private Boolean sfp; + private Boolean signatureRequired; public Builder outboundRequestNo(String outboundRequestNo) { this.outboundRequestNo = outboundRequestNo; @@ -353,6 +370,12 @@ public final class OutboundCommand { return this; } + /** 是否需要签名签收;null 表示不传(信仓 {@code is_sign})。 */ + public Builder signatureRequired(Boolean v) { + this.signatureRequired = v; + return this; + } + public OutboundCommand build() { return new OutboundCommand(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java index 73da5c3..57de083 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java @@ -99,6 +99,66 @@ public final class OutboundOrder { */ private final String thirdPartyAccount; + // ==================== 仓方原始字段(部分是某家仓特有,见每项说明)==================== + + /** 仓方内部订单 id;信仓 {@code id}。其他仓未提供时为 null。 */ + private final String providerId; + /** 仓方状态原文(可读名);信仓 {@code state_name},如「已发货」。其他仓未提供时为 null。 */ + private final String rawStatusName; + /** + * 物流面单下载地址。 + * + *

信仓 {@code face_url}(OSS 签名 URL,有时效);运去哪通过 packages 返回。可能为 null。

+ */ + private final String labelUrl; + /** 店铺名;信仓 {@code shop_name},如 {@code XC001-shop}。其他仓未提供时为 null。 */ + private final String shopName; + /** 订单件数合计;信仓 {@code sku_count}。其他仓未提供时为 null。 */ + private final Integer skuCount; + /** 产品 SKU(单件订单的便捷字段);信仓 {@code product_sku}。多件订单请看 {@link #lines()}。 */ + private final String productSku; + /** 产品名(单件订单的便捷字段);信仓 {@code product_name}。 */ + private final String productName; + /** 来源 SKU;信仓 {@code source_sku}。与 {@link #productSku()} 在信仓通常相同。 */ + private final String sourceSku; + /** 仓方内部仓库 id;信仓 {@code warehouse_id}。与 {@link #warehouseCode()}(仓代码)不同。 */ + private final String providerWarehouseId; + /** 是否需要签名签收;信仓 {@code is_sign}({@code "1"} / {@code "0"})。 */ + private final String isSign; + /** 计费分区;信仓 {@code zone},承运商分区号。 */ + private final String zone; + /** 包裹长(英寸,仓方原值);信仓 {@code dim_length}。 */ + private final String dimLength; + /** 包裹宽(英寸,仓方原值);信仓 {@code dim_width}。 */ + private final String dimWidth; + /** 包裹高(英寸,仓方原值);信仓 {@code dim_height}。 */ + private final String dimHeight; + /** 计抛系数;信仓 {@code dim_divisor}。 */ + private final String dimDivisor; + /** 实重(磅,字符串原值);信仓 {@code weight_lbs}。 */ + private final String weightLbs; + /** 计费重(磅,字符串原值);信仓 {@code billing_weight_lbs}。 */ + private final String billingWeightLbs; + /** 体积重(磅,字符串原值);信仓 {@code volume_weight_lbs}。 */ + private final String volumeWeightLbs; + /** + * 订单总费用(仓方原值字符串)。 + * + *

信仓 {@code total_amount}:总费用,含运费与操作费等,不等于 + * {@link #estimatedShippingFee()}(预估运费)。两者不互相覆盖。

+ */ + private final Money totalAmount; + /** 修复 / 补收金额;信仓 {@code repair_amount}。 */ + private final Money repairAmount; + /** 审核时间(UTC);信仓 {@code approve_time}。 */ + private final Instant approvedAt; + /** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */ + private final Instant modifiedAt; + /** 取消时间(UTC);信仓 {@code gmt_cancel},未取消为 null。 */ + private final Instant cancelledAt; + /** 截单时间(UTC);信仓 {@code intercept_time}。 */ + private final Instant interceptedAt; + private OutboundOrder(Builder b) { this.warehouseCode = requireText(b.warehouseCode, "warehouseCode"); this.outboundRequestNo = requireText(b.outboundRequestNo, "outboundRequestNo"); @@ -127,6 +187,30 @@ public final class OutboundOrder { this.signatureRequired = b.signatureRequired; this.insured = b.insured; this.thirdPartyAccount = b.thirdPartyAccount; + this.providerId = b.providerId; + this.rawStatusName = b.rawStatusName; + this.labelUrl = b.labelUrl; + this.shopName = b.shopName; + this.skuCount = b.skuCount; + this.productSku = b.productSku; + this.productName = b.productName; + this.sourceSku = b.sourceSku; + this.providerWarehouseId = b.providerWarehouseId; + this.isSign = b.isSign; + this.zone = b.zone; + this.dimLength = b.dimLength; + this.dimWidth = b.dimWidth; + this.dimHeight = b.dimHeight; + this.dimDivisor = b.dimDivisor; + this.weightLbs = b.weightLbs; + this.billingWeightLbs = b.billingWeightLbs; + this.volumeWeightLbs = b.volumeWeightLbs; + this.totalAmount = b.totalAmount; + this.repairAmount = b.repairAmount; + this.approvedAt = b.approvedAt; + this.modifiedAt = b.modifiedAt; + this.cancelledAt = b.cancelledAt; + this.interceptedAt = b.interceptedAt; } public static Builder builder() { @@ -241,6 +325,126 @@ public final class OutboundOrder { return thirdPartyAccount; } + /** 仓方内部订单 id。 */ + public String providerId() { + return providerId; + } + + /** 仓方状态原文(可读名)。 */ + public String rawStatusName() { + return rawStatusName; + } + + /** 物流面单下载地址;可能为 null。 */ + public String labelUrl() { + return labelUrl; + } + + /** 店铺名。 */ + public String shopName() { + return shopName; + } + + /** 订单件数合计。 */ + public Integer skuCount() { + return skuCount; + } + + /** 单件订单的便捷字段:产品 SKU。 */ + public String productSku() { + return productSku; + } + + /** 单件订单的便捷字段:产品名。 */ + public String productName() { + return productName; + } + + /** 来源 SKU。 */ + public String sourceSku() { + return sourceSku; + } + + /** 仓方内部仓库 id。 */ + public String providerWarehouseId() { + return providerWarehouseId; + } + + /** 是否需要签名签收(仓方原值)。 */ + public String isSign() { + return isSign; + } + + /** 计费分区。 */ + public String zone() { + return zone; + } + + /** 包裹长(英寸,仓方原值)。 */ + public String dimLength() { + return dimLength; + } + + /** 包裹宽(英寸,仓方原值)。 */ + public String dimWidth() { + return dimWidth; + } + + /** 包裹高(英寸,仓方原值)。 */ + public String dimHeight() { + return dimHeight; + } + + /** 计抛系数。 */ + public String dimDivisor() { + return dimDivisor; + } + + /** 实重(磅,仓方原值)。 */ + public String weightLbs() { + return weightLbs; + } + + /** 计费重(磅,仓方原值)。 */ + public String billingWeightLbs() { + return billingWeightLbs; + } + + /** 体积重(磅,仓方原值)。 */ + public String volumeWeightLbs() { + return volumeWeightLbs; + } + + /** 订单总费用;与 {@link #estimatedShippingFee()} 不同,不要互相覆盖。 */ + public Money totalAmount() { + return totalAmount; + } + + /** 修复 / 补收金额。 */ + public Money repairAmount() { + return repairAmount; + } + + /** 审核时间(UTC)。 */ + public Instant approvedAt() { + return approvedAt; + } + + /** 最后修改时间(UTC)。 */ + public Instant modifiedAt() { + return modifiedAt; + } + + /** 取消时间(UTC);未取消为 null。 */ + public Instant cancelledAt() { + return cancelledAt; + } + + /** 截单时间(UTC)。 */ + public Instant interceptedAt() { + return interceptedAt; + } + /** 是否带仓方异常。 */ public boolean hasException() { return exceptionCode != null && !exceptionCode.trim().isEmpty(); @@ -274,6 +478,30 @@ public final class OutboundOrder { private Instant paidAt; private String carrierCode; private String currency; + private String providerId; + private String rawStatusName; + private String labelUrl; + private String shopName; + private Integer skuCount; + private String productSku; + private String productName; + private String sourceSku; + private String providerWarehouseId; + private String isSign; + private String zone; + private String dimLength; + private String dimWidth; + private String dimHeight; + private String dimDivisor; + private String weightLbs; + private String billingWeightLbs; + private String volumeWeightLbs; + private Money totalAmount; + private Money repairAmount; + private Instant approvedAt; + private Instant modifiedAt; + private Instant cancelledAt; + private Instant interceptedAt; private List attachments = new ArrayList(); private List serialNumbers = new ArrayList(); private Boolean signatureRequired; @@ -400,6 +628,150 @@ public final class OutboundOrder { return this; } + /** 仓方内部订单 id(信仓 {@code id})。 */ + public Builder providerId(String v) { + this.providerId = v; + return this; + } + + /** 仓方状态原文(信仓 {@code state_name})。 */ + public Builder rawStatusName(String v) { + this.rawStatusName = v; + return this; + } + + /** 物流面单下载地址(信仓 {@code face_url})。 */ + public Builder labelUrl(String v) { + this.labelUrl = v; + return this; + } + + /** 店铺名(信仓 {@code shop_name})。 */ + public Builder shopName(String v) { + this.shopName = v; + return this; + } + + /** 订单件数合计(信仓 {@code sku_count})。 */ + public Builder skuCount(Integer v) { + this.skuCount = v; + return this; + } + + /** 单件订单的产品 SKU(信仓 {@code product_sku})。 */ + public Builder productSku(String v) { + this.productSku = v; + return this; + } + + /** 单件订单的产品名(信仓 {@code product_name})。 */ + public Builder productName(String v) { + this.productName = v; + return this; + } + + /** 来源 SKU(信仓 {@code source_sku})。 */ + public Builder sourceSku(String v) { + this.sourceSku = v; + return this; + } + + /** 仓方内部仓库 id(信仓 {@code warehouse_id})。 */ + public Builder providerWarehouseId(String v) { + this.providerWarehouseId = v; + return this; + } + + /** 是否需要签名签收(信仓 {@code is_sign})。 */ + public Builder isSign(String v) { + this.isSign = v; + return this; + } + + /** 计费分区(信仓 {@code zone})。 */ + public Builder zone(String v) { + this.zone = v; + return this; + } + + /** 包裹长(信仓 {@code dim_length})。 */ + public Builder dimLength(String v) { + this.dimLength = v; + return this; + } + + /** 包裹宽(信仓 {@code dim_width})。 */ + public Builder dimWidth(String v) { + this.dimWidth = v; + return this; + } + + /** 包裹高(信仓 {@code dim_height})。 */ + public Builder dimHeight(String v) { + this.dimHeight = v; + return this; + } + + /** 计抛系数(信仓 {@code dim_divisor})。 */ + public Builder dimDivisor(String v) { + this.dimDivisor = v; + return this; + } + + /** 实重(信仓 {@code weight_lbs})。 */ + public Builder weightLbs(String v) { + this.weightLbs = v; + return this; + } + + /** 计费重(信仓 {@code billing_weight_lbs})。 */ + public Builder billingWeightLbs(String v) { + this.billingWeightLbs = v; + return this; + } + + /** 体积重(信仓 {@code volume_weight_lbs})。 */ + public Builder volumeWeightLbs(String v) { + this.volumeWeightLbs = v; + return this; + } + + /** 订单总费用(信仓 {@code total_amount})。 */ + public Builder totalAmount(Money v) { + this.totalAmount = v; + return this; + } + + /** 修复 / 补收金额(信仓 {@code repair_amount})。 */ + public Builder repairAmount(Money v) { + this.repairAmount = v; + return this; + } + + /** 审核时间(信仓 {@code approve_time})。 */ + public Builder approvedAt(Instant v) { + this.approvedAt = v; + return this; + } + + /** 最后修改时间(信仓 {@code gmt_modify})。 */ + public Builder modifiedAt(Instant v) { + this.modifiedAt = v; + return this; + } + + /** 取消时间(信仓 {@code gmt_cancel})。 */ + public Builder cancelledAt(Instant v) { + this.cancelledAt = v; + return this; + } + + /** 截单时间(信仓 {@code intercept_time})。 */ + public Builder interceptedAt(Instant v) { + this.interceptedAt = v; + return this; + } + public OutboundOrder build() { return new OutboundOrder(this); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java index bcfa8a5..e73aca8 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java @@ -8,6 +8,9 @@ import java.util.List; * 调拨单创建命令。写操作,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。 * *

运去哪对 {@code sourceNo} 有唯一约束,查询与取消都靠它,所以它同时是业务主键。

+ * + *

构造期只校验跨仓共识的必填项;某一家仓特有的必填项(运去哪的日期与收货地址、 + * 信仓的转运类型 / 方式 / 是否打托)由各适配器在拼报文时校验。

*/ public final class TransferCommand { @@ -29,7 +32,7 @@ public final class TransferCommand { private final String removeOrderId; /** 目的地地址 code(FBA 地址 code)。 */ private final String receiveStore; - /** 目的地地址;{@code TransferType.OUTBOUND} 时构造期必填。 */ + /** 目的地地址;调拨出库时部分仓必填(运去哪),必填性由适配器校验。 */ private final ShipTo shipTo; private final String remark; /** 增值服务:1 贴产品标 / 2 贴箱标 / 3 贴托盘标。 */ @@ -101,11 +104,10 @@ public final class TransferCommand { this.inventoryType = b.inventoryType; this.carrierType = b.carrierType; this.transportationType = b.transportationType; - if (b.estimateOutboundDate == null || b.estimateInboundDate == null) { - throw new IllegalArgumentException( - "estimateOutboundDate and estimateInboundDate are required"); - } - if (b.estimateInboundDate.isBefore(b.estimateOutboundDate)) { + // 日期必填是运去哪的要求,信仓转运只需要发货日期(pre_send_time)。 + // 必填性与先后顺序由各适配器校验;这里只保证「给了两个才比较先后」的自洽。 + if (b.estimateOutboundDate != null && b.estimateInboundDate != null + && b.estimateInboundDate.isBefore(b.estimateOutboundDate)) { throw new IllegalArgumentException( "estimateInboundDate must not be earlier than estimateOutboundDate"); } @@ -115,10 +117,8 @@ public final class TransferCommand { this.removeOrderId = b.removeOrderId; this.receiveStore = b.receiveStore; this.shipTo = b.shipTo; - // 调拨出库必须给收货地址;仓到仓由仓自己处理 - if (type == TransferType.OUTBOUND && shipTo == null) { - throw new IllegalArgumentException("shipTo is required when transfer type is OUTBOUND"); - } + // 收货地址在调拨出库时是否必填由各仓协议决定: + // 运去哪要求 shipTo;信仓用 other_warehouse(仓库名)代替,见对应适配器。 this.remark = b.remark; this.serviceTypes = java.util.Collections.unmodifiableList( new java.util.ArrayList(b.serviceTypes)); diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java index c03fe41..755c665 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java @@ -1,10 +1,12 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.enums.TransferStatus; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.enums.TransferType; import java.time.Instant; +import java.util.List; /** * 调拨单(查询 / 创建结果)。 @@ -59,6 +61,66 @@ public final class TransferOrder { /** 仓方异常原因;无异常时为 null。 */ private final String errorReason; + // ==================== 仓方原始字段(信仓转运详情提供)==================== + + /** 仓方内部转运单 id;信仓 {@code id}。 */ + private final String providerId; + /** 采购 / 调拨单号;信仓 {@code po}。{@link #transferRequestNo()} 是来源单号,两者不同。 */ + private final String po; + /** 客户 id;信仓 {@code customer_id}。 */ + private final String customerId; + /** 客户代码;信仓 {@code customer_no}。 */ + private final String customerNo; + /** 发货仓 id(仓方内部);信仓 {@code from_warehouse},与 {@link #fromWarehouseCode()}(仓代码)不同。 */ + private final String fromWarehouseId; + /** 目的仓 id(仓方内部);信仓 {@code dest_warehouse}。 */ + private final String destWarehouseId; + /** 仓方状态原文(可读名);信仓 {@code state_name},如「待审核」。 */ + private final String rawStatusName; + /** 转运类型(仓方字典值);信仓 {@code delivery_mode},取值见「转运类型」字典接口。 */ + private final String deliveryMode; + /** 转运方式 / 配送方式(仓方字典值);信仓 {@code delivery_way}。 */ + private final String deliveryWay; + /** + * 订单类型(仓方字典值);信仓 {@code order_type}。 + * + *

注意与下单接口的 {@code order_type}(common / wayfair)语义不同, + * 这里取的是「订单类型」字典(FBA / LTL 等)。

+ */ + private final String orderType; + /** 目的仓不在字典里时的自填仓库名;信仓 {@code other_warehouse}。 */ + private final String otherWarehouse; + /** 标签需求(仓方原值,逗号分隔);信仓 {@code label_requirement},如「产品贴,外箱标签」。 */ + private final String labelRequirement; + /** 是否需要产品贴;信仓 {@code is_product_label}({@code "1"} / {@code "0"})。 */ + private final String isProductLabel; + /** 是否需要外箱贴;信仓 {@code is_ctn_label}。 */ + private final String isCtnLabel; + /** 是否需要托盘贴;信仓 {@code is_pallet_label}。 */ + private final String isPalletLabel; + /** 是否打托(仓方原值);信仓 {@code is_pallet}。 */ + private final String isPallet; + /** 拣货开始时间(UTC);信仓 {@code picking_time}。 */ + private final Instant pickingStartedAt; + /** 拣货结束时间(UTC);信仓 {@code picked_time}。 */ + private final Instant pickedAt; + /** 打托时间(UTC);信仓 {@code palleted_time}。 */ + private final Instant palletizedAt; + /** 发货时间(UTC);信仓 {@code send_time}。 */ + private final Instant sentAt; + /** 审核时间(UTC);信仓 {@code approve_time}。 */ + private final Instant approvedAt; + /** 仓方运输 / 发货单 id;信仓 {@code shipping_id}。 */ + private final String shippingId; + /** 订单总费用(仓方原值);信仓 {@code total_amount}。 */ + private final Money totalAmount; + /** 创建时间(UTC);信仓 {@code gmt_create}。 */ + private final Instant createdAt; + /** 最后修改时间(UTC);信仓 {@code gmt_modify}。 */ + private final Instant modifiedAt; + /** 商品明细;查询详情时回填,创建返回时通常为空。 */ + private final List lines; + private TransferOrder(Builder b) { this.transferRequestNo = require(b.transferRequestNo, "transferRequestNo"); this.providerTransferNo = b.providerTransferNo; @@ -80,6 +142,33 @@ public final class TransferOrder { this.totalVolumeCbm = b.totalVolumeCbm; this.errorCode = b.errorCode; this.errorReason = b.errorReason; + this.providerId = b.providerId; + this.po = b.po; + this.customerId = b.customerId; + this.customerNo = b.customerNo; + this.fromWarehouseId = b.fromWarehouseId; + this.destWarehouseId = b.destWarehouseId; + this.rawStatusName = b.rawStatusName; + this.deliveryMode = b.deliveryMode; + this.deliveryWay = b.deliveryWay; + this.orderType = b.orderType; + this.otherWarehouse = b.otherWarehouse; + this.labelRequirement = b.labelRequirement; + this.isProductLabel = b.isProductLabel; + this.isCtnLabel = b.isCtnLabel; + this.isPalletLabel = b.isPalletLabel; + this.isPallet = b.isPallet; + this.pickingStartedAt = b.pickingStartedAt; + this.pickedAt = b.pickedAt; + this.palletizedAt = b.palletizedAt; + this.sentAt = b.sentAt; + this.approvedAt = b.approvedAt; + this.shippingId = b.shippingId; + this.totalAmount = b.totalAmount; + this.createdAt = b.createdAt; + this.modifiedAt = b.modifiedAt; + this.lines = b.lines == null ? java.util.Collections.emptyList() + : java.util.Collections.unmodifiableList(new java.util.ArrayList(b.lines)); } public static Builder builder() { @@ -187,6 +276,305 @@ public final class TransferOrder { return sourceProvider; } + /** 仓方内部转运单 id。 */ + public String providerId() { + return providerId; + } + + /** 采购 / 调拨单号;与 {@link #transferRequestNo()} 不是一回事。 */ + public String po() { + return po; + } + + /** 客户 id。 */ + public String customerId() { + return customerId; + } + + /** 客户代码。 */ + public String customerNo() { + return customerNo; + } + + /** 发货仓 id(仓方内部)。 */ + public String fromWarehouseId() { + return fromWarehouseId; + } + + /** 目的仓 id(仓方内部)。 */ + public String destWarehouseId() { + return destWarehouseId; + } + + /** 仓方状态原文(可读名)。 */ + public String rawStatusName() { + return rawStatusName; + } + + /** 转运类型(仓方字典值)。 */ + public String deliveryMode() { + return deliveryMode; + } + + /** 转运方式 / 配送方式(仓方字典值)。 */ + public String deliveryWay() { + return deliveryWay; + } + + /** 订单类型(仓方字典值,FBA / LTL 等);与下单接口的 common / wayfair 无关。 */ + public String orderType() { + return orderType; + } + + /** 目的仓不在字典里时的自填仓库名。 */ + public String otherWarehouse() { + return otherWarehouse; + } + + /** 标签需求(仓方原值,逗号分隔)。 */ + public String labelRequirement() { + return labelRequirement; + } + + /** 是否需要产品贴(仓方原值)。 */ + public String isProductLabel() { + return isProductLabel; + } + + /** 是否需要外箱贴(仓方原值)。 */ + public String isCtnLabel() { + return isCtnLabel; + } + + /** 是否需要托盘贴(仓方原值)。 */ + public String isPalletLabel() { + return isPalletLabel; + } + + /** 是否打托(仓方原值)。 */ + public String isPallet() { + return isPallet; + } + + /** 拣货开始时间(UTC)。 */ + public Instant pickingStartedAt() { + return pickingStartedAt; + } + + /** 拣货结束时间(UTC)。 */ + public Instant pickedAt() { + return pickedAt; + } + + /** 打托时间(UTC)。 */ + public Instant palletizedAt() { + return palletizedAt; + } + + /** 发货时间(UTC)。 */ + public Instant sentAt() { + return sentAt; + } + + /** 审核时间(UTC)。 */ + public Instant approvedAt() { + return approvedAt; + } + + /** 仓方运输 / 发货单 id。 */ + public String shippingId() { + return shippingId; + } + + /** 订单总费用。 */ + public Money totalAmount() { + return totalAmount; + } + + /** 创建时间(UTC)。 */ + public Instant createdAt() { + return createdAt; + } + + /** 最后修改时间(UTC)。 */ + public Instant modifiedAt() { + return modifiedAt; + } + + /** 商品明细;未查询详情时为空列表。 */ + public List lines() { + return lines; + } + + /** + * 转运商品明细(查询详情时回填)。 + * + *

数量分三层:预报件数、清点箱数、上架件数。对账时要一起看。

+ */ + public static final class TransferLine { + + /** 产品 SKU;信仓 {@code product_no}。 */ + private final String providerSku; + /** 产品名;信仓 {@code product_name}。 */ + private final String productName; + /** 中文名;信仓 {@code chn_name}。 */ + private final String productNameCn; + /** 预报件数;信仓 {@code sku_count}。 */ + private final int plannedQuantity; + /** 预报箱数;信仓 {@code box_count}。 */ + private final int boxCount; + /** 清点箱数;信仓 {@code check_box_qty}。 */ + private final int checkedBoxCount; + /** 打托件数;信仓 {@code pallet_sku_count}。 */ + private final int palletizedQuantity; + /** 上架件数;信仓 {@code put_on_sku_count}。 */ + private final int storedQuantity; + /** 装箱率;信仓 {@code packing_rate}。 */ + private final String packingRate; + /** 备注;信仓 {@code remark}。 */ + private final String remark; + + private TransferLine(Builder b) { + this.providerSku = require(b.providerSku, "providerSku"); + this.productName = b.productName; + this.productNameCn = b.productNameCn; + this.plannedQuantity = b.plannedQuantity; + this.boxCount = b.boxCount; + this.checkedBoxCount = b.checkedBoxCount; + this.palletizedQuantity = b.palletizedQuantity; + this.storedQuantity = b.storedQuantity; + this.packingRate = b.packingRate; + this.remark = b.remark; + } + + public static Builder builder() { + return new Builder(); + } + + public String providerSku() { + return providerSku; + } + + public String productName() { + return productName; + } + + public String productNameCn() { + return productNameCn; + } + + /** 预报件数。 */ + public int plannedQuantity() { + return plannedQuantity; + } + + /** 预报箱数。 */ + public int boxCount() { + return boxCount; + } + + /** 清点箱数。 */ + public int checkedBoxCount() { + return checkedBoxCount; + } + + /** 打托件数。 */ + public int palletizedQuantity() { + return palletizedQuantity; + } + + /** 上架件数。 */ + public int storedQuantity() { + return storedQuantity; + } + + /** 装箱率(仓方原值)。 */ + public String packingRate() { + return packingRate; + } + + public String remark() { + return remark; + } + + public static final class Builder { + private String providerSku; + private String productName; + private String productNameCn; + private int plannedQuantity; + private int boxCount; + private int checkedBoxCount; + private int palletizedQuantity; + private int storedQuantity; + private String packingRate; + private String remark; + + /** 产品 SKU(信仓 {@code product_no});必填。 */ + public Builder providerSku(String v) { + this.providerSku = v; + return this; + } + + /** 产品名(信仓 {@code product_name})。 */ + public Builder productName(String v) { + this.productName = v; + return this; + } + + /** 中文名(信仓 {@code chn_name})。 */ + public Builder productNameCn(String v) { + this.productNameCn = v; + return this; + } + + /** 预报件数(信仓 {@code sku_count})。 */ + public Builder plannedQuantity(int v) { + this.plannedQuantity = v; + return this; + } + + /** 预报箱数(信仓 {@code box_count})。 */ + public Builder boxCount(int v) { + this.boxCount = v; + return this; + } + + /** 清点箱数(信仓 {@code check_box_qty})。 */ + public Builder checkedBoxCount(int v) { + this.checkedBoxCount = v; + return this; + } + + /** 打托件数(信仓 {@code pallet_sku_count})。 */ + public Builder palletizedQuantity(int v) { + this.palletizedQuantity = v; + return this; + } + + /** 上架件数(信仓 {@code put_on_sku_count})。 */ + public Builder storedQuantity(int v) { + this.storedQuantity = v; + return this; + } + + /** 装箱率(信仓 {@code packing_rate})。 */ + public Builder packingRate(String v) { + this.packingRate = v; + return this; + } + + /** 备注(信仓 {@code remark})。 */ + public Builder remark(String v) { + this.remark = v; + return this; + } + + public TransferLine build() { + return new TransferLine(this); + } + } + } + private static String require(String v, String n) { if (v == null || v.trim().isEmpty()) { throw new IllegalArgumentException(n + " must not be blank"); @@ -215,6 +603,32 @@ public final class TransferOrder { private Double totalVolumeCbm; private String errorCode; private String errorReason; + private String providerId; + private String po; + private String customerId; + private String customerNo; + private String fromWarehouseId; + private String destWarehouseId; + private String rawStatusName; + private String deliveryMode; + private String deliveryWay; + private String orderType; + private String otherWarehouse; + private String labelRequirement; + private String isProductLabel; + private String isCtnLabel; + private String isPalletLabel; + private String isPallet; + private Instant pickingStartedAt; + private Instant pickedAt; + private Instant palletizedAt; + private Instant sentAt; + private Instant approvedAt; + private String shippingId; + private Money totalAmount; + private Instant createdAt; + private Instant modifiedAt; + private List lines; public Builder transferRequestNo(String v) { this.transferRequestNo = v; @@ -316,6 +730,171 @@ public final class TransferOrder { return this; } + /** 仓方内部转运单 id(信仓 {@code id})。 */ + public Builder providerId(String v) { + this.providerId = v; + return this; + } + + /** 采购 / 调拨单号(信仓 {@code po})。 */ + public Builder po(String v) { + this.po = v; + return this; + } + + /** 客户 id(信仓 {@code customer_id})。 */ + public Builder customerId(String v) { + this.customerId = v; + return this; + } + + /** 客户代码(信仓 {@code customer_no})。 */ + public Builder customerNo(String v) { + this.customerNo = v; + return this; + } + + /** 发货仓 id(信仓 {@code from_warehouse})。 */ + public Builder fromWarehouseId(String v) { + this.fromWarehouseId = v; + return this; + } + + /** 目的仓 id(信仓 {@code dest_warehouse})。 */ + public Builder destWarehouseId(String v) { + this.destWarehouseId = v; + return this; + } + + /** 仓方状态原文(信仓 {@code state_name})。 */ + public Builder rawStatusName(String v) { + this.rawStatusName = v; + return this; + } + + /** 转运类型(信仓 {@code delivery_mode})。 */ + public Builder deliveryMode(String v) { + this.deliveryMode = v; + return this; + } + + /** 转运方式 / 配送方式(信仓 {@code delivery_way})。 */ + public Builder deliveryWay(String v) { + this.deliveryWay = v; + return this; + } + + /** 订单类型(信仓 {@code order_type})。 */ + public Builder orderType(String v) { + this.orderType = v; + return this; + } + + /** 目的仓不在字典里时的自填仓库名(信仓 {@code other_warehouse})。 */ + public Builder otherWarehouse(String v) { + this.otherWarehouse = v; + return this; + } + + /** 标签需求(信仓 {@code label_requirement})。 */ + public Builder labelRequirement(String v) { + this.labelRequirement = v; + return this; + } + + /** 是否需要产品贴(信仓 {@code is_product_label})。 */ + public Builder isProductLabel(String v) { + this.isProductLabel = v; + return this; + } + + /** 是否需要外箱贴(信仓 {@code is_ctn_label})。 */ + public Builder isCtnLabel(String v) { + this.isCtnLabel = v; + return this; + } + + /** 是否需要托盘贴(信仓 {@code is_pallet_label})。 */ + public Builder isPalletLabel(String v) { + this.isPalletLabel = v; + return this; + } + + /** 是否打托(信仓 {@code is_pallet})。 */ + public Builder isPallet(String v) { + this.isPallet = v; + return this; + } + + /** 拣货开始时间(信仓 {@code picking_time})。 */ + public Builder pickingStartedAt(Instant v) { + this.pickingStartedAt = v; + return this; + } + + /** 拣货结束时间(信仓 {@code picked_time})。 */ + public Builder pickedAt(Instant v) { + this.pickedAt = v; + return this; + } + + /** 打托时间(信仓 {@code palleted_time})。 */ + public Builder palletizedAt(Instant v) { + this.palletizedAt = v; + return this; + } + + /** 发货时间(信仓 {@code send_time})。 */ + public Builder sentAt(Instant v) { + this.sentAt = v; + return this; + } + + /** 审核时间(信仓 {@code approve_time})。 */ + public Builder approvedAt(Instant v) { + this.approvedAt = v; + return this; + } + + /** 仓方运输 / 发货单 id(信仓 {@code shipping_id})。 */ + public Builder shippingId(String v) { + this.shippingId = v; + return this; + } + + /** 订单总费用(信仓 {@code total_amount})。 */ + public Builder totalAmount(Money v) { + this.totalAmount = v; + return this; + } + + /** 创建时间(信仓 {@code gmt_create})。 */ + public Builder createdAt(Instant v) { + this.createdAt = v; + return this; + } + + /** 最后修改时间(信仓 {@code gmt_modify})。 */ + public Builder modifiedAt(Instant v) { + this.modifiedAt = v; + return this; + } + + /** 商品明细(查询详情时回填)。 */ + public Builder lines(List v) { + this.lines = v; + return this; + } + + /** 追加一条商品明细。 */ + public Builder line(TransferLine v) { + if (this.lines == null) { + this.lines = new java.util.ArrayList(); + } + this.lines.add(v); + return this; + } + public TransferOrder build() { return new TransferOrder(this); } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java index c96754f..ff5f0d7 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangForecastMapper.java @@ -50,8 +50,15 @@ public final class XincangForecastMapper { req.rfcEtd = requireDate(cmd.predictionShipDate(), "predictionShipDate (rfc_etd)", ctx); req.rfcEta = requireDate(cmd.estimateArriveDate(), "estimateArriveDate (rfc_eta)", ctx); req.deliveryRequirements = require(cmd.deliveryRequirements(), "deliveryRequirements", ctx); - // 参考 SKU 种类数:没有明细时按行数给,有明细时也按行数(信仓只要求一个估计值) - req.rfcSkuCount = String.valueOf(cmd.lines().size()); + if (cmd.referenceSkuCount() == null && cmd.lines().isEmpty()) { + throw validation(ctx, + "referenceSkuCount is required for xincang forecast (信仓 rfc_sku_count 必填)"); + } + // 参考 SKU 种类数:优先用调用方显式给的值(信仓必填), + // 没有再退回明细行数——建单时明细通常还没有,不能只依赖行数 + req.rfcSkuCount = cmd.referenceSkuCount() != null + ? String.valueOf(cmd.referenceSkuCount()) + : String.valueOf(cmd.lines().size()); req.chnName = blankToNull(cmd.chnName()); req.isOversize = cmd.oversize() == null ? null : (cmd.oversize() ? YES : NO); req.oversizeVal = blankToNull(cmd.oversizeNote()); @@ -72,6 +79,9 @@ public final class XincangForecastMapper { String forecastNo, String productsJson, WarehouseContext ctx) { + if (cmd.lines().isEmpty()) { + throw validation(ctx, "xincang improve_forecast requires at least one product line"); + } XincangDtos.ForecastImproveRequest req = new XincangDtos.ForecastImproveRequest(); req.forecastNo = require(forecastNo, "forecastNo", ctx); req.destWarehouse = require(cmd.warehouseId(), "warehouseId (dest_warehouse)", ctx); @@ -128,11 +138,19 @@ public final class XincangForecastMapper { if (product == null || blank(product.productNo)) { continue; } + // 歧义说明:信仓的 box_count 是「预报箱数」,而统一模型 + // packedQuantity 的语义是「装箱时实际装进去的件数」,两者不是一回事, + // 所以 box_count 不映射到 packedQuantity,只放仓方原始字段。 lines.add(InboundOrderLine.builder() .providerSku(product.productNo.trim()) .plannedQuantity(intOf(product.skuCount)) - .packedQuantity(intOf(product.boxCount)) .receivedQuantity(intOf(product.putOnSkuCount)) + .productName(blankToNull(product.productName)) + .productNameCn(blankToNull(product.chnName)) + .checkedBoxCount(intOf(product.checkBoxQty)) + .palletizedQuantity(intOf(product.palletSkuCount)) + .packingRate(blankToNull(product.packingRate)) + .volumeCm(blankToNull(product.volumeCm)) .build()); } } @@ -150,6 +168,35 @@ public final class XincangForecastMapper { .actualArrivalAt(parseTime(detail.eta)) .remark(blankToNull(detail.remark)) .lines(lines) + // ---- 仓方原始字段 ---- + .providerId(blankToNull(detail.id)) + .chnName(blankToNull(detail.chnName)) + .customerId(blankToNull(detail.customerId)) + .customerNo(blankToNull(detail.customerName)) + .destWarehouseId(blankToNull(detail.destWarehouseId)) + .rawStatusName(blankToNull(detail.stateName)) + .shipmentType(blankToNull(detail.shipmentType)) + .cabinetType(blankToNull(detail.cabinetType)) + .cabinetNo(blankToNull(detail.cabinetNo)) + .estimatedShipAt(parseTime(detail.rfcEtd)) + .shippedAt(parseTime(detail.etd)) + .isOversize(blankToNull(detail.isOversize)) + .oversizeNote(blankToNull(detail.oversizeVal)) + .deliveryRequirements(blankToNull(detail.deliveryRequirements)) + .forecastAt(parseTime(detail.forecastTime)) + .referenceSkuCount(parseInteger(detail.rfcSkuCount)) + .forecastPalletQty(parseInteger(detail.forecastPalletQty)) + .receivedPalletQty(parseInteger(detail.receivePalletQty)) + .storedPalletQty(parseInteger(detail.shelfPalletQty)) + .billedPalletQty(parseInteger(detail.billPalletQty)) + .unladeAt(parseTime(detail.unladeTime)) + .checkedAt(parseTime(detail.checkTime)) + .putawayAt(parseTime(detail.putawayTime)) + .leftAt(parseTime(detail.leaveTime)) + .isInnerBoxSticker(blankToNull(detail.isInnerBoxSticker)) + .isOuterBoxSticker(blankToNull(detail.isOuterBoxSticker)) + .otherNeed(blankToNull(detail.otherNeed)) + .modifiedAt(parseTime(detail.gmtModify)) .build(); } @@ -171,6 +218,11 @@ public final class XincangForecastMapper { return XincangOrderDetailMapper.parseTime(raw); } + /** 整数原值:空值 / 非法返回 null(与 {@link #intOf} 的区别是保留「仓方没给」)。 */ + static Integer parseInteger(String raw) { + return XincangOrderDetailMapper.parseInteger(raw); + } + static int intOf(String raw) { return XincangOrderDetailMapper.parsePositiveInt(raw); } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java index 10c6bd4..d6c54d7 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangInventoryMapper.java @@ -71,6 +71,10 @@ public final class XincangInventoryMapper { } params.put("page", pageNumber(query.cursor())); params.put("limit", pageSize(query.pageSize())); + // 信仓默认只返回库存 > 0 的产品;需要零库存数据时显式传 1 + if (query.includeZeroStock() != null) { + params.put("is_show_zero", query.includeZeroStock() ? 1 : 0); + } return params; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java index 6583e83..a48dd37 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java @@ -64,6 +64,31 @@ public final class XincangOrderDetailMapper { .exceptionCode(blankToNull(detail.apiError)) .estimatedShippingFee(parseMoney(detail.totalAmount)) .currency(CURRENCY_USD) + // ---- 仓方原始字段 ---- + .providerId(blankToNull(detail.id)) + .rawStatusName(blankToNull(detail.stateName)) + .labelUrl(blankToNull(detail.faceUrl)) + .shopName(blankToNull(detail.shopName)) + .skuCount(parseInteger(detail.skuCount)) + .productSku(blankToNull(detail.productSku)) + .productName(blankToNull(detail.productName)) + .sourceSku(blankToNull(detail.sourceSku)) + .providerWarehouseId(blankToNull(detail.warehouseId)) + .isSign(blankToNull(detail.isSign)) + .zone(blankToNull(detail.zone)) + .dimLength(blankToNull(detail.dimLength)) + .dimWidth(blankToNull(detail.dimWidth)) + .dimHeight(blankToNull(detail.dimHeight)) + .dimDivisor(blankToNull(detail.dimDivisor)) + .weightLbs(blankToNull(detail.weightLbs)) + .billingWeightLbs(blankToNull(detail.billingWeightLbs)) + .volumeWeightLbs(blankToNull(detail.volumeWeightLbs)) + .totalAmount(parseMoney(detail.totalAmount)) + .repairAmount(parseMoney(detail.repairAmount)) + .approvedAt(parseTime(detail.approveTime)) + .modifiedAt(parseTime(detail.gmtModify)) + .cancelledAt(parseTime(detail.gmtCancel)) + .interceptedAt(parseTime(detail.interceptTime)) .build(); } @@ -174,6 +199,23 @@ public final class XincangOrderDetailMapper { } } + /** + * 整数原值:空值 / 非法返回 null。 + * + *

与 {@link #parsePositiveInt} 的区别:这个把 null 与 0 区分开, + * 用于「仓方没给」与「仓方给了 0」要分开的字段(如件数合计)。

+ */ + static Integer parseInteger(String raw) { + if (blank(raw)) { + return null; + } + try { + return Integer.valueOf(raw.trim()); + } catch (NumberFormatException e) { + return null; + } + } + static int parsePositiveInt(String raw) { if (blank(raw)) { return 0; diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java index e39c422..fabc8b3 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java @@ -40,7 +40,7 @@ public final class XincangOrderMapper { /** 信仓布尔字段统一用「是 / 否」。 */ private static final String YES = "是"; private static final String NO = "否"; - /** 签名服务:模型无对应字段,固定否。 */ + /** 签名服务未指定时的兜底值:文档把它列为必填,只能给「否」。 */ private static final String SIGN_NOT_REQUIRED = NO; private XincangOrderMapper() { @@ -87,7 +87,10 @@ public final class XincangOrderMapper { form.put("phone", shipTo.phone().trim()); putIfPresent(form, "email", shipTo.email()); form.put("logistics_type", cmd.carrierCode().trim()); - form.put("is_sign", SIGN_NOT_REQUIRED); + // is_sign 是必填项:调用方给值就按值发,没给才退回「否」并说明原因 + form.put("is_sign", cmd.signatureRequired() == null + ? SIGN_NOT_REQUIRED + : (cmd.signatureRequired() ? YES : NO)); form.put("products", productsJson(cmd.lines(), json)); putIfPresent(form, "shop_name", cmd.shopName()); if (cmd.sfp() != null) { diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java index 8a3764f..326ec70 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java @@ -17,6 +17,9 @@ import java.math.RoundingMode; * *

文档未定义「包装方式 / 是否 SN / 客退处理 / 海关信息」等字段,这些统一模型字段 * 不发送,避免自行编造平台不认的键。

+ * + *

文档里标「已废弃」的 {@code ahs_weight} / {@code ahs_dimensions} / {@code oversize} + * 只在 DTO 里占位,一律不填——仓方已改为按服务商参数自动计算。

*/ public final class XincangProductMapper { @@ -54,6 +57,11 @@ public final class XincangProductMapper { req.remark = trimToNull(product.remark()); req.ckm = trimToNull(product.customItemNo()); req.productType = product.productType() > 0 ? product.productType() : null; + // product_category 由调用方按仓方字典显式给,适配器不猜 + req.productCategory = product.productCategory(); + // product_image 需要 upload.files 返回的 OSS 元数据;只有 URL 时无法组装, + // 因此这里不填 —— 明确不发送,避免被仓方当成无效图片 + req.productImage = null; return req; } diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java index 1347435..bc67f3e 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java @@ -38,9 +38,63 @@ public final class XincangTransferDetailMapper { .totalQuantity(totalQuantityOf(detail)) .estimatedOutboundAt(XincangOrderDetailMapper.parseDate(detail.preSendTime)) .remark(XincangOrderDetailMapper.blankToNull(detail.remark)) + // ---- 仓方原始字段 ---- + .providerId(XincangOrderDetailMapper.blankToNull(detail.id)) + .po(XincangOrderDetailMapper.blankToNull(detail.po)) + .customerId(XincangOrderDetailMapper.blankToNull(detail.customerId)) + .customerNo(XincangOrderDetailMapper.blankToNull(detail.customerNo)) + .fromWarehouseId(XincangOrderDetailMapper.blankToNull(detail.fromWarehouseId)) + .destWarehouseId(XincangOrderDetailMapper.blankToNull(detail.destWarehouseId)) + .rawStatusName(XincangOrderDetailMapper.blankToNull(detail.stateName)) + .deliveryMode(XincangOrderDetailMapper.blankToNull(detail.deliveryMode)) + .deliveryWay(XincangOrderDetailMapper.blankToNull(detail.deliveryWay)) + .orderType(XincangOrderDetailMapper.blankToNull(detail.orderType)) + .otherWarehouse(XincangOrderDetailMapper.blankToNull(detail.otherWarehouse)) + .labelRequirement(XincangOrderDetailMapper.blankToNull(detail.labelRequirement)) + .isProductLabel(XincangOrderDetailMapper.blankToNull(detail.isProductLabel)) + .isCtnLabel(XincangOrderDetailMapper.blankToNull(detail.isCtnLabel)) + .isPalletLabel(XincangOrderDetailMapper.blankToNull(detail.isPalletLabel)) + .isPallet(XincangOrderDetailMapper.blankToNull(detail.isPallet)) + .pickingStartedAt(XincangOrderDetailMapper.parseTime(detail.pickingTime)) + .pickedAt(XincangOrderDetailMapper.parseTime(detail.pickedTime)) + .palletizedAt(XincangOrderDetailMapper.parseTime(detail.palletedTime)) + .sentAt(XincangOrderDetailMapper.parseTime(detail.sendTime)) + .approvedAt(XincangOrderDetailMapper.parseTime(detail.approveTime)) + .shippingId(XincangOrderDetailMapper.blankToNull(detail.shippingId)) + .totalAmount(XincangOrderDetailMapper.parseMoney(detail.totalAmount)) + .createdAt(XincangOrderDetailMapper.parseTime(detail.gmtCreate)) + .modifiedAt(XincangOrderDetailMapper.parseTime(detail.gmtModify)) + .lines(toLines(detail)) .build(); } + /** 转运明细行 → 统一模型。 */ + static java.util.List toLines(XincangDtos.TransferDetail detail) { + if (detail.products == null || detail.products.isEmpty()) { + return java.util.Collections.emptyList(); + } + java.util.List out = + new java.util.ArrayList(detail.products.size()); + for (XincangDtos.TransferDetailProduct product : detail.products) { + if (product == null || XincangOrderDetailMapper.blank(product.productNo)) { + continue; + } + out.add(TransferOrder.TransferLine.builder() + .providerSku(product.productNo.trim()) + .productName(XincangOrderDetailMapper.blankToNull(product.productName)) + .productNameCn(XincangOrderDetailMapper.blankToNull(product.chnName)) + .plannedQuantity(XincangOrderDetailMapper.parsePositiveInt(product.skuCount)) + .boxCount(XincangOrderDetailMapper.parsePositiveInt(product.boxCount)) + .checkedBoxCount(XincangOrderDetailMapper.parsePositiveInt(product.checkBoxQty)) + .palletizedQuantity(XincangOrderDetailMapper.parsePositiveInt(product.palletSkuCount)) + .storedQuantity(XincangOrderDetailMapper.parsePositiveInt(product.putOnSkuCount)) + .packingRate(XincangOrderDetailMapper.blankToNull(product.packingRate)) + .remark(XincangOrderDetailMapper.blankToNull(product.remark)) + .build()); + } + return out; + } + /** 明细件数合计;明细缺失时返回 0(未知,不猜)。 */ static int totalQuantityOf(XincangDtos.TransferDetail detail) { if (detail.products == null || detail.products.isEmpty()) { diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java index 2439a53..36850fc 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java @@ -141,6 +141,34 @@ public final class XincangDtos { /** 产品图片;需先调 {@code upload.files}。统一模型暂不承载图片,通常为 null。 */ @JsonProperty("product_image") public ProductImage productImage; + + /** + * AHS 计费重量。 + * + *

文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填, + * 保留占位只为与文档字段表对齐。

+ */ + @JsonProperty("ahs_weight") + @Deprecated + public String ahsWeight; + + /** + * AHS 计费尺寸。 + * + *

文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。

+ */ + @JsonProperty("ahs_dimensions") + @Deprecated + public String ahsDimensions; + + /** + * 是否超尺寸。 + * + *

文档标注已废弃:具体值由各服务商参数自动计算。SDK 不填。

+ */ + @JsonProperty("oversize") + @Deprecated + public String oversize; } /** 产品图片(OSS 元数据)。 */ @@ -428,6 +456,14 @@ public final class XincangDtos { @JsonProperty("po") public String po; + /** 客户 id。 */ + @JsonProperty("customer_id") + public String customerId; + + /** 客户代码。 */ + @JsonProperty("customer_no") + public String customerNo; + /** 发货仓 id / 代码。 */ @JsonProperty("from_warehouse") public String fromWarehouseId; @@ -558,6 +594,22 @@ public final class XincangDtos { public String weightLbs; @JsonProperty("weight_kg") public String weightKg; + + /** 产品中文名(文档字段 {@code chn_name} 的语义;与 {@link #chnName} 同值来源)。 */ + @JsonProperty("product_name") + public String productName; + + /** 清点箱数。 */ + @JsonProperty("check_box_qty") + public String checkBoxQty; + + /** 打托件数。 */ + @JsonProperty("pallet_sku_count") + public String palletSkuCount; + + /** 上架件数。 */ + @JsonProperty("put_on_sku_count") + public String putOnSkuCount; } /** 转运详情响应外层。 */ @@ -1017,6 +1069,15 @@ public final class XincangDtos { @JsonInclude(JsonInclude.Include.NON_NULL) public static final class ForecastCreateRequest { + /** + * 客户 id。 + * + *

文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。

+ */ + @JsonProperty("customer_id") + @Deprecated + public String customerId; + /** 目的地仓。 */ @JsonProperty("dest_warehouse") public String destWarehouse; @@ -1081,6 +1142,24 @@ public final class XincangDtos { @JsonInclude(JsonInclude.Include.NON_NULL) public static final class ForecastImproveRequest { + /** + * 预报单 id。 + * + *

文档标注已舍弃,SDK 不填;保留占位以与文档字段表对齐。

+ */ + @JsonProperty("id") + @Deprecated + public String id; + + /** + * 客户 id。 + * + *

文档标注已舍弃,SDK 不填。

+ */ + @JsonProperty("customer_id") + @Deprecated + public String customerId; + @JsonProperty("forecast_no") public String forecastNo; @@ -1094,9 +1173,20 @@ public final class XincangDtos { @JsonProperty("ref_no") public String refNo; + /** + * 新增预报柜号。 + * + *

文档标注已舍弃,SDK 不填。

+ */ + @JsonProperty("old_cabinet_no") + @Deprecated + public String oldCabinetNo; + + /** 柜型:0 20GP / 1 40GP / 2 40HQ / 3 45HQ / 4 纸箱入库 / 5 托盘入库。 */ @JsonProperty("cabinet_type") public String cabinetType; + /** 柜号。 */ @JsonProperty("cabinet_no") public String cabinetNo; @@ -1108,6 +1198,15 @@ public final class XincangDtos { @JsonProperty("eta") public String eta; + /** + * 最晚免费时间(提柜)。 + * + *

文档标注已舍弃,SDK 不填。

+ */ + @JsonProperty("lfd") + @Deprecated + public String lfd; + @JsonProperty("delivery_requirements") public String deliveryRequirements; @@ -1118,13 +1217,33 @@ public final class XincangDtos { @JsonProperty("other_need") public String otherNeed; + /** + * 总件数。 + * + *

文档标注已舍弃(由 {@code products} 汇总),SDK 不填。

+ */ + @JsonProperty("sku_count_sum") + @Deprecated + public String skuCountSum; + + /** + * 总箱数。 + * + *

文档标注已舍弃(由 {@code products} 汇总),SDK 不填。

+ */ + @JsonProperty("box_count_sum") + @Deprecated + public String boxCountSum; + /** 产品明细 JSON 字符串。 */ @JsonProperty("products") public String products; + /** 船务公司 id;通过【获取船务公司】接口取得。 */ @JsonProperty("shipping_company_id") public String shippingCompanyId; + /** 预报托盘数;柜型为托盘入库时填写。 */ @JsonProperty("forecast_pallet_qty") public String forecastPalletQty; } @@ -1160,6 +1279,10 @@ public final class XincangDtos { @JsonIgnoreProperties(ignoreUnknown = true) public static final class ForecastDetail { + /** 预报单 id。 */ + @JsonProperty("id") + public String id; + @JsonProperty("forecast_no") public String forecastNo; @@ -1167,6 +1290,14 @@ public final class XincangDtos { @JsonProperty("chn_name") public String chnName; + /** 客户 id。 */ + @JsonProperty("customer_id") + public String customerId; + + /** 客户代码。 */ + @JsonProperty("customer_name") + public String customerName; + /** 目的仓 id / 代码。 */ @JsonProperty("dest_warehouse") public String destWarehouseId; @@ -1300,6 +1431,44 @@ public final class XincangDtos { /** 体积(立方厘米)。 */ @JsonProperty("volume_cm") public String volumeCm; + + /** 中文名。 */ + @JsonProperty("chn_name") + public String chnName; + + /** 英文名。 */ + @JsonProperty("en_name") + public String enName; + + /** 体积(立方英寸)。 */ + @JsonProperty("volume_ln") + public String volumeLn; + + /** 长(厘米)。 */ + @JsonProperty("size_l_cm") + public String sizeLCm; + /** 宽(厘米)。 */ + @JsonProperty("size_w_cm") + public String sizeWCm; + /** 高(厘米)。 */ + @JsonProperty("size_h_cm") + public String sizeHCm; + /** 长(英寸)。 */ + @JsonProperty("size_l_ln") + public String sizeLLn; + /** 宽(英寸)。 */ + @JsonProperty("size_w_ln") + public String sizeWLn; + /** 高(英寸)。 */ + @JsonProperty("size_h_ln") + public String sizeHLn; + + /** 预报产品创建时间。 */ + @JsonProperty("gmt_create") + public String gmtCreate; + /** 预报产品最后修改时间。 */ + @JsonProperty("gmt_modify") + public String gmtModify; } /** 预报详情响应外层。 */ diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java index bb47f38..4fa8817 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangForecastTest.java @@ -223,7 +223,9 @@ class XincangForecastTest { assertEquals(1, order.lines().size()); assertEquals("HB-B2060-RED", order.lines().get(0).providerSku()); assertEquals(100, order.lines().get(0).plannedQuantity()); - assertEquals(100, order.lines().get(0).packedQuantity()); + // box_count(预报箱数)语义不同于 packedQuantity(实际装箱件数),不再互相映射 + assertEquals(0, order.lines().get(0).packedQuantity(), + "box_count 不再冒充 packedQuantity"); assertEquals(80, order.lines().get(0).receivedQuantity()); } diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java index 3f295f9..8fd887d 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangInventoryTest.java @@ -131,6 +131,26 @@ class XincangInventoryTest { } @Test + void stockSendsShowZeroWhenRequested() { + transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY)); + + adapter.query(ctx(), InventoryQuery.builder().includeZeroStock(true).build()); + + assertTrue(transport.lastDataRequest().url().contains("is_show_zero=1"), + transport.lastDataRequest().url()); + } + + @Test + void stockOmitsShowZeroWhenUnset() { + transport.route(XincangConstants.PATH_STOCK_LIST, req -> Responses.ok(STOCK_BODY)); + + adapter.query(ctx(), InventoryQuery.builder().build()); + + assertFalse(transport.lastDataRequest().url().contains("is_show_zero"), + "未指定时不传,交给仓方默认"); + } + + @Test void ageQuerySendsBillDateRangeAndMapsRecord() { transport.route(XincangConstants.PATH_STOCK_AGE_LIST, req -> Responses.ok(AGE_BODY)); diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java new file mode 100644 index 0000000..2537ac8 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangModelRelaxTest.java @@ -0,0 +1,76 @@ +package common.ecommerce.xincang.adapter; + +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.capability.WarehouseProduct; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundLine; +import org.junit.jupiter.api.Test; + +import java.time.LocalDate; + +import static org.junit.jupiter.api.Assertions.assertNotNull; + +/** + * 统一模型里「某家仓必填、其他仓不需要」的字段不再在构造期拦截。 + * + *

这些用例守护的是:信仓可以只给它认识的字段就构造出命令, + * 不会因为运去哪的必填项(nameEn / packingType / 海关三项 / 入库商品行) + * 被迫塞无意义的值。

+ */ +class XincangModelRelaxTest { + + /** 商品:不给 nameEn / packingType / 海关三项也能构造(信仓都收不到这些字段)。 */ + @Test + void productBuildsWithoutYqnOnlyFields() { + WarehouseProduct product = WarehouseProduct.builder() + .omsSku("SKU-1") + .name("中文名") + .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100) + .build(); + assertNotNull(product); + } + + /** + * 商品:信仓 amount 必填,但只需要 declaredValue,不需要 hsCode / countryOfOrigin。 + * + *

改前「海关三项必须整组给」在构造期强制,信仓调用方被迫填两个用不上的字段。

+ */ + @Test + void productCustomsValueAloneIsAccepted() { + WarehouseProduct product = WarehouseProduct.builder() + .omsSku("SKU-2") + .name("中文名") + .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100) + .declaredValue(Money.of("1.00", "USD")) + .build(); + assertNotNull(product); + } + + /** 入库:信仓「新增预报」只建单头,可以没有商品行(明细走「完善资料」)。 */ + @Test + void inboundHeaderOnlyIsEnoughForForecastCreate() { + InboundCommand head = InboundCommand.builder() + .inboundRequestNo("FC-1") + .warehouseId("NJ-2605") + .shipmentType("2") + .cabinetType("1") + .containerNo("CAB-1") + .predictionShipDate(LocalDate.now().plusDays(1)) + .estimateArriveDate(LocalDate.now().plusDays(30)) + .deliveryRequirements("1") + .referenceSkuCount(3) + .build(); + assertNotNull(head); + } + + /** 入库:完善资料阶段要明细,这时才加行,模型允许。 */ + @Test + void inboundWithLinesStillWorks() { + InboundCommand withLines = InboundCommand.builder() + .inboundRequestNo("FC-2") + .warehouseId("NJ-2605") + .line(InboundLine.builder().omsSku("SKU-1").quantity(1).build()) + .build(); + assertNotNull(withLines); + } +} diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java index 711f01f..1e42797 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java @@ -168,6 +168,27 @@ class XincangOrderTest { } @Test + void signatureFlagFollowsCaller() { + transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"DS-SIG\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}")); + OutboundCommand signed = OutboundCommand.builder() + .outboundRequestNo("OB-SIG") + .salesPlatform(Platform.AMAZON_SC) + .carrierCode("FEDEX-G") + .warehouseId("CA-3790") + .signatureRequired(true) + .shipTo(ShipTo.builder().name("R").phone("1").countryCode("US").stateOrProvince("CA") + .city("Fontana").addressLine1("1 A St").postalCode("92337").build()) + .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(1).build()) + .build(); + + adapter.create(ctx(), signed); + + assertTrue(transport.lastDataRequest().body().contains("name=\"is_sign\"\r\n\r\n是"), + transport.lastDataRequest().body()); + } + + @Test void splitFlagIsOmittedWhenCallerDidNotSetIt() { transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok( "{\"rst\":{\"order_no\":\"DS-1\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}")); diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java index cfe3182..836425b 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java @@ -207,6 +207,32 @@ class XincangProductTest { } @Test + void productWithoutEnglishNameIsAccepted() { + // 信仓只有中文名(chn_name),没有 english name 字段; + // nameEn 是运去哪的必填项,不应在统一模型构造期强制 + routeProductList("[]"); + transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok( + "{\"rst\":true,\"errno\":0,\"err\":\"\"}")); + WarehouseProduct noEnglishName = WarehouseProduct.builder() + .omsSku("APITEST008") + .name("测试商品") + .barcode("B-8") + .packingType(0) + .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100) + .declaredValue(Money.of("1.00", "USD")) + .hsCode("9403600000") + .countryOfOrigin("US") + .build(); + + assertNotNull(adapter.createOrUpdate(ctx(), noEnglishName), + "缺 nameEn 时信仓应能正常建档"); + + String body = Objects.requireNonNull(transport.lastDataRequest()).body(); + assertTrue(body.contains("\"chn_name\":\"测试商品\""), body); + assertFalse(body.contains("nameEn"), "信仓不发送英文名"); + } + + @Test void missingDeclaredValueIsRejectedInsteadOfSendingZero() { routeProductList("[]"); WarehouseProduct noValue = WarehouseProduct.builder() diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java index 9904c47..0240ae0 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java @@ -192,6 +192,25 @@ class XincangTransferTest { } @Test + void modelNoLongerRequiresInboundDateOrShipTo() { + // 信仓转运只用 pre_send_time,也不用收件地址;模型不再强制这两个字段 + TransferCommand minimal = TransferCommand.builder() + .transferRequestNo("TR-MIN") + .type(TransferType.OUTBOUND) + .fromWarehouseCode("CA-3790").toWarehouseCode("ONT8") + .estimateOutboundDate(LocalDate.parse("2026-11-20")) + .deliveryMode("FBA").deliveryWay("Amazon(亚马逊卡车自提)") + .palletRequired(false) + .line("SKU-1", 1) + .build(); + + transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"rst\":{\"order_no\":\"LTL-MIN\"},\"errno\":0,\"err\":\"\"}")); + + assertNotNull(adapter.create(ctx(), minimal)); + } + + @Test void nonOutboundTransferTypeIsRejected() { TransferCommand cmd = TransferCommand.builder() .transferRequestNo("TR-2") diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java new file mode 100644 index 0000000..7588b77 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangProbeSupport.java @@ -0,0 +1,293 @@ +package common.ecommerce.xincang.probe; + +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.testkit.InMemoryLockProvider; +import common.ecommerce.shared.testkit.InMemoryTokenStore; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.WarehouseFacility; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.xincang.XincangConstants; +import common.ecommerce.xincang.adapter.XincangAdapter; +import org.junit.jupiter.api.Assumptions; + +import java.time.Clock; +import java.util.List; +import java.util.function.Supplier; + +/** + * 信仓联网探针的公共基座。 + * + *

默认全部跳过,用 {@code -Dxincang.probe=true} 显式开启;写接口还要再加 + * {@code -Dxincang.probe.write=true} 二次确认。凭据与业务数据一律走系统属性, + * 真实值不入库。

+ * + *
+ * mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ *     -Dxincang.probe=true \
+ *     -Dxincang.probe.appKey=你的appkey -Dxincang.probe.appSecret=你的secret \
+ *     -Dtest=XincangReadProbeTest test
+ * 
+ * + *

可选属性:{@code baseUrl}、{@code warehouseCode}、{@code sku}、{@code postcode}、 + * {@code qty}、{@code orderNo}、{@code transferNo}、{@code forecastNo}。

+ * + *

设计约束:

+ *
    + *
  • 每个探针独立执行,单个失败只打印不抛出,保证一次能跑完全部接口;
  • + *
  • 请求 / 响应都打印(截断 + 脱敏),便于和文档逐字段对照;
  • + *
  • 不硬编码任何业务数据:仓代码与承运商从目录接口现取。
  • + *
+ */ +final class XincangProbeSupport { + + /** 通用开关。 */ + static final String PROBE = "xincang.probe"; + /** 写接口二次确认。 */ + static final String PROBE_WRITE = "xincang.probe.write"; + + static final String APP_KEY = System.getProperty("xincang.probe.appKey", ""); + static final String APP_SECRET = System.getProperty("xincang.probe.appSecret", ""); + static final String BASE_URL = opt("xincang.probe.baseUrl", XincangConstants.TEST_BASE_URL); + + /** 业务输入:没有默认值,必须由调用方显式传入。 */ + static final String WAREHOUSE_CODE = opt("xincang.probe.warehouseCode", ""); + static final String SKU = opt("xincang.probe.sku", ""); + static final String POSTCODE = opt("xincang.probe.postcode", ""); + static final String ORDER_NO = opt("xincang.probe.orderNo", ""); + static final String TRANSFER_NO = opt("xincang.probe.transferNo", ""); + static final String FORECAST_NO = opt("xincang.probe.forecastNo", ""); + + private static final JacksonJsonCodec JSON = new JacksonJsonCodec(); + + /** 目录接口发现结果缓存,避免每个探针都列一遍。 */ + private static String discoveredWarehouseCode; + private static boolean warehouseDiscoveryAttempted; + private static String discoveredCarrier; + private static boolean carrierDiscoveryAttempted; + + private XincangProbeSupport() { + } + + // ---------------------------------------------------------------- 装配 + + /** 真实联网传输 + 报文打印;token 等敏感头在这里脱敏。 */ + static HttpTransport transport() { + return new LoggingTransport(new OkHttpTransport("common-ecommerce-xincang-probe")); + } + + /** 装配真实适配器;令牌只存在内存里,不落盘。 */ + static XincangAdapter adapter() { + return new XincangAdapter(transport(), JSON, new InMemoryTokenStore(), + new InMemoryLockProvider(), Clock.systemUTC()); + } + + /** 用指定传输装配,便于需要复用连接的对象。 */ + static XincangAdapter adapter(HttpTransport transport) { + return new XincangAdapter(transport, JSON, new InMemoryTokenStore(), + new InMemoryLockProvider(), Clock.systemUTC()); + } + + static WarehouseContext ctx() { + return ctx(WAREHOUSE_CODE.isEmpty() ? null : WAREHOUSE_CODE); + } + + static WarehouseContext ctx(String providerWarehouseId) { + return WarehouseContext.of("XC-PROBE", WarehouseProvider.XINCANG, providerWarehouseId, + WarehouseConnection.of(BASE_URL, ChannelSecret.builder() + .appKey(APP_KEY).appSecret(APP_SECRET).build()), + "probe-" + System.currentTimeMillis(), Clock.systemUTC()); + } + + // ---------------------------------------------------------------- 前置检查 + + /** 凭据齐全才继续,否则整个探针 skip(不算失败)。 */ + static void requireCredentials() { + Assumptions.assumeTrue(!APP_KEY.trim().isEmpty() && !APP_SECRET.trim().isEmpty(), + "未提供 -Dxincang.probe.appKey / -Dxincang.probe.appSecret,跳过探针"); + } + + /** 需要某个业务输入时用它:缺了就跳过当前用例并说明缺哪个属性。 */ + static void requireProperty(String name) { + Assumptions.assumeTrue(System.getProperty(name, "").trim().length() > 0, + "未提供 -D" + name + ",跳过该探针"); + } + + // ---------------------------------------------------------------- 执行 & 打印 + + /** 执行一步并打印结果;异常只打印不抛出,返回 null。 */ + static T step(String label, Supplier action) { + System.out.println(" [probe] " + label); + try { + T value = action.get(); + System.out.println(" [ok] " + label + " → " + describe(value)); + return value; + } catch (RuntimeException e) { + printError(e); + return null; + } + } + + static void step(String label, Runnable action) { + step(label, () -> { + action.run(); + return Boolean.TRUE; + }); + } + + /** 异常打印:类型 + 截断消息 + 平台错误字段。 */ + static void printError(RuntimeException e) { + String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage(); + System.out.println(" [ERROR] " + e.getClass().getSimpleName() + ": " + + (msg.length() <= 400 ? msg : msg.substring(0, 400) + "…")); + if (e instanceof common.ecommerce.shared.error.ChannelException) { + common.ecommerce.shared.error.ChannelException ce = + (common.ecommerce.shared.error.ChannelException) e; + System.out.println(" operation=" + ce.operation() + + " platformCode=" + ce.platformCode() + + " platformRequestId=" + ce.platformRequestId() + + " retryable=" + ce.retryable()); + } + } + + private static String describe(Object value) { + if (value == null) { + return "null"; + } + if (value instanceof List) { + return ((List) value).size() + " items"; + } + return String.valueOf(value); + } + + // ---------------------------------------------------------------- 依赖发现 + + /** + * 仓代码:优先 {@code -Dxincang.probe.warehouseCode},否则从客户仓库接口取第一家。 + * + * @return 没有可用仓时返回 null,调用方打印跳过 + */ + static String warehouseCode(XincangAdapter adapter) { + if (!WAREHOUSE_CODE.isEmpty()) { + return WAREHOUSE_CODE; + } + if (warehouseDiscoveryAttempted) { + return discoveredWarehouseCode; + } + warehouseDiscoveryAttempted = true; + try { + List facilities = adapter.warehouses(ctx()); + if (!facilities.isEmpty()) { + discoveredWarehouseCode = facilities.get(0).warehouseCode(); + System.out.println(" [discovery] 自动使用仓 " + discoveredWarehouseCode); + } + } catch (RuntimeException e) { + printError(e); + } + return discoveredWarehouseCode; + } + + /** + * 承运商 / 物流方式:优先 {@code -Dxincang.probe.carrier},否则从客户承运商接口取第一个。 + */ + static String carrier(XincangAdapter adapter) { + String configured = System.getProperty("xincang.probe.carrier", "").trim(); + if (!configured.isEmpty()) { + return configured; + } + if (carrierDiscoveryAttempted) { + return discoveredCarrier; + } + carrierDiscoveryAttempted = true; + try { + List carriers = adapter.carriers(ctx()); + if (!carriers.isEmpty()) { + discoveredCarrier = carriers.get(0); + System.out.println(" [discovery] 自动使用承运商 " + discoveredCarrier); + } + } catch (RuntimeException e) { + printError(e); + } + return discoveredCarrier; + } + + /** 业务单号后缀:保证重跑不会撞「参考号已存在」这类唯一约束。 */ + static String uniqueSuffix() { + return new java.text.SimpleDateFormat("yyyyMMdd-HHmmss") + .format(new java.util.Date()); + } + + static int qty() { + String raw = System.getProperty("xincang.probe.qty", "1").trim(); + try { + int v = Integer.parseInt(raw); + return v > 0 ? v : 1; + } catch (NumberFormatException e) { + return 1; + } + } + + static String opt(String name, String fallback) { + String value = System.getProperty(name, ""); + if (value == null) { + return fallback; + } + String trimmed = value.trim(); + return trimmed.isEmpty() ? fallback : trimmed; + } + + // ---------------------------------------------------------------- 报文打印 + + /** + * 请求 / 响应打印。 + * + *

脱敏规则:鉴权头与 URL 里的 token / secret 一律替换成 {@code ***}; + * 打印体截断到 2000 字符,避免大段 base64 或明细刷屏。

+ */ + static final class LoggingTransport implements HttpTransport { + + private static final int MAX_BODY = 2000; + + private final HttpTransport delegate; + + LoggingTransport(HttpTransport delegate) { + this.delegate = delegate; + } + + @Override + public HttpResponse execute(HttpRequest request) { + System.out.println(" --> " + request.method() + " " + maskUrl(request.url())); + System.out.println(" body " + truncate(request.body())); + long start = System.nanoTime(); + HttpResponse response = delegate.execute(request); + long millis = (System.nanoTime() - start) / 1_000_000L; + System.out.println(" <-- " + response.statusCode() + " (" + millis + "ms) " + + truncate(response.body())); + return response; + } + + /** 去掉 scheme+host,并把 query 里的敏感参数打码。 */ + private static String maskUrl(String url) { + if (url == null) { + return "null"; + } + int pathStart = url.indexOf('/', url.indexOf("://") + 3); + String path = pathStart < 0 ? url : url.substring(pathStart); + return path.replaceAll("(?i)((?:token|secret|appkey)=)[^&]*", "$1***"); + } + + private static String truncate(String body) { + if (body == null) { + return "null"; + } + return body.length() <= MAX_BODY + ? body + : body.substring(0, MAX_BODY) + "...(" + body.length() + " chars)"; + } + } +} diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java new file mode 100644 index 0000000..d3cc360 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangReadProbeTest.java @@ -0,0 +1,307 @@ +package common.ecommerce.xincang.probe; + +import common.ecommerce.warehouse.model.ChannelRecommendQuery; +import common.ecommerce.warehouse.model.ChannelRecommendResult; +import common.ecommerce.warehouse.model.InventoryAgeQuery; +import common.ecommerce.warehouse.model.InventoryAgeRecord; +import common.ecommerce.warehouse.model.InventoryQuery; +import common.ecommerce.warehouse.model.InventorySnapshot; +import common.ecommerce.warehouse.model.OutboundOrder; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.model.WarehouseFacility; +import common.ecommerce.shared.support.Page; +import common.ecommerce.xincang.XincangConstants; +import common.ecommerce.xincang.adapter.XincangAdapter; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIfSystemProperty; + +import java.time.LocalDate; +import java.util.List; + +/** + * 信仓只读接口的联网探针:核对真实出入参。 + * + *

默认跳过,用 {@code -Dxincang.probe=true} 开启。凭据与业务数据走系统属性, + * 真实值不入库;缺某个业务输入时只跳过依赖它的用例,不影响其他用例。

+ * + *
+ * mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ *     -Dxincang.probe=true \
+ *     -Dxincang.probe.appKey=... -Dxincang.probe.appSecret=... \
+ *     -Dxincang.probe.sku=... -Dxincang.probe.postcode=... \
+ *     -Dtest=XincangReadProbeTest test
+ * 
+ * + *

可选属性:{@code warehouseCode} / {@code sku} / {@code postcode} / {@code orderNo} / + * {@code transferNo} / {@code forecastNo} / {@code productPageSize}。

+ * + *

只做查询,不调用任何写接口;异常只打印不抛出,一次能跑完全部段落。

+ */ +@EnabledIfSystemProperty(named = XincangProbeSupport.PROBE, matches = "true") +class XincangReadProbeTest { + + // ================================================================ 公共资料 + + /** 客户所有仓库:拿到仓代码,同时验证目录接口。 */ + @Test + void probeCustomerWarehouses() { + XincangProbeSupport.requireCredentials(); + System.out.println("\n================ xincang / api.get_customer_warehouses ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + List warehouses = + XincangProbeSupport.step("warehouses", () -> adapter.warehouses(XincangProbeSupport.ctx())); + if (warehouses == null) { + return; + } + for (WarehouseFacility w : warehouses) { + System.out.println(" warehouse_code=" + w.warehouseCode() + + " id=" + w.providerWarehouseId() + + " " + w.city() + "/" + w.province() + "/" + w.country() + + " " + w.postcode()); + } + if (warehouses.isEmpty()) { + System.out.println(" [warn] 该账户下没有任何仓库,后续依赖仓代码的探针会跳过"); + } + } + + /** 客户所有承运商:拿到 logistics_type,用于下单与报价。 */ + @Test + void probeCustomerLogistics() { + XincangProbeSupport.requireCredentials(); + System.out.println("\n================ xincang / api.get_customer_logistics ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + List carriers = + XincangProbeSupport.step("carriers", () -> adapter.carriers(XincangProbeSupport.ctx())); + if (carriers != null) { + System.out.println(" carriers=" + carriers); + } + } + + // ================================================================ 库存 / 库龄 + + /** 实时库存:核对手上数量字段口径。 */ + @Test + void probeStockList() { + XincangProbeSupport.requireCredentials(); + System.out.println("\n================ xincang / api.stocklist ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + String warehouseCode = XincangProbeSupport.warehouseCode(adapter); + if (warehouseCode == null) { + System.out.println(" [skip] 没有可用仓代码,跳过"); + return; + } + InventoryQuery.Builder query = InventoryQuery.builder() + .warehouseCode(warehouseCode) + .pageSize(10); + if (!XincangProbeSupport.SKU.isEmpty()) { + query.sku(XincangProbeSupport.SKU); + } + Page page = XincangProbeSupport.step( + "stocklist warehouse=" + warehouseCode, + () -> adapter.query(XincangProbeSupport.ctx(warehouseCode), query.build())); + if (page == null) { + return; + } + System.out.println(" items=" + page.size() + " nextCursor=" + page.nextCursor()); + for (InventorySnapshot s : page.items()) { + System.out.println(" sku=" + s.providerSku() + + " onHand=" + s.onHand() + + " available=" + s.available() + + " reserved=" + s.reserved() + + " pending=" + s.pendingOutbound() + + " inTransit=" + s.inTransit() + + " alert=" + s.alertQuantity() + + " name=" + s.productName() + + " volumeCm=" + s.volumeCbm()); + } + } + + /** 库龄列表:默认查最近 7 天,核对计费字段。 */ + @Test + void probeStockAgeList() { + XincangProbeSupport.requireCredentials(); + System.out.println("\n================ xincang / api.stockagelist ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + LocalDate end = LocalDate.now(); + LocalDate start = end.minusDays(7); + InventoryAgeQuery query = InventoryAgeQuery.builder() + .dateRange(start, end) + .pageSize(10) + .includeFeeRate(true) + .build(); + Page page = XincangProbeSupport.step( + "stockagelist " + start + " ~ " + end, + () -> adapter.queryAges(XincangProbeSupport.ctx(), query)); + if (page == null) { + return; + } + System.out.println(" items=" + page.size() + " nextCursor=" + page.nextCursor()); + for (InventoryAgeRecord r : page.items()) { + System.out.println(" sku=" + r.providerSku() + + " warehouse=" + r.warehouseCode() + + " billingDate=" + r.billingDate() + + " inStockAt=" + r.inStockAt() + + " ageDays=" + r.ageDays() + + " qty=" + r.quantity() + + " billingQty=" + r.billingQuantity() + + " feeRate=" + r.feeRate() + + " fee=" + r.fee() + + " cabinet=" + r.cabinetNo()); + } + } + + // ================================================================ 详情 + + /** 订单详情:按 -Dxincang.probe.orderNo 查。 */ + @Test + void probeOrderDetail() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.orderNo"); + System.out.println("\n================ xincang / api.get_order ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + OutboundOrder order = XincangProbeSupport.step( + "get_order " + XincangProbeSupport.ORDER_NO, + () -> adapter.get(XincangProbeSupport.ctx(), + OutboundRef.ofProviderOrderId(XincangProbeSupport.ORDER_NO))); + if (order == null) { + return; + } + System.out.println(" orderNo=" + order.outboundRequestNo() + + " providerOrderId=" + order.providerOrderId() + + " ref=" + order.orderRef() + + " status=" + order.status() + "(raw=" + order.rawStatus() + ")" + + " labelMode=" + order.labelMode() + + " carrier=" + order.carrierCode() + + " tracking=" + order.trackingNumber() + + " exception=" + order.exceptionCode() + + " requestedAt=" + order.requestedAt() + + " shippedAt=" + order.shippedAt() + + " fee=" + order.estimatedShippingFee()); + System.out.println(" shipTo=" + order.shipTo()); + for (common.ecommerce.warehouse.model.OutboundLine line : order.lines()) { + System.out.println(" sku=" + line.providerSku() + + " qty=" + line.quantity() + + " name=" + line.declareName()); + } + } + + /** 转运详情:按 -Dxincang.probe.transferNo 查。 */ + @Test + void probeTransferDetail() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.transferNo"); + System.out.println("\n================ xincang / fba.fba_detail ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + TransferOrder order = XincangProbeSupport.step( + "fba_detail " + XincangProbeSupport.TRANSFER_NO, + () -> adapter.getTransfer(XincangProbeSupport.ctx(), XincangProbeSupport.TRANSFER_NO)); + if (order == null) { + return; + } + System.out.println(" transferRequestNo=" + order.transferRequestNo() + + " providerTransferNo=" + order.providerTransferNo() + + " from=" + order.fromWarehouseCode() + + " to=" + order.toWarehouseCode() + + " type=" + order.type() + + " status=" + order.status() + "(raw=" + order.rawStatus() + ")" + + " totalQty=" + order.totalQuantity() + + " estimatedOutboundAt=" + order.estimatedOutboundAt() + + " remark=" + order.remark()); + } + + /** 预报详情:按 -Dxincang.probe.forecastNo 查。 */ + @Test + void probeForecastDetail() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.forecastNo"); + System.out.println("\n================ xincang / forecast.forecast_detail ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + common.ecommerce.warehouse.model.InboundOrder order = XincangProbeSupport.step( + "forecast_detail " + XincangProbeSupport.FORECAST_NO, + () -> adapter.get(XincangProbeSupport.ctx(), XincangProbeSupport.FORECAST_NO)); + if (order == null) { + return; + } + System.out.println(" inboundRequestNo=" + order.inboundRequestNo() + + " providerInboundId=" + order.providerInboundId() + + " warehouse=" + order.warehouseCode() + + " status=" + order.status() + "(raw=" + order.rawStatus() + ")" + + " boxCount=" + order.boxCount() + + " createdAt=" + order.createdAt() + + " receivedAt=" + order.receivedAt() + + " estimatedArrivalAt=" + order.estimatedArrivalAt() + + " actualArrivalAt=" + order.actualArrivalAt() + + " remark=" + order.remark()); + for (common.ecommerce.warehouse.model.InboundOrderLine line : order.lines()) { + System.out.println(" sku=" + line.providerSku() + + " planned=" + line.plannedQuantity() + + " packed=" + line.packedQuantity() + + " received=" + line.receivedQuantity()); + } + } + + // ================================================================ 报价 + + /** + * 最优渠道:需要 SKU 与邮编。 + * + *

协议待核对:文档写 GET + JSON body,OkHttp 不支持 GET 带 body, + * 适配器按 POST + JSON body 下发。这里重点看仓方是否接受。

+ */ + @Test + void probeChannelRecommend() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + XincangProbeSupport.requireProperty("xincang.probe.postcode"); + System.out.println("\n================ xincang / api.calculate_order_v3 ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + ChannelRecommendQuery query = ChannelRecommendQuery.builder() + .product(XincangProbeSupport.SKU, XincangProbeSupport.qty()) + .postalCode(XincangProbeSupport.POSTCODE) + .signatureRequired(false) + .build(); + ChannelRecommendResult result = XincangProbeSupport.step( + "calculate_order_v3 sku=" + XincangProbeSupport.SKU + + " postcode=" + XincangProbeSupport.POSTCODE, + () -> adapter.recommend(XincangProbeSupport.ctx(), query)); + if (result == null) { + return; + } + if (result.optimalPlan() == null) { + System.out.println(" optimalPlan=null(该城无可用渠道,属合法结果)"); + } else { + System.out.println(" optimalPlan: warehouse=" + result.optimalPlan().warehouseCode() + + " service=" + result.optimalPlan().serviceCode() + + " total=" + result.optimalPlan().total()); + } + System.out.println(" warehouseQuotes=" + result.warehouseQuotes().size()); + for (ChannelRecommendResult.WarehouseQuote q : result.warehouseQuotes()) { + System.out.println(" warehouse=" + q.warehouseCode() + + " inventoryEnough=" + q.inventoryEnough() + + " insufficient=" + q.insufficientStockError()); + for (ChannelRecommendResult.ServiceQuote s : q.services()) { + System.out.println(" service=" + s.serviceCode() + " total=" + s.total()); + for (ChannelRecommendResult.FeeItem f : s.fees()) { + System.out.println(" " + f.bigFeeType() + "/" + f.feeType() + + " = " + f.fee()); + } + } + } + } + + // ================================================================ 商品列表 + + /** 产品列表:通过 createOrUpdate 的查重路径顺带验证(只读部分)。 */ + @Test + void probeProductLookup() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + System.out.println("\n================ xincang / api.productlist ================"); + System.out.println(" [说明] 产品列表接口只在建档查重时调用,这里直接查一次核对字段:"); + System.out.println(" sku=" + XincangProbeSupport.SKU + + ",请对照下方接口返回的 rst.data[].state(0 临时 / 1 正式)"); + System.out.println(" [提示] 走 api.add_product 会真实建档,请用 XincangWriteProbeTest。"); + System.out.println(" endpoint=" + XincangConstants.PATH_PRODUCT_LIST); + } +} diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java new file mode 100644 index 0000000..cbd6226 --- /dev/null +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangWriteProbeTest.java @@ -0,0 +1,338 @@ +package common.ecommerce.xincang.probe; + +import common.ecommerce.shared.model.Platform; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.capability.WarehouseProduct; +import common.ecommerce.warehouse.capability.WarehouseProductCapable; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.model.InboundCommand; +import common.ecommerce.warehouse.model.InboundLine; +import common.ecommerce.warehouse.model.InboundOrder; +import common.ecommerce.warehouse.model.InboundReceipt; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.OutboundOrder; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.enums.TransferType; +import common.ecommerce.xincang.adapter.XincangAdapter; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.condition.EnabledIfSystemProperty; + +import java.time.LocalDate; + +/** + * 信仓写接口的联网探针:真实下单 / 建转运 / 建预报,用于核对报文。 + * + *

默认整类跳过,需要两个开关同时打开:

+ *
+ * -Dxincang.probe=true -Dxincang.probe.write=true
+ * 
+ * + *

运行示例:

+ *
+ * mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
+ *     -Dxincang.probe=true -Dxincang.probe.write=true \
+ *     -Dxincang.probe.appKey=... -Dxincang.probe.appSecret=... \
+ *     -Dxincang.probe.sku=... -Dxincang.probe.postcode=... \
+ *     -Dtest=XincangWriteProbeTest test
+ * 
+ * + *

注意:会在仓方测试环境留下真实数据。能自清理的链路(订单、转运)会尽量删掉; + * 商品建档与预报没有删除接口,跑完需要人工清理。所有单号都带时间戳后缀, + * 重跑不会撞唯一约束。

+ */ +@EnabledIfSystemProperty(named = XincangProbeSupport.PROBE_WRITE, matches = "true") +class XincangWriteProbeTest { + + // ================================================================ 商品 + + /** + * 商品建档 / 更新:走 add_product 或 update_product(先查临时产品决定)。 + * + *

需要 {@code -Dxincang.probe.sku};金额按 1.00 USD 下发, + * 因为信仓把 amount 列为必填且我们不再兜底 0。

+ */ + @Test + void probeProductUpsert() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + System.out.println("\n================ xincang / api.add_product | api.update_product ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + + WarehouseProduct product = WarehouseProduct.builder() + .omsSku(XincangProbeSupport.SKU) + .name("探针商品") + .nameEn("Probe Product") + .barcode("PROBE-" + XincangProbeSupport.uniqueSuffix()) + .packingType(0) + .lengthCm(30) + .widthCm(20) + .heightCm(10) + .weightGrams(500) + .declaredValue(Money.of("1.00", "USD")) + .hsCode("9403600000") + .countryOfOrigin("US") + .build(); + + WarehouseProductCapable.ProductResult result = XincangProbeSupport.step( + "createOrUpdate sku=" + XincangProbeSupport.SKU, + () -> adapter.createOrUpdate(XincangProbeSupport.ctx(), product)); + if (result != null) { + System.out.println(" providerSku=" + result.providerSku() + + " status=" + result.status() + + " rawStatus=" + result.rawStatus()); + System.out.println(" [注意] 没有删除产品接口,跑完需人工清理或复用该 SKU。"); + } + } + + // ================================================================ 出库 + + /** + * 出库闭环:下单 → 详情回读 → 删除。 + * + *

需要 sku + postcode;承运商从目录接口自动取(或 {@code -Dxincang.probe.carrier})。

+ */ + @Test + void probeOutboundRoundTrip() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + XincangProbeSupport.requireProperty("xincang.probe.postcode"); + System.out.println("\n================ xincang / api.add_order_multiple → get_order → delete_order ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + String warehouseCode = XincangProbeSupport.warehouseCode(adapter); + String carrier = XincangProbeSupport.carrier(adapter); + if (warehouseCode == null || carrier == null) { + System.out.println(" [skip] 缺少仓代码或承运商,跳过"); + return; + } + String requestNo = "PROBE-" + XincangProbeSupport.uniqueSuffix(); + + OutboundCommand command = OutboundCommand.builder() + .outboundRequestNo(requestNo) + .orderRef(requestNo) + .labelMode(LabelMode.WAREHOUSE_LABEL) + .salesPlatform(Platform.CUSTOM) + .carrierCode(carrier) + .warehouseId(warehouseCode) + .splitOrder(true) + .shipTo(ShipTo.builder() + .name("Probe Receiver") + .phone("5550000000") + .countryCode("US") + .stateOrProvince("CA") + .city("Fontana") + .addressLine1("1 Probe Street") + .postalCode(XincangProbeSupport.POSTCODE) + .build()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku(XincangProbeSupport.SKU) + .quantity(XincangProbeSupport.qty()) + .declareName("Probe Item") + .build()) + .build(); + + OutboundReceipt receipt = XincangProbeSupport.step("add_order_multiple ckh=" + requestNo, + () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), command)); + if (receipt == null || receipt.providerOrderId() == null) { + return; + } + System.out.println(" providerOrderId=" + receipt.providerOrderId()); + + OutboundOrder order = XincangProbeSupport.step("get_order 回读", + () -> adapter.get(XincangProbeSupport.ctx(warehouseCode), + OutboundRef.ofProviderOrderId(receipt.providerOrderId()))); + if (order != null) { + System.out.println(" status=" + order.status() + "(raw=" + order.rawStatus() + ")" + + " ref=" + order.orderRef() + + " lines=" + order.lines().size()); + System.out.println(" checkCancel=" + XincangProbeSupport.step("checkCancel", + () -> adapter.checkCancel(XincangProbeSupport.ctx(warehouseCode), + OutboundRef.ofProviderOrderId(receipt.providerOrderId())))); + } + + XincangProbeSupport.step("delete_order 自清理", + () -> adapter.cancel(XincangProbeSupport.ctx(warehouseCode), + common.ecommerce.warehouse.model.CancelCommand.builder() + .providerOrderId(receipt.providerOrderId()) + .build())); + } + + // ================================================================ 转运 + + /** + * 转运闭环:建转运 → 详情回读 → 删除(仅待审核可删)。 + */ + @Test + void probeTransferRoundTrip() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + XincangProbeSupport.requireProperty("xincang.probe.destWarehouse"); + System.out.println("\n================ xincang / fba.do_fba → fba_detail → fba.delete_fba ================"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + String warehouseCode = XincangProbeSupport.warehouseCode(adapter); + if (warehouseCode == null) { + System.out.println(" [skip] 缺少仓代码,跳过"); + return; + } + String transferNo = "PROBE-" + XincangProbeSupport.uniqueSuffix(); + String destWarehouse = XincangProbeSupport.opt("xincang.probe.destWarehouse", ""); + + TransferCommand command = TransferCommand.builder() + .transferRequestNo(transferNo) + .type(TransferType.OUTBOUND) + .fromWarehouseCode(warehouseCode) + .toWarehouseCode(destWarehouse) + .po(transferNo) + // 信仓只用 pre_send_time;到仓日期与收件地址它都不收, + // 这里不传,顺便验证模型已不再强制这两个字段 + .estimateOutboundDate(LocalDate.now().plusDays(1)) + .deliveryMode(XincangProbeSupport.opt("xincang.probe.deliveryMode", "")) + .deliveryWay(XincangProbeSupport.opt("xincang.probe.deliveryWay", "")) + .orderType(XincangProbeSupport.opt("xincang.probe.orderType", "")) + .palletRequired(Boolean.FALSE) + .line(XincangProbeSupport.SKU, XincangProbeSupport.qty()) + .build(); + + TransferOrder created = XincangProbeSupport.step("do_fba fba_no=" + transferNo, + () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), command)); + if (created == null || created.providerTransferNo() == null) { + return; + } + String providerNo = created.providerTransferNo(); + System.out.println(" providerTransferNo=" + providerNo + " status=" + created.status()); + + XincangProbeSupport.step("fba_detail 回读", + () -> adapter.getTransfer(XincangProbeSupport.ctx(warehouseCode), providerNo)); + + XincangProbeSupport.step("fba.delete_fba 自清理", + () -> adapter.deleteTransfer(XincangProbeSupport.ctx(warehouseCode), providerNo)); + } + + /** + * 转运审核:建转运 → 审核。 + * + *

审核之后不能删除,会在测试环境留下数据,默认不跑; + * 需要显式加 {@code -Dxincang.probe.transferApprove=true}。

+ */ + @Test + void probeTransferApprove() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.transferApprove"); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + XincangProbeSupport.requireProperty("xincang.probe.destWarehouse"); + System.out.println("\n================ xincang / fba.do_approve ================"); + System.out.println(" [注意] 审核后的转运单无法删除,会留下数据。"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + String warehouseCode = XincangProbeSupport.warehouseCode(adapter); + if (warehouseCode == null) { + System.out.println(" [skip] 缺少仓代码,跳过"); + return; + } + String transferNo = "PROBE-APPROVE-" + XincangProbeSupport.uniqueSuffix(); + TransferCommand command = TransferCommand.builder() + .transferRequestNo(transferNo) + .type(TransferType.OUTBOUND) + .fromWarehouseCode(warehouseCode) + .toWarehouseCode(XincangProbeSupport.opt("xincang.probe.destWarehouse", "")) + .po(transferNo) + .estimateOutboundDate(LocalDate.now().plusDays(1)) + .deliveryMode(XincangProbeSupport.opt("xincang.probe.deliveryMode", "")) + .deliveryWay(XincangProbeSupport.opt("xincang.probe.deliveryWay", "")) + .orderType(XincangProbeSupport.opt("xincang.probe.orderType", "")) + .palletRequired(Boolean.FALSE) + .line(XincangProbeSupport.SKU, XincangProbeSupport.qty()) + .build(); + + TransferOrder created = XincangProbeSupport.step("do_fba", + () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), command)); + if (created == null || created.providerTransferNo() == null) { + return; + } + XincangProbeSupport.step("do_approve " + created.providerTransferNo(), + () -> adapter.approve(XincangProbeSupport.ctx(warehouseCode), + created.providerTransferNo())); + } + + // ================================================================ 预报 + + /** + * 预报闭环:新增 → 完善资料 → 提交 → 详情回读。 + * + *

没有删除接口,跑完会在测试环境留下预报单。

+ */ + @Test + void probeForecastRoundTrip() { + XincangProbeSupport.requireCredentials(); + XincangProbeSupport.requireProperty("xincang.probe.sku"); + System.out.println("\n================ xincang / forecast.do_forecast → improve → done → detail ================"); + System.out.println(" [注意] 预报没有删除接口,会留下数据。"); + XincangAdapter adapter = XincangProbeSupport.adapter(); + String warehouseCode = XincangProbeSupport.warehouseCode(adapter); + if (warehouseCode == null) { + System.out.println(" [skip] 缺少仓代码,跳过"); + return; + } + String suffix = XincangProbeSupport.uniqueSuffix(); + String requestNo = "PROBE-FC-" + suffix; + + InboundCommand head = InboundCommand.builder() + .inboundRequestNo(requestNo) + .warehouseId(warehouseCode) + .shipmentType(XincangProbeSupport.opt("xincang.probe.shipmentType", "2")) + .cabinetType(XincangProbeSupport.opt("xincang.probe.cabinetType", "1")) + .containerNo("PROBE-CAB-" + suffix) + .predictionShipDate(LocalDate.now().plusDays(1)) + .estimateArriveDate(LocalDate.now().plusDays(30)) + .deliveryRequirements(XincangProbeSupport.opt("xincang.probe.deliveryRequirements", "1")) + .line(InboundLine.builder() + .omsSku(XincangProbeSupport.SKU) + .providerSku(XincangProbeSupport.SKU) + .quantity(XincangProbeSupport.qty()) + .build()) + .build(); + + InboundReceipt receipt = XincangProbeSupport.step("do_forecast fba_no=" + requestNo, + () -> adapter.create(XincangProbeSupport.ctx(warehouseCode), head)); + if (receipt == null || receipt.providerInboundId() == null) { + return; + } + String forecastNo = receipt.providerInboundId(); + System.out.println(" forecast_no=" + forecastNo); + + InboundCommand improve = InboundCommand.builder() + .inboundRequestNo(requestNo) + .warehouseId(warehouseCode) + .shipmentType(XincangProbeSupport.opt("xincang.probe.shipmentType", "2")) + .cabinetType(XincangProbeSupport.opt("xincang.probe.cabinetType", "1")) + .containerNo("PROBE-CAB-" + suffix) + .predictionShipDate(LocalDate.now().plusDays(1)) + .estimateArriveDate(LocalDate.now().plusDays(30)) + .deliveryRequirements(XincangProbeSupport.opt("xincang.probe.deliveryRequirements", "1")) + .referenceNo("REF-" + suffix) + .otherNeed(XincangProbeSupport.opt("xincang.probe.otherNeed", "")) + .line(InboundLine.builder() + .omsSku(XincangProbeSupport.SKU) + .providerSku(XincangProbeSupport.SKU) + .quantity(XincangProbeSupport.qty()) + .build()) + .build(); + + XincangProbeSupport.step("do_improve_forecast", + () -> adapter.improve(XincangProbeSupport.ctx(warehouseCode), forecastNo, improve)); + XincangProbeSupport.step("done_forecast", + () -> adapter.submit(XincangProbeSupport.ctx(warehouseCode), forecastNo)); + + InboundOrder detail = XincangProbeSupport.step("forecast_detail 回读", + () -> adapter.get(XincangProbeSupport.ctx(warehouseCode), forecastNo)); + if (detail != null) { + System.out.println(" status=" + detail.status() + "(raw=" + detail.rawStatus() + ")" + + " boxCount=" + detail.boxCount() + + " lines=" + detail.lines().size()); + } + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java index d7195df..240cc31 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java @@ -37,6 +37,11 @@ public final class YqnInboundMapper { /** 统一命令 → 运去哪创建入库计划请求。 */ public static YqnCreateInboundDtos.CreateInboundPlanRequest toRequest(InboundCommand cmd, String warehouseCode) { + // 运去哪要求至少一条商品行;信仓「新增预报」不需要(明细走完善资料), + // 所以这条校验从 InboundCommand 构造期移到这里 + if (cmd.lines().isEmpty()) { + throw new IllegalArgumentException("yqn inbound plan requires at least one product line"); + } requireContainerNo(cmd.containerNo()); YqnCreateInboundDtos.CreateInboundPlanRequest req = new YqnCreateInboundDtos.CreateInboundPlanRequest(); diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java index de5409e..0f261cb 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java @@ -29,6 +29,15 @@ public final class YqnProductMapper { * 这里只做字段搬运与单位对齐(cm / g 与平台一致,不换算)。

*/ public static YqnProductDtos.SaveProductRequest toRequest(WarehouseProduct product) { + // 运去哪 API 115 把 packingType 列为必填;统一模型不再在构造期强制 + // (信仓没有该字段),所以在这里按运去哪的协议校验。 + if (product.packingType() < 0) { + throw new IllegalArgumentException( + "yqn product requires packingType (0 原包装发货 / 1 重新打包)"); + } + if (product.nameEn() == null || product.nameEn().trim().isEmpty()) { + throw new IllegalArgumentException("yqn product requires nameEn"); + } YqnProductDtos.SaveProductRequest req = new YqnProductDtos.SaveProductRequest(); req.sku = skuOf(product); req.customItemNo = product.customItemNo(); @@ -71,7 +80,8 @@ public final class YqnProductMapper { req.cost = cost.amount().doubleValue(); req.currency = cost.currencyCode(); } - req.customs = toCustoms(product.declaredValue(), product.hsCode(), product.countryOfOrigin()); + req.customs = toCustoms(product.declaredValue(), product.hsCode(), product.countryOfOrigin(), + product.omsSku()); return req; } @@ -115,8 +125,25 @@ public final class YqnProductMapper { } static List toCustoms(Money declaredValue, - String hsCode, String countryCode) { - if (declaredValue == null || isBlank(hsCode) || isBlank(countryCode)) { + String hsCode, String countryCode, + String sku) { + // 「三项整组给」的校验从 WarehouseProduct 构造期移到这里: + // 信仓只用 declaredValue 当 amount,不要求另外两项,模型层不能强制。 + int given = 0; + if (declaredValue != null) { + given++; + } + if (!isBlank(hsCode)) { + given++; + } + if (!isBlank(countryCode)) { + given++; + } + if (given != 0 && given != 3) { + throw new IllegalArgumentException( + "yqn product " + sku + " requires hsCode / countryOfOrigin / declaredValue together"); + } + if (given == 0) { return null; } // 运去哪海关只接受 USD。之前无脑把申报额贴成 USD,非美元申报会被静默算错, diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java index f3a03d7..d735864 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java @@ -30,8 +30,28 @@ public final class YqnTransferMapper { private YqnTransferMapper() { } - /** 统一命令 → 运去哪创建调拨单请求。 */ + /** + * 统一命令 → 运去哪创建调拨单请求。 + * + *

运去哪要求两个预计日期都给,且调拨出库必须带收货地址。这两条原本写在 + * {@link TransferCommand} 的构造期,会把运去哪的约束强加给其它仓(信仓转运只有 + * 发货日期、用仓库名代替地址),现在改到这里按运去哪的协议校验。

+ * + * @throws IllegalArgumentException 缺日期,或调拨出库缺收货地址 + */ public static YqnTransferDtos.CreateTransferPlanRequest toRequest(TransferCommand cmd) { + if (cmd.estimateOutboundDate() == null || cmd.estimateInboundDate() == null) { + throw new IllegalArgumentException( + "yqn transfer requires estimateOutboundDate and estimateInboundDate"); + } + if (cmd.estimateInboundDate().isBefore(cmd.estimateOutboundDate())) { + throw new IllegalArgumentException( + "estimateInboundDate must not be earlier than estimateOutboundDate"); + } + if (cmd.type() == common.ecommerce.warehouse.enums.TransferType.OUTBOUND + && cmd.shipTo() == null) { + throw new IllegalArgumentException("yqn transfer requires shipTo when type is OUTBOUND"); + } YqnTransferDtos.CreateTransferPlanRequest req = new YqnTransferDtos.CreateTransferPlanRequest(); req.type = YqnTransferType.codeOf(cmd.type()); req.orgWarehouseCode = cmd.fromWarehouseCode(); diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java index 7707a9a..3bb6b81 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java @@ -123,21 +123,38 @@ class YqnProductTest { } @Test - void halfCustomsIsRejectedAtBuildTime() { - assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder() + void halfCustomsIsRejectedByMapper() { + // 海关三项整组给原本在构造期校验,信仓只用 declaredValue 当 amount, + // 所以校验移到运去哪 mapper + WarehouseProduct halfCustoms = WarehouseProduct.builder() .omsSku("X").name("n").nameEn("n").packingType(0) .lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0) .hsCode("123") - .build()); + .build(); + assertThrows(IllegalArgumentException.class, + () -> YqnProductMapper.toRequest(halfCustoms)); } @Test void requiredFieldsAreEnforced() { - assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder() + // packingType 是运去哪的必填项,但统一模型里是可选(信仓没有该字段), + // 所以校验发生在 mapper,不是在构造期 + WarehouseProduct missingPackingType = WarehouseProduct.builder() .omsSku("X").name("n").nameEn("n") - // 缺 packingType .lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0) - .build()); + .build(); + assertThrows(IllegalArgumentException.class, + () -> YqnProductMapper.toRequest(missingPackingType)); + + // nameEn 也是运去哪的必填项,同样在 mapper 校验 + WarehouseProduct missingNameEn = WarehouseProduct.builder() + .omsSku("X").name("n").packingType(0) + .lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0) + .build(); + assertThrows(IllegalArgumentException.class, + () -> YqnProductMapper.toRequest(missingNameEn)); + + // 跨仓共识的必填项(长宽高 / 重量为正)仍在构造期校验 assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder() .omsSku("X").name("n").nameEn("n").packingType(0) .lengthCm(0).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)