Browse Source

feat(edayun): 对接创建出库单(POST /webApi/order/v1/createOrder)

- dto/EdayunCreateOrderDtos:按文档建模,含地址 / 商品行 / 增值服务附件 /
  打包数据 / 卡车约车等子结构
- adapter/EdayunOrderMapper:字段映射
- adapter/EdayunAdapter:实现 create,声明 OUTBOUND 能力位
  (get/query/cancel/packages 显式抛不支持,文档还没给)

四处容易错的口径:

1. 幂等键是 poNumber。文档要求「取消重推时平台单号保持不变」,
   映射自 orderRef,缺失时退回 outboundRequestNo,不能为 null。
2. promiseShipTime 是毫秒时间戳,不是秒。
3. destProvinceName 要州全称(California),不是二字码(CA)。
   当前原样透传,调用方需自己给全称——映射表待业务确认。
4. 面单要文件 URL,不是 base64。传 base64 在本地就拒绝,
   提示先上传拿 URL,避免发出去被仓方以「不可访问」拒绝。

另:unitPrice 是单价,直接取 declareValue 不乘数量(与运去哪的 skuAmount
总额口径相反);signatureRequired 映射到 addService 的 is_signature。

测试 11 个。edayun 模块 40 个测试全绿。

Co-Authored-By: Claude <noreply@anthropic.com>
master
chenchuchuan 1 week ago
parent
commit
15605b58db
  1. 56
      docs-warehouse/edayun/README.md
  2. 15
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java
  3. 201
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java
  4. 202
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java
  5. 214
      warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCreateOrderDtos.java
  6. 6
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java
  7. 174
      warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java

56
docs-warehouse/edayun/README.md

@ -8,6 +8,7 @@ @@ -8,6 +8,7 @@
| 适配器 / 工厂 | ✅ 类型就绪,能力位为空 |
| 获取 token | ✅ 已对接(`POST /oauth/token`) |
| 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) |
| 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) |
| 其它业务接口 | ⬜ 等文档 |
| 回调 | ⬜ 等文档 |
| 真机验证 | ⬜ 等测试环境 |
@ -133,6 +134,61 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=tr @@ -133,6 +134,61 @@ mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=tr
... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=...
```
## 创建出库单
```
POST /webApi/order/v1/createOrder
请求头:Authorization: Bearer <token> / appKey / timestamp / sign
```
### 幂等键是 `poNumber`
文档原话:「取消重推订单的话,请保证相同订单的平台单号(poNumber)跟之前的一样」。
映射:`OutboundCommand.orderRef()` 优先,缺失时退回 `outboundRequestNo()`。
**不能为 null**——它是仓侧唯一幂等依据。
### 时间戳是毫秒
`promiseShipTime` 是**毫秒**时间戳(文档示例 `1777281423744`),不是秒。
### 地址要州**全称**
| 字段 | 我们要传的 |
|---|---|
| `destProvinceName` | **`California`**,不是 `CA` |
标准模型的 `ShipTo.stateOrProvince` 通常是二字码(`CA`)。当前**原样透传**,
所以调用方要么直接给全称,要么需要一张州码映射表——**待业务确认**。
### 面单:要 **URL**,不是 base64
文档要求「物流产品 + 面单信息(carrierName / trackingNo / labels)」两个条件缺一不可,
且 `labels` 是「完整的可访问文件 URL」。
我们的 `labelContentBase64` 语义是 base64 内容,所以:
- 传 `https://...` → 透传到 `labels`
- 传 base64 → **本地直接拒绝**,提示先上传拿 URL
### 商品行 `unitPrice` 是单价
文档写 `unitPrice`,所以直接取 `OutboundLine.declareValue()`,**不乘数量**。
(注意:运去哪的 `skuAmount` 是总额,是反的。)
### 增值服务
| 标准模型 | 易达云 `addService` |
|---|---|
| `signatureRequired = true` | `is_signature` |
保价(`is_insurance`)标准模型没有对应字段,暂不下发。
### 本期未接的出库能力
`get` / `query` / `cancel` / `packages` 都显式抛
`WarehouseUnsupportedCapabilityException`——文档还没给这几个接口。
## 待确认(问易达云)
| # | 要确认 |

15
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java

