Browse Source

feat(xincang): 对接商品新增 / 更新(api.add_product / api.update_product)

信仓没有 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 <noreply@anthropic.com>
feature/supplier-lingxing
lml 2 weeks ago
parent
commit
8078e72de9
  1. 10
      README.md
  2. 22
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
  3. 126
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  4. 114
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangProductMapper.java
  5. 114
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
  6. 23
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/http/XincangRequestFactory.java
  7. 7
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
  8. 251
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java

10
README.md

@ -135,7 +135,7 @@ sequenceDiagram
| `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter | | `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter |
| `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 |
| `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) |
| `warehouse-sdk-xincang` | 信仓三方仓适配器(本轮只落地登录换 token;能力位留空) | | `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token + 商品建档 / 更新) |
依赖方向: 依赖方向:
``` ```
@ -320,10 +320,10 @@ common.ecommerce
│ └── http YqnRequestFactory / YqnEnvelope / YqnRateLimiter │ └── http YqnRequestFactory / YqnEnvelope / YqnRateLimiter
│ │
└── xincang 信仓三方仓(warehouse-sdk-xincang) └── xincang 信仓三方仓(warehouse-sdk-xincang)
├── XincangConstants 测试基址、登录路径、query 参数名、限流 ├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流
├── auth XincangTokenClient(GET /api.login,无 refresh) ├── auth XincangTokenClient(GET /api.login,无 refresh)
├── adapter XincangAdapter(本轮仅登录) / XincangAdapterFactory ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper
├── dto XincangDtos.LoginResponse ├── dto XincangDtos(登录 / 商品)
└── http XincangRequestFactory / XincangEnvelope / XincangRateLimiter └── http XincangRequestFactory / XincangEnvelope / XincangRateLimiter
``` ```
@ -914,7 +914,7 @@ mvn test # 全部
mvn -pl lingxing test # 单模块 mvn -pl lingxing test # 单模块
mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test mvn -pl lingxing -Dtest=LingxingSdkListingCallTest test
mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试 mvn -pl warehouse-sdk-yqn test # 运去哪 P1 契约测试
mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 令牌缓存 mvn -pl warehouse-sdk-xincang -am test # 信仓登录 / 令牌缓存 / 商品建档
``` ```
--- ---

22
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java

@ -38,6 +38,18 @@ public final class XincangConstants {
/** 登录换取 token。 */ /** 登录换取 token。 */
public static final String PATH_LOGIN = "/api.login"; 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} 头。 */ /** 登录响应里的 token 归入哪个作用域;信仓用 query 参数传递,不是 {@code Authorization} 头。 */
public static final String TOKEN_LOCATION = "query"; 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_ERRNO = "0";
public static final String SUCCESS_RST_CODE = "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 有效期兜底值(秒)。 * token 有效期兜底值(秒)。
* *
@ -74,6 +91,11 @@ public final class XincangConstants {
/** 信仓以北京时间为准(文档「时间:北京时间」)。 */ /** 信仓以北京时间为准(文档「时间:北京时间」)。 */
public static final ZoneId SYSTEM_ZONE = PlatformTime.BEIJING_ZONE; 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() { private XincangConstants() {
} }
} }

126
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -1,40 +1,68 @@
package common.ecommerce.xincang.adapter; package common.ecommerce.xincang.adapter;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport; import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JsonCodec; import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.http.TokenManager; import common.ecommerce.http.TokenManager;
import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.spi.AccessToken; import common.ecommerce.shared.spi.AccessToken;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; 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.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.XincangConstants;
import common.ecommerce.xincang.auth.XincangTokenClient; 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.time.Clock;
import java.util.EnumSet; import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/** /**
* 信仓适配器(本期只做登录换 token)。 * 信仓适配器。
* *
* <p>文档确认的鉴权方式:{@code GET /api.login?appkey=&secret=} 换取客户级 token, * <p>文档确认的鉴权方式:{@code GET /api.login?appkey=&secret=} 换取客户级 token,
* 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里。 * 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里
* 本轮只落地登录与令牌缓存,出库 / 库存 / 预报等能力位<b>一律不声明</b>, * (新增 / 更新产品的请求体 schema 里也要求一份,见 {@link XincangRequestFactory})。</p>
* 门面调用这些能力会显式抛 {@code WarehouseUnsupportedCapabilityException}。</p> *
* <p>已实现能力:商品建档 / 更新({@link WarehouseCapability#PRODUCT})。
* 其余能力位不声明,门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException}。</p>
* *
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。</p> * {@code WarehouseConnection} 传入。</p>
*/ */
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 XincangTokenClient tokenClient;
private final TokenManager tokenManager; 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) { TokenStore tokenStore, LockProvider lockProvider, Clock clock) {
this.transport = transport;
this.json = json;
this.tokenClient = new XincangTokenClient(transport, json, clock); this.tokenClient = new XincangTokenClient(transport, json, clock);
// 信仓 token 2h、无 refresh 接口:到期前 10 分钟重新登录换取; // 信仓 token 2h、无 refresh 接口:到期前 10 分钟重新登录换取;
// TokenManager 负责锁内防击穿与缓存读写,缓存键按 appkey(客户级)。 // TokenManager 负责锁内防击穿与缓存读写,缓存键按 appkey(客户级)。
@ -45,6 +73,8 @@ public final class XincangAdapter implements WarehouseAdapter {
return tokenClient.fetch(secret.endpointBaseUrl(), secret.appKey(), secret.appSecret()); return tokenClient.fetch(secret.endpointBaseUrl(), secret.appKey(), secret.appSecret());
} }
}; };
this.requestFactory = new XincangRequestFactory(json);
this.rateLimiter = new XincangRateLimiter();
} }
@Override @Override
@ -57,10 +87,9 @@ public final class XincangAdapter implements WarehouseAdapter {
return WarehouseProvider.XINCANG; return WarehouseProvider.XINCANG;
} }
/** 本期没有已实现的能力;后续接入业务接口时再逐个声明。 */
@Override @Override
public EnumSet<WarehouseCapability> capabilities() { public EnumSet<WarehouseCapability> 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()); return tokenManager.getOrRefresh(tokenKey(ctx.secret()), ctx.secret());
} }
// ------------------------------------------------------------------ 商品
/**
* 创建或更新商品。
*
* <p>信仓没有 upsert 接口,按「先查临时产品、有则更新、无则新增」实现:</p>
* <ul>
* <li>{@code api.add_product} 新建的是<b>临时产品</b>({@code state=0}),
* 要用于出库还需另行上架为正式产品({@code api.pub_product},本轮未接入)</li>
* <li>{@code api.update_product} 只对临时产品有效;若同 SKU 已是正式产品,
* 新增会返回「产品SKU已存在」,这里原样抛给调用方,不静默忽略</li>
* </ul>
*
* @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 是否已是临时产品。
*
* <p>{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配,
* 这里再按 {@code product_no} 精确比对一次。</p>
*/
private XincangDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token,
String sku) {
Map<String, Object> 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<XincangDtos.ProductListItem> 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<String, Object> 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。 * 令牌缓存维度:信仓 token 按客户(appkey)发放,同一 appkey 下多仓共用一个 token。
* *

114
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})。
*
* <p>平台字段名只出现在本类与 {@link XincangDtos}。单位换算也在这里:
* 统一模型用 cm / g,信仓用 inch / lbs,按 {@link XincangConstants} 里的常量换算并保留 4 位小数
* (文档「最长四位小数」)。</p>
*
* <p>文档未定义「包装方式 / 是否 SN / 客退处理 / 海关信息」等字段,这些统一模型字段
* <b>不发送</b>,避免自行编造平台不认的键。</p>
*/
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。
*
* <p>信仓把 {@code bar_code} 列为必填且查重(重复会报「产品条形码已存在」),
* 用 SKU 兜底可以保证单次建档能通过;调用方应尽量显式给真实条码。</p>
*/
public static String barcodeOf(WarehouseProduct product) {
String barcode = product.barcode();
if (barcode != null && !barcode.trim().isEmpty()) {
return barcode.trim();
}
return skuOf(product);
}
/**
* 金额:取申报价值。
*
* <p>信仓 {@code amount} 固定美元且最多两位小数,其他币种直接拒绝,避免静默按美元记错价。
* 未给申报价值时按 0.00 发送(文档必填项)。</p>
*/
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;
}
}

114
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java

@ -1,8 +1,11 @@
package common.ecommerce.xincang.dto; package common.ecommerce.xincang.dto;
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.annotation.JsonProperty;
import java.math.BigDecimal;
/** /**
* 信仓报文结构。 * 信仓报文结构。
* *
@ -65,4 +68,115 @@ public final class XincangDtos {
@JsonProperty("token") @JsonProperty("token")
public String token; public String token;
} }
/**
* 新增 / 更新产品请求({@code POST api.add_product} / {@code api.update_product})。
*
* <p>信仓这两个接口的 {@code token} 放在 <b>请求体</b>里(文档 required 列表含 {@code token});
* 新增接口的 query 里同时也收一份,见 {@code XincangRequestFactory}。</p>
*
* <p>单位:金额美元、尺寸英寸、重量磅;与统一模型(cm / g)的换算在
* {@code XincangProductMapper}。</p>
*/
@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[]} 的元素。
*
* <p>只声明判断「是否已存在、处于什么状态」需要的字段。</p>
*/
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class ProductListItem {
/** 产品 SKU。 */
@JsonProperty("product_no")
public String productNo;
/** 产品状态:0 临时产品 / 1 正式产品。 */
@JsonProperty("state")
public String state;
}
} }

23
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}。 * 业务 GET:在 {@code params} 上补 {@code token}。
* *
* <p>后续接口(订单 / 库存 / 预报)都要求 token 作为 query 参数,这个方法集中处理, * <p>订单 / 库存 / 预报 / 产品列表等接口都要求 token 作为 query 参数,这个方法集中处理,
* 免得各 Source 各写一遍。本轮只落地登录,接入业务接口时直接复用。</p> * 免得各处各写一遍。</p>
*/ */
public HttpRequest getWithToken(String baseUrl, String path, Map<String, Object> params, public HttpRequest getWithToken(String baseUrl, String path, Map<String, Object> params,
String token, String operation) { String token, String operation) {
@ -77,6 +77,25 @@ public final class XincangRequestFactory {
return get(baseUrl, path, query, operation); return get(baseUrl, path, query, operation);
} }
/**
* 业务 POST:JSON 请求体,token 同时放 query。
*
* <p>信仓的写接口把 {@code token} 列为必填 <b>query</b> 参数(新增订单、删除产品等均如此),
* 而新增 / 更新产品在请求体 schema 里又要求一份 {@code token}。
* 这里统一两处都带:query 是文档的通用约定,body 由调用方按接口需要自行放入。</p>
*/
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 序列化,其余按字符串。 */ /** 集合 / 对象按 JSON 序列化,其余按字符串。 */
private String stringify(Object value) { private String stringify(Object value) {
if (value instanceof Collection || value instanceof Map) { if (value instanceof Collection || value instanceof Map) {

7
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 org.junit.jupiter.api.Test;
import java.time.Duration; import java.time.Duration;
import java.util.EnumSet;
import static org.junit.jupiter.api.Assertions.*; import static org.junit.jupiter.api.Assertions.*;
@ -113,12 +114,14 @@ class XincangAdapterTest {
} }
@Test @Test
void capabilitiesAreEmptyUntilBusinessApisLand() { void declaresProductOnly() {
XincangAdapter adapter = adapter(); XincangAdapter adapter = adapter();
assertEquals(WarehouseProvider.XINCANG, adapter.provider()); assertEquals(WarehouseProvider.XINCANG, adapter.provider());
assertEquals(XincangConstants.ADAPTER_ID, adapter.adapterId()); 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)); assertFalse(adapter.supports("XC-CA-3790", WarehouseCapability.OUTBOUND));
} }
} }

251
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.*;
/**
* 信仓商品建档契约测试。
*
* <p>覆盖:先查临时产品再决定 add / update、单位换算(cm→inch、g→lbs)、
* token 在两处(query 与 body)、必填兜底与错误传播。</p>
*/
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));
}
}
Loading…
Cancel
Save