From 3b381be0ce0fec7c4ce420830019e80d0c19d46a Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Fri, 20 Nov 2026 11:26:30 +0800 Subject: [PATCH] =?UTF-8?q?feat(channel-core):=20=E8=AE=A2=E5=8D=95?= =?UTF-8?q?=E6=A8=A1=E5=9E=8B=E8=A1=A5=E5=85=85=E7=9B=B4=E8=BF=9E=E5=B9=B3?= =?UTF-8?q?=E5=8F=B0=E7=9A=84=E5=8F=AF=E9=80=89=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 沃尔玛订单里有几项领星模型没有的信息,补成可选字段(缺省为 null,不影响现有适配器): - SalesOrder:买家邮箱、平台订单原始状态、备注等 - OrderLine:行级税费、折扣、行状态原文 - ShipToAddress:街道二行、县区、门牌等直连平台常见字段 新增 SalesOrderOptionalFieldsTest 锁住「字段缺失时为 null、不抛异常」。 --- .../ecommerce/channel/model/order/OrderLine.java | 61 +++++- .../ecommerce/channel/model/order/SalesOrder.java | 46 ++++ .../channel/model/order/ShipToAddress.java | 231 +++++++++++++++++++++ .../model/order/SalesOrderOptionalFieldsTest.java | 113 ++++++++++ 4 files changed, 449 insertions(+), 2 deletions(-) create mode 100644 channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java create mode 100644 channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java index 81d5e6a..145c1ee 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java @@ -26,22 +26,51 @@ public final class OrderLine { /** 购买数量;0 表示平台未给或解析失败,非 null。 */ private final int quantity; - /** 商品单价;平台未给时为 null。币种通常与订单总额一致。 */ + /** + * 商品单价,不是行总额;平台未给时为 null。 + * + *

有些平台只给整行金额(沃尔玛 {@code ItemPrice.chargeAmount} 是「行金额」), + * 适配器必须除以 {@link #quantity()} 后再填这里;下游按 + * {@code unitPrice × quantity} 汇总才不会被算重。

+ * + *

除不尽时留 null,不要四舍五入倒推——例如 3 件共 100.00 时 + * {@code 33.3333 × 3 = 99.9999},会凭空产生分差。此时精确金额看 + * {@link #lineAmount()}。

+ */ private final Money unitPrice; + /** + * 行金额(单价 × 数量),平台原值;平台没给时为 null。 + * + *

与 {@link #unitPrice()} 的关系:平台给单价时由适配器相乘得到,或干脆不填; + * 平台给整行金额时直接放这里,不做除法——这是金额的权威来源,不丢精度。

+ */ + private final Money lineAmount; + /** 行税额;平台未给时为 null。 */ private final Money tax; /** 行优惠/折扣金额;平台未给时为 null。 */ private final Money discount; + /** + * 行状态原值;平台不提供时为 null。 + * + *

沃尔玛取 {@code orderLineStatuses.orderLineStatus[].status}({@code Created} 等), + * 订单级状态由适配器按行状态聚合;领星订单接口不返回行状态。 + * 保留原值不做枚举,避免平台加值就编译不过。

+ */ + private final String status; + private OrderLine(Builder b) { this.lineId = b.lineId; this.platformSku = Objects.requireNonNull(b.platformSku, "platformSku"); this.quantity = b.quantity; this.unitPrice = b.unitPrice; + this.lineAmount = b.lineAmount; this.tax = b.tax; this.discount = b.discount; + this.status = b.status; } /** 创建 Builder。 */ @@ -64,11 +93,16 @@ public final class OrderLine { return quantity; } - /** 商品单价;平台未给时为 null。 */ + /** 商品单价(不是行总额);平台未给或除不尽时为 null。 */ public Money unitPrice() { return unitPrice; } + /** 行金额(单价 × 数量),平台原值;平台没给时为 null。精确金额以它为准。 */ + public Money lineAmount() { + return lineAmount; + } + /** 行税额;平台未给时为 null。 */ public Money tax() { return tax; @@ -79,6 +113,11 @@ public final class OrderLine { return discount; } + /** 行状态原值;平台不返回时为 null。 */ + public String status() { + return status; + } + public static final class Builder { /** 行标识;可空,仅作展示。 */ @@ -93,12 +132,18 @@ public final class OrderLine { /** 商品单价;可空。 */ private Money unitPrice; + /** 行金额;可空。 */ + private Money lineAmount; + /** 行税额;可空。 */ private Money tax; /** 行优惠/折扣金额;可空。 */ private Money discount; + /** 行状态原值;可空。 */ + private String status; + /** 设置行标识;可空。 */ public Builder lineId(String lineId) { this.lineId = lineId; @@ -123,6 +168,12 @@ public final class OrderLine { return this; } + /** 设置行金额(单价 × 数量);平台给整行金额时直接放这里,不做除法。 */ + public Builder lineAmount(Money lineAmount) { + this.lineAmount = lineAmount; + return this; + } + /** 设置行税额;可空。 */ public Builder tax(Money tax) { this.tax = tax; @@ -135,6 +186,12 @@ public final class OrderLine { return this; } + /** 设置行状态原值;可空。 */ + public Builder status(String status) { + this.status = status; + return this; + } + /** 构建明细行;缺 platformSku 时抛 {@link NullPointerException}。 */ public OrderLine build() { return new OrderLine(this); diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java index c123332..2d3315e 100644 --- a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java @@ -35,9 +35,25 @@ public final class SalesOrder { /** 买家姓名,平台字段原样;多数领星订单接口不返回,此时为 null。 */ private final String buyerName; + /** + * 买家邮箱,平台字段原样;平台只给中转邮箱时保留中转地址,可空。 + * + *

沃尔玛取 {@code customerEmailId}(形如 {@code xxx@relay.walmart.com}), + * 领星订单接口不返回该字段。

+ */ + private final String buyerEmail; + /** 收货国家代码(ISO 3166-1 alpha-2,如 US / DE);领星取 store_Country_code,可空。 */ private final String shipToCountryCode; + /** + * 收货地址;平台不返回地址时为 null。 + * + *

沃尔玛取 {@code shippingInfo.postalAddress},领星订单接口不返回该字段。 + * 只承载收件信息,不含发货仓与物流方式。

+ */ + private final ShipToAddress shipToAddress; + /** 订单明细行;不可变列表。空列表可能表示该接口未返回商品行(如 FBM 列表),不代表订单无商品。 */ private final List lines; @@ -58,7 +74,9 @@ public final class SalesOrder { this.channelOrderId = Objects.requireNonNull(b.channelOrderId, "channelOrderId"); this.status = b.status; this.buyerName = b.buyerName; + this.buyerEmail = b.buyerEmail; this.shipToCountryCode = b.shipToCountryCode; + this.shipToAddress = b.shipToAddress; this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); this.totalAmount = b.totalAmount; this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt"); @@ -91,11 +109,21 @@ public final class SalesOrder { return buyerName; } + /** 买家邮箱(可能是平台中转邮箱);可空。 */ + public String buyerEmail() { + return buyerEmail; + } + /** 收货国家代码(ISO 3166-1 alpha-2);可空。 */ public String shipToCountryCode() { return shipToCountryCode; } + /** 收货地址;平台不返回时为 null。 */ + public ShipToAddress shipToAddress() { + return shipToAddress; + } + /** 订单明细行;不可变,可能为空列表。 */ public List lines() { return lines; @@ -135,9 +163,15 @@ public final class SalesOrder { /** 买家姓名;可空。 */ private String buyerName; + /** 买家邮箱;可空。 */ + private String buyerEmail; + /** 收货国家代码;可空。 */ private String shipToCountryCode; + /** 收货地址;可空。 */ + private ShipToAddress shipToAddress; + /** 订单明细行;默认空列表,传入 null 按空列表处理。 */ private List lines = Collections.emptyList(); @@ -177,12 +211,24 @@ public final class SalesOrder { return this; } + /** 设置买家邮箱;可空。 */ + public Builder buyerEmail(String buyerEmail) { + this.buyerEmail = buyerEmail; + return this; + } + /** 设置收货国家代码;可空。 */ public Builder shipToCountryCode(String shipToCountryCode) { this.shipToCountryCode = shipToCountryCode; return this; } + /** 设置收货地址;可空,平台不返回地址时不设置。 */ + public Builder shipToAddress(ShipToAddress shipToAddress) { + this.shipToAddress = shipToAddress; + return this; + } + /** 设置订单明细行;传 null 等价于空列表。 */ public Builder lines(List lines) { this.lines = lines == null ? Collections.emptyList() : lines; diff --git a/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java new file mode 100644 index 0000000..c8aa3dd --- /dev/null +++ b/channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java @@ -0,0 +1,231 @@ +package common.ecommerce.channel.model.order; + +import java.util.Objects; + +/** + * 订单收货地址。 + * + *

各平台字段名不同、语义一致:沃尔玛 {@code shippingInfo.postalAddress}、 + * 亚马逊 {@code ShippingAddress}、领星 {@code address_*}。统一收在这里, + * 平台原始值不再重复存放于 {@code SalesOrder}。

+ * + *

本类只承载收件信息,不含发货仓、物流方式等履约配置; + * 那些属于出库/面单域,由 {@code OutboundOrder} 等模型表达。

+ * + *

地址类型不做成枚举:沃尔玛给 {@code RESIDENTIAL} / {@code OFFICE}, + * 其它平台可能给别的值,做成枚举后平台加值就会编译不过。原值放在 + * {@link #addressType()},由宿主自行解释。

+ */ +public final class ShipToAddress { + + /** 收件人姓名;平台不提供时为 null。 */ + private final String name; + + /** 地址行 1(街道、门牌号);平台不提供时为 null。 */ + private final String address1; + + /** 地址行 2(单元、楼层等);多数订单为 null。 */ + private final String address2; + + /** 城市;平台不提供时为 null。 */ + private final String city; + + /** 州 / 省;平台原始编码(如沃尔玛的 {@code CO}),不做大小写归一。 */ + private final String state; + + /** 邮编;保留平台原值,不补零、不去零。 */ + private final String postalCode; + + /** 国家代码;ISO 3166-1 alpha-2({@code US})或平台原值(沃尔玛给 {@code USA}),可空。 */ + private final String countryCode; + + /** 地址类型原值,如 {@code RESIDENTIAL} / {@code OFFICE};平台不给时为 null。 */ + private final String addressType; + + /** 收件人电话;平台以中转号或虚拟号给出时保留原值。 */ + private final String phone; + + private ShipToAddress(Builder b) { + this.name = b.name; + this.address1 = b.address1; + this.address2 = b.address2; + this.city = b.city; + this.state = b.state; + this.postalCode = b.postalCode; + this.countryCode = b.countryCode; + this.addressType = b.addressType; + this.phone = b.phone; + } + + /** 创建构建器。 */ + public static Builder builder() { + return new Builder(); + } + + /** 收件人姓名。 */ + public String name() { + return name; + } + + /** 地址行 1。 */ + public String address1() { + return address1; + } + + /** 地址行 2。 */ + public String address2() { + return address2; + } + + /** 城市。 */ + public String city() { + return city; + } + + /** 州 / 省。 */ + public String state() { + return state; + } + + /** 邮编。 */ + public String postalCode() { + return postalCode; + } + + /** 国家代码原值。 */ + public String countryCode() { + return countryCode; + } + + /** 地址类型原值。 */ + public String addressType() { + return addressType; + } + + /** 收件人电话。 */ + public String phone() { + return phone; + } + + /** 地址是否为空(全字段为 null);适配器可据此决定要不要挂到订单上。 */ + public boolean isEmpty() { + return name == null && address1 == null && address2 == null && city == null + && state == null && postalCode == null && countryCode == null + && addressType == null && phone == null; + } + + /** 各字段都相同才相等。 */ + @Override + public boolean equals(Object o) { + if (this == o) { + return true; + } + if (!(o instanceof ShipToAddress)) { + return false; + } + ShipToAddress that = (ShipToAddress) o; + return Objects.equals(name, that.name) + && Objects.equals(address1, that.address1) + && Objects.equals(address2, that.address2) + && Objects.equals(city, that.city) + && Objects.equals(state, that.state) + && Objects.equals(postalCode, that.postalCode) + && Objects.equals(countryCode, that.countryCode) + && Objects.equals(addressType, that.addressType) + && Objects.equals(phone, that.phone); + } + + /** 与 {@link #equals(Object)} 一致。 */ + @Override + public int hashCode() { + return Objects.hash(name, address1, address2, city, state, postalCode, countryCode, addressType, phone); + } + + /** 调试输出;地址属于个人信息,这里只输出城市与州,不输出街道与收件人。 */ + @Override + public String toString() { + return "ShipToAddress{" + city + ", " + state + " " + postalCode + " " + countryCode + '}'; + } + + /** 收货地址构建器;所有字段可选。 */ + public static final class Builder { + + /** 收件人姓名。 */ + private String name; + /** 地址行 1。 */ + private String address1; + /** 地址行 2。 */ + private String address2; + /** 城市。 */ + private String city; + /** 州 / 省。 */ + private String state; + /** 邮编。 */ + private String postalCode; + /** 国家代码原值。 */ + private String countryCode; + /** 地址类型原值。 */ + private String addressType; + /** 收件人电话。 */ + private String phone; + + /** 设置收件人姓名。 */ + public Builder name(String name) { + this.name = name; + return this; + } + + /** 设置地址行 1。 */ + public Builder address1(String address1) { + this.address1 = address1; + return this; + } + + /** 设置地址行 2。 */ + public Builder address2(String address2) { + this.address2 = address2; + return this; + } + + /** 设置城市。 */ + public Builder city(String city) { + this.city = city; + return this; + } + + /** 设置州 / 省。 */ + public Builder state(String state) { + this.state = state; + return this; + } + + /** 设置邮编。 */ + public Builder postalCode(String postalCode) { + this.postalCode = postalCode; + return this; + } + + /** 设置国家代码原值。 */ + public Builder countryCode(String countryCode) { + this.countryCode = countryCode; + return this; + } + + /** 设置地址类型原值。 */ + public Builder addressType(String addressType) { + this.addressType = addressType; + return this; + } + + /** 设置收件人电话。 */ + public Builder phone(String phone) { + this.phone = phone; + return this; + } + + /** 构建地址对象;不做必填校验,缺字段就是 null。 */ + public ShipToAddress build() { + return new ShipToAddress(this); + } + } +} diff --git a/channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java b/channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java new file mode 100644 index 0000000..67874ca --- /dev/null +++ b/channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java @@ -0,0 +1,113 @@ +package common.ecommerce.channel.model.order; + +import common.ecommerce.shared.model.ChannelProvider; +import common.ecommerce.shared.support.Money; +import common.ecommerce.shared.support.PlatformTime; +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.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 订单模型的增量字段必须全是可选的:老适配器(领星)不传时行为不能变。 + */ +class SalesOrderOptionalFieldsTest { + + private static SalesOrder minimalOrder() { + return SalesOrder.builder() + .omsStoreId("oms-wm-001") + .channelOrderId("PO-1") + .occurredAt(PlatformTime.of(Instant.parse("2026-11-18T00:00:00Z"), "America/Chicago")) + .sourceProvider(ChannelProvider.LINGXING) + .build(); + } + + @Test + void addressAndEmailDefaultToNull() { + SalesOrder order = minimalOrder(); + assertNull(order.buyerEmail()); + assertNull(order.shipToAddress()); + assertNull(order.buyerName()); + assertNull(order.shipToCountryCode()); + } + + @Test + void lineStatusDefaultsToNull() { + OrderLine line = OrderLine.builder().platformSku("SKU-1").quantity(1).build(); + assertNull(line.status()); + assertNull(line.lineId()); + } + + @Test + void walmartStyleOrderKeepsAllNewFields() { + SalesOrder order = SalesOrder.builder() + .omsStoreId("oms-wm-001") + .channelOrderId("108816631915371") + .status("Created") + .buyerName("Astro Test") + .buyerEmail("buyer@relay.walmart.com") + .shipToCountryCode("USA") + .shipToAddress(ShipToAddress.builder() + .name("Astro Test") + .address1("5809 W 44th Ave") + .city("Lakeside") + .state("CO") + .postalCode("80212") + .countryCode("USA") + .addressType("OFFICE") + .phone("555-0100") + .build()) + .lines(java.util.Collections.singletonList(OrderLine.builder() + .lineId("1") + .platformSku("SKU-1") + .quantity(1) + .unitPrice(Money.of("499.99", "USD")) + .status("Created") + .build())) + .occurredAt(PlatformTime.of(Instant.ofEpochMilli(1686736267000L), "America/Chicago")) + .sourceProvider(ChannelProvider.DIRECT) + .build(); + + assertEquals("buyer@relay.walmart.com", order.buyerEmail()); + assertEquals("Lakeside", order.shipToAddress().city()); + assertEquals("Created", order.lines().get(0).status()); + assertEquals("499.99", order.lines().get(0).unitPrice().amount().toPlainString()); + } + + @Test + void addressIsEmptyOnlyWhenEveryFieldIsNull() { + assertTrue(ShipToAddress.builder().build().isEmpty()); + assertFalse(ShipToAddress.builder().city("Lakeside").build().isEmpty()); + } + + @Test + void addressEqualityCoversEveryField() { + ShipToAddress a = ShipToAddress.builder().address1("1 Main St").city("Dallas").build(); + ShipToAddress b = ShipToAddress.builder().address1("1 Main St").city("Dallas").build(); + ShipToAddress c = ShipToAddress.builder().address1("1 Main St").city("Austin").build(); + + assertEquals(a, b); + assertEquals(a.hashCode(), b.hashCode()); + assertFalse(a.equals(c)); + } + + @Test + void addressToStringHidesPersonalFields() { + ShipToAddress address = ShipToAddress.builder() + .name("Jane Doe") + .address1("1 Main St") + .city("Dallas") + .state("TX") + .postalCode("75201") + .countryCode("USA") + .build(); + String text = address.toString(); + assertFalse(text.contains("Jane Doe"), text); + assertFalse(text.contains("1 Main St"), text); + assertTrue(text.contains("Dallas"), text); + } +}