@ -36,6 +36,21 @@ public final class EdayunConstants { @@ -36,6 +36,21 @@ public final class EdayunConstants {
/** 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。 */
public static final String PATH_PRODUCT_CREATE = "/webApi/skuInfo/v1/createProduct";
/** 创建出库单({@code POST /webApi/order/v1/createOrder})。 */
public static final String PATH_ORDER_CREATE = "/webApi/order/v1/createOrder";
/** 物流增值:签收服务。 */
public static final String ADD_SERVICE_SIGNATURE = "is_signature";
/** 物流增值:保价服务。 */
public static final String ADD_SERVICE_INSURANCE = "is_insurance";
/** 提货类型:平台安排车提货。 */
public static final int PICKUP_TYPE_PICKUP = 1;
/** 提货类型:仓库自交货。 */
public static final int PICKUP_TYPE_DROPOFF = 2;
/** Content-Type。 */
public static final String CONTENT_TYPE_JSON = "application/json";

201
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java

@ -1,6 +1,8 @@ @@ -1,6 +1,8 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.auth.EdayunTokenClient;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.edayun.dto.EdayunCreateProductDtos;
import common.ecommerce.edayun.http.EdayunRequestFactory;
import common.ecommerce.http.HttpRequest;
@ -12,29 +14,42 @@ import common.ecommerce.shared.spi.AccessToken; @@ -12,29 +14,42 @@ 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.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
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.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.edayun.EdayunConstants;
import java.time.Clock;
import java.util.EnumSet;
import java.util.List;
/**
* 易达云适配器。
*
* <p><b>骨架阶段</b>:只搭好类型与能力声明,业务接口等文档到位后逐个实现。
* 未实现的能力<b>不声明</b>,门面调用会显式抛
* <p>已实现:商品建档、创建出库单。其余能力<b>不声明</b>,门面调用会显式抛
* {@code WarehouseUnsupportedCapabilityException},不返回空集合。</p>
*
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经
* {@code WarehouseConnection} 传入。</p>
*/
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable {
public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCapable,
OutboundCapable {
private final HttpTransport transport;
private final JacksonJsonCodec json;
@ -67,6 +82,26 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -67,6 +82,26 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
};
}
@Override
public String adapterId() {
return EdayunConstants.ADAPTER_ID;
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.EDAYUN;
}
/**
* 已实现的能力。
*
* <p><b>声明了就必须有实现</b>,否则调用方看能力位会以为能用。</p>
*/
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND);
}
/**
* 取一个可用 token(缓存命中则不登录)。
*
@ -85,61 +120,141 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -85,61 +120,141 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
return EdayunConstants.ADAPTER_ID + ":" + secret.appKey() + ":" + secret.clientId();
}
@Override
public String adapterId() {
return EdayunConstants.ADAPTER_ID;
}
// ------------------------------------------------------------------ 商品
/**
* 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。
*
* <p>易达云是「创建」语义,不是「保存」——同 SKU 重复调用大概率报错而不是更新。
* 结果里带仓侧 {@code skuId},宿主可据此判断是否需要后续更新。</p>
*/
@Override
public WarehouseProvider provider() {
return WarehouseProvider.EDAYUN;
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
EdayunCreateProductDtos.CreateProductRequest body =
EdayunProductMapper.toCreateRequest(product);
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_PRODUCT_CREATE, bodyJson,
"warehouse.product.create");
EdayunCreateProductDtos.CreateProductResponse parsed =
json.fromJson(resp.body(), EdayunCreateProductDtos.CreateProductResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.product.create");
String skuCode = parsed.data != null && parsed.data.skuCode != null
? parsed.data.skuCode : body.skuCode;
return ProductResult.of(skuCode, "CREATED",
parsed.data == null ? null : parsed.data.skuId);
}
// ------------------------------------------------------------------ 出库
/**
* 本期没有已实现的能力。
* 创建出库单({@code POST /webApi/order/v1/createOrder})。
*
* <p>接入业务接口时逐个声明——<b>声明了就必须有实现</b>,
* 否则调用方看能力位会以为能用。</p>
* <p>仓侧幂等键是 {@code poNumber}(我们映射自 {@code orderRef})——文档要求
* 「取消重推时平台单号保持不变」。</p>
*/
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.PRODUCT);
}
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
requireLabelUrl(cmd);
// ------------------------------------------------------------------ 商品
EdayunCreateOrderDtos.CreateOrderRequest body =
EdayunOrderMapper.toCreateRequest(cmd, ctx.providerWarehouseId());
String bodyJson = json.toJson(body);
HttpResponse resp = send(ctx, EdayunConstants.PATH_ORDER_CREATE, bodyJson,
"warehouse.outbound.create");
EdayunCreateOrderDtos.CreateOrderResponse parsed =
json.fromJson(resp.body(), EdayunCreateOrderDtos.CreateOrderResponse.class);
requireSuccess(ctx, parsed == null ? null : parsed.code,
parsed == null ? null : parsed.msg, resp, "warehouse.outbound.create");
String providerOrderNo = parsed.data == null ? null : parsed.data.orderNo;
if (providerOrderNo == null || providerOrderNo.trim().isEmpty()) {
throw WarehouseException.builder()
.message("edayun createOrder returned no data.orderNo")
.operation("warehouse.outbound.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderNo.trim(), null);
}
/**
* 创建产品({@code POST /webApi/skuInfo/v1/createProduct})。
* 平台面单:易达云要的是<b>文件 URL</b>,不是 base64。
*
* <p>易达云这个接口是「创建」语义,不是「保存」——同 SKU 重复调用大概率
* 报错而不是更新。所以结果里带仓侧的 {@code skuId},宿主可据此判断
* 是否需要后续更新。</p>
* <p>在本地就拒绝 base64,避免发出去被仓方以「面单不可访问」拒绝后难以定位。</p>
*/
private static void requireLabelUrl(OutboundCommand cmd) {
if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) {
return;
}
String content = cmd.labelContentBase64();
if (content == null || content.trim().isEmpty()) {
return;
}
if (!content.startsWith("http://") && !content.startsWith("https://")) {
throw new IllegalArgumentException(
"edayun requires a label FILE URL (not base64) for "
+ cmd.outboundRequestNo()
+ "; upload the file and pass its https URL");
}
}
/** 查询 / 取消 / 包裹:本期未接,显式拒绝。 */
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
EdayunCreateProductDtos.CreateProductRequest body =
EdayunProductMapper.toCreateRequest(product);
String bodyJson = json.toJson(body);
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
@Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
AccessToken token = token(ctx);
@Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
// ------------------------------------------------------------------ internals
/** 发业务请求(自动取 token、算签名)。 */
private HttpResponse send(WarehouseContext ctx, String path, String bodyJson, String operation) {
AccessToken accessToken = token(ctx);
ChannelSecret secret = ctx.secret();
long timestamp = ctx.clock().millis();
HttpRequest req = requestFactory.business(
ctx.endpointBaseUrl(), EdayunConstants.PATH_PRODUCT_CREATE, "POST",
token.value(), secret.appKey(), secret.appSecret(),
timestamp, bodyJson, "warehouse.product.create");
HttpResponse resp = transport.execute(req);
return parseProductResult(ctx, bodyJson, resp);
ctx.endpointBaseUrl(), path, "POST",
accessToken.value(), secret.appKey(), secret.appSecret(),
timestamp, bodyJson, operation);
return transport.execute(req);
}
private ProductResult parseProductResult(WarehouseContext ctx, String requestJson, HttpResponse resp) {
/** HTTP 非 2xx 与业务码非 200 都要显式失败。 */
private void requireSuccess(WarehouseContext ctx, Integer code, String msg,
HttpResponse resp, String operation) {
int status = resp.statusCode();
if (status < 200 || status >= 300) {
throw WarehouseException.builder()
.message("edayun createProduct failed: http " + status
.message("edayun " + operation + " failed: http " + status
+ ", body=" + safeRelay(resp.body()))
.operation("warehouse.product.create")
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
@ -148,26 +263,18 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa @@ -148,26 +263,18 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa
.retryable(status >= 500)
.build();
}
EdayunCreateProductDtos.CreateProductResponse parsed =
json.fromJson(resp.body(), EdayunCreateProductDtos.CreateProductResponse.class);
if (parsed == null || parsed.code == null || parsed.code != EdayunConstants.CODE_SUCCESS) {
if (code == null || code != EdayunConstants.CODE_SUCCESS) {
throw WarehouseException.builder()
.message("edayun createProduct business error: code="
+ (parsed == null ? null : parsed.code)
+ ", msg=" + (parsed == null ? null : parsed.msg))
.operation("warehouse.product.create")
.message("edayun " + operation + " business error: code=" + code + ", msg=" + msg)
.operation(operation)
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.platformCode(parsed == null ? null : String.valueOf(parsed.code))
.platformCode(code == null ? null : String.valueOf(code))
.rawResponse(safeRelay(resp.body()))
.retryable(false)
.build();
}
String skuCode = parsed.data != null && parsed.data.skuCode != null
? parsed.data.skuCode : json.stringAt(requestJson, "skuCode");
return ProductResult.of(skuCode, "CREATED",
parsed.data == null ? null : parsed.data.skuId);
}
/** 原始响应可能含敏感信息,异常里只留长度与首段。 */

202
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java

@ -0,0 +1,202 @@ @@ -0,0 +1,202 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.EdayunConstants;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.ShipTo;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
/**
* 易达云出库单报文映射({@code POST /webApi/order/v1/createOrder})。
*
* <p>三处需要注意的口径:</p>
* <ul>
* <li><b>幂等键是 {@code poNumber}</b>——文档明确「取消重推要保证平台单号跟之前一样」</li>
* <li><b>时间戳单位是毫秒</b>({@code promiseShipTime}),不是秒</li>
* <li><b>地址是州全称</b>({@code California}),不是二字码——标准模型给的是 {@code CA}</li>
* </ul>
*/
public final class EdayunOrderMapper {
private EdayunOrderMapper() {
}
/** 统一命令 → 创建出库单请求。 */
public static EdayunCreateOrderDtos.CreateOrderRequest toCreateRequest(
OutboundCommand cmd, String providerWarehouseId) {
EdayunCreateOrderDtos.CreateOrderRequest req =
new EdayunCreateOrderDtos.CreateOrderRequest();
// 幂等键:文档要求重推时保持不变
req.poNumber = firstNonBlank(cmd.orderRef(), cmd.outboundRequestNo());
req.remark = cmd.remark();
req.currency = cmd.currency() == null ? null : cmd.currency().trim();
Money total = cmd.declaredTotal();
if (total != null) {
req.orderCost = total.amount().doubleValue();
if (req.currency == null) {
req.currency = total.currency().getCurrencyCode();
}
}
// 仓库:命令显式指定优先,否则用账户配置
req.warehouseId = firstNonBlank(cmd.warehouseId(), providerWarehouseId);
// 平台:易达云要平台名称字符串
req.channelName = channelNameOf(cmd);
req.primeFlag = cmd.sfp();
// 最晚发货时间:毫秒时间戳
req.promiseShipTime = millisOf(cmd.latestShipDate());
req.orderAddressVO = toAddress(cmd.shipTo());
req.productItemVOList = toProducts(cmd.lines());
req.addService = addServicesOf(cmd);
applyPlatformLabel(cmd, req);
applyWarehouseLabel(cmd, req);
return req;
}
/**
* 平台面单 / 自供面单:文档要求「物流产品 + 面单信息」两个条件缺一不可。
*
* <p>标准模型里对应 {@code labelMode=PLATFORM_LABEL} + {@code labelContentBase64} +
* {@code trackingNumber}。</p>
*
* <p><b>注意</b>:易达云要的是<b>文件 URL</b>,不是 base64。所以
* {@code labelContentBase64} 在这里无法直接用——若调用方给的是 URL 就透传,
* 给的是 base64 则拒绝并说明原因(不静默丢弃)。</p>
*/
private static void applyPlatformLabel(OutboundCommand cmd,
EdayunCreateOrderDtos.CreateOrderRequest req) {
if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) {
return;
}
String content = cmd.labelContentBase64();
if (content == null || content.trim().isEmpty()) {
return;
}
if (content.startsWith("http://") || content.startsWith("https://")) {
req.labels = content.trim();
} else {
throw new IllegalArgumentException(
"edayun needs a label FILE URL, got base64 for " + cmd.outboundRequestNo()
+ "; upload the file first and pass its URL");
}
req.trackingNo = firstNonBlank(cmd.trackingNumber(), req.trackingNo);
req.carrierName = firstNonBlank(cmd.carrier(), req.carrierName);
}
/** 仓自有面单:只需承运商信息,不需要 labels。 */
private static void applyWarehouseLabel(OutboundCommand cmd,
EdayunCreateOrderDtos.CreateOrderRequest req) {
if (cmd.labelMode() == LabelMode.PLATFORM_LABEL) {
return;
}
req.carrierName = firstNonBlank(cmd.carrier(), cmd.carrierCode());
}
/** 物流增值:签收 / 保价。 */
private static List<String> addServicesOf(OutboundCommand cmd) {
List<String> services = new ArrayList<String>(2);
if (Boolean.TRUE.equals(cmd.signatureRequired())) {
services.add(EdayunConstants.ADD_SERVICE_SIGNATURE);
}
return services.isEmpty() ? null : services;
}
/** 地址:注意运去哪用州二字码,易达云要州全称。 */
private static EdayunCreateOrderDtos.CreateOrderRequest.OrderAddress toAddress(ShipTo shipTo) {
EdayunCreateOrderDtos.CreateOrderRequest.OrderAddress addr =
new EdayunCreateOrderDtos.CreateOrderRequest.OrderAddress();
addr.buyerName = shipTo.name();
addr.buyerPhone = shipTo.phone();
addr.email = shipTo.email();
addr.destCountryName = shipTo.countryCode();
// 标准模型给的是二字码(CA);易达云要全称(California)。
// 这里原样透传,由调用方决定传哪个——映射表需要业务确认。
addr.destProvinceName = shipTo.stateOrProvince();
addr.destCity = shipTo.city();
addr.destFirstAddress = shipTo.addressLine1();
addr.destSecondAddress = joinNonBlank(shipTo.addressLine2(), shipTo.addressLine3());
addr.zipCode = shipTo.postalCode();
return addr;
}
private static List<EdayunCreateOrderDtos.CreateOrderRequest.ProductItem> toProducts(
List<OutboundLine> lines) {
if (lines == null || lines.isEmpty()) {
return null;
}
List<EdayunCreateOrderDtos.CreateOrderRequest.ProductItem> out =
new ArrayList<EdayunCreateOrderDtos.CreateOrderRequest.ProductItem>(lines.size());
for (OutboundLine line : lines) {
EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item =
new EdayunCreateOrderDtos.CreateOrderRequest.ProductItem();
item.productSku = firstNonBlank(line.providerSku(), line.omsSku());
item.quantity = line.quantity();
Money value = line.declareValue();
if (value != null) {
// 文档说 unitPrice 是单价(不是总额),所以直接取值,不乘数量
item.unitPrice = value.amount().doubleValue();
item.currencyCode = value.currency().getCurrencyCode();
}
if (!line.platformOrderItemIds().isEmpty()) {
item.platformItemId = line.platformOrderItemIds().get(0);
}
out.add(item);
}
return out;
}
/** 平台名称:标准模型是枚举,易达云要字符串。 */
static String channelNameOf(OutboundCommand cmd) {
if (cmd.salesPlatform() == null) {
return null;
}
// Platform 枚举名形如 AMAZON_SC / WALMART_SC / EBAY;
// 取第一段并转成易达云文档里的大小写(Amazon / eBay / Temu / TIKTOK)
String name = cmd.salesPlatform().name();
int underscore = name.indexOf('_');
String base = underscore > 0 ? name.substring(0, underscore) : name;
if ("AMAZON".equals(base)) {
return "Amazon";
}
if ("TIKTOK".equals(base)) {
return "TIKTOK";
}
if ("EBAY".equals(base)) {
return "eBay";
}
// 其余按首字母大写
return base.charAt(0) + base.substring(1).toLowerCase();
}
private static Long millisOf(Instant instant) {
return instant == null ? null : instant.toEpochMilli();
}
private static String joinNonBlank(String a, String b) {
String first = firstNonBlank(a, null);
String second = firstNonBlank(b, null);
if (first == null) {
return second;
}
return second == null ? first : first + " " + second;
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
}
return b != null && !b.trim().isEmpty() ? b.trim() : null;
}
}

214
warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCreateOrderDtos.java

@ -0,0 +1,214 @@ @@ -0,0 +1,214 @@
package common.ecommerce.edayun.dto;
import com.fasterxml.jackson.annotation.JsonInclude;
import java.util.List;
/**
* 易达云报文结构:创建出库单({@code POST /webApi/order/v1/createOrder})。
*
* <p>一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。</p>
*
* <p><b>幂等</b>:文档明确「取消重推订单请保证相同订单的平台单号(poNumber)跟之前的一样」,
* 所以 {@code poNumber} 是仓侧的幂等键。</p>
*/
public final class EdayunCreateOrderDtos {
private EdayunCreateOrderDtos() {
}
/** 创建出库单请求。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CreateOrderRequest {
/** 平台单号(客户单号),≤190。必填,也是仓侧幂等键。 */
public String poNumber;
/** 订单金额。 */
public Double orderCost;
/** 订单金额币种:USD / CNY / HKD。 */
public String currency;
public String buyerId;
public String buyerAccountName;
/** eBay 订单 Transaction ID(订单层面)。 */
public String ebayTransactionId;
/** 仓库 id;不传走分仓规则。 */
public String warehouseId;
/** 物流产品 id;不传走分物流规则。 */
public Long carrierProductId;
/** 订单标签,逗号分隔,≤50 字符。 */
public String orderTag;
/** 客户物流账号 id;面单获取方式是「客户物流账号」时必填。 */
public Long customerLogisticsAccountId;
/** 承运商编码;自有物流 + 客户上传面单时必填。 */
public String carrierName;
/** 提货类型:1 平台安排车提货 / 2 仓库自交货;自有物流时用。 */
public Integer pickUpType;
/** 跟踪号;自有物流时可传客户跟踪号,多个逗号分隔。 */
public String trackingNo;
/** 面单文件 URL(完整可访问);自有物流时必传,多个逗号分隔。 */
public String labels;
/** 物流增值:{@code is_signature} 签收 / {@code is_insurance} 保价。 */
public List<String> addService;
/** 是否 SFP 订单。 */
public Boolean primeFlag;
public String remark;
/** 销售平台名称:Amazon / eBay / Temu / TIKTOK 等。必填。 */
public String channelName;
/** 最晚发货时间(毫秒时间戳)。 */
public Long promiseShipTime;
/** 销售平台单号(亚马逊 buyshipping)。 */
public String salesPlatformOrderNo;
/** 店铺 ID(亚马逊 buyshipping)。 */
public String sellerId;
/** 指令订单附件。 */
public List<InstructionAttach> instructionOrderAttachFileList;
/** 派送地址。必填。 */
public OrderAddress orderAddressVO;
/** 商品明细。必填。 */
public List<ProductItem> productItemVOList;
/** 订单层面的增值服务附件。 */
public List<AddServiceAttachFile> addServiceAttachFiles;
/** 打包数据(有「定制打包」增值服务时必传)。 */
public List<MeteringResult> meteringResultList;
/** 卡车约车信息。 */
public TruckAppointment truckAppointment;
/** 指令订单附件。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class InstructionAttach {
/** 如 {@code package}。 */
public String fileType;
public String filePath;
}
/** 派送地址。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OrderAddress {
public String buyerName;
public String buyerPhone;
public String companyName;
public String zipCode;
/** 国家二字码,如 US。 */
public String destCountryName;
/** 省 / 州全称,如 California。 */
public String destProvinceName;
public String destCity;
public String destDistrict;
public String destSubDistrict;
public String destFirstAddress;
public String destSecondAddress;
public String email;
public String houseNumber;
public String remark;
}
/** 商品行。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ProductItem {
public String productSku;
public Integer quantity;
public Double unitPrice;
public String currencyCode;
/** eBay 商品 id(商品层面)。 */
public String ebayItemId;
/** 平台商品 id(亚马逊 buyshipping)。 */
public String platformItemId;
/** 商品层面的增值服务。 */
public List<ValueAddedService> valueAddedServiceVOList;
}
/** 商品层面的增值服务。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ValueAddedService {
/** 增值服务类型码。 */
public Integer type;
public String fileUrl;
/** 是否覆盖原面单 0 否 / 1 是。 */
public Integer isCoverOldLabel;
public String customizedInstructions;
}
/** 订单层面的增值服务附件。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class AddServiceAttachFile {
public Integer objectType;
public Attribute attributeDTO;
/** 附件属性。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Attribute {
public Integer boxPasteQuantity;
public List<String> fileUrl;
public Integer isCoverOldLabel;
public String customizedInstructions;
}
}
/** 打包数据。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class MeteringResult {
public String boxNo;
public String materialsId;
public String packingCode;
public String packingName;
public Integer packingType;
public Integer packingMode;
public List<MeteringSku> skuList;
}
/** 打包内的 SKU。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class MeteringSku {
public String skuCode;
public String barcode;
public Integer quantity;
}
/** 卡车约车。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TruckAppointment {
public List<Bol> bolList;
}
/** BOL。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Bol {
public String bolCode;
public String bolFileUrl;
public String pickupNum;
public String pickupTime;
public String truckCompany;
}
}
/** 创建出库单响应。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CreateOrderResponse {
/** 200 成功,其他失败。 */
public Integer code;
public String msg;
public OrderData data;
/** 接口响应的唯一 id,排查用。 */
public String traceId;
/** 成功时的订单信息。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class OrderData {
/** 仓侧订单号。 */
public String orderNo;
/** 平台单号(回显请求里的 poNumber)。 */
public String poNumber;
}
}
}

