Browse Source

feat(yqn): 接入商品创建/编辑(API 115 /v1/product/save)

按官方文档落三条此前只能靠猜的契约:
- 鉴权头确认是 x-api-key(原来猜的 token)
- 响应信封确认是 statusCode/status/code/message,code=200 成功;
  空响应体或缺失 code 不再当作成功处理
- 商品路径确认是 /v1/product/save

新增 YqnProductMapper:统一 WarehouseProduct → SaveProductRequest。
customs 按“国家 + HS + 申报价值”整组下发,币种固定 USD;
没给全时整个 customs 不发。WarehouseProduct 在构造期就挡住半组字段。

WarehouseProduct 按 API 115 的必填项重写:packingType / 长宽高 / 重量 / SN
改为必填,单位写进字段名(cm、g),避免适配器之间靠注释约定换算。

出库相关的字段仍待打样核对(Spec §8.6 第 2/5/9 项)。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
067d815888
  1. 313
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  2. 11
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  3. 21
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  4. 105
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  5. 134
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  6. 60
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/http/YqnEnvelope.java
  7. 12
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java
  8. 152
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java
  9. 2
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/http/YqnRequestFactoryTest.java

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

@ -2,29 +2,101 @@ package common.ecommerce.warehouse.capability;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
/** 仓商品建档入参。 */ import java.util.Objects;
/**
* 仓商品建档入参。
*
* <p>单位写进字段名(cm / g),避免适配器之间靠注释约定换算。
* 运去哪 API 115 的必填项(sku / 中英文名 / 包装方式 / 长宽高 / 重量 / SN)
* 在这里都是必填,缺了在构造期就失败,而不是等平台报错。</p>
*/
public final class WarehouseProduct { public final class WarehouseProduct {
private final String omsSku; private final String omsSku;
private final String providerSku; private final String providerSku;
private final String customItemNo;
private final String barcode;
private final String name; private final String name;
private final String nameEn; private final String nameEn;
private final String description;
/** 产品类型:1 成品 / 2 配件 / 3 耗材;0 表示未指定(平台默认成品)。 */
private final int productType;
/** 发货包装:0 原包装发货 / 1 重新打包。 */
private final int packingType;
private final double lengthCm;
private final double widthCm;
private final double heightCm;
/** 重量,单位克。 */
private final double weightGrams;
/** 单品尺寸;任一项未给则为 0,表示不传。 */
private final double itemLengthCm;
private final double itemWidthCm;
private final double itemHeightCm;
/** 是否需要 SN:0 否 / 1 是。 */
private final int requireSn;
/** 外包装样式:0 裸包装 / 1 销售包装 / 2 物流包装;-1 表示不传。 */
private final int packageStyle;
/** 客退处理方式:0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认;-1 表示不传。 */
private final int returnDealMethod;
private final Money declaredValue; private final Money declaredValue;
private final String hsCode; private final String hsCode;
private final String countryOfOrigin; private final String countryOfOrigin;
private final double weightKg; /** 报关中文名。 */
private final String barcode; private final String declaredName;
/** 报关英文名。 */
private final String declaredNameEn;
private final Money cost;
private final String link;
private final String remark;
private WarehouseProduct(Builder b) { private WarehouseProduct(Builder b) {
this.omsSku = require(b.omsSku, "omsSku"); this.omsSku = require(b.omsSku, "omsSku");
this.providerSku = b.providerSku; this.providerSku = b.providerSku;
this.customItemNo = b.customItemNo;
this.barcode = b.barcode;
this.name = require(b.name, "name"); this.name = require(b.name, "name");
this.nameEn = b.nameEn; this.nameEn = require(b.nameEn, "nameEn");
this.description = b.description;
this.productType = b.productType;
if (b.packingType < 0) {
throw new IllegalArgumentException("packingType is required (0 原包装发货 / 1 重新打包)");
}
this.packingType = b.packingType;
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
this.heightCm = requirePositive(b.heightCm, "heightCm");
this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
this.itemLengthCm = b.itemLengthCm;
this.itemWidthCm = b.itemWidthCm;
this.itemHeightCm = b.itemHeightCm;
this.requireSn = b.requireSn;
this.packageStyle = b.packageStyle;
this.returnDealMethod = b.returnDealMethod;
this.declaredValue = b.declaredValue; this.declaredValue = b.declaredValue;
this.hsCode = b.hsCode; this.hsCode = b.hsCode;
this.countryOfOrigin = b.countryOfOrigin; this.countryOfOrigin = b.countryOfOrigin;
this.weightKg = b.weightKg; this.declaredName = b.declaredName;
this.barcode = b.barcode; this.declaredNameEn = b.declaredNameEn;
this.cost = b.cost;
this.link = b.link;
this.remark = b.remark;
// 海关信息要么整组给、要么整组不给:国家编码 / 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");
}
} }
public static Builder builder() { public static Builder builder() {
@ -35,10 +107,20 @@ public final class WarehouseProduct {
return omsSku; return omsSku;
} }
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */
public String providerSku() { public String providerSku() {
return providerSku; return providerSku;
} }
public String customItemNo() {
return customItemNo;
}
/** 条码 / UPC。 */
public String barcode() {
return barcode;
}
public String name() { public String name() {
return name; return name;
} }
@ -47,6 +129,60 @@ public final class WarehouseProduct {
return nameEn; return nameEn;
} }
public String description() {
return description;
}
public int productType() {
return productType;
}
public int packingType() {
return packingType;
}
public double lengthCm() {
return lengthCm;
}
public double widthCm() {
return widthCm;
}
public double heightCm() {
return heightCm;
}
/** 重量,单位克。 */
public double weightGrams() {
return weightGrams;
}
public double itemLengthCm() {
return itemLengthCm;
}
public double itemWidthCm() {
return itemWidthCm;
}
public double itemHeightCm() {
return itemHeightCm;
}
public int requireSn() {
return requireSn;
}
public int packageStyle() {
return packageStyle;
}
public int returnDealMethod() {
return returnDealMethod;
}
/** 申报价值;未设置时为 null,此时不传海关信息。 */
public Money declaredValue() { public Money declaredValue() {
return declaredValue; return declaredValue;
} }
@ -55,35 +191,83 @@ public final class WarehouseProduct {
return hsCode; return hsCode;
} }
/** 原产国 / 清关国家编码,ISO 3166-1 alpha-2。 */
public String countryOfOrigin() { public String countryOfOrigin() {
return countryOfOrigin; return countryOfOrigin;
} }
public double weightKg() { public String declaredName() {
return weightKg; return declaredName;
} }
public String barcode() { public String declaredNameEn() {
return barcode; return declaredNameEn;
}
public Money cost() {
return cost;
}
public String link() {
return link;
}
public String remark() {
return remark;
}
/** 是否给了任何海关信息。 */
public boolean hasCustoms() {
return declaredValue != null;
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
} }
private static String require(String v, String n) { private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) { if (!hasText(v)) {
throw new IllegalArgumentException(n + " must not be blank"); throw new IllegalArgumentException(n + " must not be blank");
} }
return v.trim(); return v.trim();
} }
private static double requirePositive(double v, String n) {
if (v <= 0) {
throw new IllegalArgumentException(n + " must be positive");
}
return v;
}
public static final class Builder { public static final class Builder {
private String omsSku; private String omsSku;
private String providerSku; private String providerSku;
private String customItemNo;
private String barcode;
private String name; private String name;
private String nameEn; private String nameEn;
private String description;
private int productType;
private int packingType = -1;
private double lengthCm;
private double widthCm;
private double heightCm;
private double weightGrams;
private double itemLengthCm;
private double itemWidthCm;
private double itemHeightCm;
private int requireSn;
private int packageStyle = -1;
private int returnDealMethod = -1;
private Money declaredValue; private Money declaredValue;
private String hsCode; private String hsCode;
private String countryOfOrigin; private String countryOfOrigin;
private double weightKg; private String declaredName;
private String barcode; private String declaredNameEn;
private Money cost;
private String link;
private String remark;
public Builder omsSku(String v) { public Builder omsSku(String v) {
this.omsSku = v; this.omsSku = v;
@ -95,6 +279,16 @@ public final class WarehouseProduct {
return this; return this;
} }
public Builder customItemNo(String v) {
this.customItemNo = v;
return this;
}
public Builder barcode(String v) {
this.barcode = v;
return this;
}
public Builder name(String v) { public Builder name(String v) {
this.name = v; this.name = v;
return this; return this;
@ -105,6 +299,73 @@ public final class WarehouseProduct {
return this; return this;
} }
public Builder description(String v) {
this.description = v;
return this;
}
public Builder productType(int v) {
this.productType = v;
return this;
}
/** 0 原包装发货 / 1 重新打包;<b>必填</b>。 */
public Builder packingType(int v) {
this.packingType = v;
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 itemLengthCm(double v) {
this.itemLengthCm = v;
return this;
}
public Builder itemWidthCm(double v) {
this.itemWidthCm = v;
return this;
}
public Builder itemHeightCm(double v) {
this.itemHeightCm = v;
return this;
}
public Builder requireSn(int v) {
this.requireSn = v;
return this;
}
public Builder packageStyle(int v) {
this.packageStyle = v;
return this;
}
public Builder returnDealMethod(int v) {
this.returnDealMethod = v;
return this;
}
public Builder declaredValue(Money v) { public Builder declaredValue(Money v) {
this.declaredValue = v; this.declaredValue = v;
return this; return this;
@ -120,16 +381,34 @@ public final class WarehouseProduct {
return this; return this;
} }
public Builder weightKg(double v) { public Builder declaredName(String v) {
this.weightKg = v; this.declaredName = v;
return this; return this;
} }
public Builder barcode(String v) { public Builder declaredNameEn(String v) {
this.barcode = v; this.declaredNameEn = v;
return this;
}
public Builder cost(Money v) {
this.cost = v;
return this;
}
public Builder link(String v) {
this.link = v;
return this;
}
public Builder remark(String v) {
this.remark = v;
return this; return this;
} }
/**
* @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐
*/
public WarehouseProduct build() { public WarehouseProduct build() {
return new WarehouseProduct(this); return new WarehouseProduct(this);
} }

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

@ -20,15 +20,12 @@ public final class YqnConstants {
public static final String PRODUCTION_BASE_URL = "https://open-hwc.yqn.com"; public static final String PRODUCTION_BASE_URL = "https://open-hwc.yqn.com";
/** /**
* 组织级 Token 的请求头名。 * 组织级 Token 的请求头名。API 115 文档确认:{@code x-api-key},固定值放请求头,无签名。
*
* <p><b>待核对</b>(Spec §8.6 第 1 项):有效期、是否参与签名、是否需 IP 白名单。
* 先按「固定 token 放请求头」实现,核实后只改这一处。</p>
*/ */
public static final String TOKEN_HEADER = "token"; public static final String TOKEN_HEADER = "x-api-key";
/** 商品建档。 */ /** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_CREATE = "/product/createEditProduct"; public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 出库单创建(一件代发 + 平台面单发货)。 */ /** 出库单创建(一件代发 + 平台面单发货)。 */
public static final String PATH_ORDER_CREATE = "/saleorder/OrderCreate"; public static final String PATH_ORDER_CREATE = "/saleorder/OrderCreate";
/** 出库单查询。 */ /** 出库单查询。 */

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

@ -8,6 +8,8 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException;
import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.error.WarehouseException;
@ -44,7 +46,7 @@ import java.util.Map;
* <p>字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」, * <p>字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」,
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p> * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/ */
public final class YqnAdapter implements OutboundCapable { public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable {
/** 运去哪请求里的时间格式;待核对。 */ /** 运去哪请求里的时间格式;待核对。 */
private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
@ -74,10 +76,27 @@ public final class YqnAdapter implements OutboundCapable {
@Override @Override
public java.util.EnumSet<WarehouseCapability> capabilities() { public java.util.EnumSet<WarehouseCapability> capabilities() {
return java.util.EnumSet.of( return java.util.EnumSet.of(
WarehouseCapability.PRODUCT,
WarehouseCapability.OUTBOUND, WarehouseCapability.OUTBOUND,
WarehouseCapability.SPLIT); WarehouseCapability.SPLIT);
} }
// ------------------------------------------------------------------ 商品
/**
* 创建 / 编辑商品(API 115,{@code /v1/product/save})。
*
* <p>接口本身是保存语义(同 SKU 再调即更新),因此不区分 create 与 update。
* 响应只有 {@code code/message},没有 data,所以结果里只回填请求侧 SKU。</p>
*/
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
YqnDtos.SaveProductRequest body = YqnProductMapper.toRequest(product);
String raw = execute(ctx, YqnConstants.PATH_PRODUCT_SAVE, body, "warehouse.product.create");
return ProductResult.of(YqnProductMapper.skuOf(product), "SAVED",
json.stringAt(raw, "message"));
}
// ------------------------------------------------------------------ 出库 // ------------------------------------------------------------------ 出库
@Override @Override

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

@ -0,0 +1,105 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.yqn.dto.YqnDtos;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
/**
* 运去哪商品报文映射(API 115 / {@code /v1/product/save})。
*
* <p>平台字段名只出现在本类与 {@link YqnDtos}。</p>
*/
public final class YqnProductMapper {
/** 运去哪清关信息只接受美元。 */
private static final String CUSTOMS_CURRENCY = "USD";
private YqnProductMapper() {
}
/**
* 统一商品 → 运去哪保存请求。
*
* <p>运去哪必填的长宽高与重量在 {@link WarehouseProduct} 构造期已校验,
* 这里只做字段搬运与单位对齐(cm / g 与平台一致,不换算)。</p>
*/
public static YqnDtos.SaveProductRequest toRequest(WarehouseProduct product) {
YqnDtos.SaveProductRequest req = new YqnDtos.SaveProductRequest();
req.sku = skuOf(product);
req.customItemNo = product.customItemNo();
req.upc = product.barcode();
req.productType = product.productType() > 0 ? product.productType() : null;
req.name = product.name();
req.nameEn = product.nameEn();
req.description = product.description();
req.packingType = product.packingType();
req.length = product.lengthCm();
req.width = product.widthCm();
req.height = product.heightCm();
req.weight = product.weightGrams();
req.itemLength = positiveOrNull(product.itemLengthCm());
req.itemWidth = positiveOrNull(product.itemWidthCm());
req.itemHeight = positiveOrNull(product.itemHeightCm());
req.isRequireSn = product.requireSn();
req.packageStyle = product.packageStyle() >= 0 ? product.packageStyle() : null;
req.returnDealMethod = product.returnDealMethod() >= 0 ? product.returnDealMethod() : null;
req.customName = product.declaredName();
req.customNameEn = product.declaredNameEn();
req.link = product.link();
req.remark = product.remark();
Money cost = product.cost();
if (cost != null) {
req.cost = cost.amount().doubleValue();
req.currency = cost.currencyCode();
}
req.customs = toCustoms(product.declaredValue(), product.hsCode(), product.countryOfOrigin());
return req;
}
/** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */
public static String skuOf(WarehouseProduct product) {
String providerSku = product.providerSku();
if (providerSku != null && !providerSku.trim().isEmpty()) {
return providerSku.trim();
}
return product.omsSku();
}
/**
* 海关信息:国家编码 + HS Code + 进口申报价值/币种 构成一条。
*
* <p>三项没有整组给时返回 null(不发 customs),
* {@link WarehouseProduct} 已在构造期挡掉「只给一半」的情况。</p>
*/
static List<YqnDtos.SaveProductRequest.Customs> toCustoms(Money declaredValue,
String hsCode, String countryCode) {
if (declaredValue == null || isBlank(hsCode) || isBlank(countryCode)) {
return null;
}
YqnDtos.SaveProductRequest.Customs customs = new YqnDtos.SaveProductRequest.Customs();
customs.countryCode = countryCode.trim().toUpperCase(Locale.ROOT);
customs.customCode = hsCode.trim();
customs.importDeclaredValue = declaredValue.amount().doubleValue();
customs.importDeclaredCurrency = CUSTOMS_CURRENCY;
customs.exportDeclaredValue = declaredValue.amount().doubleValue();
customs.exportDeclaredCurrency = CUSTOMS_CURRENCY;
List<YqnDtos.SaveProductRequest.Customs> out =
new ArrayList<YqnDtos.SaveProductRequest.Customs>(1);
out.add(customs);
return out;
}
private static Double positiveOrNull(double v) {
return v > 0 ? v : null;
}
private static boolean isBlank(String v) {
return v == null || v.trim().isEmpty();
}
}

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

@ -1,14 +1,15 @@
package common.ecommerce.yqn.dto; package common.ecommerce.yqn.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List; import java.util.List;
import java.util.Map;
/** /**
* 运去哪报文结构。 * 运去哪报文结构。
* *
* <p><b>字段名待核对</b>(Spec §8.6):本文档只写契约层,请求/响应字段由打样阶段 * <p>商品相关字段以 API 115 官方文档为准({@code /v1/product/save})。
* 按官方文档逐项核对。这里先按运去哪文档的命名习惯落地,联调时只改本类与 * 出库相关字段仍待打样核对(Spec §8.6 第 2/5/9 项)。字段差异只改本类与
* {@link YqnOutboundMapper},不动门面与模型。</p> * 对应的 Mapper,不动门面与领域模型。</p>
*/ */
public final class YqnDtos { public final class YqnDtos {
@ -138,37 +139,114 @@ public final class YqnDtos {
public String currency; public String currency;
} }
/** 商品建档请求。 */ /**
public static final class CreateProductRequest { * 商品创建 / 编辑请求(API 115,{@code /v1/product/save})。
*
* <p>必填:sku / name / nameEn / packingType / length / width / height / weight /
* isRequireSn。{@code customs} 数组里任一字段出现时,四项必须同时给。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class SaveProductRequest {
/** 产品 SKU。 */
public String sku; public String sku;
/** 自定义产品编码。 */
public String customItemNo;
/** UPC 编码。 */
public String upc;
/** 1 成品 / 2 配件 / 3 耗材;不传默认成品。 */
public Integer productType;
/** 中文名称。 */
public String name; public String name;
/** 英文名称。 */
public String nameEn; public String nameEn;
public String declaredValue; /** 产品描述;不填默认取 {@link #nameEn}。 */
public String description;
/** 0 原包装发货 / 1 重新打包。 */
public Integer packingType;
/** 产品长(cm),一箱多件的尺寸。 */
public Double length;
/** 产品宽(cm)。 */
public Double width;
/** 产品高(cm)。 */
public Double height;
/** 产品重量(g)。 */
public Double weight;
/** 单品长(cm)。 */
public Double itemLength;
/** 单品宽(cm)。 */
public Double itemWidth;
/** 单品高(cm)。 */
public Double itemHeight;
/** 保质期管理 0 否 / 1 是。 */
public Integer expirationControl;
/** 保质期天数。 */
public Integer expirationDate;
/** 装箱数量。 */
public Integer packedQty;
/** 外箱长(cm)。 */
public Double packedLength;
/** 外箱宽(cm)。 */
public Double packedWidth;
/** 外箱高(cm)。 */
public Double packedHeight;
/** 外箱重量(g)。 */
public Double packedWeight;
/** 成本。 */
public Double cost;
/** 币种。 */
public String currency; public String currency;
public String hsCode; /** 是否保价 Y / N。 */
public String countryOfOrigin; public String isInsuranceFlag;
public double weight; /** 保价费用。 */
public String barcode; public Double isInsuranceRate;
} /** 备注。 */
public String remark;
/** 商品建档响应。 */ /** 报关中文名。 */
public static final class CreateProductResponse { public String customName;
/** 报关英文名。 */
public String sku; public String customNameEn;
public String status; /** 是否需要 SN 0 否 / 1 是。 */
} public Integer isRequireSn;
/** 外包装样式 0 裸包装 / 1 销售包装 / 2 物流包装。 */
/** 通用分页信封。 */ public Integer packageStyle;
public static final class PageEnvelope<T> { /** 序列号管理方式 1 全链路 SN / 2 SN 出库采集。 */
public Integer snMgmtMode;
/** 客退处理方式 0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。 */
public Integer returnDealMethod;
/** 批次管理。 */
public LotControl lotControl;
/** 商品链接。 */
public String link;
/** 清关信息;各国一条。 */
public List<Customs> customs;
/** 批次管理。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class LotControl {
/** 是否开启批次管理 0 否 / 1 是。 */
public Integer lotEnabled;
/** 开启后必填:本商品需要开启的批次属性编码。 */
public List<String> lotAttrCodeList;
}
public T data; /** 一条进口海关信息;四项同进同退。 */
public int total; @JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Customs {
/** 国家编码,如 US。 */
public String countryCode;
/** HS Code。 */
public String customCode;
/** 进口申报价值。 */
public Double importDeclaredValue;
/** 进口申报价值币种,枚举仅 USD。 */
public String importDeclaredCurrency;
/** 出口申报价值。 */
public Double exportDeclaredValue;
/** 出口申报价值币种,枚举仅 USD。 */
public String exportDeclaredCurrency;
}
} }
/** 预留:运去哪接口若要求签名,参数放在这里。 */
public static final class SignRequest {
public Map<String, String> params;
}
} }

60
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/http/YqnEnvelope.java

@ -13,14 +13,18 @@ import common.ecommerce.yqn.YqnConstants;
/** /**
* 运去哪响应信封校验。 * 运去哪响应信封校验。
* *
* <p><b>待核对</b>(Spec §8.6):运去哪的成功码字段名与取值未在文档中固化。 * <p>运去哪统一信封(API 115 确认):</p>
* 先按常见的 {@code code / message / data} 处理,成功码按 {@code "0"} 判定; * <pre>
* 联调时如果实际是 {@code "200"} 或 {@code success=true},只改本类。</p> * { "statusCode": 200, "status": 0, "code": 200, "message": "产品创建成功" }
* </pre>
*
* <p>HTTP 恒为 200,成败看 <b>body 里的 {@code code}:200 成功</b>。401/403/429/5xx
* 仍按 HTTP 语义映射,便于网关或代理层直接拒绝时也能正确分类。</p>
*/ */
public final class YqnEnvelope { public final class YqnEnvelope {
/** 待核对:成功码。 */ /** 业务成功码。 */
static final String SUCCESS_CODE = "0"; public static final int SUCCESS_CODE = 200;
private final String rawBody; private final String rawBody;
private final String requestId; private final String requestId;
@ -83,24 +87,39 @@ public final class YqnEnvelope {
String body = response.body(); String body = response.body();
if (body == null || body.trim().isEmpty()) { if (body == null || body.trim().isEmpty()) {
// 部分接口成功时无响应体;按成功处理 throw new ValidationException(ChannelException.builder()
return new YqnEnvelope(body, requestId); .message("yqn returned an empty body; cannot verify business code")
.operation(operation)
.provider(YqnConstants.ADAPTER_ID)
.requestId(requestId)
.platformCode(String.valueOf(status))
.retryable(false));
} }
String code = json.stringAt(body, "code");
if (code != null && !SUCCESS_CODE.equals(code.trim())) { Integer code = intOrNull(json.stringAt(body, "code"));
if (code == null) {
throw new ValidationException(ChannelException.builder()
.message("yqn response has no business code: " + truncate(body))
.operation(operation)
.provider(YqnConstants.ADAPTER_ID)
.requestId(requestId)
.rawResponse(truncate(body))
.retryable(false));
}
if (code != SUCCESS_CODE) {
throw new PlatformBusinessException(ChannelException.builder() throw new PlatformBusinessException(ChannelException.builder()
.message("yqn business error: code=" + code + ", message=" + json.stringAt(body, "message")) .message("yqn business error: code=" + code + ", message=" + messageOf(json, body))
.operation(operation) .operation(operation)
.provider(YqnConstants.ADAPTER_ID) .provider(YqnConstants.ADAPTER_ID)
.requestId(requestId) .requestId(requestId)
.platformCode(code) .platformCode(String.valueOf(code))
.rawResponse(truncate(body)) .rawResponse(truncate(body))
.retryable(false)); .retryable(false));
} }
return new YqnEnvelope(body, requestId); return new YqnEnvelope(body, requestId);
} }
/** 原始响应体(可能为 null)。 */ /** 原始响应体(已确认业务成功)。 */
public String body() { public String body() {
return rawBody; return rawBody;
} }
@ -110,6 +129,23 @@ public final class YqnEnvelope {
return requestId; return requestId;
} }
/** 业务提示语;运去哪用 {@code message},兼容 {@code msg}。 */
private static String messageOf(JacksonJsonCodec json, String body) {
String message = json.stringAt(body, "message");
return message != null ? message : json.stringAt(body, "msg");
}
private static Integer intOrNull(String value) {
if (value == null || value.trim().isEmpty()) {
return null;
}
try {
return Integer.valueOf(value.trim());
} catch (NumberFormatException e) {
return null;
}
}
/** {@code Retry-After} 秒折算毫秒;缺失按 1s。 */ /** {@code Retry-After} 秒折算毫秒;缺失按 1s。 */
private static long retryAfterMillis(HttpResponse response) { private static long retryAfterMillis(HttpResponse response) {
String header = response.header("Retry-After"); String header = response.header("Retry-After");

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

@ -77,7 +77,7 @@ class YqnAdapterTest {
void createMapsCommandAndReadsProviderOrderId() { void createMapsCommandAndReadsProviderOrderId() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok( .route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"orderNo\":\"YQN202611090001\",\"status\":\"ACCEPTED\"}}")); "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orderNo\":\"YQN202611090001\",\"status\":\"ACCEPTED\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.model.OutboundReceipt receipt = common.ecommerce.warehouse.model.OutboundReceipt receipt =
@ -108,7 +108,7 @@ class YqnAdapterTest {
void getMapsStatusAndTracking() { void getMapsStatusAndTracking() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok( .route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"orders\":[{\"orderNo\":\"YQN1\"," "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orders\":[{\"orderNo\":\"YQN1\","
+ "\"customerOrderNo\":\"OB-3\",\"status\":\"SHIPPED\"," + "\"customerOrderNo\":\"OB-3\",\"status\":\"SHIPPED\","
+ "\"trackingNumber\":\"TRK1\",\"carrier\":\"FEDEX\"," + "\"trackingNumber\":\"TRK1\",\"carrier\":\"FEDEX\","
+ "\"createTime\":\"2026-11-08 10:00:00\"}]}}")); + "\"createTime\":\"2026-11-08 10:00:00\"}]}}"));
@ -128,7 +128,7 @@ class YqnAdapterTest {
void checkCancelBlocksShippedOrder() { void checkCancelBlocksShippedOrder() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok( .route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"orders\":[{\"orderNo\":\"YQN1\"," "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"orders\":[{\"orderNo\":\"YQN1\","
+ "\"customerOrderNo\":\"OB-4\",\"status\":\"SHIPPED\"}]}}")); + "\"customerOrderNo\":\"OB-4\",\"status\":\"SHIPPED\"}]}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
@ -140,7 +140,7 @@ class YqnAdapterTest {
void cancelChargedWithoutAcceptThrows() { void cancelChargedWithoutAcceptThrows() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CANCEL, req -> Responses.ok( .route(YqnConstants.PATH_ORDER_CANCEL, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"cancelType\":\"CHARGED\"," "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{\"cancelType\":\"CHARGED\","
+ "\"cancelFee\":\"5.00\",\"currency\":\"USD\"}}")); + "\"cancelFee\":\"5.00\",\"currency\":\"USD\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
@ -159,7 +159,7 @@ class YqnAdapterTest {
void businessErrorCodeBecomesException() { void businessErrorCodeBecomesException() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE, .route(YqnConstants.PATH_ORDER_CREATE,
req -> Responses.ok("{\"code\":\"1001\",\"message\":\"sku not found\"}")); req -> Responses.ok("{\"statusCode\":200,\"status\":0,\"code\":1001,\"message\":\"sku not found\"}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
RuntimeException ex = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class, RuntimeException ex = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
@ -170,7 +170,7 @@ class YqnAdapterTest {
@Test @Test
void missingOrderNoIsNotSilentSuccess() { void missingOrderNoIsNotSilentSuccess() {
RecordingTransport transport = RecordingTransport.create() RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok("{\"code\":\"0\",\"data\":{}}")); .route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok("{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class, org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,

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

@ -0,0 +1,152 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.yqn.YqnConstants;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 商品保存(API 115)契约测试。
*/
class YqnProductTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-09T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of("https://pr-hwc-open-api.yqn.com",
ChannelSecret.builder().appSecret("key-1").build()),
"req-1", CLOCK);
}
private static WarehouseProduct product() {
return WarehouseProduct.builder()
.omsSku("DM00001")
.name("测试商品")
.nameEn("Test Product")
.packingType(1)
.lengthCm(30)
.widthCm(20)
.heightCm(10)
.weightGrams(500)
.requireSn(0)
.build();
}
@Test
void savesProductWithDocumentedShape() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"产品创建成功\"}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.capability.WarehouseProductCapable.ProductResult result =
adapter.createOrUpdate(ctx(), product());
assertEquals("DM00001", result.providerSku());
assertEquals("SAVED", result.status());
assertEquals("产品创建成功", result.rawStatus());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"sku\":\"DM00001\""), body);
assertTrue(body.contains("\"nameEn\":\"Test Product\""), body);
assertTrue(body.contains("\"packingType\":1"), body);
assertTrue(body.contains("\"weight\":500.0"), body);
assertTrue(body.contains("\"isRequireSn\":0"), body);
// 未给的可选项不应出现
assertTrue(!body.contains("customs"), body);
assertTrue(!body.contains("\"cost\""), body);
assertEquals("key-1", transport.recorded().get(0).headers().get("x-api-key"));
}
@Test
void providerSkuWinsWhenMapped() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
WarehouseProduct mapped = WarehouseProduct.builder()
.omsSku("OMS-1")
.providerSku("YQN-1")
.name("测试商品")
.nameEn("Test")
.packingType(0)
.lengthCm(1).widthCm(1).heightCm(1).weightGrams(1)
.requireSn(0)
.build();
adapter.createOrUpdate(ctx(), mapped);
assertTrue(transport.lastDataRequest().body().contains("\"sku\":\"YQN-1\""));
}
@Test
void customsIsSentOnlyWhenAllThreeGiven() {
WarehouseProduct withCustoms = WarehouseProduct.builder()
.omsSku("DM00002")
.name("测试商品")
.nameEn("Test Product")
.packingType(0)
.lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
.requireSn(0)
.countryOfOrigin("us")
.hsCode("1234567890")
.declaredValue(Money.of("12.50", "USD"))
.build();
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_PRODUCT_SAVE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"}"));
new YqnAdapter(transport, new JacksonJsonCodec()).createOrUpdate(ctx(), withCustoms);
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"countryCode\":\"US\""), body);
assertTrue(body.contains("\"customCode\":\"1234567890\""), body);
assertTrue(body.contains("\"importDeclaredValue\":12.5"), body);
assertTrue(body.contains("\"importDeclaredCurrency\":\"USD\""), body);
}
@Test
void halfCustomsIsRejectedAtBuildTime() {
assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder()
.omsSku("X").name("n").nameEn("n").packingType(0)
.lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)
.hsCode("123")
.build());
}
@Test
void requiredFieldsAreEnforced() {
assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder()
.omsSku("X").name("n").nameEn("n")
// 缺 packingType
.lengthCm(1).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)
.build());
assertThrows(IllegalArgumentException.class, () -> WarehouseProduct.builder()
.omsSku("X").name("n").nameEn("n").packingType(0)
.lengthCm(0).widthCm(1).heightCm(1).weightGrams(1).requireSn(0)
.build());
}
@Test
void productCapabilityIsDeclared() {
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
}
}

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

@ -68,7 +68,7 @@ class YqnRequestFactoryTest {
assertEquals("POST", req.method()); assertEquals("POST", req.method());
assertEquals(BASE + "/saleorder/OrderCreate", req.url()); assertEquals(BASE + "/saleorder/OrderCreate", req.url());
assertEquals(TOKEN, req.headers().get(YqnConstants.TOKEN_HEADER)); assertEquals(TOKEN, req.headers().get("x-api-key"));
assertEquals("req-1", req.headers().get("requestId")); assertEquals("req-1", req.headers().get("requestId"));
assertEquals("{\"warehouseCode\":\"RF_NY_US\"}", req.body()); assertEquals("{\"warehouseCode\":\"RF_NY_US\"}", req.body());
assertEquals("application/json", req.contentType()); assertEquals("application/json", req.contentType());

Loading…
Cancel
Save