diff --git a/docs-warehouse/edayun/README.md b/docs-warehouse/edayun/README.md index b236d70..924aaea 100644 --- a/docs-warehouse/edayun/README.md +++ b/docs-warehouse/edayun/README.md @@ -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 ... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... ``` +## 创建出库单 + +``` +POST /webApi/order/v1/createOrder +请求头:Authorization: Bearer / 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`——文档还没给这几个接口。 + ## 待确认(问易达云) | # | 要确认 | diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java index 4abdfcd..72d09ec 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/EdayunConstants.java @@ -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"; diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java index 2bc8ed1..e967eb5 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapter.java @@ -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; 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; /** * 易达云适配器。 * - *

骨架阶段:只搭好类型与能力声明,业务接口等文档到位后逐个实现。 - * 未实现的能力不声明,门面调用会显式抛 + *

已实现:商品建档、创建出库单。其余能力不声明,门面调用会显式抛 * {@code WarehouseUnsupportedCapabilityException},不返回空集合。

* *

适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。

*/ -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 }; } + @Override + public String adapterId() { + return EdayunConstants.ADAPTER_ID; + } + + @Override + public WarehouseProvider provider() { + return WarehouseProvider.EDAYUN; + } + + /** + * 已实现的能力。 + * + *

声明了就必须有实现,否则调用方看能力位会以为能用。

+ */ + @Override + public EnumSet capabilities() { + return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND); + } + /** * 取一个可用 token(缓存命中则不登录)。 * @@ -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})。 + * + *

易达云是「创建」语义,不是「保存」——同 SKU 重复调用大概率报错而不是更新。 + * 结果里带仓侧 {@code skuId},宿主可据此判断是否需要后续更新。

+ */ @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})。 * - *

接入业务接口时逐个声明——声明了就必须有实现, - * 否则调用方看能力位会以为能用。

+ *

仓侧幂等键是 {@code poNumber}(我们映射自 {@code orderRef})——文档要求 + * 「取消重推时平台单号保持不变」。

*/ @Override - public EnumSet 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})。 + * 平台面单:易达云要的是文件 URL,不是 base64。 * - *

易达云这个接口是「创建」语义,不是「保存」——同 SKU 重复调用大概率 - * 报错而不是更新。所以结果里带仓侧的 {@code skuId},宿主可据此判断 - * 是否需要后续更新。

+ *

在本地就拒绝 base64,避免发出去被仓方以「面单不可访问」拒绝后难以定位。

*/ + 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 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 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 .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); } /** 原始响应可能含敏感信息,异常里只留长度与首段。 */ diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java new file mode 100644 index 0000000..83cf061 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunOrderMapper.java @@ -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})。 + * + *

三处需要注意的口径:

+ *
    + *
  • 幂等键是 {@code poNumber}——文档明确「取消重推要保证平台单号跟之前一样」
  • + *
  • 时间戳单位是毫秒({@code promiseShipTime}),不是秒
  • + *
  • 地址是州全称({@code California}),不是二字码——标准模型给的是 {@code CA}
  • + *
+ */ +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; + } + + /** + * 平台面单 / 自供面单:文档要求「物流产品 + 面单信息」两个条件缺一不可。 + * + *

标准模型里对应 {@code labelMode=PLATFORM_LABEL} + {@code labelContentBase64} + + * {@code trackingNumber}。

+ * + *

注意:易达云要的是文件 URL,不是 base64。所以 + * {@code labelContentBase64} 在这里无法直接用——若调用方给的是 URL 就透传, + * 给的是 base64 则拒绝并说明原因(不静默丢弃)。

+ */ + 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 addServicesOf(OutboundCommand cmd) { + List services = new ArrayList(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 toProducts( + List lines) { + if (lines == null || lines.isEmpty()) { + return null; + } + List out = + new ArrayList(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; + } +} diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCreateOrderDtos.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCreateOrderDtos.java new file mode 100644 index 0000000..eebd1b2 --- /dev/null +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/dto/EdayunCreateOrderDtos.java @@ -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})。 + * + *

一个文件对应一个接口,只放该接口的请求 / 响应与内嵌子结构。

+ * + *

幂等:文档明确「取消重推订单请保证相同订单的平台单号(poNumber)跟之前的一样」, + * 所以 {@code poNumber} 是仓侧的幂等键。

+ */ +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 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 instructionOrderAttachFileList; + + /** 派送地址。必填。 */ + public OrderAddress orderAddressVO; + + /** 商品明细。必填。 */ + public List productItemVOList; + + /** 订单层面的增值服务附件。 */ + public List addServiceAttachFiles; + + /** 打包数据(有「定制打包」增值服务时必传)。 */ + public List 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 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 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 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 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; + } + } +} diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java index 7de7ca8..758bd3d 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunAdapterTest.java @@ -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 { 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)); } } diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java new file mode 100644 index 0000000..fc601fa --- /dev/null +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunOrderTest.java @@ -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})报文映射。 + * + *

重点:poNumber 是仓侧幂等键、promiseShipTime 是毫秒、州是全称不是二字码。

+ */ +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); + } +}