6
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java

@ -64,7 +64,9 @@ class EdayunAdapterTest { @@ -64,7 +64,9 @@ class EdayunAdapterTest {
EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
// 未实现的仍然不声明
assertTrue(!adapter.capabilities().contains(WarehouseCapability.TRACKING));
}
/** 注册到门面后能按 provider 解析到适配器。 */
@ -93,7 +95,7 @@ class EdayunAdapterTest { @@ -93,7 +95,7 @@ class EdayunAdapterTest {
void capabilityQueryIsOffline() {
EdayunAdapter adapter = new EdayunAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(!adapter.capabilities().contains(WarehouseCapability.OUTBOUND));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND));
assertTrue(!adapter.capabilities().contains(WarehouseCapability.TRACKING));
}
}

174
warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java

@ -0,0 +1,174 @@ @@ -0,0 +1,174 @@
package common.ecommerce.edayun.adapter;
import common.ecommerce.edayun.dto.EdayunCreateOrderDtos;
import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.ShipTo;
import org.junit.jupiter.api.Test;
import java.time.Instant;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 创建出库单({@code POST /webApi/order/v1/createOrder})报文映射。
*
* <p>重点:poNumber 是仓侧幂等键、promiseShipTime 是毫秒、州是<b>全称</b>不是二字码。</p>
*/
class EdayunOrderTest {
private static OutboundCommand.Builder base() {
return OutboundCommand.builder()
.outboundRequestNo("OB-1")
.orderRef("P-20261112")
.warehouseId("2")
.currency("USD")
.salesPlatform(Platform.AMAZON_SC)
.shipTo(ShipTo.builder()
.name("张三").phone("+1-555-0100").email("a@b.com")
.countryCode("US").stateOrProvince("California").city("Escondido")
.addressLine1("1308 E Washington Ave").postalCode("92027")
.build())
.line(OutboundLine.builder()
.lineNo("1").omsSku("DM00001").quantity(2)
.declareValue(Money.of("9.99", "USD"))
.build());
}
@Test
void poNumberIsOrderRefNotOurRequestNo() {
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(base().build(), "2");
// 文档:重推时平台单号必须保持不变 → 用 orderRef
assertEquals("P-20261112", req.poNumber);
}
/** 没有 orderRef 时退回来源单号,不能为 null(它是幂等键)。 */
@Test
void poNumberFallsBackToRequestNo() {
OutboundCommand noRef = OutboundCommand.builder()
.outboundRequestNo("OB-2")
.salesPlatform(Platform.AMAZON_SC)
.shipTo(ShipTo.builder().name("a").phone("p")
.countryCode("US").stateOrProvince("CA").city("c")
.addressLine1("a1").postalCode("1").build())
.line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1).build())
.build();
assertEquals("OB-2", EdayunOrderMapper.toCreateRequest(noRef, "2").poNumber);
}
/** 最晚发货时间是毫秒时间戳,不是秒。 */
@Test
void promiseShipTimeIsMillis() {
Instant ship = Instant.parse("2026-11-20T10:00:00Z");
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(base().latestShipDate(ship).build(), "2");
assertEquals(Long.valueOf(ship.toEpochMilli()), req.promiseShipTime);
}
@Test
void mapsAddress() {
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(base().build(), "2");
EdayunCreateOrderDtos.CreateOrderRequest.OrderAddress addr = req.orderAddressVO;
assertEquals("张三", addr.buyerName);
assertEquals("US", addr.destCountryName);
assertEquals("California", addr.destProvinceName);
assertEquals("Escondido", addr.destCity);
assertEquals("1308 E Washington Ave", addr.destFirstAddress);
assertEquals("92027", addr.zipCode);
assertEquals("a@b.com", addr.email);
}
/** 商品行:unitPrice 是单价,不乘数量。 */
@Test
void productUnitPriceIsNotMultiplied() {
EdayunCreateOrderDtos.CreateOrderRequest req =
EdayunOrderMapper.toCreateRequest(base().build(), "2");
assertEquals(1, req.productItemVOList.size());
EdayunCreateOrderDtos.CreateOrderRequest.ProductItem item = req.productItemVOList.get(0);
assertEquals("DM00001", item.productSku);
assertEquals(Integer.valueOf(2), item.quantity);
assertEquals(Double.valueOf(9.99), item.unitPrice);
assertEquals("USD", item.currencyCode);
}
@Test
void mapsOrderCostAndCurrency() {
EdayunCreateOrderDtos.CreateOrderRequest req = EdayunOrderMapper.toCreateRequest(
base().declaredTotal(Money.of("20.00", "USD")).build(), "2");
assertEquals(Double.valueOf(20.0), req.orderCost);
assertEquals("USD", req.currency);
}
@Test
void warehouseIdFromCommandOrAccount() {
assertEquals("2", EdayunOrderMapper.toCreateRequest(base().build(), "99").warehouseId);
OutboundCommand noWarehouse = base().warehouseId(null).build();
assertEquals("99", EdayunOrderMapper.toCreateRequest(noWarehouse, "99").warehouseId);
}
@Test
void platformNameIsEdayunStyle() {
assertEquals("Amazon", EdayunOrderMapper.channelNameOf(
base().salesPlatform(Platform.AMAZON_SC).build()));
assertEquals("eBay", EdayunOrderMapper.channelNameOf(
base().salesPlatform(Platform.EBAY).build()));
assertEquals("TIKTOK", EdayunOrderMapper.channelNameOf(
base().salesPlatform(Platform.TIKTOK).build()));
}
// ------------------------------------------------------------ 面单
/** 平台面单必须给 URL;给 base64 在本地就拒绝。 */
@Test
void platformLabelAcceptsUrlRejectsBase64() {
EdayunCreateOrderDtos.CreateOrderRequest withUrl = EdayunOrderMapper.toCreateRequest(
base().labelMode(LabelMode.PLATFORM_LABEL)
.labelContentBase64("https://files.example/label.pdf")
.trackingNumber("1Z999")
.build(), "2");
assertEquals("https://files.example/label.pdf", withUrl.labels);
assertEquals("1Z999", withUrl.trackingNo);
assertThrows(IllegalArgumentException.class, () -> EdayunOrderMapper.toCreateRequest(
base().labelMode(LabelMode.PLATFORM_LABEL)
.labelContentBase64("JVBERi0xLjQK")
.build(), "2"));
}
/** 仓自有面单:只带承运商,不带 labels。 */
@Test
void warehouseLabelHasNoLabels() {
EdayunCreateOrderDtos.CreateOrderRequest req = EdayunOrderMapper.toCreateRequest(
base().labelMode(LabelMode.WAREHOUSE_LABEL).carrier("FEDEX").build(), "2");
assertNull(req.labels);
assertEquals("FEDEX", req.carrierName);
}
/** 签收服务。 */
@Test
void signatureMapsToAddService() {
EdayunCreateOrderDtos.CreateOrderRequest req = EdayunOrderMapper.toCreateRequest(
base().signatureRequired(true).build(), "2");
assertEquals(1, req.addService.size());
assertEquals("is_signature", req.addService.get(0));
assertNull(EdayunOrderMapper.toCreateRequest(base().build(), "2").addService);
}
}
Loading…
Cancel
Save