Browse Source

feat(channel-core): 订单模型补充直连平台的可选字段

沃尔玛订单里有几项领星模型没有的信息,补成可选字段(缺省为 null,不影响现有适配器):

- SalesOrder:买家邮箱、平台订单原始状态、备注等
- OrderLine:行级税费、折扣、行状态原文
- ShipToAddress:街道二行、县区、门牌等直连平台常见字段

新增 SalesOrderOptionalFieldsTest 锁住「字段缺失时为 null、不抛异常」。
feature/walmart
lml 2 days ago
parent
commit
3b381be0ce
  1. 61
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java
  2. 46
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java
  3. 231
      channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java
  4. 113
      channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java

61
channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/OrderLine.java

@ -26,22 +26,51 @@ public final class OrderLine { @@ -26,22 +26,51 @@ public final class OrderLine {
/** 购买数量;0 表示平台未给或解析失败,非 null。 */
private final int quantity;
/** 商品单价;平台未给时为 null。币种通常与订单总额一致。 */
/**
* 商品<b>单价</b>,不是行总额;平台未给时为 null。
*
* <p>有些平台只给整行金额(沃尔玛 {@code ItemPrice.chargeAmount} 是「行金额」),
* 适配器必须除以 {@link #quantity()} 后再填这里;下游按
* {@code unitPrice × quantity} 汇总才不会被算重。</p>
*
* <p><b>除不尽时留 null</b>,不要四舍五入倒推——例如 3 件共 100.00 时
* {@code 33.3333 × 3 = 99.9999},会凭空产生分差。此时精确金额看
* {@link #lineAmount()}。</p>
*/
private final Money unitPrice;
/**
* 行金额(单价 × 数量),平台原值;平台没给时为 null。
*
* <p>与 {@link #unitPrice()} 的关系:平台给单价时由适配器相乘得到,或干脆不填;
* 平台给整行金额时直接放这里,<b>不做除法</b>——这是金额的权威来源,不丢精度。</p>
*/
private final Money lineAmount;
/** 行税额;平台未给时为 null。 */
private final Money tax;
/** 行优惠/折扣金额;平台未给时为 null。 */
private final Money discount;
/**
* 行状态原值;平台不提供时为 null。
*
* <p>沃尔玛取 {@code orderLineStatuses.orderLineStatus[].status}({@code Created} 等),
* 订单级状态由适配器按行状态聚合;领星订单接口不返回行状态。
* 保留原值不做枚举,避免平台加值就编译不过。</p>
*/
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 { @@ -64,11 +93,16 @@ public final class OrderLine {
return quantity;
}
/** 商品单价;平台未给时为 null。 */
/** 商品<b>单价</b>(不是行总额);平台未给或除不尽时为 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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);

46
channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/SalesOrder.java

@ -35,9 +35,25 @@ public final class SalesOrder { @@ -35,9 +35,25 @@ public final class SalesOrder {
/** 买家姓名,平台字段原样;多数领星订单接口不返回,此时为 null。 */
private final String buyerName;
/**
* 买家邮箱,平台字段原样;平台只给中转邮箱时保留中转地址,可空。
*
* <p>沃尔玛取 {@code customerEmailId}(形如 {@code xxx@relay.walmart.com}),
* 领星订单接口不返回该字段。</p>
*/
private final String buyerEmail;
/** 收货国家代码(ISO 3166-1 alpha-2,如 US / DE);领星取 store_Country_code,可空。 */
private final String shipToCountryCode;
/**
* 收货地址;平台不返回地址时为 null。
*
* <p>沃尔玛取 {@code shippingInfo.postalAddress},领星订单接口不返回该字段。
* 只承载收件信息,不含发货仓与物流方式。</p>
*/
private final ShipToAddress shipToAddress;
/** 订单明细行;不可变列表。空列表可能表示该接口未返回商品行(如 FBM 列表),不代表订单无商品。 */
private final List<OrderLine> lines;
@ -58,7 +74,9 @@ public final class SalesOrder { @@ -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<OrderLine>(b.lines));
this.totalAmount = b.totalAmount;
this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt");
@ -91,11 +109,21 @@ public final class SalesOrder { @@ -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<OrderLine> lines() {
return lines;
@ -135,9 +163,15 @@ public final class SalesOrder { @@ -135,9 +163,15 @@ public final class SalesOrder {
/** 买家姓名;可空。 */
private String buyerName;
/** 买家邮箱;可空。 */
private String buyerEmail;
/** 收货国家代码;可空。 */
private String shipToCountryCode;
/** 收货地址;可空。 */
private ShipToAddress shipToAddress;
/** 订单明细行;默认空列表,传入 null 按空列表处理。 */
private List<OrderLine> lines = Collections.emptyList();
@ -177,12 +211,24 @@ public final class SalesOrder { @@ -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<OrderLine> lines) {
this.lines = lines == null ? Collections.<OrderLine>emptyList() : lines;

231
channel-sdk-core/src/main/java/common/ecommerce/channel/model/order/ShipToAddress.java

@ -0,0 +1,231 @@ @@ -0,0 +1,231 @@
package common.ecommerce.channel.model.order;
import java.util.Objects;
/**
* 订单收货地址。
*
* <p>各平台字段名不同、语义一致:沃尔玛 {@code shippingInfo.postalAddress}、
* 亚马逊 {@code ShippingAddress}、领星 {@code address_*}。统一收在这里,
* 平台原始值不再重复存放于 {@code SalesOrder}。</p>
*
* <p>本类只承载<b>收件信息</b>,不含发货仓、物流方式等履约配置;
* 那些属于出库/面单域,由 {@code OutboundOrder} 等模型表达。</p>
*
* <p><b>地址类型不做成枚举</b>:沃尔玛给 {@code RESIDENTIAL} / {@code OFFICE},
* 其它平台可能给别的值,做成枚举后平台加值就会编译不过。原值放在
* {@link #addressType()},由宿主自行解释。</p>
*/
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);
}
}
}

113
channel-sdk-core/src/test/java/common/ecommerce/channel/model/order/SalesOrderOptionalFieldsTest.java

@ -0,0 +1,113 @@ @@ -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);
}
}
Loading…
Cancel
Save