Browse Source

feat(yqn): 按 API 123 对接创建销售订单

文档把出库下单的契约定死了,替换掉此前按命名习惯猜的字段:

- 路径 /saleorder/OrderCreate → /v1/saleOrder/create
- 响应只有 data.orderId(仓内部数字 id),没有字符串单号;
  幂等结果引用改存这个 id
- 必填扩到 10 项:来源单号、完整收件地址、联系人电话、销售平台、商品行

OutboundCommand 补 API 123 需要的维度:
- salesPlatform 改必填,类型用渠道域的 Platform 枚举,由适配器映射到
  仓方平台码。仓按平台做路由与面单归属,不给就猜错,所以宁可构造期失败
- 新增 carrierCode / shipServiceLevel / latestShipDate /
  estimatedDeliveryTime / currency / packages
- ShipTo 补 addressLine3(运去哪要求地址最多三行)

新增 OutboundPackageSpec:多包裹拆单,尺寸 cm、重量 g、含包裹内 SKU 与
打包耗材编码。不传则由仓按默认规则打包。

未接的部分保持原样:FindOrderInfor / OrderCancel 仍是旧假设,
取消预判与包裹查询等查询类接口等文档再对齐。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
89ed0101f9
  1. 101
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
  2. 160
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundPackageSpec.java
  3. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java
  4. 1
      warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java
  5. 4
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  6. 10
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  7. 149
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  8. 188
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  9. 13
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java
  10. 2
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/http/YqnRequestFactoryTest.java

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

