diff --git a/docs-warehouse/edayun/TODO.md b/docs-warehouse/edayun/TODO.md index 3c744c6..61b3053 100644 --- a/docs-warehouse/edayun/TODO.md +++ b/docs-warehouse/edayun/TODO.md @@ -5,6 +5,7 @@ ## 待仓方确认 | # | 问题 | 当前处理 | 影响 | +|---|---|---|---| | 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 | | 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java index 7f8211f..d37c3aa 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/CaseMarkPrintCapable.java @@ -21,7 +21,7 @@ public interface CaseMarkPrintCapable extends WarehouseAdapter { * * @return 已生成的文件(地址或 base64);仓方未返回文件时抛出异常,不返回 null * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException - * 该仓不声明 {@code BARCODE_PRINT} + * 该仓不声明 {@code CASE_MARK_PRINT} */ WarehouseLabel printCaseMarks(WarehouseContext ctx, CaseMarkPrintCommand cmd); } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java index cbdfa19..371ac8d 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseDirectoryCapable.java @@ -44,22 +44,18 @@ public interface WarehouseDirectoryCapable extends WarehouseAdapter { *
与 {@link #carriers} 的区别:那个只给一串物流方式码,这个是承运商 → * 物流服务的两层结构,宿主要做下拉框或按承运商筛选时用这个。
* - *默认走 {@link #carriers} 把码包装成没有名称的条目;能给出结构的仓应覆盖。
+ *默认不支持,不拿 {@link #carriers} 的码硬凑成两层结构—— + * 那样会得到 {@code carrierId == nameEn == "FEDEX-G"} 这种假条目, + * 宿主若按类注释「下单时 carrierName 填 nameEn()」使用,就会把物流方式码 + * 当成承运商名发出去。能给出真实结构的仓自己覆盖。
* * @return 承运商列表;仓方返回空时为 empty list(不是错误) * @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException - * 该仓不声明 {@code DIRECTORY} 或没有承运商接口 + * 该仓没有承运商目录接口 */ default List已实现:商品建档、创建出库单。其余能力不声明,门面调用会显式抛 - * {@code WarehouseUnsupportedCapabilityException},不返回空集合。
+ *已实现的能力见 {@link #capabilities()};没声明的能力门面会显式抛 + * {@code WarehouseUnsupportedCapabilityException},不返回空集合。
* *适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。
@@ -905,7 +905,9 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa // 统一模型不区分业务类型,默认查「店铺订单」(1); // 不传反而返回全账号的产品,量太大 EdayunLogisticsProductDtos.ListProductRequest body = EdayunLogisticsProductMapper.toRequest( - ctx.providerWarehouseId(), APPLICABLE_BUSINESS_STORE_ORDER); + EdayunLogisticsProductMapper.resolveWarehouseId( + warehouseCode, ctx.providerWarehouseId()), + APPLICABLE_BUSINESS_STORE_ORDER); String bodyJson = json.toJson(body); HttpResponse resp = send(ctx, EdayunConstants.PATH_LOGISTICS_PRODUCTS, bodyJson, @@ -1031,12 +1033,13 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa *统一模型的 {@code BoxLabelCommand} 没有「选哪些箱」的字段, * 所以默认整单打印;要打部分箱用重载。
* - *真机未验证:PR 环境该接口返回「接口不存在或未启用」, - * 换到 {@code /newPrintCaseMark}(无 ContentType 后缀)能过参数校验 - * (缺 pageSize 报「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」), - * 但补全后一律「内部服务器错误」。见 docs-warehouse/edayun/TODO.md。
+ *刻意不是 public、也没声明 {@code SKU_LABEL} 能力位:该接口在 PR 环境 + * 参数齐全后一律「内部服务器错误」(路径已确认存在,缺参数有中文校验提示), + * 属于仓方服务端异常。放成 public 会让调用方以为门面够得到,实际门面按 + * {@code SKU_LABEL} 门控、会直接抛不支持。等仓方修复后再提升可见性并声明能力位。 + * 见 docs-warehouse/edayun/TODO.md #68。
*/ - public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) { + WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd) { EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd); return sendSkuLabel(ctx, body); } @@ -1046,8 +1049,8 @@ public final class EdayunAdapter implements WarehouseAdapter, WarehouseProductCa * * @param selection 选箱条件;四选一,全空时本地拒绝 */ - public WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd, - EdayunSkuLabelMapper.CaseSelection selection) { + WarehouseLabel printSkuLabel(WarehouseContext ctx, BoxLabelCommand cmd, + EdayunSkuLabelMapper.CaseSelection selection) { EdayunSkuLabelDtos.PrintSkuLabelRequest body = EdayunSkuLabelMapper.toRequest(cmd, selection); return sendSkuLabel(ctx, body); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java index 7156fa4..092cff6 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunAdapterFactory.java @@ -8,7 +8,6 @@ import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.sdk.WarehouseAdapter; -import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; /** * 易达云适配器工厂。 diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java index 2319de1..753d3e6 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunLogisticsProductMapper.java @@ -36,6 +36,26 @@ public final class EdayunLogisticsProductMapper { return req; } + /** + * 解析仓方仓 id:显式指定的 {@code warehouseCode} 优先,否则用账户配置的。 + * + *两者都必须是易达云的数字仓 id——统一模型叫 {@code warehouseCode} + * 但易达云这个接口只认数字 id。给了非数字就本地拒绝,避免静默退回账户仓 + * (那样调用方以为按自己的仓查了,实际不是)。
+ */ + static String resolveWarehouseId(String warehouseCode, String providerWarehouseId) { + String explicit = warehouseCode == null ? null : warehouseCode.trim(); + if (explicit != null && !explicit.isEmpty()) { + if (warehouseIdOf(explicit) == null) { + throw new IllegalArgumentException( + "edayun logistics products need a numeric warehouse id, got: " + explicit + + " (the unified warehouseCode must carry edayun's numeric id here)"); + } + return explicit; + } + return providerWarehouseId; + } + /** 响应 → 统一产品清单;跳过 {@code -998} 与无效行。 */ public static List静默丢弃的后果是调用方以为条件生效了,实际没有。三个字段的情况:
+ *命令上的 {@code warehouseId} 优先于账户配置——宿主可能指定别的退货仓。
@@ -134,6 +165,10 @@ public final class EdayunReturnMapper { } } + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } + private static String firstNonBlank(String a, String b) { if (a != null && !a.trim().isEmpty()) { return a.trim(); diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java index 235181e..df9f963 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunRmaListMapper.java @@ -64,12 +64,7 @@ public final class EdayunRmaListMapper { req.trackingNos = query.trackingNo().trim(); } - Long warehouseId = warehouseIdOf(providerWarehouseId); - if (warehouseId != null) { - req.warehouseId = warehouseId; - } else if (hasText(query.warehouseCode())) { - req.warehouseCode = query.warehouseCode().trim(); - } + applyWarehouseFilter(req, query, providerWarehouseId); if (hasText(query.providerSku())) { req.skuCode = query.providerSku().trim(); @@ -87,6 +82,32 @@ public final class EdayunRmaListMapper { } /** + * 仓过滤:账户仓 id 与调用方给的仓编码只能二选一。 + * + *易达云文档写明「{@code warehouseCode}(优先使用仓库 id)」,两者同时给时 + * 仓方会忽略编码。若调用方显式指定了另一个仓编码,静默按账户仓查会把 + * 过滤条件丢掉、结果反而变宽——这种冲突在本地拒绝,不猜。
+ */ + private static void applyWarehouseFilter(EdayunRmaListDtos.SelectRmaListRequest req, + ReturnQuery query, String providerWarehouseId) { + Long warehouseId = warehouseIdOf(providerWarehouseId); + String requested = hasText(query.warehouseCode()) ? query.warehouseCode().trim() : null; + + if (warehouseId != null) { + if (requested != null && !requested.equals(String.valueOf(warehouseId))) { + throw new IllegalArgumentException( + "edayun return list cannot filter by warehouseCode '" + requested + + "' while the account is bound to numeric warehouse id " + + warehouseId + "; the vendor would ignore warehouseCode" + + " and query the account warehouse instead"); + } + req.warehouseId = warehouseId; + return; + } + req.warehouseCode = requested; + } + + /** * 单号类型 → 易达云 {@code orderNoSearchType}。 * *null 时按退货单号(1)——仓方默认口径,且与「查某一张 RMA」的直觉一致。
@@ -153,9 +174,10 @@ public final class EdayunRmaListMapper { // 列表没有来源单号字段,用 RMA 号兜底;orderRef 用平台 / 出库单号 .returnRequestNo(firstNonBlank(row.rmaCode, row.ordOrderCode)) .providerReturnId(row.rmaCode) - // 文档响应示例没有 warehouseCode,但真机会返回,优先用它 - .warehouseCode(firstNonBlank(row.warehouseCode, row.warehouseName, - fallbackWarehouseCode)) + // 列表有 warehouseCode(真机返回,文档示例里没有)就直接用; + // **不能退化成 warehouseName**——那是展示名(美西1仓), + // 宿主拿 warehouseCode 做 equals / 回传查询会全线失效。 + .warehouseCode(firstNonBlank(row.warehouseCode, fallbackWarehouseCode)) .orderRef(firstNonBlank(row.platformOrderCode, row.ordOrderCode)) .type(row.returnTypeName) .status(EdayunRmaStatus.toCore(row.status, row.statusName)) diff --git a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java index 5726b17..e753c08 100644 --- a/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java +++ b/warehouse-sdk-edayun/src/main/java/common/ecommerce/edayun/adapter/EdayunTrackMapper.java @@ -66,7 +66,9 @@ public final class EdayunTrackMapper { .carrier(track.carrierName) // 仓方状态是数字码,码表没给;保留原值而不是猜成某个字符串 .status(track.status == null ? null : String.valueOf(track.status)) - .signedBy(track.receiver) + // track.receiver 是「收件人」,不是「签收人」——在途就有值。 + // signedBy 的约定是「未签收为 null」,映射它会让每个在途包裹都被 + // 判成已签收。易达云响应里没有签收人字段,宁可不填。 .firstOnlineAt(parseLocal(track.onlineTime, zone)) .deliveredAt(parseLocal(track.deliveredTime, zone)); diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java index 2080f8b..b471856 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunCarrierTest.java @@ -18,7 +18,6 @@ import java.util.List; 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; /** @@ -150,11 +149,4 @@ class EdayunCarrierTest { assertTrue(transport.lastDataRequest().body().contains("\"warehouseId\":2")); } - /** 仓库列表接口易达云没有,显式拒绝而不是空列表。 */ - @Test - void warehousesAreUnsupported() { - assertThrows(RuntimeException.class, - () -> new EdayunAdapter(stub("{}"), new JacksonJsonCodec()) - .warehouses(ctx("2"))); - } } diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java index 1e33d4d..da18447 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunInventoryTest.java @@ -165,7 +165,8 @@ class EdayunInventoryTest { /** 仓编码缺失时回退 OMS 仓编码,快照必须有 warehouseCode。 */ @Test - void warehouseCodeFallsBack() { EdayunInventoryDtos.InventoryRow r = row(); + void warehouseCodeFallsBack() { + EdayunInventoryDtos.InventoryRow r = row(); r.warehouseCode = null; assertEquals("EDY-WH", EdayunInventoryMapper.toPage( @@ -173,7 +174,8 @@ class EdayunInventoryTest { .items().get(0).warehouseCode()); } - /** 没有 SKU 的行跳过,不应让整页失败。 */ @Test + /** 没有 SKU 的行跳过,不应让整页失败。 */ + @Test void rowsWithoutSkuAreSkipped() { EdayunInventoryDtos.InventoryRow dirty = row(); dirty.skuCode = " "; diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java index 19f5921..f81e129 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunReturnTest.java @@ -84,6 +84,41 @@ class EdayunReturnTest { EdayunReturnMapper.toRequest(cmd, "2").relationNo); } + /** 易达云不接受的命令字段要在本地拒绝,不能静默丢弃。 */ + @Test + void unsupportedCommandFieldsAreRejected() { + assertTrue(throwsOn(ReturnCommand.builder() + .returnRequestNo("RT-9").saleOrderNo("SO-1") + .returnTrackingNo("1Z1").carrierCode("UPS") + .lineName("默认项目") + .line("sku", 1, ReturnDealMethod.DESTROY).build()) + .contains("lineName")); + + assertTrue(throwsOn(ReturnCommand.builder() + .returnRequestNo("RT-9").saleOrderNo("SO-1") + .returnTrackingNo("1Z1").carrierCode("UPS") + .estimatedReceiveDate(java.time.LocalDate.of(2026, 12, 1)) + .line("sku", 1, ReturnDealMethod.DESTROY).build()) + .contains("estimatedReceiveDate")); + + assertTrue(throwsOn(ReturnCommand.builder() + .returnRequestNo("RT-9").saleOrderNo("SO-1") + .returnTrackingNo("1Z1").carrierCode("UPS") + .returnReason("damaged") + .line("sku", 1, ReturnDealMethod.DESTROY).build()) + .contains("returnReason")); + } + + private static String throwsOn(ReturnCommand cmd) { + try { + EdayunReturnMapper.toRequest(cmd, "2"); + org.junit.jupiter.api.Assertions.fail("should have thrown"); + return ""; + } catch (IllegalArgumentException e) { + return e.getMessage(); + } + } + @Test void nonNumericWarehouseGoesToWarehouseCode() { ReturnCommand noWarehouse = ReturnCommand.builder() diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java index 3496789..10cc8d6 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunRmaListTest.java @@ -102,6 +102,29 @@ class EdayunRmaListTest { EdayunRmaListMapper.orderNoSearchTypeOf(ReturnQueryNoType.PLATFORM_ORDER_NO)); } + /** + * 账户绑了数字仓 id 时,调用方再传一个不同的仓编码要本地拒绝—— + * 仓方会忽略 warehouseCode,静默按账户仓查会让结果反而变宽。 + */ + @Test + void conflictingWarehouseCodeIsRejected() { + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> EdayunRmaListMapper.toRequest( + base().warehouseCode("USNY").build(), "2", ZoneOffset.UTC, 1)); + + assertTrue(ex.getMessage().contains("cannot filter by warehouseCode"), ex.getMessage()); + } + + /** 传的仓编码与账户仓 id 一致时放行。 */ + @Test + void matchingWarehouseCodeIsAccepted() { + EdayunRmaListDtos.SelectRmaListRequest req = EdayunRmaListMapper.toRequest( + base().warehouseCode("2").build(), "2", ZoneOffset.UTC, 1); + + assertEquals(Long.valueOf(2L), req.warehouseId); + assertNull(req.warehouseCode); + } + @Test void warehouseIdGoesNumeric() { EdayunRmaListDtos.SelectRmaListRequest numeric = @@ -155,6 +178,7 @@ class EdayunRmaListTest { row.ordOrderCode = "ORD822935302"; row.trackingNo = "ORD822935302"; row.warehouseName = "美西1仓"; + row.warehouseCode = "USLA"; row.warehouseId = 2L; row.returnType = 0; row.returnTypeName = "未妥投退回"; @@ -170,7 +194,8 @@ class EdayunRmaListTest { assertEquals("RMA2411058099", ret.returnRequestNo()); assertEquals("RMA2411058099", ret.providerReturnId()); - assertEquals("美西1仓", ret.warehouseCode()); + // warehouseCode 必须是仓编码,不能是展示名(美西1仓) + assertEquals("USLA", ret.warehouseCode()); assertEquals("102002", ret.orderRef()); assertEquals("未妥投退回", ret.type()); // 6 = 处理中-等待指令 → 待收货 @@ -191,11 +216,11 @@ class EdayunRmaListTest { assertEquals("USLA", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode()); } - /** 没有仓编码时回退仓名,再回退 OMS 仓编码。 */ + /** 响应没有仓编码时直接回退 OMS 仓编码——**不能**退化成仓名(美西1仓)。 */ @Test - void warehouseCodeFallsBackToOms() { + void warehouseCodeFallsBackToOmsNotDisplayName() { EdayunRmaListDtos.RmaRow r = row(); - r.warehouseName = null; + r.warehouseCode = null; assertEquals("EDY-WH", EdayunRmaListMapper.toReturn(r, "EDY-WH").warehouseCode()); } diff --git a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java index 407616e..bbdfa95 100644 --- a/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java +++ b/warehouse-sdk-edayun/src/test/java/common/ecommerce/edayun/adapter/EdayunTrackTest.java @@ -102,7 +102,8 @@ class EdayunTrackTest { assertEquals("LF-1741871641090", info.trackingNumber()); assertEquals("fedex", info.carrier()); assertEquals("1", info.status()); - assertEquals("123", info.signedBy()); + // receiver 是收件人,不是签收人;signedBy 必须为空(未签收契约) + assertNull(info.signedBy()); // 上网 / 妥投时间按 GMT-04:00 解释 assertEquals(Instant.parse("2025-08-19T12:17:00Z"), info.firstOnlineAt()); assertEquals(Instant.parse("2025-08-20T14:00:00Z"), info.deliveredAt());