From 8078e72de9b0fb685ba86e48f4689d7b3db9a2e5 Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Mon, 9 Nov 2026 17:55:35 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5?=
=?UTF-8?q?=E5=95=86=E5=93=81=E6=96=B0=E5=A2=9E=20/=20=E6=9B=B4=E6=96=B0?=
=?UTF-8?q?=EF=BC=88api.add=5Fproduct=20/=20api.update=5Fproduct=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
信仓没有 upsert 接口,createOrUpdate 按「先查临时产品,有则更新、无则新增」实现:
- GET api.productlist?state=0 按 SKU 查临时产品,结果再按 product_no 精确比对,
防止 key 模糊匹配把相似 SKU 误判为已存在
- 命中走 api.update_product(只对临时产品有效),否则 api.add_product
- 写接口 token 同时放 query(文档通用约定)与请求体(产品接口 schema 要求)
- WarehouseProduct 的 cm / g 按常量换算成信仓的 inch / lbs,保留 4 位小数;
金额取 declaredValue 并固定 USD,非美元直接拒绝,避免静默按美元记错价
- bar_code 缺失时退回 SKU;packing_rate 固定 1(必填项);
包装方式 / SN / 海关等信仓未定义的字段不发送
- 适配器改为实现 WarehouseProductCapable,能力位声明 PRODUCT
未接入 api.pub_product:建档结果仍是临时产品(state=0),上架正式产品另行接入。
Co-Authored-By: Claude Code
---
README.md | 10 +-
.../common/ecommerce/xincang/XincangConstants.java | 22 ++
.../ecommerce/xincang/adapter/XincangAdapter.java | 126 ++++++++++-
.../xincang/adapter/XincangProductMapper.java | 114 ++++++++++
.../common/ecommerce/xincang/dto/XincangDtos.java | 114 ++++++++++
.../xincang/http/XincangRequestFactory.java | 23 +-
.../xincang/adapter/XincangAdapterTest.java | 7 +-
.../xincang/adapter/XincangProductTest.java | 251 +++++++++++++++++++++
8 files changed, 648 insertions(+), 19 deletions(-)
create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
diff --git a/README.md b/README.md
index 3bf5b09..81b4efb 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ sequenceDiagram
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
-| `warehouse-sdk-xincang` | 信仓三方仓适配器(本轮只落地登录换 token;能力位留空) |
+| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token + 商品建档 / 更新) |
依赖方向:
```
@@ -320,10 +320,10 @@ common.ecommerce
│ └── http YqnRequestFactory / YqnEnvelope / YqnRateLimiter
│
└── xincang 信仓三方仓(warehouse-sdk-xincang)
- ├── XincangConstants 测试基址、登录路径、query 参数名、限流
+ ├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流
├── auth XincangTokenClient(GET /api.login,无 refresh)
- ├── adapter XincangAdapter(本轮仅登录) / XincangAdapterFactory
- ├── dto XincangDtos.LoginResponse
+ ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper
+ ├── dto XincangDtos(登录 / 商品)
└── http XincangRequestFactory / XincangEnvelope / XincangRateLimiter
```
@@ -914,7 +914,7 @@ mvn test # 全部
mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
-mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 令牌缓存
+mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 令牌缓存 / 商品建档
```
---
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
index b37c696..58f3f5f 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
@@ -38,6 +38,18 @@ public final class XincangConstants {
/** 登录换取 token。 */
public static final String PATH_LOGIN = "/api.login";
+ /** 新增产品(临时产品,状态 0)。 */
+ public static final String PATH_PRODUCT_ADD = "/api.add_product";
+
+ /** 更新产品;只接受临时产品。 */
+ public static final String PATH_PRODUCT_UPDATE = "/api.update_product";
+
+ /** 上架正式产品。 */
+ public static final String PATH_PRODUCT_PUBLISH = "/api.pub_product";
+
+ /** 产品列表;{@code state} 必填:0 临时产品 / 1 正式产品。 */
+ public static final String PATH_PRODUCT_LIST = "/api.productlist";
+
/** 登录响应里的 token 归入哪个作用域;信仓用 query 参数传递,不是 {@code Authorization} 头。 */
public static final String TOKEN_LOCATION = "query";
@@ -53,6 +65,11 @@ public final class XincangConstants {
public static final String SUCCESS_ERRNO = "0";
public static final String SUCCESS_RST_CODE = "0";
+ /** 每磅折合克数,用于把 {@code WarehouseProduct.weightGrams} 换算成信仓的 {@code weight_lbs}。 */
+ public static final double GRAMS_PER_POUND = 453.59237;
+ /** 每英寸折合厘米数,用于把 {@code WarehouseProduct.*Cm} 换算成信仓的 {@code size_*_ln}。 */
+ public static final double CENTIMETERS_PER_INCH = 2.54;
+
/**
* token 有效期兜底值(秒)。
*
@@ -74,6 +91,11 @@ public final class XincangConstants {
/** 信仓以北京时间为准(文档「时间:北京时间」)。 */
public static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE;
+ /** 商品状态:临时产品(`api.add_product` 新建后的状态;只有临时产品能更新 / 删除)。 */
+ public static final String PRODUCT_STATE_TEMPORARY = "0";
+ /** 商品状态:正式产品(可下单出库)。 */
+ public static final String PRODUCT_STATE_FORMAL = "1";
+
private XincangConstants() {
}
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
index 809ae36..8a783d3 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
@@ -1,40 +1,68 @@
package common.ecommerce.xincang.adapter;
+import common.ecommerce.http.HttpRequest;
+import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
-import common.ecommerce.http.JsonCodec;
+import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.TokenManager;
+import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
-import common.ecommerce.warehouse.sdk.WarehouseAdapter;
+import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.auth.XincangTokenClient;
+import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.http.XincangEnvelope;
+import common.ecommerce.xincang.http.XincangRateLimiter;
+import common.ecommerce.xincang.http.XincangRequestFactory;
import java.time.Clock;
import java.util.EnumSet;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
/**
- * 信仓适配器(本期只做登录换 token)。
+ * 信仓适配器。
*
* 文档确认的鉴权方式:{@code GET /api.login?appkey=&secret=} 换取客户级 token,
- * 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里。
- * 本轮只落地登录与令牌缓存,出库 / 库存 / 预报等能力位一律不声明,
- * 门面调用这些能力会显式抛 {@code WarehouseUnsupportedCapabilityException}。
+ * 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里
+ * (新增 / 更新产品的请求体 schema 里也要求一份,见 {@link XincangRequestFactory})。
+ *
+ * 已实现能力:商品建档 / 更新({@link WarehouseCapability#PRODUCT})。
+ * 其余能力位不声明,门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException}。
*
* 适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。
*/
-public final class XincangAdapter implements WarehouseAdapter {
+public final class XincangAdapter implements WarehouseProductCapable {
+
+ private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
+ private static final String OP_PRODUCT_ADD = "warehouse.product.add";
+ private static final String OP_PRODUCT_UPDATE = "warehouse.product.update";
+
+ /** 查重时只取一页;按 SKU 过滤后通常 0~1 条。 */
+ private static final int PRODUCT_QUERY_LIMIT = 100;
+ /** 信仓产品状态:0 临时产品。 */
+ private static final String STATE_TEMPORARY = XincangConstants.PRODUCT_STATE_TEMPORARY;
+ private final HttpTransport transport;
+ private final JacksonJsonCodec json;
private final XincangTokenClient tokenClient;
private final TokenManager tokenManager;
+ private final XincangRequestFactory requestFactory;
+ private final XincangRateLimiter rateLimiter;
- public XincangAdapter(HttpTransport transport, JsonCodec json,
+ public XincangAdapter(HttpTransport transport, JacksonJsonCodec json,
TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
+ this.transport = transport;
+ this.json = json;
this.tokenClient = new XincangTokenClient(transport, json, clock);
// 信仓 token 2h、无 refresh 接口:到期前 10 分钟重新登录换取;
// TokenManager 负责锁内防击穿与缓存读写,缓存键按 appkey(客户级)。
@@ -45,6 +73,8 @@ public final class XincangAdapter implements WarehouseAdapter {
return tokenClient.fetch(secret.endpointBaseUrl(), secret.appKey(), secret.appSecret());
}
};
+ this.requestFactory = new XincangRequestFactory(json);
+ this.rateLimiter = new XincangRateLimiter();
}
@Override
@@ -57,10 +87,9 @@ public final class XincangAdapter implements WarehouseAdapter {
return WarehouseProvider.XINCANG;
}
- /** 本期没有已实现的能力;后续接入业务接口时再逐个声明。 */
@Override
public EnumSet capabilities() {
- return EnumSet.noneOf(WarehouseCapability.class);
+ return EnumSet.of(WarehouseCapability.PRODUCT);
}
/**
@@ -75,6 +104,83 @@ public final class XincangAdapter implements WarehouseAdapter {
return tokenManager.getOrRefresh(tokenKey(ctx.secret()), ctx.secret());
}
+ // ------------------------------------------------------------------ 商品
+
+ /**
+ * 创建或更新商品。
+ *
+ * 信仓没有 upsert 接口,按「先查临时产品、有则更新、无则新增」实现:
+ *
+ * - {@code api.add_product} 新建的是临时产品({@code state=0}),
+ * 要用于出库还需另行上架为正式产品({@code api.pub_product},本轮未接入)
+ * - {@code api.update_product} 只对临时产品有效;若同 SKU 已是正式产品,
+ * 新增会返回「产品SKU已存在」,这里原样抛给调用方,不静默忽略
+ *
+ *
+ * @return {@code status} 为 {@code ADDED} / {@code UPDATED},{@code rawStatus} 为信仓产品状态码
+ * @throws PlatformBusinessException 信仓业务失败(SKU / 条码重复、参数不合法等)
+ */
+ @Override
+ public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
+ AccessToken token = login(ctx);
+ XincangDtos.ProductRequest body = XincangProductMapper.toRequest(product, token.value());
+
+ boolean existsAsTemporary = findTemporaryProduct(ctx, token, body.productNo) != null;
+ if (existsAsTemporary) {
+ execute(ctx, XincangConstants.PATH_PRODUCT_UPDATE, body, token, OP_PRODUCT_UPDATE);
+ return ProductResult.of(body.productNo, "UPDATED", STATE_TEMPORARY);
+ }
+ execute(ctx, XincangConstants.PATH_PRODUCT_ADD, body, token, OP_PRODUCT_ADD);
+ return ProductResult.of(body.productNo, "ADDED", STATE_TEMPORARY);
+ }
+
+ /**
+ * 查该 SKU 是否已是临时产品。
+ *
+ * {@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配,
+ * 这里再按 {@code product_no} 精确比对一次。
+ */
+ private XincangDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token,
+ String sku) {
+ Map params = new LinkedHashMap<>();
+ params.put("state", 0);
+ params.put("page", 1);
+ params.put("limit", PRODUCT_QUERY_LIMIT);
+ params.put("key", sku);
+ String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token, OP_PRODUCT_QUERY);
+
+ List items =
+ json.listAt(raw, "rst.data", XincangDtos.ProductListItem.class);
+ for (XincangDtos.ProductListItem item : items) {
+ if (sku.equals(item.productNo)) {
+ return item;
+ }
+ }
+ return null;
+ }
+
+ // ------------------------------------------------------------------ internals
+
+ /** 写接口:JSON 请求体(含 token)+ query token。 */
+ private String execute(WarehouseContext ctx, String path, Object body,
+ AccessToken token, String operation) {
+ rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND);
+ HttpRequest req = requestFactory.postJsonWithToken(ctx.endpointBaseUrl(), path,
+ json.toJson(body), token.value(), operation);
+ HttpResponse resp = transport.execute(req);
+ return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body();
+ }
+
+ /** 读接口:query token。 */
+ private String executeGet(WarehouseContext ctx, String path, Map params,
+ AccessToken token, String operation) {
+ rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND);
+ HttpRequest req = requestFactory.getWithToken(ctx.endpointBaseUrl(), path, params,
+ token.value(), operation);
+ HttpResponse resp = transport.execute(req);
+ return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body();
+ }
+
/**
* 令牌缓存维度:信仓 token 按客户(appkey)发放,同一 appkey 下多仓共用一个 token。
*
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
new file mode 100644
index 0000000..e89aadc
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
@@ -0,0 +1,114 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.capability.WarehouseProduct;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.dto.XincangDtos;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+
+/**
+ * 信仓商品报文映射({@code POST api.add_product} / {@code api.update_product})。
+ *
+ * 平台字段名只出现在本类与 {@link XincangDtos}。单位换算也在这里:
+ * 统一模型用 cm / g,信仓用 inch / lbs,按 {@link XincangConstants} 里的常量换算并保留 4 位小数
+ * (文档「最长四位小数」)。
+ *
+ * 文档未定义「包装方式 / 是否 SN / 客退处理 / 海关信息」等字段,这些统一模型字段
+ * 不发送,避免自行编造平台不认的键。
+ */
+public final class XincangProductMapper {
+
+ /** 文档限制:数量类字段最长四位小数。 */
+ private static final int SCALE = 4;
+ /** 金额最长两位小数。 */
+ private static final int AMOUNT_SCALE = 2;
+ /** 装箱率未提供时按 1 发送(必填项)。 */
+ private static final int DEFAULT_PACKING_RATE = 1;
+
+ private XincangProductMapper() {
+ }
+
+ /**
+ * 统一商品 → 信仓新增 / 更新请求。
+ *
+ * @param product 已通过 {@link WarehouseProduct} 构造期校验的商品
+ * @param token 业务令牌;两个接口的请求体都要求
+ * @throws IllegalArgumentException 申报价值不是美元(信仓 amount 固定 USD)
+ */
+ public static XincangDtos.ProductRequest toRequest(WarehouseProduct product, String token) {
+ XincangDtos.ProductRequest req = new XincangDtos.ProductRequest();
+ req.token = token;
+ req.productNo = skuOf(product);
+ req.chnName = product.name();
+ req.amount = amount(product.declaredValue());
+ req.barCode = barcodeOf(product);
+ req.weightLbs = decimal(product.weightGrams())
+ .divide(decimal(XincangConstants.GRAMS_PER_POUND), SCALE, RoundingMode.HALF_UP);
+ req.packingRate = DEFAULT_PACKING_RATE;
+ req.sizeLLn = inches(product.lengthCm());
+ req.sizeWLn = inches(product.widthCm());
+ req.sizeHLn = inches(product.heightCm());
+ req.remark = trimToNull(product.remark());
+ req.ckm = trimToNull(product.customItemNo());
+ req.productType = product.productType() > 0 ? product.productType() : null;
+ 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();
+ }
+
+ /**
+ * 条码:统一模型未给条码时退回 SKU。
+ *
+ * 信仓把 {@code bar_code} 列为必填且查重(重复会报「产品条形码已存在」),
+ * 用 SKU 兜底可以保证单次建档能通过;调用方应尽量显式给真实条码。
+ */
+ public static String barcodeOf(WarehouseProduct product) {
+ String barcode = product.barcode();
+ if (barcode != null && !barcode.trim().isEmpty()) {
+ return barcode.trim();
+ }
+ return skuOf(product);
+ }
+
+ /**
+ * 金额:取申报价值。
+ *
+ * 信仓 {@code amount} 固定美元且最多两位小数,其他币种直接拒绝,避免静默按美元记错价。
+ * 未给申报价值时按 0.00 发送(文档必填项)。
+ */
+ private static BigDecimal amount(Money declaredValue) {
+ if (declaredValue == null) {
+ return BigDecimal.ZERO.setScale(AMOUNT_SCALE, RoundingMode.UNNECESSARY);
+ }
+ if (!"USD".equalsIgnoreCase(declaredValue.currencyCode())) {
+ throw new IllegalArgumentException(
+ "xincang product amount is USD only, got " + declaredValue.currencyCode());
+ }
+ return declaredValue.amount().setScale(AMOUNT_SCALE, RoundingMode.HALF_UP);
+ }
+
+ private static BigDecimal inches(double cm) {
+ return decimal(cm).divide(decimal(XincangConstants.CENTIMETERS_PER_INCH), SCALE, RoundingMode.HALF_UP);
+ }
+
+ private static BigDecimal decimal(double value) {
+ return BigDecimal.valueOf(value);
+ }
+
+ private static String trimToNull(String v) {
+ if (v == null) {
+ return null;
+ }
+ String trimmed = v.trim();
+ return trimmed.isEmpty() ? null : trimmed;
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
index 4333d81..ad34d40 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
@@ -1,8 +1,11 @@
package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty;
+import java.math.BigDecimal;
+
/**
* 信仓报文结构。
*
@@ -65,4 +68,115 @@ public final class XincangDtos {
@JsonProperty("token")
public String token;
}
+
+ /**
+ * 新增 / 更新产品请求({@code POST api.add_product} / {@code api.update_product})。
+ *
+ * 信仓这两个接口的 {@code token} 放在 请求体里(文档 required 列表含 {@code token});
+ * 新增接口的 query 里同时也收一份,见 {@code XincangRequestFactory}。
+ *
+ * 单位:金额美元、尺寸英寸、重量磅;与统一模型(cm / g)的换算在
+ * {@code XincangProductMapper}。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ProductRequest {
+
+ /** 令牌。 */
+ @JsonProperty("token")
+ public String token;
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_no")
+ public String productNo;
+
+ /** 中文名。 */
+ @JsonProperty("chn_name")
+ public String chnName;
+
+ /** 金额,美元,最长两位小数。 */
+ @JsonProperty("amount")
+ public BigDecimal amount;
+
+ /** 产品条码。 */
+ @JsonProperty("bar_code")
+ public String barCode;
+
+ /** 毛重,磅,最长四位小数。 */
+ @JsonProperty("weight_lbs")
+ public BigDecimal weightLbs;
+
+ /** 装箱率 / 箱率。 */
+ @JsonProperty("packing_rate")
+ public Integer packingRate;
+
+ /** 长,英寸,最长四位小数。 */
+ @JsonProperty("size_l_ln")
+ public BigDecimal sizeLLn;
+
+ /** 宽,英寸,最长四位小数。 */
+ @JsonProperty("size_w_ln")
+ public BigDecimal sizeWLn;
+
+ /** 高,英寸,最长四位小数。 */
+ @JsonProperty("size_h_ln")
+ public BigDecimal sizeHLn;
+
+ /** 备注。 */
+ @JsonProperty("remark")
+ public String remark;
+
+ /** 仓库码(信仓 {@code ckm})。 */
+ @JsonProperty("ckm")
+ public String ckm;
+
+ /** 产品类型:1 普货 / 2 配件 / 3 危险品;不传默认 1。 */
+ @JsonProperty("product_type")
+ public Integer productType;
+
+ /** 产品品类:0 其它 / 1 家具 / 2 食品 / 3 汽配 / 4 服饰 / 5 化妆品 / 6 鞋类 / 7 玩具 / 8 电子 / 9 数码。 */
+ @JsonProperty("product_category")
+ public Integer productCategory;
+
+ /** 产品图片;需先调 {@code upload.files}。统一模型暂不承载图片,通常为 null。 */
+ @JsonProperty("product_image")
+ public ProductImage productImage;
+ }
+
+ /** 产品图片(OSS 元数据)。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class ProductImage {
+
+ /** 存储类型,如 {@code aliyun_oss}。 */
+ @JsonProperty("type")
+ public String type;
+
+ /** bucket 名。 */
+ @JsonProperty("bucket")
+ public String bucket;
+
+ /** 对象键。 */
+ @JsonProperty("file_name")
+ public String fileName;
+
+ /** 可访问 URL。 */
+ @JsonProperty("file_url")
+ public String fileUrl;
+ }
+
+ /**
+ * 产品列表响应({@code GET api.productlist})中 {@code rst.data[]} 的元素。
+ *
+ * 只声明判断「是否已存在、处于什么状态」需要的字段。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class ProductListItem {
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_no")
+ public String productNo;
+
+ /** 产品状态:0 临时产品 / 1 正式产品。 */
+ @JsonProperty("state")
+ public String state;
+ }
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
index 8b92c6e..8417dd4 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
@@ -63,8 +63,8 @@ public final class XincangRequestFactory {
/**
* 业务 GET:在 {@code params} 上补 {@code token}。
*
- * 后续接口(订单 / 库存 / 预报)都要求 token 作为 query 参数,这个方法集中处理,
- * 免得各 Source 各写一遍。本轮只落地登录,接入业务接口时直接复用。
+ * 订单 / 库存 / 预报 / 产品列表等接口都要求 token 作为 query 参数,这个方法集中处理,
+ * 免得各处各写一遍。
*/
public HttpRequest getWithToken(String baseUrl, String path, Map params,
String token, String operation) {
@@ -77,6 +77,25 @@ public final class XincangRequestFactory {
return get(baseUrl, path, query, operation);
}
+ /**
+ * 业务 POST:JSON 请求体,token 同时放 query。
+ *
+ * 信仓的写接口把 {@code token} 列为必填 query 参数(新增订单、删除产品等均如此),
+ * 而新增 / 更新产品在请求体 schema 里又要求一份 {@code token}。
+ * 这里统一两处都带:query 是文档的通用约定,body 由调用方按接口需要自行放入。
+ */
+ public HttpRequest postJsonWithToken(String baseUrl, String path, String jsonBody,
+ String token, String operation) {
+ return HttpRequest.builder()
+ .method("POST")
+ .url(trimTrailingSlash(baseUrl) + path + "?" + urlEncode(XincangConstants.QUERY_TOKEN)
+ + "=" + urlEncode(requireText(token, "xincang requires a token; call login first")))
+ .contentType("application/json")
+ .body(jsonBody)
+ .operation(operation)
+ .build();
+ }
+
/** 集合 / 对象按 JSON 序列化,其余按字符串。 */
private String stringify(Object value) {
if (value instanceof Collection || value instanceof Map) {
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
index 47edd41..9b7cfb5 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
@@ -15,6 +15,7 @@ import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.time.Duration;
+import java.util.EnumSet;
import static org.junit.jupiter.api.Assertions.*;
@@ -113,12 +114,14 @@ class XincangAdapterTest {
}
@Test
- void capabilitiesAreEmptyUntilBusinessApisLand() {
+ void declaresProductOnly() {
XincangAdapter adapter = adapter();
assertEquals(WarehouseProvider.XINCANG, adapter.provider());
assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId());
- assertTrue(adapter.capabilities().isEmpty(), "本期只做登录,不声明任何能力位");
+ assertEquals(EnumSet.of(WarehouseCapability.PRODUCT), adapter.capabilities(),
+ "当前只落地商品建档,不声明其它能力位");
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
}
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
new file mode 100644
index 0000000..1e50fcb
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
@@ -0,0 +1,251 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+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.capability.WarehouseProductCapable.ProductResult;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 信仓商品建档契约测试。
+ *
+ * 覆盖:先查临时产品再决定 add / update、单位换算(cm→inch、g→lbs)、
+ * token 在两处(query 与 body)、必填兜底与错误传播。
+ */
+class XincangProductTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-09T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-CA-3790", WarehouseProvider.XINCANG, "CA-3790",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ private static WarehouseProduct product(String sku) {
+ return WarehouseProduct.builder()
+ .omsSku(sku)
+ .name("测试商品")
+ .nameEn("Test Product")
+ .barcode("BARCODE-1")
+ .packingType(0)
+ .lengthCm(30.48)
+ .widthCm(25.4)
+ .heightCm(10)
+ .weightGrams(1000)
+ .productType(1)
+ // 统一模型要求海关三项整组给(信仓不发送这三项,只取 declaredValue 作 amount)
+ .declaredValue(Money.of("30.49", "USD"))
+ .hsCode("9403600000")
+ .countryOfOrigin("US")
+ .remark("remark 1")
+ .build();
+ }
+
+ /** 产品列表:给定条目 JSON 数组内容。 */
+ private void routeProductList(String dataJson) {
+ transport.route(XincangConstants.PATH_PRODUCT_LIST, req -> Responses.ok(
+ "{\"rst\":{\"code\":\"0\",\"msg\":\"\",\"data\":" + dataJson + ",\"count\":\"1\"},"
+ + "\"errno\":0,\"err\":\"\",\"trace_id\":\"t-list\"}"));
+ }
+
+ @Test
+ void addsProductWhenSkuIsNew() {
+ routeProductList("[]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-add\"}"));
+
+ ProductResult result = adapter.createOrUpdate(ctx(), product("APITEST001"));
+
+ assertEquals("APITEST001", result.providerSku());
+ assertEquals("ADDED", result.status());
+ assertEquals("0", result.rawStatus());
+
+ // 三个请求:登录 → 产品列表 → 新增
+ assertEquals(3, transport.recorded().size());
+
+ String addBody = transport.lastDataRequest().body();
+ assertTrue(addBody.contains("\"product_no\":\"APITEST001\""), addBody);
+ assertTrue(addBody.contains("\"chn_name\":\"测试商品\""), addBody);
+ assertTrue(addBody.contains("\"bar_code\":\"BARCODE-1\""), addBody);
+ assertTrue(addBody.contains("\"amount\":30.49"), addBody);
+ // 1000g → 2.2046 lbs;30.48cm → 12.0000 in
+ assertTrue(addBody.contains("\"weight_lbs\":2.2046"), addBody);
+ assertTrue(addBody.contains("\"size_l_ln\":12.0000"), addBody);
+ assertTrue(addBody.contains("\"size_w_ln\":10.0000"), addBody);
+ assertTrue(addBody.contains("\"size_h_ln\":3.9370"), addBody);
+ assertTrue(addBody.contains("\"packing_rate\":1"), addBody);
+ assertTrue(addBody.contains("\"product_type\":1"), addBody);
+ // token 在 body 与 query 两处
+ assertTrue(addBody.contains("\"token\":\"{T-1}\""), addBody);
+ assertTrue(transport.lastDataRequest().url().endsWith("/api.add_product?token=%7BT-1%7D"),
+ transport.lastDataRequest().url());
+ }
+
+ @Test
+ void updatesProductWhenTemporaryAlreadyExists() {
+ routeProductList("[{\"product_no\":\"APITEST001\",\"state\":\"0\"}]");
+ transport.route(XincangConstants.PATH_PRODUCT_UPDATE, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-upd\"}"));
+
+ ProductResult result = adapter.createOrUpdate(ctx(), product("APITEST001"));
+
+ assertEquals("UPDATED", result.status());
+ assertTrue(transport.lastDataRequest().url().contains("/api.update_product"), "应走更新接口");
+ assertTrue(!transport.lastDataRequest().url().contains("/api.add_product"));
+ }
+
+ @Test
+ void listQueryUsesStateTemporaryAndSkuKey() {
+ routeProductList("[]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\"}"));
+
+ adapter.createOrUpdate(ctx(), product("APITEST002"));
+
+ // dataRequests() 会排除含 /oauth/access-token 的请求,但信仓登录路径是 /api.login,
+ // 需要按路径自己取业务请求
+ String listUrl = null;
+ for (common.ecommerce.http.HttpRequest req : transport.recorded()) {
+ if (req.url().contains(XincangConstants.PATH_PRODUCT_LIST)) {
+ listUrl = req.url();
+ }
+ }
+ assertNotNull(listUrl, "应调用产品列表");
+ assertTrue(listUrl.contains("/api.productlist?"), listUrl);
+ assertTrue(listUrl.contains("state=0"), listUrl);
+ assertTrue(listUrl.contains("key=APITEST002"), listUrl);
+ assertTrue(listUrl.contains("token=%7BT-1%7D"), listUrl);
+ }
+
+ @Test
+ void skuIsFilteredExactlySoSimilarSkuIsNotMistakenAsExisting() {
+ // 列表按 key 模糊返回了别的 SKU,必须再精确比对
+ routeProductList("[{\"product_no\":\"APITEST003-OLD\",\"state\":\"0\"}]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\"}"));
+
+ ProductResult result = adapter.createOrUpdate(ctx(), product("APITEST003"));
+
+ assertEquals("ADDED", result.status());
+ }
+
+ @Test
+ void formalProductIsNotTreatedAsUpdatable() {
+ // 正式产品(state=1)不在临时产品列表里;新增会让信仓报「SKU已存在」,原样抛出
+ routeProductList("[]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"产品SKU已存在\",\"trace_id\":\"t-dup\"}"));
+
+ common.ecommerce.shared.error.PlatformBusinessException e =
+ assertThrows(common.ecommerce.shared.error.PlatformBusinessException.class,
+ () -> adapter.createOrUpdate(ctx(), product("APITEST004")));
+
+ assertTrue(e.getMessage().contains("产品SKU已存在"), e.getMessage());
+ assertEquals("t-dup", e.platformRequestId());
+ }
+
+ @Test
+ void barcodeFallsBackToSkuAndAmountToZeroWhenMissing() {
+ routeProductList("[]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\"}"));
+ WarehouseProduct noBarcode = WarehouseProduct.builder()
+ .omsSku("APITEST005")
+ .name("测试商品")
+ .nameEn("Test")
+ .packingType(0)
+ .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
+ .build();
+
+ adapter.createOrUpdate(ctx(), noBarcode);
+
+ String body = transport.lastDataRequest().body();
+ assertTrue(body.contains("\"bar_code\":\"APITEST005\""), body);
+ assertTrue(body.contains("\"amount\":0.00"), body);
+ // 未指定产品类型时不发该字段
+ assertTrue(!body.contains("product_type"), body);
+ }
+
+ @Test
+ void nonUsdDeclaredValueIsRejectedBeforeSending() {
+ WarehouseProduct eur = WarehouseProduct.builder()
+ .omsSku("APITEST006")
+ .name("测试商品")
+ .nameEn("Test")
+ .barcode("B-6")
+ .packingType(0)
+ .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
+ .declaredValue(Money.of("10.00", "EUR"))
+ .hsCode("9403600000")
+ .countryOfOrigin("DE")
+ .build();
+
+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,
+ () -> adapter.createOrUpdate(ctx(), eur));
+ assertTrue(e.getMessage().contains("USD"), e.getMessage());
+ }
+
+ @Test
+ void providerSkuWinsWhenMapped() {
+ routeProductList("[]");
+ transport.route(XincangConstants.PATH_PRODUCT_ADD, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\"}"));
+ WarehouseProduct mapped = WarehouseProduct.builder()
+ .omsSku("OMS-1")
+ .providerSku("XC-1")
+ .name("测试商品")
+ .nameEn("Test")
+ .barcode("B-1")
+ .packingType(0)
+ .lengthCm(10).widthCm(10).heightCm(10).weightGrams(100)
+ .build();
+
+ ProductResult result = adapter.createOrUpdate(ctx(), mapped);
+
+ assertEquals("XC-1", result.providerSku());
+ assertTrue(transport.lastDataRequest().body().contains("\"product_no\":\"XC-1\""));
+ }
+
+ @Test
+ void productCapabilityIsDeclared() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
+ assertFalse(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
+ }
+}
From cde4bac44a633f659c00c19aedbf63e5534bed47 Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Tue, 10 Nov 2026 11:09:52 +0800
Subject: [PATCH 2/2] =?UTF-8?q?feat(xincang):=20=E5=AF=B9=E6=8E=A5?=
=?UTF-8?q?=E4=B8=80=E5=8D=95=E5=A4=9A=E4=BB=B6=E4=B8=8B=E5=8D=95=E4=B8=8E?=
=?UTF-8?q?=E8=BD=AC=E8=BF=90=E5=88=9B=E5=BB=BA=20/=20=E5=AE=A1=E6=A0=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 新增订单一单多件:POST api.add_order_multiple,multipart/form-data,
products 字段是 JSON 字符串;返回 rst.order_no 作为仓侧单号
- 新增转运:POST fba.do_fba,application/json,返回 rst.order_no,
创建后处于待审核
- 转运审核:POST fba.do_approve,无请求体,token 与 order_no 都在 query
仓库域内核的配套扩展(YQN 不受影响,原有测试全绿):
- OutboundCommand 增加 splitOrder,仅声明了 SPLIT 的仓解释
- TransferCommand 增加 po / orderType / deliveryMode / deliveryWay /
otherWarehouseName / labelRequirements / palletRequired / 各类贴标份数
- TransferCapable 增加默认 approve(不支持的仓显式拒绝),
WarehouseOperations.approveTransfer 走幂等守卫,动作键 approve
字段映射的取舍:
- logistics_type 用 carrierCode 承载;ckh 用 outboundRequestNo(要求唯一)
- is_sign 模型无对应字段,固定发「否」
- order_type:Wayfair → wayfair,其余 → common
- 地址超过 32 字符的部分自动拆到 address2
- 字典字段(orderType / deliveryMode / deliveryWay / labelRequirements)
只接受仓方字典原值,SDK 不做归一
- 信仓这版不收申报信息与包裹尺寸,统一模型里的对应字段不发送
- 转运仅支持 TransferType.OUTBOUND(信仓转运 = 仓到平台仓)
---
README.md | 9 +-
.../warehouse/capability/TransferCapable.java | 15 ++
.../ecommerce/warehouse/model/OutboundCommand.java | 25 +++
.../ecommerce/warehouse/model/TransferCommand.java | 164 +++++++++++++++++
.../warehouse/sdk/WarehouseOperations.java | 22 +++
.../common/ecommerce/xincang/XincangConstants.java | 12 ++
.../ecommerce/xincang/adapter/XincangAdapter.java | 164 ++++++++++++++++-
.../xincang/adapter/XincangOrderMapper.java | 179 +++++++++++++++++++
.../xincang/adapter/XincangTransferMapper.java | 154 ++++++++++++++++
.../adapter/XincangUnsupportedOutbound.java | 49 ++++++
.../common/ecommerce/xincang/dto/XincangDtos.java | 150 ++++++++++++++++
.../ecommerce/xincang/http/XincangMultipart.java | 81 +++++++++
.../xincang/http/XincangRequestFactory.java | 36 +++-
.../xincang/adapter/XincangAdapterTest.java | 10 +-
.../xincang/adapter/XincangOrderTest.java | 178 +++++++++++++++++++
.../xincang/adapter/XincangProductTest.java | 15 +-
.../xincang/adapter/XincangTransferTest.java | 195 +++++++++++++++++++++
17 files changed, 1434 insertions(+), 24 deletions(-)
create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
create mode 100644 warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java
create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
create mode 100644 warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
diff --git a/README.md b/README.md
index 81b4efb..30370b8 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ sequenceDiagram
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
-| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token + 商品建档 / 更新) |
+| `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、一单多件下单、转运创建 / 审核) |
依赖方向:
```
@@ -322,9 +322,10 @@ common.ecommerce
└── xincang 信仓三方仓(warehouse-sdk-xincang)
├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流
├── auth XincangTokenClient(GET /api.login,无 refresh)
- ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper
+ ├── adapter XincangAdapter / XincangAdapterFactory /
+ │ XincangProductMapper / XincangOrderMapper / XincangTransferMapper
├── dto XincangDtos(登录 / 商品)
- └── http XincangRequestFactory / XincangEnvelope / XincangRateLimiter
+ └── http XincangRequestFactory / XincangMultipart / XincangEnvelope / XincangRateLimiter
```
包名统一前缀 `common.ecommerce.`,下表省略前缀。
@@ -914,7 +915,7 @@ mvn test # 全部
mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
-mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 令牌缓存 / 商品建档
+mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 商品 / 下单 / 转运
```
---
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
index 7c91790..b25bfcb 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
@@ -21,4 +21,19 @@ public interface TransferCapable extends WarehouseAdapter {
* 仓不支持该调拨类型
*/
TransferOrder create(WarehouseContext ctx, TransferCommand cmd);
+
+ /**
+ * 审核通过调拨单。写操作,幂等键
+ * {@code warehouseCode + transferRequestNo + "approve"}。
+ *
+ * 信仓的「转运审核」({@code POST fba.do_approve})走这里:
+ * {@code transferRequestNo} 传仓侧转运单号(信仓 {@code order_no},
+ * 即 {@code create} 返回的 {@code providerTransferNo})。
+ *
+ * 没有审核环节的仓默认拒绝,不静默当作成功。
+ */
+ default void approve(WarehouseContext ctx, String transferRequestNo) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.WarehouseCapability.TRANSFER);
+ }
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
index af0e062..2f931de 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
@@ -38,6 +38,13 @@ public final class OutboundCommand {
private final Instant estimatedDeliveryTime;
/** 下单币种;null 时为 USD。 */
private final String currency;
+ /**
+ * 仓侧拆单开关;null 表示按仓的默认规则。
+ *
+ * 仅对声明了 {@code WarehouseCapability.SPLIT} 的仓有意义。
+ * 信仓 {@code is_split}:true 拆成一单一品(每件一张面单),false 打包成一张面单。
+ */
+ private final Boolean splitOrder;
private OutboundCommand(Builder b) {
if (b.outboundRequestNo == null || b.outboundRequestNo.trim().isEmpty()) {
@@ -63,6 +70,7 @@ public final class OutboundCommand {
this.latestShipDate = b.latestShipDate;
this.estimatedDeliveryTime = b.estimatedDeliveryTime;
this.currency = b.currency;
+ this.splitOrder = b.splitOrder;
}
public static Builder builder() {
@@ -144,6 +152,16 @@ public final class OutboundCommand {
return currency;
}
+ /**
+ * 仓侧拆单开关;null 表示按仓默认规则。
+ *
+ * 只有声明了 {@code WarehouseCapability.SPLIT} 的仓会解释该值,
+ * 其余适配器应忽略它,不得自行编造拆单行为。
+ */
+ public Boolean splitOrder() {
+ return splitOrder;
+ }
+
public static final class Builder {
private String outboundRequestNo;
@@ -162,6 +180,7 @@ public final class OutboundCommand {
private Instant latestShipDate;
private Instant estimatedDeliveryTime;
private String currency;
+ private Boolean splitOrder;
public Builder outboundRequestNo(String outboundRequestNo) {
this.outboundRequestNo = outboundRequestNo;
@@ -251,6 +270,12 @@ public final class OutboundCommand {
return this;
}
+ /** 仓侧拆单开关;null 表示按仓默认规则。 */
+ public Builder splitOrder(Boolean splitOrder) {
+ this.splitOrder = splitOrder;
+ return this;
+ }
+
public OutboundCommand build() {
return new OutboundCommand(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
index 33d36a1..cfbe34a 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
@@ -1,5 +1,7 @@
package common.ecommerce.warehouse.model;
+import java.util.List;
+
/**
* 调拨单创建命令。写操作,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。
*
@@ -37,6 +39,32 @@ public final class TransferCommand {
private final java.util.List tags;
private final java.util.List batches;
+ /**
+ * 标签需求:{@code 产品贴} / {@code 外箱标签} / {@code 托盘标签},可多选。
+ *
+ * 仓侧只接受它自己字典里的值,因此这里保存仓方原文(由调用方从仓的字典接口取),
+ * SDK 不做枚举归一,免得联想出仓方不认的标签名。
+ */
+ private final List labelRequirements;
+ /** 是否需要打托;null 表示不传(仓按默认规则)。 */
+ private final Boolean palletRequired;
+ /** 产品贴打印份数;null 表示不传。 */
+ private final Integer productLabelCopies;
+ /** 外箱贴打印份数;null 表示不传。 */
+ private final Integer cartonLabelCopies;
+ /** 托盘贴打印份数;null 表示不传。 */
+ private final Integer palletLabelCopies;
+ /** PO 号;部分仓(信仓)要求,其余为 null。 */
+ private final String po;
+ /** 订单类型(仓方字典值,如信仓 FBA / LTL);null 表示不传。 */
+ private final String orderType;
+ /** 转运类型(仓方字典值);null 表示不传。 */
+ private final String deliveryMode;
+ /** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */
+ private final String deliveryWay;
+ /** 目的仓不在仓方字典时的自填仓库名;null 表示不传。 */
+ private final String otherWarehouseName;
+
private TransferCommand(Builder b) {
if (b.transferRequestNo == null || b.transferRequestNo.trim().isEmpty()) {
throw new IllegalArgumentException("transferRequestNo must not be blank");
@@ -83,6 +111,22 @@ public final class TransferCommand {
new java.util.ArrayList(b.tags));
this.batches = java.util.Collections.unmodifiableList(
new java.util.ArrayList(b.batches));
+ java.util.List labels = new java.util.ArrayList();
+ for (String label : b.labelRequirements) {
+ if (label != null && !label.trim().isEmpty()) {
+ labels.add(label.trim());
+ }
+ }
+ this.labelRequirements = java.util.Collections.unmodifiableList(labels);
+ this.palletRequired = b.palletRequired;
+ this.productLabelCopies = b.productLabelCopies;
+ this.cartonLabelCopies = b.cartonLabelCopies;
+ this.palletLabelCopies = b.palletLabelCopies;
+ this.po = b.po;
+ this.orderType = b.orderType;
+ this.deliveryMode = b.deliveryMode;
+ this.deliveryWay = b.deliveryWay;
+ this.otherWarehouseName = b.otherWarehouseName;
}
public static Builder builder() {
@@ -166,6 +210,56 @@ public final class TransferCommand {
return tags;
}
+ /** 标签需求原文(仓方字典值),可能为空列表。 */
+ public List labelRequirements() {
+ return labelRequirements;
+ }
+
+ /** 是否需要打托;null 表示不传。 */
+ public Boolean palletRequired() {
+ return palletRequired;
+ }
+
+ /** 产品贴打印份数;null 表示不传。 */
+ public Integer productLabelCopies() {
+ return productLabelCopies;
+ }
+
+ /** 外箱贴打印份数;null 表示不传。 */
+ public Integer cartonLabelCopies() {
+ return cartonLabelCopies;
+ }
+
+ /** 托盘贴打印份数;null 表示不传。 */
+ public Integer palletLabelCopies() {
+ return palletLabelCopies;
+ }
+
+ /** PO 号;部分仓要求,未设置为 null。 */
+ public String po() {
+ return po;
+ }
+
+ /** 订单类型(仓方字典值);null 表示不传。 */
+ public String orderType() {
+ return orderType;
+ }
+
+ /** 转运类型(仓方字典值);null 表示不传。 */
+ public String deliveryMode() {
+ return deliveryMode;
+ }
+
+ /** 转运方式 / 配送方式(仓方字典值);null 表示不传。 */
+ public String deliveryWay() {
+ return deliveryWay;
+ }
+
+ /** 目的仓不在字典时的自填仓库名;null 表示不传。 */
+ public String otherWarehouseName() {
+ return otherWarehouseName;
+ }
+
public java.util.List batches() {
return batches;
}
@@ -225,6 +319,16 @@ public final class TransferCommand {
private final java.util.List lines = new java.util.ArrayList();
private final java.util.List tags = new java.util.ArrayList();
private final java.util.List batches = new java.util.ArrayList();
+ private final java.util.List labelRequirements = new java.util.ArrayList();
+ private Boolean palletRequired;
+ private Integer productLabelCopies;
+ private Integer cartonLabelCopies;
+ private Integer palletLabelCopies;
+ private String po;
+ private String orderType;
+ private String deliveryMode;
+ private String deliveryWay;
+ private String otherWarehouseName;
public Builder transferRequestNo(String v) {
this.transferRequestNo = v;
@@ -331,6 +435,66 @@ public final class TransferCommand {
return this;
}
+ /** 标签需求(仓方字典原文),可多次调用。 */
+ public Builder labelRequirement(String v) {
+ this.labelRequirements.add(v);
+ return this;
+ }
+
+ /** 是否需要打托;null 表示不传。 */
+ public Builder palletRequired(Boolean v) {
+ this.palletRequired = v;
+ return this;
+ }
+
+ /** 产品贴打印份数;null 表示不传。 */
+ public Builder productLabelCopies(Integer v) {
+ this.productLabelCopies = v;
+ return this;
+ }
+
+ /** 外箱贴打印份数;null 表示不传。 */
+ public Builder cartonLabelCopies(Integer v) {
+ this.cartonLabelCopies = v;
+ return this;
+ }
+
+ /** 托盘贴打印份数;null 表示不传。 */
+ public Builder palletLabelCopies(Integer v) {
+ this.palletLabelCopies = v;
+ return this;
+ }
+
+ /** PO 号;部分仓要求。 */
+ public Builder po(String v) {
+ this.po = v;
+ return this;
+ }
+
+ /** 订单类型(仓方字典值)。 */
+ public Builder orderType(String v) {
+ this.orderType = v;
+ return this;
+ }
+
+ /** 转运类型(仓方字典值)。 */
+ public Builder deliveryMode(String v) {
+ this.deliveryMode = v;
+ return this;
+ }
+
+ /** 转运方式 / 配送方式(仓方字典值)。 */
+ public Builder deliveryWay(String v) {
+ this.deliveryWay = v;
+ return this;
+ }
+
+ /** 目的仓不在字典时的自填仓库名。 */
+ public Builder otherWarehouseName(String v) {
+ this.otherWarehouseName = v;
+ return this;
+ }
+
public TransferCommand build() {
return new TransferCommand(this);
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
index e482497..769d983 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
@@ -106,6 +106,28 @@ public final class WarehouseOperations {
return result.value();
}
+ /**
+ * 审核通过调拨单。写操作:强制经幂等守卫,幂等键
+ * {@code warehouseCode + transferRequestNo + approve}。
+ *
+ * @param transferRequestNo 仓侧调拨单号({@code create} 返回的 {@code providerTransferNo})
+ */
+ public void approveTransfer(final String transferRequestNo) {
+ require(WarehouseCapability.TRANSFER, TransferCapable.class);
+ if (guard == null) {
+ throw new IllegalStateException("WarehouseSdk requires an idempotencyStore for write operations");
+ }
+ final TransferCapable capable = (TransferCapable) adapter;
+ guard.execute(
+ WarehouseWriteScope.of(provider.name(), account.warehouseCode(),
+ transferRequestNo, "approve"),
+ () -> {
+ capable.approve(ctx, transferRequestNo);
+ return transferRequestNo;
+ },
+ ref -> ref);
+ }
+
/** 库存视图。 */
public InventoryView inventory() {
return new InventoryView();
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
index 58f3f5f..4551b76 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
@@ -50,6 +50,18 @@ public final class XincangConstants {
/** 产品列表;{@code state} 必填:0 临时产品 / 1 正式产品。 */
public static final String PATH_PRODUCT_LIST = "/api.productlist";
+ /** 新增订单一单多件({@code multipart/form-data};一票一件请用 {@code api.add_order})。 */
+ public static final String PATH_ORDER_ADD_MULTIPLE = "/api.add_order_multiple";
+
+ /** 新增转运({@code application/json})。 */
+ public static final String PATH_TRANSFER_CREATE = "/fba.do_fba";
+
+ /** 转运审核;{@code order_no} 为转运单号,走 query。 */
+ public static final String PATH_TRANSFER_APPROVE = "/fba.do_approve";
+
+ /** 转运列表。 */
+ public static final String PATH_TRANSFER_LIST = "/fba.fbalist";
+
/** 登录响应里的 token 归入哪个作用域;信仓用 query 参数传递,不是 {@code Authorization} 头。 */
public static final String TOKEN_LOCATION = "query";
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
index 8a783d3..4a90428 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
@@ -10,15 +10,31 @@ import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore;
+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.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
+import common.ecommerce.warehouse.error.WarehouseException;
+import common.ecommerce.warehouse.model.CancelCommand;
+import common.ecommerce.warehouse.model.CancelEligibility;
+import common.ecommerce.warehouse.model.CancelResult;
+import common.ecommerce.warehouse.model.OutboundCommand;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.OutboundQuery;
+import common.ecommerce.warehouse.model.OutboundReceipt;
+import common.ecommerce.warehouse.model.OutboundRef;
+import common.ecommerce.warehouse.model.PackageResult;
+import common.ecommerce.warehouse.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.auth.XincangTokenClient;
import common.ecommerce.xincang.dto.XincangDtos;
import common.ecommerce.xincang.http.XincangEnvelope;
+import common.ecommerce.xincang.http.XincangMultipart;
import common.ecommerce.xincang.http.XincangRateLimiter;
import common.ecommerce.xincang.http.XincangRequestFactory;
@@ -35,13 +51,15 @@ import java.util.Map;
* 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里
* (新增 / 更新产品的请求体 schema 里也要求一份,见 {@link XincangRequestFactory})。
*
- * 已实现能力:商品建档 / 更新({@link WarehouseCapability#PRODUCT})。
- * 其余能力位不声明,门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException}。
+ * 已实现能力:商品建档 / 更新({@code PRODUCT})、出库下单({@code OUTBOUND})、
+ * 转运创建 / 审核({@code TRANSFER})。出库的查询 / 取消 / 包裹字段未接入,
+ * 调用会显式抛不支持异常,不返回空集合。
*
* 适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。
*/
-public final class XincangAdapter implements WarehouseProductCapable {
+public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable,
+ TransferCapable {
private static final String OP_PRODUCT_QUERY = "warehouse.product.query";
private static final String OP_PRODUCT_ADD = "warehouse.product.add";
@@ -89,7 +107,8 @@ public final class XincangAdapter implements WarehouseProductCapable {
@Override
public EnumSet capabilities() {
- return EnumSet.of(WarehouseCapability.PRODUCT);
+ return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
+ WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT);
}
/**
@@ -159,6 +178,111 @@ public final class XincangAdapter implements WarehouseProductCapable {
return null;
}
+ // ------------------------------------------------------------------ 出库
+
+ /**
+ * 下发出库单(一单多件)。
+ *
+ * 信仓下单有两个接口:{@code api.add_order}(一票一件)与
+ * {@code api.add_order_multiple}(一单多件)。统一模型允许一单多行,
+ * 所以这里固定走多件接口;单行订单也走它。
+ *
+ * 该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON;
+ * 返回的 {@code rst.order_no} 是信仓系统单号({@code DS-...}),
+ * {@code rst.order_id} 是内部 id,优先取单号。
+ *
+ * 查询 / 取消 / 包裹等接口本轮未接入,调用会显式抛不支持异常。
+ */
+ @Override
+ public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
+ Map form = XincangOrderMapper.toForm(ctx, cmd, json);
+ String raw = executeMultipart(ctx, XincangConstants.PATH_ORDER_ADD_MULTIPLE, form,
+ "warehouse.outbound.create");
+ XincangDtos.OrderResult result = json.fromJson(raw, XincangDtos.OrderResponse.class).rst;
+ if (result == null || blank(result.orderNo)) {
+ throw WarehouseException.builder()
+ .message("xincang create order returned no rst.order_no: " + safeRelay(raw))
+ .operation("warehouse.outbound.create")
+ .warehouseCode(ctx.warehouseCode())
+ .provider(provider().name())
+ .requestId(ctx.requestId())
+ .retryable(false)
+ .rawResponse(safeRelay(raw))
+ .build();
+ }
+ return OutboundReceipt.of(cmd.outboundRequestNo(), result.orderNo, null);
+ }
+
+ @Override
+ public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
+ throw XincangUnsupportedOutbound.getUnsupported(ctx);
+ }
+
+ @Override
+ public Page query(WarehouseContext ctx, OutboundQuery query) {
+ throw XincangUnsupportedOutbound.queryUnsupported(ctx);
+ }
+
+ @Override
+ public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
+ throw XincangUnsupportedOutbound.checkCancelUnsupported(ctx);
+ }
+
+ @Override
+ public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
+ throw XincangUnsupportedOutbound.cancelUnsupported(ctx);
+ }
+
+ @Override
+ public List packages(WarehouseContext ctx, OutboundRef ref) {
+ throw XincangUnsupportedOutbound.packagesUnsupported(ctx);
+ }
+
+ // ------------------------------------------------------------------ 调拨 / 转运
+
+ /**
+ * 新增转运({@code POST fba.do_fba})。
+ *
+ * 信仓的转运是从信仓发往平台仓,统一模型里用 {@code TransferType.OUTBOUND}。
+ * 字典字段(订单类型 / 转运类型 / 转运方式 / 标签需求)只接受信仓字典原值,
+ * 由调用方传入,SDK 不做归一。
+ */
+ @Override
+ public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) {
+ String productsJson = json.toJson(XincangTransferMapper.products(cmd));
+ XincangDtos.TransferRequest body = XincangTransferMapper.toRequest(cmd, ctx, productsJson);
+ String raw = execute(ctx, XincangConstants.PATH_TRANSFER_CREATE, body, login(ctx),
+ "warehouse.transfer.create");
+ XincangDtos.TransferResult result = json.fromJson(raw, XincangDtos.TransferResponse.class).rst;
+ if (result == null || blank(result.orderNo)) {
+ throw WarehouseException.builder()
+ .message("xincang transfer returned no rst.order_no: " + safeRelay(raw))
+ .operation("warehouse.transfer.create")
+ .warehouseCode(ctx.warehouseCode())
+ .provider(provider().name())
+ .requestId(ctx.requestId())
+ .retryable(false)
+ .rawResponse(safeRelay(raw))
+ .build();
+ }
+ return XincangTransferMapper.toCreated(cmd, result.orderNo);
+ }
+
+ /**
+ * 转运审核({@code POST fba.do_approve?token=&order_no=})。
+ *
+ * 注意是 POST 但无请求体,参数全在 query。
+ *
+ * @param transferRequestNo 信仓转运单号,即 {@link #create} 返回的 {@code providerTransferNo}
+ */
+ @Override
+ public void approve(WarehouseContext ctx, String transferRequestNo) {
+ Map params = new LinkedHashMap();
+ params.put("order_no", transferRequestNo);
+ executePostQuery(ctx, XincangConstants.PATH_TRANSFER_APPROVE, params,
+ "warehouse.transfer.approve");
+ }
+
// ------------------------------------------------------------------ internals
/** 写接口:JSON 请求体(含 token)+ query token。 */
@@ -171,6 +295,26 @@ public final class XincangAdapter implements WarehouseProductCapable {
return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body();
}
+ /** 写接口:multipart 表单 + query token(信仓一单多件下单)。 */
+ private String executeMultipart(WarehouseContext ctx, String path, Map form,
+ String operation) {
+ rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND);
+ HttpRequest req = XincangMultipart.post(ctx.endpointBaseUrl(), path, form,
+ login(ctx).value(), operation);
+ HttpResponse resp = transport.execute(req);
+ return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body();
+ }
+
+ /** POST 但无请求体:参数全在 query(转运审核)。 */
+ private String executePostQuery(WarehouseContext ctx, String path, Map params,
+ String operation) {
+ rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND);
+ HttpRequest req = requestFactory.postWithoutBodyWithToken(ctx.endpointBaseUrl(), path, params,
+ login(ctx).value(), operation);
+ HttpResponse resp = transport.execute(req);
+ return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body();
+ }
+
/** 读接口:query token。 */
private String executeGet(WarehouseContext ctx, String path, Map params,
AccessToken token, String operation) {
@@ -189,4 +333,16 @@ public final class XincangAdapter implements WarehouseProductCapable {
static String tokenKey(ChannelSecret secret) {
return XincangConstants.ADAPTER_ID + ":" + secret.appKey();
}
+
+ private static boolean blank(String v) {
+ return v == null || v.trim().isEmpty();
+ }
+
+ /** 原始响应可能含收件人信息,异常里只留首段。 */
+ private static String safeRelay(String raw) {
+ if (raw == null) {
+ return null;
+ }
+ return raw.length() <= 300 ? raw : raw.substring(0, 300) + "...";
+ }
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
new file mode 100644
index 0000000..2e1edf0
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
@@ -0,0 +1,179 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.http.JsonCodec;
+import common.ecommerce.shared.error.ChannelException;
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.model.Platform;
+import common.ecommerce.warehouse.WarehouseProvider;
+import common.ecommerce.warehouse.model.OutboundCommand;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.dto.XincangDtos;
+
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 信仓出库下单报文映射({@code POST api.add_order_multiple})。
+ *
+ * 该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON 字符串。
+ * 平台字段名只出现在本类与 {@link XincangDtos}。
+ *
+ * 文档没有对应字段的就不发:申报信息(HS / 原产国 / 申报价值)、包裹尺寸等
+ * 统一模型里有,但信仓这版接口不收,硬塞只会被忽略或报错。
+ */
+public final class XincangOrderMapper {
+
+ /** 信仓要求发货时间格式 {@code yyyy-MM-dd HH:mm:ss}(北京时间)。 */
+ private static final DateTimeFormatter REQUIRED_DELIVERY_TIME =
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+ /** 地址 1 上限 32 字符,超出部分走 address2。 */
+ private static final int ADDRESS_MAX = 32;
+ /** 订单类型:信仓只接受 common / wayfair。 */
+ static final String ORDER_TYPE_COMMON = "common";
+ static final String ORDER_TYPE_WAYFAIR = "wayfair";
+ /** 签名服务:信仓只收「是 / 否」,模型里没有该字段,默认否。 */
+ private static final String SIGN_NOT_REQUIRED = "否";
+
+ private XincangOrderMapper() {
+ }
+
+ /**
+ * 统一命令 → 信仓一单多件下单表单。
+ *
+ * @param ctx 本次调用上下文(取仓编码)
+ * @param cmd 出库命令
+ * @param json 用于序列化 {@code products}
+ * @throws ValidationException 缺少仓编码或收件人必填项
+ */
+ public static Map toForm(WarehouseContext ctx, OutboundCommand cmd, JsonCodec json) {
+ ShipTo shipTo = cmd.shipTo();
+ requireText(shipTo.name(), "shipTo.name", ctx);
+ requireText(shipTo.phone(), "shipTo.phone", ctx);
+ requireText(shipTo.countryCode(), "shipTo.countryCode", ctx);
+ requireText(shipTo.stateOrProvince(), "shipTo.stateOrProvince", ctx);
+ requireText(shipTo.city(), "shipTo.city", ctx);
+ requireText(shipTo.postalCode(), "shipTo.postalCode", ctx);
+ requireText(shipTo.addressLine1(), "shipTo.addressLine1", ctx);
+
+ String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId());
+ requireText(warehouseCode, "warehouseCode", ctx);
+ // 信仓 logistics_type 是必填的物流方式字典值,这里用 carrierCode 承载
+ requireText(cmd.carrierCode(), "carrierCode (信仓 logistics_type)", ctx);
+
+ Map form = new LinkedHashMap();
+ form.put("order_type", orderTypeOf(cmd.salesPlatform()));
+ form.put("warehouse_code", warehouseCode);
+ // ckh = 参考号,信仓要求唯一;用 OMS 出库单号,便于回查
+ form.put("ckh", cmd.outboundRequestNo());
+
+ Address address = splitAddress(shipTo.addressLine1());
+ form.put("country", shipTo.countryCode().trim());
+ form.put("province", shipTo.stateOrProvince().trim());
+ form.put("city", shipTo.city().trim());
+ form.put("address", address.line1);
+ putIfPresent(form, "address2", address.line2);
+ form.put("postcode", shipTo.postalCode().trim());
+ form.put("receive_user", shipTo.name().trim());
+ form.put("phone", shipTo.phone().trim());
+ putIfPresent(form, "email", shipTo.email());
+ form.put("logistics_type", cmd.carrierCode().trim());
+ form.put("is_sign", SIGN_NOT_REQUIRED);
+ form.put("products", productsJson(cmd.lines(), json));
+
+ // 不传 is_split 时信仓默认 1(拆单);只有调用方显式给值才下发
+ if (cmd.splitOrder() != null) {
+ form.put("is_split", cmd.splitOrder() ? "1" : "0");
+ }
+ Instant latest = cmd.latestShipDate();
+ if (latest != null) {
+ form.put("required_delivery_time", REQUIRED_DELIVERY_TIME.format(
+ LocalDateTime.ofInstant(latest, XincangConstants.SYSTEM_ZONE)));
+ }
+ putIfPresent(form, "remark", cmd.remark());
+ return form;
+ }
+
+ /** 商品明细:{@code [{"product_sku":"...","sku_count":"1"}, ...]}。 */
+ static String productsJson(List lines, JsonCodec json) {
+ List products = new ArrayList(lines.size());
+ for (OutboundLine line : lines) {
+ XincangDtos.OrderProduct product = new XincangDtos.OrderProduct();
+ product.productSku = skuOf(line);
+ product.skuCount = String.valueOf(line.quantity());
+ products.add(product);
+ }
+ return json.toJson(products);
+ }
+
+ /** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */
+ static String skuOf(OutboundLine line) {
+ String providerSku = line.providerSku();
+ if (providerSku != null && !providerSku.trim().isEmpty()) {
+ return providerSku.trim();
+ }
+ return line.omsSku();
+ }
+
+ /**
+ * 信仓订单类型只接受 {@code common} / {@code wayfair}。
+ *
+ * Wayfair 渠道走 {@code wayfair};其余平台走 {@code common}。
+ * 信仓不区分其它平台,不做臆造映射。
+ */
+ static String orderTypeOf(Platform platform) {
+ return platform == Platform.WAYFAIR ? ORDER_TYPE_WAYFAIR : ORDER_TYPE_COMMON;
+ }
+
+ /** 地址超过 32 字符的部分截到 address2,避免被仓侧截断丢信息。 */
+ static Address splitAddress(String address) {
+ String trimmed = address.trim();
+ if (trimmed.length() <= ADDRESS_MAX) {
+ return new Address(trimmed, null);
+ }
+ return new Address(trimmed.substring(0, ADDRESS_MAX), trimmed.substring(ADDRESS_MAX));
+ }
+
+ /** 拆好的地址。 */
+ static final class Address {
+ final String line1;
+ final String line2;
+
+ Address(String line1, String line2) {
+ this.line1 = line1;
+ this.line2 = line2;
+ }
+ }
+
+ private static void putIfPresent(Map form, String key, String value) {
+ if (value != null && !value.trim().isEmpty()) {
+ form.put(key, value.trim());
+ }
+ }
+
+ private static String requireText(String value, String field, WarehouseContext ctx) {
+ if (value == null || value.trim().isEmpty()) {
+ throw new ValidationException(ChannelException.builder()
+ .message("xincang outbound requires " + field)
+ .operation("warehouse.outbound.create")
+ .provider(WarehouseProvider.XINCANG.name())
+ .requestId(ctx.requestId())
+ .retryable(false));
+ }
+ return value.trim();
+ }
+
+ private static String firstNonBlank(String a, String b) {
+ if (a != null && !a.trim().isEmpty()) {
+ return a.trim();
+ }
+ return b == null ? null : b.trim();
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
new file mode 100644
index 0000000..6c3e4e9
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
@@ -0,0 +1,154 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ChannelException;
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.warehouse.WarehouseProvider;
+import common.ecommerce.warehouse.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.model.TransferStatus;
+import common.ecommerce.warehouse.model.TransferType;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.dto.XincangDtos;
+
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 信仓转运 / 调拨报文映射({@code POST fba.do_fba})。
+ *
+ * 信仓的「转运」= 从信仓发货到平台仓(FBA / 其它),在统一模型里对应
+ * {@link TransferType#OUTBOUND}:发货仓是信仓自己,目的仓是平台仓。
+ *
+ * 字典字段({@code order_type} / {@code delivery_mode} / {@code delivery_way} /
+ * {@code label_requirement})信仓只认它自己字典的原值,调用方需从字典接口取;
+ * SDK 不做枚举归一,也不猜测取值。
+ */
+public final class XincangTransferMapper {
+
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+ /** 目的仓不在字典里时的固定写法(文档要求)。 */
+ static final String OTHER_WAREHOUSE_NAME = "其他仓库";
+ /** 标签需求多选分隔符。 */
+ private static final String LABEL_SEPARATOR = ",";
+
+ private XincangTransferMapper() {
+ }
+
+ /** 统一命令 → 信仓新增转运请求。 */
+ public static XincangDtos.TransferRequest toRequest(TransferCommand cmd, WarehouseContext ctx,
+ String productsJson) {
+ if (cmd.type() != TransferType.OUTBOUND) {
+ throw validation(ctx, "xincang transfer only supports OUTBOUND (warehouse -> platform), got "
+ + cmd.type());
+ }
+ XincangDtos.TransferRequest req = new XincangDtos.TransferRequest();
+ req.fbaNo = cmd.transferRequestNo();
+ req.po = firstNonBlank(cmd.po(), cmd.transferRequestNo());
+ req.fromWarehouseName = require(cmd.fromWarehouseCode(),
+ "fromWarehouseCode (信仓 from_warehouse_name)", ctx);
+ req.destWarehouseName = require(cmd.toWarehouseCode(),
+ "toWarehouseCode (信仓 dest_warehouse_name)", ctx);
+ req.otherWarehouse = blankToNull(cmd.otherWarehouseName());
+ req.orderType = blankToNull(cmd.orderType());
+ req.deliveryMode = require(cmd.deliveryMode(), "deliveryMode (信仓转运类型字典值)", ctx);
+ req.deliveryWay = require(cmd.deliveryWay(), "deliveryWay (信仓转运方式字典值)", ctx);
+ req.preSendTime = formatDate(cmd.estimateOutboundDate());
+ if (req.preSendTime == null) {
+ throw validation(ctx, "estimateOutboundDate is required (信仓 pre_send_time)");
+ }
+ if (cmd.palletRequired() == null) {
+ throw validation(ctx, "palletRequired is required (信仓 is_pallet)");
+ }
+ req.isPallet = booleanText(cmd.palletRequired());
+ req.labelRequirement = cmd.labelRequirements().isEmpty() ? null : join(cmd.labelRequirements());
+ req.products = productsJson;
+ req.remark = blankToNull(cmd.remark());
+ req.productPrintCopies = copies(cmd.productLabelCopies());
+ req.ctnPrintCopies = copies(cmd.cartonLabelCopies());
+ req.palletPrintCopies = copies(cmd.palletLabelCopies());
+ return req;
+ }
+
+ /** 转运单创建结果 → 统一模型;信仓只回 {@code order_no},其余字段留空。 */
+ public static TransferOrder toCreated(TransferCommand cmd, String providerTransferNo) {
+ return TransferOrder.builder()
+ .transferRequestNo(cmd.transferRequestNo())
+ .providerTransferNo(providerTransferNo)
+ .fromWarehouseCode(cmd.fromWarehouseCode())
+ .toWarehouseCode(cmd.toWarehouseCode())
+ .type(cmd.type())
+ // 新增成功后处于待审核;审核走 approve
+ .status(TransferStatus.PENDING_REVIEW)
+ .rawStatus("0")
+ .build();
+ }
+
+ /** 产品明细:{@code [{"product_no":"SKU","sku_count":"1"}]}。 */
+ public static List products(TransferCommand cmd) {
+ List products =
+ new ArrayList(cmd.lines().size());
+ for (TransferCommand.TransferLine line : cmd.lines()) {
+ XincangDtos.TransferProduct product = new XincangDtos.TransferProduct();
+ product.productNo = line.providerSku();
+ product.skuCount = String.valueOf(line.quantity());
+ products.add(product);
+ }
+ return products;
+ }
+
+ /** 打托:true → 是 / false → 否 / null → 不传。 */
+ private static String booleanText(Boolean value) {
+ if (value == null) {
+ return null;
+ }
+ return value ? "是" : "否";
+ }
+
+ private static String copies(Integer copies) {
+ return copies == null ? null : String.valueOf(copies);
+ }
+
+ private static String formatDate(LocalDate date) {
+ return date == null ? null : DATE.format(date);
+ }
+
+ private static String join(List values) {
+ StringBuilder sb = new StringBuilder();
+ for (String value : values) {
+ if (sb.length() > 0) {
+ sb.append(LABEL_SEPARATOR);
+ }
+ sb.append(value);
+ }
+ return sb.toString();
+ }
+
+ private static String require(String value, String field, WarehouseContext ctx) {
+ if (value == null || value.trim().isEmpty()) {
+ throw validation(ctx, field + " is required for xincang transfer");
+ }
+ return value.trim();
+ }
+
+ private static String firstNonBlank(String a, String fallback) {
+ if (a != null && !a.trim().isEmpty()) {
+ return a.trim();
+ }
+ return fallback;
+ }
+
+ private static String blankToNull(String v) {
+ return v == null || v.trim().isEmpty() ? null : v.trim();
+ }
+
+ private static ValidationException validation(WarehouseContext ctx, String message) {
+ return new ValidationException(ChannelException.builder()
+ .message(message)
+ .operation("warehouse.transfer.create")
+ .provider(WarehouseProvider.XINCANG.name())
+ .requestId(ctx.requestId())
+ .retryable(false));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
new file mode 100644
index 0000000..0de5d3b
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
@@ -0,0 +1,49 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ChannelException;
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.warehouse.WarehouseProvider;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+
+
+/**
+ * 信仓暂时不支持的出库 / 调拨能力。
+ *
+ * 本轮只接入「新增订单」与「转运创建 / 审核」,查询、取消、包裹都还没接。
+ * 这里统一抛 {@link ValidationException}({@code retryable=false}),不返回空集合——
+ * 静默返回 {@code null} / 空会让调用方以为「仓说没有这单」。
+ */
+final class XincangUnsupportedOutbound {
+
+ private XincangUnsupportedOutbound() {
+ }
+
+ static ValidationException queryUnsupported(WarehouseContext ctx) {
+ throw unsupported(ctx, "warehouse.outbound.query");
+ }
+
+ static ValidationException getUnsupported(WarehouseContext ctx) {
+ throw unsupported(ctx, "warehouse.outbound.get");
+ }
+
+ static ValidationException checkCancelUnsupported(WarehouseContext ctx) {
+ throw unsupported(ctx, "warehouse.outbound.checkCancel");
+ }
+
+ static ValidationException cancelUnsupported(WarehouseContext ctx) {
+ throw unsupported(ctx, "warehouse.outbound.cancel");
+ }
+
+ static ValidationException packagesUnsupported(WarehouseContext ctx) {
+ throw unsupported(ctx, "warehouse.outbound.packages");
+ }
+
+ private static ValidationException unsupported(WarehouseContext ctx, String operation) {
+ return new ValidationException(ChannelException.builder()
+ .message("xincang does not implement " + operation + " yet")
+ .operation(operation)
+ .provider(WarehouseProvider.XINCANG.name())
+ .requestId(ctx.requestId())
+ .retryable(false));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
index ad34d40..5cd7db0 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
@@ -179,4 +179,154 @@ public final class XincangDtos {
@JsonProperty("state")
public String state;
}
+
+ /**
+ * 新增订单(一单多件)请求中的一条商品。
+ *
+ * 信仓把整组商品 JSON 序列化后放进 multipart 的 {@code products} 字段。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class OrderProduct {
+
+ /** 产品 SKU。 */
+ @JsonProperty("product_sku")
+ public String productSku;
+
+ /** 数量(字符串)。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+ }
+
+ /**
+ * 新增订单(一单多件)响应中的 {@code rst}。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderResult {
+
+ /** 信仓系统单号(DS-...)。 */
+ @JsonProperty("order_no")
+ public String orderNo;
+
+ /** 信仓内部订单 id。 */
+ @JsonProperty("order_id")
+ public String orderId;
+ }
+
+ /**
+ * 新增转运请求({@code POST fba.do_fba})。
+ *
+ * 附件字段(产品贴 / 外箱贴 / 托盘贴 / BOL)要求先用 {@code upload.files} 上传,
+ * 再把它返回的 {@code data.data} 对象原样放进来;统一模型不承载附件,本轮不发送。
+ */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class TransferRequest {
+
+ /** 转运单号(业务侧),必填。 */
+ @JsonProperty("fba_no")
+ public String fbaNo;
+
+ /** PO 号,必填。 */
+ @JsonProperty("po")
+ public String po;
+
+ /** 发货仓(仓方字典名称),必填。 */
+ @JsonProperty("from_warehouse_name")
+ public String fromWarehouseName;
+
+ /** 目的仓(仓方字典名称),必填。 */
+ @JsonProperty("dest_warehouse_name")
+ public String destWarehouseName;
+
+ /** 其它仓库名;目的仓选「其他仓库」时填。 */
+ @JsonProperty("other_warehouse")
+ public String otherWarehouse;
+
+ /** 转运类型(订单类型字典值),必填。 */
+ @JsonProperty("order_type")
+ public String orderType;
+
+ /** 转运类型(转运类型字典值),必填。 */
+ @JsonProperty("delivery_mode")
+ public String deliveryMode;
+
+ /** 转运方式 / 配送方式(字典值),必填。 */
+ @JsonProperty("delivery_way")
+ public String deliveryWay;
+
+ /** 预约发货时间 {@code yyyy-MM-dd}。 */
+ @JsonProperty("pre_send_time")
+ public String preSendTime;
+
+ /** 标签需求,多选用英文逗号分隔,如 {@code 产品贴,外箱标签}。 */
+ @JsonProperty("label_requirement")
+ public String labelRequirement;
+
+ /** 是否需要打托:{@code 是} / {@code 否}。 */
+ @JsonProperty("is_pallet")
+ public String isPallet;
+
+ /** 产品明细 JSON 字符串。 */
+ @JsonProperty("products")
+ public String products;
+
+ /** 备注。 */
+ @JsonProperty("remark")
+ public String remark;
+
+ /** 产品贴打印份数。 */
+ @JsonProperty("product_print_copies")
+ public String productPrintCopies;
+
+ /** 外箱贴打印份数。 */
+ @JsonProperty("ctn_print_copies")
+ public String ctnPrintCopies;
+
+ /** 托盘贴打印份数。 */
+ @JsonProperty("pallet_print_copies")
+ public String palletPrintCopies;
+ }
+
+ /** 新增转运请求里的产品明细(序列化进 {@code products} 字符串)。 */
+ @JsonInclude(JsonInclude.Include.NON_NULL)
+ public static final class TransferProduct {
+
+ /** 产品 SKU,必填。 */
+ @JsonProperty("product_no")
+ public String productNo;
+
+ /** 数量(字符串),必填。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+
+ /** 备注。 */
+ @JsonProperty("remark")
+ public String remark;
+ }
+
+ /** 转运单创建结果 {@code rst}。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferResult {
+
+ /** 信仓转运单号(LTL...),审核时传它。 */
+ @JsonProperty("order_no")
+ public String orderNo;
+ }
+
+ /** 新增订单响应外层,用于取 {@code rst}。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderResponse {
+
+ /** 下单结果;业务失败时为 null。 */
+ @JsonProperty("rst")
+ public OrderResult rst;
+ }
+
+ /** 新增转运响应外层,用于取 {@code rst}。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferResponse {
+
+ /** 转运结果;业务失败时为 null。 */
+ @JsonProperty("rst")
+ public TransferResult rst;
+ }
}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java
new file mode 100644
index 0000000..6d942d5
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangMultipart.java
@@ -0,0 +1,81 @@
+package common.ecommerce.xincang.http;
+
+import common.ecommerce.http.HttpRequest;
+
+import java.io.UnsupportedEncodingException;
+import java.net.URLEncoder;
+import java.util.Map;
+import java.util.TreeMap;
+
+/**
+ * multipart/form-data 请求体构造。
+ *
+ * 信仓「新增订单一单多件」要求 {@code multipart/form-data},字段值里的
+ * {@code products} 本身就是一段 JSON 字符串。这里用固定 boundary,
+ * 保证同一份入参生成的报文每次都一样,便于契约测试断言。
+ */
+public final class XincangMultipart {
+
+ /** 固定 boundary:报文可预测。 */
+ static final String BOUNDARY = "----commonEcommerceXincangBoundary";
+ /** 与 boundary 配套的 Content-Type。 */
+ public static final String CONTENT_TYPE = "multipart/form-data; boundary=" + BOUNDARY;
+
+ private XincangMultipart() {
+ }
+
+ /** 构造一个不带文件、只有文本字段的 multipart 请求。 */
+ public static HttpRequest post(String baseUrl, String path, Map form,
+ String token, String operation) {
+ return HttpRequest.builder()
+ .method("POST")
+ .url(trimTrailingSlash(baseUrl) + path
+ + "?token=" + urlEncode(token))
+ .contentType(CONTENT_TYPE)
+ .body(body(form))
+ .operation(operation)
+ .build();
+ }
+
+ /**
+ * 字段按 key 升序输出(信仓文档不要求顺序,固定顺序只为可断言)。
+ *
+ * 值为 null 的字段跳过——可选字段没给就不发,避免把空串误当成业务值。
+ */
+ static String body(Map form) {
+ StringBuilder sb = new StringBuilder();
+ Map sorted = new TreeMap();
+ if (form != null) {
+ for (Map.Entry e : form.entrySet()) {
+ if (e.getValue() != null) {
+ sorted.put(e.getKey(), e.getValue());
+ }
+ }
+ }
+ for (Map.Entry e : sorted.entrySet()) {
+ sb.append("--").append(BOUNDARY).append("\r\n")
+ .append("Content-Disposition: form-data; name=\"").append(e.getKey()).append("\"\r\n")
+ .append("\r\n")
+ .append(e.getValue()).append("\r\n");
+ }
+ sb.append("--").append(BOUNDARY).append("--\r\n");
+ return sb.toString();
+ }
+
+ private static String trimTrailingSlash(String url) {
+ String trimmed = url.trim();
+ int end = trimmed.length();
+ while (end > 0 && trimmed.charAt(end - 1) == '/') {
+ end--;
+ }
+ return trimmed.substring(0, end);
+ }
+
+ private static String urlEncode(String v) {
+ try {
+ return URLEncoder.encode(v == null ? "" : v, "UTF-8");
+ } catch (UnsupportedEncodingException e) {
+ throw new IllegalStateException(e);
+ }
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
index 8417dd4..aea6eb8 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
@@ -36,8 +36,38 @@ public final class XincangRequestFactory {
return get(baseUrl, XincangConstants.PATH_LOGIN, query, operation);
}
+ /**
+ * 业务 POST:参数全部放 query、无请求体。
+ *
+ * 信仓「转运审核」({@code POST fba.do_approve?token=&order_no=})就是这种形态:
+ * 方法必须是 POST,但文档 body 为 none。
+ */
+ public HttpRequest postWithoutBodyWithToken(String baseUrl, String path, Map params,
+ String token, String operation) {
+ Map query = new LinkedHashMap<>();
+ if (params != null) {
+ query.putAll(params);
+ }
+ query.put(XincangConstants.QUERY_TOKEN, requireText(token,
+ "xincang requires a token; call login first"));
+ return HttpRequest.builder()
+ .method("POST")
+ .url(urlWithQuery(baseUrl, path, query))
+ .operation(operation)
+ .build();
+ }
+
/** GET:业务参数全部放 query。 */
public HttpRequest get(String baseUrl, String path, Map params, String operation) {
+ return HttpRequest.builder()
+ .method("GET")
+ .url(urlWithQuery(baseUrl, path, params))
+ .operation(operation)
+ .build();
+ }
+
+ /** 拼 {@code base + path?k=v},null 值跳过。 */
+ private String urlWithQuery(String baseUrl, String path, Map params) {
StringBuilder url = new StringBuilder(trimTrailingSlash(baseUrl)).append(path);
if (params != null && !params.isEmpty()) {
url.append('?');
@@ -53,11 +83,7 @@ public final class XincangRequestFactory {
first = false;
}
}
- return HttpRequest.builder()
- .method("GET")
- .url(url.toString())
- .operation(operation)
- .build();
+ return url.toString();
}
/**
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
index 9b7cfb5..dfb83a4 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
@@ -114,14 +114,16 @@ class XincangAdapterTest {
}
@Test
- void declaresProductOnly() {
+ void declaresImplementedCapabilities() {
XincangAdapter adapter = adapter();
assertEquals(WarehouseProvider.XINCANG, adapter.provider());
assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId());
- assertEquals(EnumSet.of(WarehouseCapability.PRODUCT), adapter.capabilities(),
- "当前只落地商品建档,不声明其它能力位");
+ assertEquals(EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND,
+ WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT), adapter.capabilities());
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
- assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
+ // 库存 / 退货等未接入,仍是 false
+ assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.INVENTORY_QUERY));
}
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
new file mode 100644
index 0000000..adda5c6
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
@@ -0,0 +1,178 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+import common.ecommerce.shared.testkit.RecordingTransport;
+import common.ecommerce.shared.testkit.Responses;
+import common.ecommerce.shared.model.Platform;
+import common.ecommerce.warehouse.WarehouseCapability;
+import common.ecommerce.warehouse.WarehouseProvider;
+import common.ecommerce.warehouse.model.LabelMode;
+import common.ecommerce.warehouse.model.OutboundCommand;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.OutboundReceipt;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 信仓出库下单(一单多件)契约测试。
+ */
+class XincangOrderTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+ private static final String TOKEN = "{T-1}";
+
+ private RecordingTransport transport;
+ private MutableClock clock;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ clock = MutableClock.atUtc("2026-11-10T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"" + TOKEN + "\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-CA-3790", WarehouseProvider.XINCANG, "CA-3790",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ private static OutboundCommand command(Boolean split) {
+ OutboundCommand.Builder b = OutboundCommand.builder()
+ .outboundRequestNo("OB-20261110-001")
+ .orderRef("SO-1")
+ .labelMode(LabelMode.WAREHOUSE_LABEL)
+ .salesPlatform(Platform.AMAZON_SC)
+ .carrierCode("FEDEX-G")
+ .warehouseId("CA-3790")
+ .shipTo(ShipTo.builder()
+ .name("Receiver")
+ .phone("5550000")
+ .countryCode("US")
+ .stateOrProvince("CA")
+ .city("Fontana")
+ .addressLine1("3790 DE FOREST CIRCLE, UNIT B, EXTRA LONG SUFFIX")
+ .postalCode("92337")
+ .build())
+ .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(2).build())
+ .line(OutboundLine.builder().lineNo("2").omsSku("SKU-B").providerSku("SKU-B-XC")
+ .quantity(1).build());
+ if (split != null) {
+ b.splitOrder(split);
+ }
+ return b.build();
+ }
+
+ @Test
+ void createsMultiLineOrderAsMultipart() {
+ transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok(
+ "{\"rst\":{\"order_no\":\"DS-B001-26101300025\",\"order_id\":\"125553878740636306\"},"
+ + "\"errno\":0,\"err\":\"\",\"trace_id\":\"t-order\"}"));
+
+ OutboundReceipt receipt = adapter.create(ctx(), command(true));
+
+ assertEquals("OB-20261110-001", receipt.outboundRequestNo());
+ assertEquals("DS-B001-26101300025", receipt.providerOrderId());
+
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("POST", req.method());
+ assertTrue(req.url().contains("/api.add_order_multiple?token="), req.url());
+ assertTrue(req.contentType().startsWith("multipart/form-data; boundary="), req.contentType());
+
+ String body = req.body();
+ assertTrue(body.contains("name=\"ckh\"\r\n\r\nOB-20261110-001"), body);
+ assertTrue(body.contains("name=\"warehouse_code\"\r\n\r\nCA-3790"), body);
+ assertTrue(body.contains("name=\"logistics_type\"\r\n\r\nFEDEX-G"), body);
+ assertTrue(body.contains("name=\"order_type\"\r\n\r\ncommon"), body);
+ assertTrue(body.contains("name=\"is_split\"\r\n\r\n1"), body);
+ // 商品明细是一段 JSON 字符串
+ assertTrue(body.contains("\"product_sku\":\"SKU-A\""), body);
+ assertTrue(body.contains("\"sku_count\":\"2\""), body);
+ // 仓侧 SKU 优先
+ assertTrue(body.contains("\"product_sku\":\"SKU-B-XC\""), body);
+ // 地址超过 32 位走 address2(前 32 字符 = "3790 DE FOREST CIRCLE, UNIT B, E")
+ assertTrue(body.contains("name=\"address\"\r\n\r\n3790 DE FOREST CIRCLE, UNIT B, E\r\n"), body);
+ assertTrue(body.contains("name=\"address2\"\r\n\r\nXTRA LONG SUFFIX"), body);
+ }
+
+ @Test
+ void splitFlagIsOmittedWhenCallerDidNotSetIt() {
+ transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok(
+ "{\"rst\":{\"order_no\":\"DS-1\",\"order_id\":\"1\"},\"errno\":0,\"err\":\"\"}"));
+
+ adapter.create(ctx(), command(null));
+
+ assertFalse(transport.lastDataRequest().body().contains("name=\"is_split\""),
+ "未显式指定时交给信仓默认(拆单)");
+ }
+
+ @Test
+ void missingShipToFieldFailsBeforeSending() {
+ transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok("{}"));
+ OutboundCommand cmd = OutboundCommand.builder()
+ .outboundRequestNo("OB-2")
+ .salesPlatform(Platform.AMAZON_SC)
+ .carrierCode("FEDEX-G")
+ .warehouseId("CA-3790")
+ .shipTo(ShipTo.builder().name("R").countryCode("US").stateOrProvince("CA")
+ .city("Fontana").addressLine1("1 A St").postalCode("92337").build())
+ .line(OutboundLine.builder().lineNo("1").omsSku("SKU-A").quantity(1).build())
+ .build();
+
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.create(ctx(), cmd));
+ assertTrue(e.getMessage().contains("shipTo.phone"), e.getMessage());
+ // 登录后即失败,不应发出下单请求
+ assertFalse(transport.recorded().stream().anyMatch(
+ r -> r.url().contains(XincangConstants.PATH_ORDER_ADD_MULTIPLE)));
+ }
+
+ @Test
+ void missingProviderOrderNoIsNotSilentSuccess() {
+ transport.route(XincangConstants.PATH_ORDER_ADD_MULTIPLE, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-x\"}"));
+
+ common.ecommerce.warehouse.error.WarehouseException e =
+ assertThrows(common.ecommerce.warehouse.error.WarehouseException.class,
+ () -> adapter.create(ctx(), command(true)));
+ assertTrue(e.getMessage().contains("rst.order_no"), e.getMessage());
+ }
+
+ @Test
+ void queryAndCancelAreExplicitlyUnsupported() {
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.get(ctx(), null));
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.query(ctx(), null));
+ assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
+ }
+
+ @Test
+ void outboundCapabilityIsDeclared() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.SPLIT));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
index 1e50fcb..e2e33f6 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
@@ -19,6 +19,7 @@ import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Duration;
+import java.util.Objects;
import static org.junit.jupiter.api.Assertions.*;
@@ -113,8 +114,8 @@ class XincangProductTest {
assertTrue(addBody.contains("\"product_type\":1"), addBody);
// token 在 body 与 query 两处
assertTrue(addBody.contains("\"token\":\"{T-1}\""), addBody);
- assertTrue(transport.lastDataRequest().url().endsWith("/api.add_product?token=%7BT-1%7D"),
- transport.lastDataRequest().url());
+ assertTrue(Objects.requireNonNull(transport.lastDataRequest()).url().endsWith("/api.add_product?token=%7BT-1%7D"),
+ Objects.requireNonNull(transport.lastDataRequest()).url());
}
@Test
@@ -126,8 +127,8 @@ class XincangProductTest {
ProductResult result = adapter.createOrUpdate(ctx(), product("APITEST001"));
assertEquals("UPDATED", result.status());
- assertTrue(transport.lastDataRequest().url().contains("/api.update_product"), "应走更新接口");
- assertTrue(!transport.lastDataRequest().url().contains("/api.add_product"));
+ assertTrue(Objects.requireNonNull(transport.lastDataRequest()).url().contains("/api.update_product"), "应走更新接口");
+ assertFalse(Objects.requireNonNull(transport.lastDataRequest()).url().contains("/api.add_product"));
}
@Test
@@ -195,11 +196,11 @@ class XincangProductTest {
adapter.createOrUpdate(ctx(), noBarcode);
- String body = transport.lastDataRequest().body();
+ String body = Objects.requireNonNull(transport.lastDataRequest()).body();
assertTrue(body.contains("\"bar_code\":\"APITEST005\""), body);
assertTrue(body.contains("\"amount\":0.00"), body);
// 未指定产品类型时不发该字段
- assertTrue(!body.contains("product_type"), body);
+ assertFalse(body.contains("product_type"), body);
}
@Test
@@ -245,7 +246,7 @@ class XincangProductTest {
@Test
void productCapabilityIsDeclared() {
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
- assertFalse(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
+ assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.PRODUCT));
}
}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
new file mode 100644
index 0000000..4315968
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
@@ -0,0 +1,195 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.ValidationException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+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.model.TransferCommand;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.model.TransferStatus;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.model.TransferType;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.LocalDate;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 信仓转运:新增({@code fba.do_fba})与审核({@code fba.do_approve})契约测试。
+ */
+class XincangTransferTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-10T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-CA-3790", WarehouseProvider.XINCANG, "CA-3790",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ private static TransferCommand command() {
+ return TransferCommand.builder()
+ .transferRequestNo("TR-20261110-001")
+ .type(TransferType.OUTBOUND)
+ .fromWarehouseCode("CA-3790")
+ .toWarehouseCode("ONT8")
+ .po("PO-58016")
+ .orderType("FBA")
+ .deliveryMode("FBA")
+ .deliveryWay("Amazon(亚马逊卡车自提)")
+ .estimateOutboundDate(LocalDate.parse("2026-11-12"))
+ .estimateInboundDate(LocalDate.parse("2026-11-20"))
+ .shipTo(ShipTo.builder().name("FBA").countryCode("US").stateOrProvince("CA")
+ .city("San Bernardino").addressLine1("1 Amazon Way").postalCode("92408").build())
+ .palletRequired(true)
+ .labelRequirement("产品贴")
+ .labelRequirement("外箱标签")
+ .productLabelCopies(4)
+ .cartonLabelCopies(2)
+ .remark("测试转运")
+ .line("LSS29ORANGE", 5)
+ .line("LSS29BLUE", 1)
+ .build();
+ }
+
+ @Test
+ void createsTransferWithJsonBody() {
+ transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok(
+ "{\"rst\":{\"order_no\":\"LTL26101500002\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-fba\"}"));
+
+ TransferOrder order = adapter.create(ctx(), command());
+
+ assertEquals("TR-20261110-001", order.transferRequestNo());
+ assertEquals("LTL26101500002", order.providerTransferNo());
+ assertEquals(TransferStatus.PENDING_REVIEW, order.status());
+
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("POST", req.method());
+ assertTrue(req.url().contains("/fba.do_fba?token="), req.url());
+ String body = req.body();
+ assertTrue(body.contains("\"fba_no\":\"TR-20261110-001\""), body);
+ assertTrue(body.contains("\"po\":\"PO-58016\""), body);
+ assertTrue(body.contains("\"from_warehouse_name\":\"CA-3790\""), body);
+ assertTrue(body.contains("\"dest_warehouse_name\":\"ONT8\""), body);
+ assertTrue(body.contains("\"delivery_mode\":\"FBA\""), body);
+ assertTrue(body.contains("\"delivery_way\":\"Amazon(亚马逊卡车自提)\""), body);
+ assertTrue(body.contains("\"pre_send_time\":\"2026-11-12\""), body);
+ assertTrue(body.contains("\"is_pallet\":\"是\""), body);
+ assertTrue(body.contains("\"label_requirement\":\"产品贴,外箱标签\""), body);
+ assertTrue(body.contains("\"product_print_copies\":\"4\""), body);
+ assertTrue(body.contains("\"ctn_print_copies\":\"2\""), body);
+ // products 是 JSON 字符串
+ assertTrue(body.contains("\\\"product_no\\\":\\\"LSS29ORANGE\\\""), body);
+ assertTrue(body.contains("\\\"sku_count\\\":\\\"5\\\""), body);
+ }
+
+ @Test
+ void approvePostsOrderNoInQueryWithoutBody() {
+ transport.route(XincangConstants.PATH_TRANSFER_APPROVE, req -> Responses.ok(
+ "{\"rst\":true,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-approve\"}"));
+
+ adapter.approve(ctx(), "LTL26101500002");
+
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("POST", req.method());
+ assertTrue(req.url().contains("/fba.do_approve?"), req.url());
+ assertTrue(req.url().contains("order_no=LTL26101500002"), req.url());
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+ assertNull(req.body(), "转运审核无请求体");
+ }
+
+ @Test
+ void approveFailurePropagatesBusinessError() {
+ transport.route(XincangConstants.PATH_TRANSFER_APPROVE, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"转运单状态不允许审核\",\"trace_id\":\"t-bad\"}"));
+
+ common.ecommerce.shared.error.PlatformBusinessException e =
+ assertThrows(common.ecommerce.shared.error.PlatformBusinessException.class,
+ () -> adapter.approve(ctx(), "LTL1"));
+ assertTrue(e.getMessage().contains("不允许审核"), e.getMessage());
+ }
+
+ @Test
+ void nonOutboundTransferTypeIsRejected() {
+ TransferCommand cmd = TransferCommand.builder()
+ .transferRequestNo("TR-2")
+ .type(TransferType.WAREHOUSE_TO_WAREHOUSE)
+ .fromWarehouseCode("A").toWarehouseCode("B")
+ .estimateOutboundDate(LocalDate.now()).estimateInboundDate(LocalDate.now())
+ .line("SKU", 1)
+ .build();
+
+ ValidationException e = assertThrows(ValidationException.class,
+ () -> adapter.create(ctx(), cmd));
+ assertTrue(e.getMessage().contains("OUTBOUND"), e.getMessage());
+ }
+
+ @Test
+ void missingDictionaryFieldsFailBeforeSending() {
+ TransferCommand cmd = TransferCommand.builder()
+ .transferRequestNo("TR-3")
+ .type(TransferType.OUTBOUND)
+ .fromWarehouseCode("CA-3790").toWarehouseCode("ONT8")
+ .estimateOutboundDate(LocalDate.now())
+ .estimateInboundDate(LocalDate.now().plusDays(1))
+ .shipTo(ShipTo.builder().name("FBA").countryCode("US").stateOrProvince("CA")
+ .city("San Bernardino").addressLine1("1 Amazon Way").postalCode("92408").build())
+ .line("SKU", 1)
+ .build();
+
+ ValidationException e = assertThrows(ValidationException.class,
+ () -> adapter.create(ctx(), cmd));
+ assertTrue(e.getMessage().contains("deliveryMode"), e.getMessage());
+ assertFalse(transport.recorded().stream()
+ .anyMatch(r -> r.url().contains(XincangConstants.PATH_TRANSFER_CREATE)));
+ }
+
+ @Test
+ void missingTransferNoIsNotSilentSuccess() {
+ transport.route(XincangConstants.PATH_TRANSFER_CREATE, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\"}"));
+
+ common.ecommerce.warehouse.error.WarehouseException e =
+ assertThrows(common.ecommerce.warehouse.error.WarehouseException.class,
+ () -> adapter.create(ctx(), command()));
+ assertTrue(e.getMessage().contains("rst.order_no"), e.getMessage());
+ }
+
+ @Test
+ void transferCapabilityDeclared() {
+ assertTrue(adapter.capabilities().contains(WarehouseCapability.TRANSFER));
+ assertTrue(adapter.supports("XC-CA-3790", WarehouseCapability.TRANSFER));
+ }
+}