From 703694c3df4cbd5fd99e5faa948d25f81a46c1bc Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Mon, 2 Nov 2026 11:46:31 +0800 Subject: [PATCH] =?UTF-8?q?fix(lingxing):=20=E6=8C=89=E7=9C=9F=E5=AE=9E?= =?UTF-8?q?=E5=93=8D=E5=BA=94=E9=87=8D=E5=86=99=E8=AE=A2=E5=8D=95=20DTO=20?= =?UTF-8?q?=E4=B8=8E=E5=AD=97=E6=AE=B5=E6=98=A0=E5=B0=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 真实 /pb/mp/order/v2/list 响应与文档摘录不一致,原 DTO 字段名全部落空, channelOrderId 为 null,导致 SalesOrder 构造抛 NPE。 - 订单字段改为 global_order_no / amount_currency / status / item_info / platform_info / transaction_info - 平台单号从 platform_info[] 取,合并单排序后取第一个,保证 canonicalKey 稳定 - 收货国家取 platform_info[].store_Country_code - 下单时间取 global_purchase_time,缺失时回落 platform_info[].purchase_time - 金额清洗币种符号与千分位(¥49.16 → 49.16) - 夹具与映射测试按真实结构重写 --- .../ecommerce/lingxing/LingxingOrderMapper.java | 158 ++++++++++++++----- .../ecommerce/lingxing/dto/LingxingOrderDto.java | 93 ++++++----- .../lingxing/dto/LingxingOrderItemDto.java | 61 ++++++-- .../lingxing/dto/LingxingPlatformInfoDto.java | 54 +++++++ .../lingxing/dto/LingxingTransactionInfoDto.java | 30 ++++ .../lingxing/LingxingOrderMapperTest.java | 49 ++++-- .../fixtures/lingxing/orderList/success.json | 173 +++++++++++++++------ 7 files changed, 452 insertions(+), 166 deletions(-) create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingPlatformInfoDto.java create mode 100644 lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingTransactionInfoDto.java diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java index bd8bba4..f9396f4 100644 --- a/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java +++ b/lingxing/src/main/java/common/ecommerce/lingxing/LingxingOrderMapper.java @@ -3,24 +3,35 @@ package common.ecommerce.lingxing; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.lingxing.dto.LingxingOrderDto; import common.ecommerce.lingxing.dto.LingxingOrderItemDto; +import common.ecommerce.lingxing.dto.LingxingPlatformInfoDto; +import common.ecommerce.lingxing.dto.LingxingTransactionInfoDto; import common.ecommerce.model.ChannelProvider; -import common.ecommerce.model.support.Money; import common.ecommerce.model.order.OrderLine; -import common.ecommerce.model.Platform; -import common.ecommerce.model.support.PlatformTime; import common.ecommerce.model.order.SalesOrder; +import common.ecommerce.model.support.Money; +import common.ecommerce.model.support.PlatformTime; import java.time.Instant; import java.time.ZoneId; import java.util.ArrayList; import java.util.Collections; -import java.util.Comparator; import java.util.List; /** * 领星订单 → 统一模型。 * *
领星订单是唯一的映射入口,平台差异全部收敛在这里。
+ * + *字段来源({@code /pb/mp/order/v2/list}):
+ *优先平台单号;缺失时退回领星 order_id(此时跨 provider 无法去重, - * 会由 DuplicateOrderGuard 记录差异)。
+ *优先平台单号;合并单会有多个平台单号,排序后取第一个,保证多次同步得到同一个 key。 + * 都没有时退回领星系统单号(此时跨 provider 无法去重,由 DuplicateOrderGuard 记录差异)。
*/ static String resolveChannelOrderId(LingxingOrderDto dto) { - if (dto.getPlatformOrderNo() != null && !dto.getPlatformOrderNo().trim().isEmpty()) { - return dto.getPlatformOrderNo().trim(); + List待核对:字段名依据领星 OpenAPI 文档摘录,联调时以官方最新文档 - * 与真实响应为准;调整集中在本 DTO 与 {@code LingxingOrderMapper}。
- * - *纯数据容器,使用 Lombok 生成访问器;不承载任何业务不变量。
+ *字段名以 2026-10 官方文档与真实响应为准。几个容易踩的点:
+ *纯数据容器,使用 Lombok 生成访问器。
+ *SKU 语义:{@code msku} 是平台侧 SKU,{@code local_sku} 是领星本地 SKU。 + * 对齐直连渠道时应优先用 {@code msku}。
*/ @Getter @Setter @JsonIgnoreProperties(ignoreUnknown = true) public class LingxingOrderItemDto { - @JsonProperty("order_item_id") - private String orderItemId; + /** 系统商品唯一 ID。 */ + @JsonProperty("id") + private String id; - /** 领星 MSKU,需映射回平台 SKU 才能与直连对齐。 */ - @JsonProperty("sku") - private String sku; + /** 商品行系统唯一键。 */ + @JsonProperty("global_item_no") + private String globalItemNo; - /** 平台 SKU(部分接口返回)。 */ - @JsonProperty("platform_sku") - private String platformSku; + /** 订单明细单号。 */ + @JsonProperty("order_item_no") + private String orderItemNo; + + /** 平台 SKU。 */ + @JsonProperty("msku") + private String msku; + + /** 领星本地 SKU。 */ + @JsonProperty("local_sku") + private String localSku; + + /** 亚马逊 ASIN / 多平台商品 ID。 */ + @JsonProperty("product_no") + private String productNo; + + /** 品名。 */ + @JsonProperty("local_product_name") + private String localProductName; @JsonProperty("quantity") private Integer quantity; - @JsonProperty("item_price") - private String itemPrice; + /** 单价,币种取 {@code amount_currency},可能带币种符号。 */ + @JsonProperty("unit_price_amount") + private String unitPriceAmount; + + /** 商品金额(单价 × 数量)。 */ + @JsonProperty("item_price_amount") + private String itemPriceAmount; + + /** 折扣。 */ + @JsonProperty("discount_amount") + private String discountAmount; - @JsonProperty("tax") - private String tax; + /** 商品税费。 */ + @JsonProperty("tax_amount") + private String taxAmount; - @JsonProperty("discount") - private String discount; + /** 该行对应的平台单号。 */ + @JsonProperty("platform_order_no") + private String platformOrderNo; } diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingPlatformInfoDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingPlatformInfoDto.java new file mode 100644 index 0000000..dd4edec --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingPlatformInfoDto.java @@ -0,0 +1,54 @@ +package common.ecommerce.lingxing.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星订单的平台单信息({@code data.list[].platform_info[]})。 + * + *注意 {@code platform_code} 在这里是字符串(如 {@code "10008"}), + * 而请求参数里是整数数组。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class LingxingPlatformInfoDto { + + /** 平台 CODE,字符串形态。 */ + @JsonProperty("platform_code") + private String platformCode; + + /** 平台订单唯一标识;Shopify 下与 platform_order_name 不同。 */ + @JsonProperty("platform_order_no") + private String platformOrderNo; + + /** 平台订单编号(核对平台单号用这个)。 */ + @JsonProperty("platform_order_name") + private String platformOrderName; + + /** 收货国家二字码。注意官方字段名里 C 是大写。 */ + @JsonProperty("store_Country_code") + private String storeCountryCode; + + /** 平台单状态。 */ + @JsonProperty("status") + private String status; + + /** 平台支付状态。 */ + @JsonProperty("payment_status") + private String paymentStatus; + + /** 平台发货状态。 */ + @JsonProperty("shipping_status") + private String shippingStatus; + + /** 平台订购时间,epoch 秒。 */ + @JsonProperty("purchase_time") + private Long purchaseTime; + + /** 平台发货时间,epoch 秒。 */ + @JsonProperty("delivery_time") + private Long deliveryTime; +} diff --git a/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingTransactionInfoDto.java b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingTransactionInfoDto.java new file mode 100644 index 0000000..23ba9fb --- /dev/null +++ b/lingxing/src/main/java/common/ecommerce/lingxing/dto/LingxingTransactionInfoDto.java @@ -0,0 +1,30 @@ +package common.ecommerce.lingxing.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; +import lombok.Getter; +import lombok.Setter; + +/** + * 领星订单的交易信息({@code data.list[].transaction_info[]})。 + * + *金额是带币种符号的字符串(如 {@code "¥49.16"}),由 mapper 清洗后再转 + * {@link common.ecommerce.model.support.Money}。
+ */ +@Getter +@Setter +@JsonIgnoreProperties(ignoreUnknown = true) +public class LingxingTransactionInfoDto { + + /** 订单总额。 */ + @JsonProperty("order_total_amount") + private String orderTotalAmount; + + /** 商品金额。 */ + @JsonProperty("order_item_amount") + private String orderItemAmount; + + /** 折扣金额。 */ + @JsonProperty("discount_amount") + private String discountAmount; +} diff --git a/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java index 9c0c6b9..d2f33c4 100644 --- a/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java +++ b/lingxing/src/test/java/common/ecommerce/lingxing/LingxingOrderMapperTest.java @@ -1,9 +1,9 @@ package common.ecommerce.lingxing; -import common.ecommerce.model.Platform; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.lingxing.dto.LingxingOrderDto; import common.ecommerce.model.ChannelProvider; +import common.ecommerce.model.Platform; import common.ecommerce.model.order.SalesOrder; import common.ecommerce.testkit.Fixtures; import org.junit.jupiter.api.Test; @@ -13,6 +13,7 @@ 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; class LingxingOrderMapperTest { @@ -30,7 +31,8 @@ class LingxingOrderMapperTest { assertEquals("oms-wm-001", o.omsStoreId()); assertEquals("PO-123456789", o.channelOrderId()); - assertEquals("Shipped", o.status()); + // 领星系统状态原值:6 已发货 + assertEquals("6", o.status()); assertEquals("US", o.shipToCountryCode()); assertEquals(2, o.lines().size()); assertEquals("SKU-RED-M", o.lines().get(0).platformSku()); @@ -43,23 +45,48 @@ class LingxingOrderMapperTest { } @Test - void fallsBackToSkuWhenPlatformSkuMissing() { - SalesOrder o = mapper.toSalesOrder(fixture().get(1), "oms-ebay-001", ZoneId.of("America/New_York")); - assertEquals("MSKU-GREEN-S", o.lines().get(0).platformSku()); - assertNull(o.lines().get(0).tax()); - } - - @Test - void platformOrderNamesSortedForStableCanonicalKey() { + void mergedOrderPicksSortedFirstPlatformOrderNo() { // 返回顺序是 EBAY-2222, EBAY-1111,取排序后第一个,保证多次同步 key 稳定 SalesOrder o = mapper.toSalesOrder(fixture().get(1), "oms-ebay-001", ZoneId.of("America/New_York")); assertEquals("EBAY-1111", o.channelOrderId()); } @Test - void fallsBackToLingxingOrderIdWhenNoPlatformNo() { + void fallsBackToLingxingGlobalOrderNoWhenNoPlatformInfo() { SalesOrder o = mapper.toSalesOrder(fixture().get(2), "oms-tts-001", ZoneId.of("Europe/London")); assertEquals("LX-1003", o.channelOrderId()); + assertEquals(0, o.lines().size()); + assertNull(o.shipToCountryCode()); + } + + @Test + void stripsCurrencySymbolFromAmounts() { + // 真实响应里 order_total_amount 可能是 "¥15.00" + SalesOrder o = mapper.toSalesOrder(fixture().get(1), "oms-ebay-001", ZoneId.of("America/New_York")); + assertEquals("15.00 USD", o.totalAmount().toString()); + } + + @Test + void blankAmountBecomesNull() { + SalesOrder o = mapper.toSalesOrder(fixture().get(1), "oms-ebay-001", ZoneId.of("America/New_York")); + // tax_amount 是空串,不能变成 0 或抛异常 + assertNull(o.lines().get(0).tax()); + } + + @Test + void cleanAmountHandlesSymbolsCommasAndSigns() { + assertEquals("49.16", LingxingOrderMapper.cleanAmount("¥49.16")); + assertEquals("-0.98", LingxingOrderMapper.cleanAmount("¥-0.98")); + assertEquals("1234.56", LingxingOrderMapper.cleanAmount("1,234.56")); + assertEquals("14.00", LingxingOrderMapper.cleanAmount("JP¥14.00")); + assertNull(LingxingOrderMapper.cleanAmount("")); + assertNull(LingxingOrderMapper.cleanAmount("¥")); + assertNull(LingxingOrderMapper.cleanAmount(null)); + } + @Test + void missingBothOrderNumbersFailsLoudly() { + LingxingOrderDto dto = new LingxingOrderDto(); + assertThrows(IllegalArgumentException.class, () -> LingxingOrderMapper.resolveChannelOrderId(dto)); } @Test diff --git a/lingxing/src/test/resources/fixtures/lingxing/orderList/success.json b/lingxing/src/test/resources/fixtures/lingxing/orderList/success.json index 33fb5bb..a0f9753 100644 --- a/lingxing/src/test/resources/fixtures/lingxing/orderList/success.json +++ b/lingxing/src/test/resources/fixtures/lingxing/orderList/success.json @@ -1,76 +1,149 @@ { "code": 0, - "msg": "success", + "message": "操作成功", + "request_id": "351a5dcef3da43ebaca27bfeec606a9b.1793586299739", + "response_time": "2026-11-02 10:24:59", "data": { - "total": 3, + "total": "3", "list": [ { - "order_id": "LX-1001", - "platform_order_no": "PO-123456789", - "platform_code": 10008, + "global_order_no": "103351413752115712", + "original_global_order_no": null, + "reference_no": "1", "store_id": "1108413237731", - "order_status": "Shipped", - "buyer_name": "John Doe", - "country_code": "US", - "currency_code": "USD", - "order_total": "59.97", - "purchase_time": 1793001600, - "update_time": 1793088000, - "purchase_time_locale": "2026-10-26 08:00:00", - "update_time_locale": "2026-10-27 08:00:00", - "item_list": [ + "amount_currency": "USD", + "status": 6, + "delivery_type": 2, + "update_time": "1793088000", + "global_purchase_time": 1793001600, + "global_delivery_time": 0, + "item_info": [ { - "order_item_id": "ITEM-1", - "sku": "MSKU-RED-M", - "platform_sku": "SKU-RED-M", + "id": "8745387", + "global_item_no": "ITEM-1", + "order_item_no": "ITEM-1", + "msku": "SKU-RED-M", + "local_sku": "", + "product_no": "", + "local_product_name": "Red Shirt", "quantity": 2, - "item_price": "19.99", - "tax": "1.60", - "discount": "0.00" + "unit_price_amount": "19.99", + "item_price_amount": "39.98", + "discount_amount": "0.00", + "tax_amount": "1.60", + "platform_order_no": "PO-123456789" }, { - "order_item_id": "ITEM-2", - "sku": "MSKU-BLUE-L", + "id": "8745388", + "global_item_no": "ITEM-2", + "order_item_no": "ITEM-2", + "msku": "SKU-BLUE-L", + "local_sku": "", + "product_no": "", + "local_product_name": "Blue Shirt", "quantity": 1, - "item_price": "19.99", - "tax": "0.80", - "discount": "0.00" + "unit_price_amount": "19.99", + "item_price_amount": "19.99", + "discount_amount": "0.00", + "tax_amount": "0.80", + "platform_order_no": "PO-123456789" + } + ], + "platform_info": [ + { + "order_from": "线上订单", + "platform_order_no": "PO-123456789", + "platform_order_name": "PO-123456789", + "platform_code": "10008", + "store_Country_code": "US", + "status": "Shipped", + "payment_status": "paid", + "shipping_status": "fulfilled", + "purchase_time": 1793001600, + "delivery_time": 0 + } + ], + "transaction_info": [ + { + "order_item_amount": "59.97", + "discount_amount": "0.00", + "order_total_amount": "59.97" } ] }, { - "order_id": "LX-1002", - "platform_order_names": ["EBAY-2222", "EBAY-1111"], - "platform_code": 10003, + "global_order_no": "103351413752115713", "store_id": "1108413237731", - "order_status": "Paid", - "buyer_name": "Jane Roe", - "country_code": "US", - "currency_code": "USD", - "order_total": "15.00", - "purchase_time": 1793002000, - "update_time": 1793088000, - "item_list": [ + "amount_currency": "USD", + "status": 4, + "delivery_type": 2, + "update_time": "1793088000", + "global_purchase_time": 1793002000, + "item_info": [ { - "order_item_id": "ITEM-3", - "sku": "MSKU-GREEN-S", + "id": "8745390", + "global_item_no": "ITEM-3", + "order_item_no": "ITEM-3", + "msku": "MSKU-GREEN-S", + "local_sku": "", + "product_no": "", "quantity": 1, - "item_price": "15.00" + "unit_price_amount": "15.00", + "item_price_amount": "15.00", + "discount_amount": "0.00", + "tax_amount": "", + "platform_order_no": "EBAY-2222" + } + ], + "platform_info": [ + { + "platform_order_no": "EBAY-2222", + "platform_order_name": "EBAY-2222", + "platform_code": "10003", + "store_Country_code": "US", + "status": "Paid", + "payment_status": "paid", + "shipping_status": "", + "purchase_time": 1793002000, + "delivery_time": 0 + }, + { + "platform_order_no": "EBAY-1111", + "platform_order_name": "EBAY-1111", + "platform_code": "10003", + "store_Country_code": "US", + "status": "Paid", + "payment_status": "paid", + "shipping_status": "", + "purchase_time": 1793002000, + "delivery_time": 0 + } + ], + "transaction_info": [ + { + "order_item_amount": "¥15.00", + "discount_amount": "¥0.00", + "order_total_amount": "¥15.00" } ] }, { - "order_id": "LX-1003", - "platform_code": 10011, + "global_order_no": "LX-1003", "store_id": "1108413237731", - "order_status": "Unpaid", - "buyer_name": "No Platform No", - "country_code": "GB", - "currency_code": "GBP", - "order_total": "10.00", - "purchase_time": 1793003000, - "update_time": 1793088000, - "item_list": [] + "amount_currency": "GBP", + "status": 3, + "delivery_type": 2, + "update_time": "1793088000", + "global_purchase_time": 1793003000, + "item_info": [], + "platform_info": [], + "transaction_info": [ + { + "order_item_amount": "10.00", + "discount_amount": "0.00", + "order_total_amount": "10.00" + } + ] } ] }