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; @@ -2,29 +2,101 @@ package common.ecommerce.warehouse.capability;
import common.ecommerce.shared.support.Money;
/** 仓商品建档入参。 */
import java.util.Objects;
/**
* 仓商品建档入参。
*
* <p>单位写进字段名(cm / g),避免适配器之间靠注释约定换算。
* 运去哪 API 115 的必填项(sku / 中英文名 / 包装方式 / 长宽高 / 重量 / SN)
* 在这里都是必填,缺了在构造期就失败,而不是等平台报错。</p>
*/
public final class WarehouseProduct {
private final String omsSku;
private final String providerSku;
private final String customItemNo;
private final String barcode;
private final String name;
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 String hsCode;
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) {
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 = 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.hsCode = b.hsCode;
this.countryOfOrigin = b.countryOfOrigin;
this.weightKg = b.weightKg;
this.barcode = b.barcode;
this.declaredName = b.declaredName;
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() {
@ -35,10 +107,20 @@ public final class WarehouseProduct { @@ -35,10 +107,20 @@ public final class WarehouseProduct {
return omsSku;
}
/** 仓侧 SKU;未映射时适配器用 {@link #omsSku()}。 */
public String providerSku() {
return providerSku;
}
public String customItemNo() {
return customItemNo;
}
/** 条码 / UPC。 */
public String barcode() {
return barcode;
}
public String name() {
return name;
}
@ -47,6 +129,60 @@ public final class WarehouseProduct { @@ -47,6 +129,60 @@ public final class WarehouseProduct {
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() {
return declaredValue;
}
@ -55,35 +191,83 @@ public final class WarehouseProduct { @@ -55,35 +191,83 @@ public final class WarehouseProduct {
return hsCode;
}
/** 原产国 / 清关国家编码,ISO 3166-1 alpha-2。 */
public String countryOfOrigin() {
return countryOfOrigin;
}
public double weightKg() {
return weightKg;
public String declaredName() {
return declaredName;
}
public String barcode() {
return barcode;
public String declaredNameEn() {
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) {
if (v == null || v.trim().isEmpty()) {
if (!hasText(v)) {
throw new IllegalArgumentException(n + " must not be blank");
}
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 {
private String omsSku;
private String providerSku;
private String customItemNo;
private String barcode;
private String name;
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 String hsCode;
private String countryOfOrigin;
private double weightKg;
private String barcode;
private String declaredName;
private String declaredNameEn;
private Money cost;
private String link;
private String remark;
public Builder omsSku(String v) {
this.omsSku = v;
@ -95,6 +279,16 @@ public final class WarehouseProduct { @@ -95,6 +279,16 @@ public final class WarehouseProduct {
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) {
this.name = v;
return this;
@ -105,6 +299,73 @@ public final class WarehouseProduct { @@ -105,6 +299,73 @@ public final class WarehouseProduct {
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) {
this.declaredValue = v;
return this;
@ -120,16 +381,34 @@ public final class WarehouseProduct { @@ -120,16 +381,34 @@ public final class WarehouseProduct {
return this;
}
public Builder weightKg(double v) {
this.weightKg = v;
public Builder declaredName(String v) {
this.declaredName = v;
return this;
}
public Builder barcode(String v) {
this.barcode = v;
public Builder declaredNameEn(String 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;
}
/**
* @throws IllegalArgumentException 必填项缺失、尺寸/重量非正、海关三项不齐
*/
public WarehouseProduct build() {
return new WarehouseProduct(this);
}

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

@ -20,15 +20,12 @@ public final class YqnConstants { @@ -20,15 +20,12 @@ public final class YqnConstants {
public static final String PRODUCTION_BASE_URL = "https://open-hwc.yqn.com";
/**
* 组织级 Token 的请求头名。
*
* <p><b>待核对</b>(Spec §8.6 第 1 项):有效期、是否参与签名、是否需 IP 白名单。
* 先按「固定 token 放请求头」实现,核实后只改这一处。</p>
* 组织级 Token 的请求头名。API 115 文档确认:{@code x-api-key},固定值放请求头,无签名。
*/
public static final String TOKEN_HEADER = "token";
public static final String TOKEN_HEADER = "x-api-key";
/** 商品建档。 */
public static final String PATH_PRODUCT_CREATE = "/product/createEditProduct";
/** 商品创建 / 编辑(V1 推荐版)。 */
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
/** 出库单创建(一件代发 + 平台面单发货)。 */
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; @@ -8,6 +8,8 @@ import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
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.OutboundCancelChargeRequiredException;
import common.ecommerce.warehouse.error.WarehouseException;
@ -44,7 +46,7 @@ import java.util.Map; @@ -44,7 +46,7 @@ import java.util.Map;
* <p>字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」,
* 字段差异收敛在 {@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");
@ -74,10 +76,27 @@ public final class YqnAdapter implements OutboundCapable { @@ -74,10 +76,27 @@ public final class YqnAdapter implements OutboundCapable {
@Override
public java.util.EnumSet<WarehouseCapability> capabilities() {
return java.util.EnumSet.of(
WarehouseCapability.PRODUCT,
WarehouseCapability.OUTBOUND,
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

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

@ -0,0 +1,105 @@ @@ -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 @@ @@ -1,14 +1,15 @@
package common.ecommerce.yqn.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
import java.util.Map;
/**
* 运去哪报文结构。
*
* <p><b>字段名待核对</b>(Spec §8.6):本文档只写契约层,请求/响应字段由打样阶段
* 按官方文档逐项核对。这里先按运去哪文档的命名习惯落地,联调时只改本类与
* {@link YqnOutboundMapper},不动门面与模型。</p>
* <p>商品相关字段以 API 115 官方文档为准({@code /v1/product/save})。
* 出库相关字段仍待打样核对(Spec §8.6 第 2/5/9 项)。字段差异只改本类与
* 对应的 Mapper,不动门面与领域模型。</p>
*/
public final class YqnDtos {
@ -138,37 +139,114 @@ public final class YqnDtos { @@ -138,37 +139,114 @@ public final class YqnDtos {
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 customItemNo;
/** UPC 编码。 */
public String upc;
/** 1 成品 / 2 配件 / 3 耗材;不传默认成品。 */
public Integer productType;
/** 中文名称。 */
public String name;
/** 英文名称。 */
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 hsCode;
public String countryOfOrigin;
public double weight;
public String barcode;
}
/** 商品建档响应。 */
public static final class CreateProductResponse {
public String sku;
public String status;
}
/** 通用分页信封。 */
public static final class PageEnvelope<T> {
/** 是否保价 Y / N。 */
public String isInsuranceFlag;
/** 保价费用。 */
public Double isInsuranceRate;
/** 备注。 */
public String remark;
/** 报关中文名。 */
public String customName;
/** 报关英文名。 */
public String customNameEn;
/** 是否需要 SN 0 否 / 1 是。 */
public Integer isRequireSn;
/** 外包装样式 0 裸包装 / 1 销售包装 / 2 物流包装。 */
public Integer packageStyle;
/** 序列号管理方式 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; @@ -13,14 +13,18 @@ import common.ecommerce.yqn.YqnConstants;
/**
* 运去哪响应信封校验。
*
* <p><b>待核对</b>(Spec §8.6):运去哪的成功码字段名与取值未在文档中固化。
* 先按常见的 {@code code / message / data} 处理,成功码按 {@code "0"} 判定;
* 联调时如果实际是 {@code "200"} 或 {@code success=true},只改本类。</p>
* <p>运去哪统一信封(API 115 确认):</p>
* <pre>
* { "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 {
/** 待核对:成功码。 */
static final String SUCCESS_CODE = "0";
/** 业务成功码。 */
public static final int SUCCESS_CODE = 200;
private final String rawBody;
private final String requestId;
@ -83,24 +87,39 @@ public final class YqnEnvelope { @@ -83,24 +87,39 @@ public final class YqnEnvelope {
String body = response.body();
if (body == null || body.trim().isEmpty()) {
// 部分接口成功时无响应体;按成功处理
return new YqnEnvelope(body, requestId);
throw new ValidationException(ChannelException.builder()
.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()
.message("yqn business error: code=" + code + ", message=" + json.stringAt(body, "message"))
.message("yqn business error: code=" + code + ", message=" + messageOf(json, body))
.operation(operation)
.provider(YqnConstants.ADAPTER_ID)
.requestId(requestId)
.platformCode(code)
.platformCode(String.valueOf(code))
.rawResponse(truncate(body))
.retryable(false));
}
return new YqnEnvelope(body, requestId);
}
/** 原始响应体(可能为 null)。 */
/** 原始响应体(已确认业务成功)。 */
public String body() {
return rawBody;
}
@ -110,6 +129,23 @@ public final class YqnEnvelope { @@ -110,6 +129,23 @@ public final class YqnEnvelope {
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。 */
private static long retryAfterMillis(HttpResponse response) {
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 { @@ -77,7 +77,7 @@ class YqnAdapterTest {
void createMapsCommandAndReadsProviderOrderId() {
RecordingTransport transport = RecordingTransport.create()
.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());
common.ecommerce.warehouse.model.OutboundReceipt receipt =
@ -108,7 +108,7 @@ class YqnAdapterTest { @@ -108,7 +108,7 @@ class YqnAdapterTest {
void getMapsStatusAndTracking() {
RecordingTransport transport = RecordingTransport.create()
.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\","
+ "\"trackingNumber\":\"TRK1\",\"carrier\":\"FEDEX\","
+ "\"createTime\":\"2026-11-08 10:00:00\"}]}}"));
@ -128,7 +128,7 @@ class YqnAdapterTest { @@ -128,7 +128,7 @@ class YqnAdapterTest {
void checkCancelBlocksShippedOrder() {
RecordingTransport transport = RecordingTransport.create()
.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\"}]}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
@ -140,7 +140,7 @@ class YqnAdapterTest { @@ -140,7 +140,7 @@ class YqnAdapterTest {
void cancelChargedWithoutAcceptThrows() {
RecordingTransport transport = RecordingTransport.create()
.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\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
@ -159,7 +159,7 @@ class YqnAdapterTest { @@ -159,7 +159,7 @@ class YqnAdapterTest {
void businessErrorCodeBecomesException() {
RecordingTransport transport = RecordingTransport.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());
RuntimeException ex = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
@ -170,7 +170,7 @@ class YqnAdapterTest { @@ -170,7 +170,7 @@ class YqnAdapterTest {
@Test
void missingOrderNoIsNotSilentSuccess() {
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());
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 @@ @@ -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 { @@ -68,7 +68,7 @@ class YqnRequestFactoryTest {
assertEquals("POST", req.method());
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("{\"warehouseCode\":\"RF_NY_US\"}", req.body());
assertEquals("application/json", req.contentType());

Loading…
Cancel
Save