@ -1,7 +1,9 @@ @@ -1,7 +1,9 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.support.Money;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
@ -18,11 +20,24 @@ public final class OutboundCommand { @@ -18,11 +20,24 @@ public final class OutboundCommand {
private final String orderRef;
private final LabelMode labelMode;
private final String carrier;
/** 承运商服务代码,如 FedEx Ground。 */
private final String carrierCode;
private final String warehouseId;
private final ShipTo shipTo;
private final List<OutboundLine> lines;
private final List<OutboundPackageSpec> packages;
private final Money declaredTotal;
private final String remark;
/** 销售平台;仓方按平台做路由、面单与标签规则,必填。 */
private final Platform salesPlatform;
/** 发货时效等级。 */
private final String shipServiceLevel;
/** 最晚发货时间(UTC)。 */
private final Instant latestShipDate;
/** 最晚送达时间(UTC)。 */
private final Instant estimatedDeliveryTime;
/** 下单币种;null 时为 USD。 */
private final String currency;
private OutboundCommand(Builder b) {
if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) {
@ -32,14 +47,22 @@ public final class OutboundCommand { @@ -32,14 +47,22 @@ public final class OutboundCommand {
this.orderRef = b.orderRef;
this.labelMode = b.labelMode == null ? LabelMode.WAREHOUSE_LABEL : b.labelMode;
this.carrier = b.carrier;
this.carrierCode = b.carrierCode;
this.warehouseId = b.warehouseId;
this.shipTo = java.util.Objects.requireNonNull(b.shipTo, "shipTo");
if (b.lines.isEmpty()) {
throw new IllegalArgumentException("lines must not be empty");
}
this.lines = Collections.unmodifiableList(new ArrayList<OutboundLine>(b.lines));
this.packages = b.packages == null ? Collections.<OutboundPackageSpec>emptyList()
: Collections.unmodifiableList(new ArrayList<OutboundPackageSpec>(b.packages));
this.declaredTotal = b.declaredTotal;
this.remark = b.remark;
this.salesPlatform = java.util.Objects.requireNonNull(b.salesPlatform, "salesPlatform");
this.shipServiceLevel = b.shipServiceLevel;
this.latestShipDate = b.latestShipDate;
this.estimatedDeliveryTime = b.estimatedDeliveryTime;
this.currency = b.currency;
}
public static Builder builder() {
@ -65,6 +88,11 @@ public final class OutboundCommand { @@ -65,6 +88,11 @@ public final class OutboundCommand {
return carrier;
}
/** 承运商服务代码(物流商服务 code);为 null 时走仓的分物流渠道规则。 */
public String carrierCode() {
return carrierCode;
}
/** 仓侧仓 ID;为 null 时适配器用账户配置里的仓。 */
public String warehouseId() {
return warehouseId;
@ -78,6 +106,11 @@ public final class OutboundCommand { @@ -78,6 +106,11 @@ public final class OutboundCommand {
return lines;
}
/** 包裹拆分信息;空列表表示交给仓按默认规则打包。 */
public List<OutboundPackageSpec> packages() {
return packages;
}
public Money declaredTotal() {
return declaredTotal;
}
@ -86,17 +119,49 @@ public final class OutboundCommand { @@ -86,17 +119,49 @@ public final class OutboundCommand {
return remark;
}
/** 销售平台,必填。 */
public Platform salesPlatform() {
return salesPlatform;
}
/** 发货时效等级;null 为标准。 */
public String shipServiceLevel() {
return shipServiceLevel;
}
/** 最晚发货时间(UTC)。 */
public Instant latestShipDate() {
return latestShipDate;
}
/** 最晚送达时间(UTC)。 */
public Instant estimatedDeliveryTime() {
return estimatedDeliveryTime;
}
/** 下单币种;null 时适配器按 USD 下发。 */
public String currency() {
return currency;
}
public static final class Builder {
private String outboundRequestNo;
private String orderRef;
private LabelMode labelMode;
private String carrier;
private String carrierCode;
private String warehouseId;
private ShipTo shipTo;
private final List<OutboundLine> lines = new ArrayList<OutboundLine>();
private List<OutboundPackageSpec> packages;
private Money declaredTotal;
private String remark;
private Platform salesPlatform;
private String shipServiceLevel;
private Instant latestShipDate;
private Instant estimatedDeliveryTime;
private String currency;
public Builder outboundRequestNo(String outboundRequestNo) {
this.outboundRequestNo = outboundRequestNo;
@ -118,11 +183,21 @@ public final class OutboundCommand { @@ -118,11 +183,21 @@ public final class OutboundCommand {
return this;
}
public Builder carrierCode(String carrierCode) {
this.carrierCode = carrierCode;
return this;
}
public Builder warehouseId(String warehouseId) {
this.warehouseId = warehouseId;
return this;
}
public Builder packages(List<OutboundPackageSpec> packages) {
this.packages = packages;
return this;
}
public Builder shipTo(ShipTo shipTo) {
this.shipTo = shipTo;
return this;
@ -150,6 +225,32 @@ public final class OutboundCommand { @@ -150,6 +225,32 @@ public final class OutboundCommand {
return this;
}
/** 销售平台,必填。 */
public Builder salesPlatform(Platform salesPlatform) {
this.salesPlatform = salesPlatform;
return this;
}
public Builder shipServiceLevel(String shipServiceLevel) {
this.shipServiceLevel = shipServiceLevel;
return this;
}
public Builder latestShipDate(Instant latestShipDate) {
this.latestShipDate = latestShipDate;
return this;
}
public Builder estimatedDeliveryTime(Instant estimatedDeliveryTime) {
this.estimatedDeliveryTime = estimatedDeliveryTime;
return this;
}
public Builder currency(String currency) {
this.currency = currency;
return this;
}
public OutboundCommand build() {
return new OutboundCommand(this);
}

160
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundPackageSpec.java

@ -0,0 +1,160 @@ @@ -0,0 +1,160 @@
package common.ecommerce.warehouse.model;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 出库包裹拆分信息。
*
* <p>仓支持多包裹拆单;{@link #skuInfos()} 为空且只有一个包裹时表示所有 SKU 装同一箱。
* 尺寸单位 cm、重量单位 g,与仓库域其它模型一致。</p>
*/
public final class OutboundPackageSpec {
private final String refNo;
private final double lengthCm;
private final double widthCm;
private final double heightCm;
private final double weightGrams;
private final List<SkuInfo> skuInfos;
/**
* 打包耗材:20 不使用耗材 / 21 纸箱打包 / 22 快递袋打包。
*
* <p>仓方必填;未指定时留空列表由适配器按平台默认补齐。</p>
*/
private final List<Integer> materialTypes;
private OutboundPackageSpec(Builder b) {
this.refNo = b.refNo;
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
this.heightCm = requirePositive(b.heightCm, "heightCm");
this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
for (SkuInfo sku : b.skuInfos) {
if (sku == null) {
throw new IllegalArgumentException("skuInfos must not contain null");
}
}
this.skuInfos = Collections.unmodifiableList(new ArrayList<SkuInfo>(b.skuInfos));
this.materialTypes = Collections.unmodifiableList(new ArrayList<Integer>(b.materialTypes));
}
public static Builder builder() {
return new Builder();
}
/** 包裹参考号;运去哪要求与附件里的 packageNo 一致。 */
public String refNo() {
return refNo;
}
public double lengthCm() {
return lengthCm;
}
public double widthCm() {
return widthCm;
}
public double heightCm() {
return heightCm;
}
public double weightGrams() {
return weightGrams;
}
/** 本包裹内的 SKU 与数量;空列表表示所有 SKU 都在这一箱。 */
public List<SkuInfo> skuInfos() {
return skuInfos;
}
/** 打包耗材编码;空列表表示未指定。 */
public List<Integer> materialTypes() {
return materialTypes;
}
private static double requirePositive(double v, String n) {
if (v <= 0) {
throw new IllegalArgumentException(n + " must be positive");
}
return v;
}
/** 包裹内一个 SKU 的数量。 */
public static final class SkuInfo {
private final String sku;
private final int qty;
public SkuInfo(String sku, int qty) {
if (sku == null || sku.trim().isEmpty()) {
throw new IllegalArgumentException("sku must not be blank");
}
if (qty <= 0) {
throw new IllegalArgumentException("qty must be positive");
}
this.sku = sku.trim();
this.qty = qty;
}
public String sku() {
return sku;
}
public int qty() {
return qty;
}
}
public static final class Builder {
private String refNo;
private double lengthCm;
private double widthCm;
private double heightCm;
private double weightGrams;
private final List<SkuInfo> skuInfos = new ArrayList<SkuInfo>();
private final List<Integer> materialTypes = new ArrayList<Integer>();
public Builder refNo(String refNo) {
this.refNo = refNo;
return this;
}
public Builder lengthCm(double v) {
this.lengthCm = v;
return this;
}
public Builder widthCm(double v) {
this.widthCm = v;
return this;
}
public Builder heightCm(double v) {
this.heightCm = v;
return this;
}
public Builder weightGrams(double v) {
this.weightGrams = v;
return this;
}
public Builder sku(String sku, int qty) {
this.skuInfos.add(new SkuInfo(sku, qty));
return this;
}
public Builder materialType(int code) {
this.materialTypes.add(code);
return this;
}
public OutboundPackageSpec build() {
return new OutboundPackageSpec(this);
}
}
}

12
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ShipTo.java

@ -17,6 +17,7 @@ public final class ShipTo { @@ -17,6 +17,7 @@ public final class ShipTo {
private final String city;
private final String addressLine1;
private final String addressLine2;
private final String addressLine3;
private final String postalCode;
private ShipTo(Builder b) {
@ -28,6 +29,7 @@ public final class ShipTo { @@ -28,6 +29,7 @@ public final class ShipTo {
this.city = Objects.requireNonNull(b.city, "city");
this.addressLine1 = Objects.requireNonNull(b.addressLine1, "addressLine1");
this.addressLine2 = b.addressLine2;
this.addressLine3 = b.addressLine3;
this.postalCode = b.postalCode;
}
@ -68,6 +70,10 @@ public final class ShipTo { @@ -68,6 +70,10 @@ public final class ShipTo {
return addressLine2;
}
public String addressLine3() {
return addressLine3;
}
public String postalCode() {
return postalCode;
}
@ -88,6 +94,7 @@ public final class ShipTo { @@ -88,6 +94,7 @@ public final class ShipTo {
private String city;
private String addressLine1;
private String addressLine2;
private String addressLine3;
private String postalCode;
public Builder name(String name) {
@ -130,6 +137,11 @@ public final class ShipTo { @@ -130,6 +137,11 @@ public final class ShipTo {
return this;
}
public Builder addressLine3(String addressLine3) {
this.addressLine3 = addressLine3;
return this;
}
public Builder postalCode(String postalCode) {
this.postalCode = postalCode;
return this;

1
warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java

@ -63,6 +63,7 @@ class WarehouseSdkTest { @@ -63,6 +63,7 @@ class WarehouseSdkTest {
.outboundRequestNo(requestNo)
.orderRef("SO-1")
.labelMode(LabelMode.WAREHOUSE_LABEL)
.salesPlatform(common.ecommerce.shared.model.Platform.WALMART_SC)
.shipTo(ShipTo.builder()
.name("B") // 测试数据
.countryCode("US")

4
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -26,8 +26,8 @@ public final class YqnConstants { @@ -26,8 +26,8 @@ public final class YqnConstants {
/** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 出库单创建(一件代发 + 平台面单发货)。 */
public static final String PATH_ORDER_CREATE = "/saleorder/OrderCreate";
/** 创建销售订单(API 123)。 */
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
/** 出库单查询。 */
public static final String PATH_ORDER_FIND = "/saleorder/FindOrderInfor";
/** 出库单取消。 */

10
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -105,11 +105,12 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -105,11 +105,12 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
YqnDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, warehouseId(ctx, cmd.warehouseId()));
String raw = execute(ctx, YqnConstants.PATH_ORDER_CREATE, body, "warehouse.outbound.create");
String providerOrderId = json.stringAt(raw, "data.orderNo");
// API 123 只回 data.orderId(仓内部数字 id),不回字符串单号
String providerOrderId = json.stringAt(raw, "data.orderId");
if (providerOrderId == null || providerOrderId.trim().isEmpty()) {
// 仓未返回单号时不能静默成功:幂等键记了成功但没法回查
// 仓未返回 id 时不能静默成功:幂等键记了成功但没法回查
throw WarehouseException.builder()
.message("yqn create returned no orderNo: " + safeRelay(raw))
.message("yqn create returned no data.orderId: " + safeRelay(raw))
.operation("warehouse.outbound.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
@ -118,8 +119,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -118,8 +119,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
.rawResponse(safeRelay(raw))
.build();
}
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderId,
json.stringAt(raw, "data.status"));
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderId, null);
}
@Override

149
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java

@ -2,13 +2,14 @@ package common.ecommerce.yqn.adapter; @@ -2,13 +2,14 @@ package common.ecommerce.yqn.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.model.CancelEligibility;
import common.ecommerce.warehouse.model.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundPackageSpec;
import common.ecommerce.warehouse.model.OutboundStatus;
import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.yqn.dto.YqnDtos;
@ -34,56 +35,135 @@ public final class YqnOutboundMapper { @@ -34,56 +35,135 @@ public final class YqnOutboundMapper {
/** 运去哪时间按仓所在地解释;账户未配时回退北京时区。 */
private static final ZoneId DEFAULT_ZONE = ZoneId.of("Asia/Shanghai");
/** 运去哪下单币种默认 USD。 */
private static final String DEFAULT_CURRENCY = "USD";
private YqnOutboundMapper() {
}
/** 统一命令 → 运去哪下单请求。 */
public static YqnDtos.CreateOrderRequest toRequest(OutboundCommand cmd, String warehouseId) {
/** 统一命令 → 运去哪创建销售订单请求(API 123)。 */
public static YqnDtos.CreateOrderRequest toRequest(OutboundCommand cmd, String warehouseCode) {
YqnDtos.CreateOrderRequest req = new YqnDtos.CreateOrderRequest();
req.warehouseCode = warehouseId;
req.customerOrderNo = cmd.outboundRequestNo();
req.referenceNo = cmd.orderRef();
req.labelMode = cmd.labelMode().name();
req.shippingMethod = cmd.carrier();
req.orderNo = cmd.outboundRequestNo();
req.poNumber = cmd.orderRef();
req.warehouseCode = warehouseCode;
req.carrier = cmd.carrier();
req.carrierCode = cmd.carrierCode();
req.currency = cmd.currency() == null ? DEFAULT_CURRENCY : cmd.currency();
req.shipServiceLevel = cmd.shipServiceLevel();
req.latestShipDate = formatTime(cmd.latestShipDate());
req.estimatedDeliveryTime = formatTime(cmd.estimatedDeliveryTime());
req.salesPlatform = salesPlatformOf(cmd.salesPlatform());
req.remark = cmd.remark();
req.receiver = toReceiver(cmd.shipTo());
req.items = toItems(cmd.lines());
ShipTo shipTo = cmd.shipTo();
req.shipToCountry = shipTo.countryCode();
req.shipToState = shipTo.stateOrProvince();
req.shipToCity = shipTo.city();
req.shipToPostal = shipTo.postalCode();
req.shipToAddress1 = shipTo.addressLine1();
req.shipToAddress2 = shipTo.addressLine2();
req.shipToAddress3 = shipTo.addressLine3();
req.shipToContact = shipTo.name();
req.shipToTelephone = shipTo.phone();
req.buyerName = shipTo.name();
req.buyerEmail = shipTo.email();
req.productItems = toProductItems(cmd.lines());
req.packageItems = toPackageItems(cmd.packages());
return req;
}
private static YqnDtos.CreateOrderRequest.Receiver toReceiver(ShipTo shipTo) {
YqnDtos.CreateOrderRequest.Receiver r = new YqnDtos.CreateOrderRequest.Receiver();
r.name = shipTo.name();
r.phone = shipTo.phone();
r.email = shipTo.email();
r.country = shipTo.countryCode();
r.state = shipTo.stateOrProvince();
r.city = shipTo.city();
r.address1 = shipTo.addressLine1();
r.address2 = shipTo.addressLine2();
r.zipCode = shipTo.postalCode();
return r;
/** 仓库域 Platform → 运去哪 salesPlatform 码;无映射按「其他」99。 */
static int salesPlatformOf(Platform platform) {
if (platform == null) {
throw new IllegalArgumentException(
"salesPlatform is required; warehouse routes and validates by platform");
}
switch (platform) {
case AMAZON_SC:
case AMAZON_VC:
return 1;
case WALMART_SC:
case WALMART_1P:
return 2;
case BESTBUY:
return 3;
case WAYFAIR:
return 5;
case TARGET:
return 6;
case TEMU:
return 9;
case TIKTOK:
return 10;
case EBAY:
return 11;
case SHEIN:
return 14;
case ALIEXPRESS:
return 15;
default:
return 99;
}
}
private static List<YqnDtos.CreateOrderRequest.OrderItem> toItems(List<OutboundLine> lines) {
List<YqnDtos.CreateOrderRequest.OrderItem> items =
new ArrayList<YqnDtos.CreateOrderRequest.OrderItem>(lines.size());
private static List<YqnDtos.CreateOrderRequest.ProductItem> toProductItems(List<OutboundLine> lines) {
List<YqnDtos.CreateOrderRequest.ProductItem> items =
new ArrayList<YqnDtos.CreateOrderRequest.ProductItem>(lines.size());
for (OutboundLine line : lines) {
YqnDtos.CreateOrderRequest.OrderItem item = new YqnDtos.CreateOrderRequest.OrderItem();
YqnDtos.CreateOrderRequest.ProductItem item = new YqnDtos.CreateOrderRequest.ProductItem();
item.sku = line.providerSku() != null ? line.providerSku() : line.omsSku();
item.quantity = line.quantity();
item.declareName = line.declareName();
item.declareNameEn = line.declareNameEn();
item.lineNo = line.lineNo();
Money value = line.declareValue();
item.declareValue = value == null ? null : value.amount().toPlainString();
item.currency = value == null ? null : value.currencyCode();
item.hsCode = line.hsCode();
item.countryOfOrigin = line.countryOfOrigin();
if (value != null) {
item.skuAmount = value.amount().doubleValue();
}
items.add(item);
}
return items;
}
private static List<YqnDtos.CreateOrderRequest.PackageItem> toPackageItems(
List<OutboundPackageSpec> packages) {
if (packages == null || packages.isEmpty()) {
return null;
}
List<YqnDtos.CreateOrderRequest.PackageItem> out =
new ArrayList<YqnDtos.CreateOrderRequest.PackageItem>(packages.size());
for (OutboundPackageSpec spec : packages) {
YqnDtos.CreateOrderRequest.PackageItem item = new YqnDtos.CreateOrderRequest.PackageItem();
item.refNo = spec.refNo();
item.length = spec.lengthCm();
item.width = spec.widthCm();
item.height = spec.heightCm();
item.weight = spec.weightGrams();
if (!spec.materialTypes().isEmpty()) {
item.materialType = new ArrayList<Integer>(spec.materialTypes());
}
if (!spec.skuInfos().isEmpty()) {
List<YqnDtos.CreateOrderRequest.PackageSku> skus =
new ArrayList<YqnDtos.CreateOrderRequest.PackageSku>(spec.skuInfos().size());
for (OutboundPackageSpec.SkuInfo sku : spec.skuInfos()) {
YqnDtos.CreateOrderRequest.PackageSku one =
new YqnDtos.CreateOrderRequest.PackageSku();
one.sku = sku.sku();
one.qty = sku.qty();
skus.add(one);
}
item.skuInfos = skus;
}
out.add(item);
}
return out;
}
/** 运去哪时间格式 {@code yyyy-MM-dd HH:mm:ss}。 */
static String formatTime(Instant instant) {
return instant == null ? null : TIME_FORMAT.format(instant.atZone(DEFAULT_ZONE));
}
/** 运去哪出库单 → 统一模型。 */
public static OutboundOrder toOrder(YqnDtos.OrderInfo info, String warehouseCode, ZoneId zone) {
return OutboundOrder.builder()
@ -180,11 +260,6 @@ public final class YqnOutboundMapper { @@ -180,11 +260,6 @@ public final class YqnOutboundMapper {
return CancelEligibility.BLOCKED;
}
/** 面单模式 → 能力要求的模式名。 */
public static String labelModeName(LabelMode mode) {
return mode == null ? LabelMode.WAREHOUSE_LABEL.name() : mode.name();
}
/** 解析运去哪时间;失败返回 null,不因时间格式阻断业务。 */
static Instant parseTime(String value, ZoneId zone) {
if (value == null || value.trim().isEmpty()) {

188
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -16,59 +16,169 @@ public final class YqnDtos { @@ -16,59 +16,169 @@ public final class YqnDtos {
private YqnDtos() {
}
/** 出库下单请求。 */
/**
* 创建销售订单请求(API 123,{@code /v1/saleOrder/create})。
*
* <p>必填:orderNo / shipToCountry / shipToState / shipToCity / shipToPostal /
* shipToAddress1 / shipToContact / shipToTelephone / salesPlatform / productItems。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CreateOrderRequest {
/** 仓编码(运去哪仓代码,如 RF_NY_US)。 */
/** 来源单号;用 OMS 的出库单号,仓侧回查与幂等锚点。 */
public String orderNo;
/** 承运商,如 FedEx / UPS。 */
public String carrier;
/** 物流商服务 Code;不传走仓的分物流渠道规则。 */
public String carrierCode;
/** 仓 code;不传走分仓规则。 */
public String warehouseCode;
/** 客户订单号;是否支持外部单号待核对(§8.6 第 2 项)。 */
public String customerOrderNo;
/** 参考单号。 */
public String referenceNo;
/** 面单模式:WAREHOUSE_LABEL / PLATFORM_LABEL。 */
public String labelMode;
/** 指定承运商,如 WLC-FEDEX。 */
public String shippingMethod;
/** 收件人。 */
public Receiver receiver;
/** 商品明细。 */
public List<OrderItem> items;
/** 备注。 */
/** 币种,不填默认 USD。 */
public String currency;
/** 支付时间 {@code yyyy-MM-dd HH:mm:ss};不填默认当前时间。 */
public String paidAt;
/** 目的国家,2 位字符。必填。 */
public String shipToCountry;
/** 目的州;美加为 2 位编码。必填。 */
public String shipToState;
/** 目的城市。必填。 */
public String shipToCity;
/** 发运邮编。必填。 */
public String shipToPostal;
/** 发运地址1。必填。 */
public String shipToAddress1;
public String shipToAddress2;
public String shipToAddress3;
/** 发运联系人。必填。 */
public String shipToContact;
/** 发运联系电话。必填。 */
public String shipToTelephone;
/** 客户姓名。 */
public String buyerName;
/** 客户邮箱。 */
public String buyerEmail;
/** third party 账号。 */
public String thirdPartyAccount;
/** 发货时效:Standard-48 Hours / Same Day Ship Out / Outbound First Class;不填为标准。 */
public String shipServiceLevel;
/** 平台订单号。 */
public String poNumber;
/** Amazon 店铺 Seller ID。 */
public String sellerCode;
/** 店铺名称;传入时会校验系统内是否存在。 */
public String channelAccount;
/** 订单特殊标签 0 无 / 1 SFP / 2 VC;不填默认无。 */
public Integer isPrime;
/** 最晚发货时间 {@code yyyy-MM-dd HH:mm:ss}。 */
public String latestShipDate;
/** 最晚送达时间 {@code yyyy-MM-dd HH:mm:ss}。 */
public String estimatedDeliveryTime;
/** 销售平台类型,码值见 API 123;必填。 */
public Integer salesPlatform;
/** ERP 来源类型;领星为 1。 */
public Integer erpPlatform;
public String remark;
/** 收件人(明文,OMS 先解密再下发)。 */
public static final class Receiver {
/** 产品行,必填。 */
public List<ProductItem> productItems;
/** 附件(面单 / 装箱单 / BOL 等);非必填,传了就要给全必填子字段。 */
public List<AttachInfoItem> attachInfoItems;
/** 发货包裹;不传则由仓按默认规则打包。 */
public List<PackageItem> packageItems;
/** 业务标签 100 售后卡 / 110 贴发票 / 20 不使用耗材 / 21 纸箱打包 / 22 快递袋打包 / 150 采集 SN。 */
public List<Integer> tags;
/** 产品行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ProductItem {
/** 发货产品 SKU。 */
public String sku;
/** 父商品 ERP SKU;箱产品必填。 */
public String parentErpsku;
/** 批次属性,JSON 字符串。 */
public String batchItems;
/** 商品形态 0 单一产品 / 2 箱产品;箱产品必填。 */
public Integer saleType;
/** 标准件数;箱产品必填。 */
public Integer standardQuantity;
/** 发货数量。 */
public Integer quantity;
/** 是否保价 0 否 / 1 是;不填从产品中心取。 */
public Integer isInsure;
/** 签收类型 0 不签收 / 1 直接 / 2 成人 / 3 间接;不填从产品中心取。 */
public Integer isSignature;
/** 当前 SKU 总金额(美元)。 */
public Double skuAmount;
/** 投保金额;保价时必填。 */
public Double insureAmount;
/** 商品货号。 */
public String articleNo;
/** EAN 条码。 */
public String ean;
/** 供应商货号。 */
public String supplierArticleNo;
/** 行号,当前订单内唯一。 */
public String lineNo;
/** 产品订单序列号;各平台语义不同。 */
public String skuOrderSn;
/** 产品交易序列号;各平台语义不同。 */
public String skuTransactionSn;
/** 危险品标签。 */
public String dangerousLabel;
/** 危险品标签数量。 */
public Integer dangerousLabelQty;
}
/** 附件。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class AttachInfoItem {
/** 附件名称,建议用 TrackingNo 且不带后缀。 */
public String name;
public String phone;
public String email;
public String country;
public String state;
public String city;
public String address1;
public String address2;
public String zipCode;
/** 附件 URL;与 {@link #file} 至少给一个。 */
public String url;
/** base64 内容;给了就忽略 url。 */
public String file;
/** 0 面单 / 1 装箱单 / 2 BOL / 3 其他 / 4 箱标 / 5 托盘标 / 6 商品标 / 7 发票 / 8 发货计划。 */
public Integer type;
/** base64 时的格式:png / pdf,默认 pdf。 */
public String fileType;
public String remark;
/** 包裹号,与包裹的 refNo 一致。 */
public String packageNo;
}
/** 商品行。 */
public static final class OrderItem {
/** 包裹。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class PackageItem {
public String refNo;
/** 长(cm),必填。 */
public Double length;
/** 宽(cm),必填。 */
public Double width;
/** 高(cm),必填。 */
public Double height;
/** 重量(g),必填。 */
public Double weight;
/** 包裹内 SKU;只有一个包裹时可省略,表示全部 SKU 同箱。 */
public List<PackageSku> skuInfos;
/** 打包耗材 20 / 21 / 22,必填。 */
public List<Integer> materialType;
}
/** 包裹内 SKU 数量。 */
public static final class PackageSku {
public String sku;
public int quantity;
public String declareName;
public String declareNameEn;
public String declareValue;
public String currency;
public String hsCode;
public String countryOfOrigin;
public Integer qty;
}
}
/** 出库下单响应。 */
/** 创建销售订单响应的 {@code data}。 */
public static final class CreateOrderResponse {
/** 运去哪订单号。 */
public String orderNo;
/** 仓受理状态原值。 */
public String status;
/** 仓侧订单 id,列表查询时可用。 */
public Long orderId;
}
/** 出库单查询请求。 */

13
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java

@ -51,6 +51,7 @@ class YqnAdapterTest { @@ -51,6 +51,7 @@ class YqnAdapterTest {
.outboundRequestNo(requestNo)
.orderRef("SO-1")
.labelMode(mode)
.salesPlatform(common.ecommerce.shared.model.Platform.WALMART_SC)
.carrier("WLC-FEDEX")
.warehouseId("RF_NY_US")
.shipTo(ShipTo.builder()
@ -77,20 +78,22 @@ class YqnAdapterTest { @@ -77,20 +78,22 @@ class YqnAdapterTest {
void createMapsCommandAndReadsProviderOrderId() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orderNo\":\"YQN202611090001\",\"status\":\"ACCEPTED\"}}"));
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orderId\":10001}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.model.OutboundReceipt receipt =
adapter.create(ctx(), command("OB-1", LabelMode.WAREHOUSE_LABEL));
assertEquals("OB-1", receipt.outboundRequestNo());
assertEquals("YQN202611090001", receipt.providerOrderId());
assertEquals("ACCEPTED", receipt.rawStatus());
assertEquals("10001", receipt.providerOrderId());
assertEquals(null, receipt.rawStatus());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"customerOrderNo\":\"OB-1\""), body);
assertTrue(body.contains("\"orderNo\":\"OB-1\""), body);
assertTrue(body.contains("\"sku\":\"DM00001\""), body);
assertTrue(body.contains("\"shippingMethod\":\"WLC-FEDEX\""), body);
assertTrue(body.contains("\"carrier\":\"WLC-FEDEX\""), body);
assertTrue(body.contains("\"salesPlatform\":2"), body);
assertTrue(body.contains("\"shipToContact\":\"Test\""), body);
assertEquals("token-1", transport.recorded().get(0).headers().get(YqnConstants.TOKEN_HEADER));
}

2
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/http/YqnRequestFactoryTest.java

@ -67,7 +67,7 @@ class YqnRequestFactoryTest { @@ -67,7 +67,7 @@ class YqnRequestFactoryTest {
secret(), ctx(), "warehouse.outbound.create");
assertEquals("POST", req.method());
assertEquals(BASE + "/saleorder/OrderCreate", req.url());
assertEquals(BASE + "/v1/saleOrder/create", req.url());
assertEquals(TOKEN, req.headers().get("x-api-key"));
assertEquals("req-1", req.headers().get("requestId"));
assertEquals("{\"warehouseCode\":\"RF_NY_US\"}", req.body());

Loading…
Cancel
Save