From e716a2593e7ba7e774cbe53c22bac4f55fbf0ed6 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Thu, 19 Nov 2026 09:18:31 +0800 Subject: [PATCH] =?UTF-8?q?feat(walmart):=20=E6=B2=83=E5=B0=94=E7=8E=9B=20?= =?UTF-8?q?Marketplace=20=E7=9B=B4=E8=BF=9E=E9=80=82=E9=85=8D=E5=99=A8?= =?UTF-8?q?=EF=BC=88=E5=8F=AA=E8=AF=BB=E4=B8=80=E6=9C=9F=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 通道 ChannelProvider.DIRECT + Platform.WALMART_SC,新增模块 channel-sdk-walmart。 一期只做只读:鉴权、订单、商品、售后。标发、退款、商品写入不在本期, 对应能力位也不声明——门面调用会显式抛 UnsupportedCapabilityException。 【core 模型增量】全部是可选字段,不影响领星现有行为: - 新增 ShipToAddress(收件信息;toString 只输出城市/州/邮编,不输出街道与姓名) - SalesOrder 增加 buyerEmail / shipToAddress - OrderLine 增加 status(行状态原值)与 lineAmount(行金额,金额权威来源) - OrderLine.unitPrice 明确为「单价」:行金额除以数量,除不尽时留 null 而不是四舍五入倒推,否则 unitPrice × quantity 与原金额会差出分差 【适配器】 - POST /v3/token(Basic Auth + client_credentials),按 clientId 缓存, 提前 120s 续期;401/403 时 forceRefresh 后重发一次 - GET /v3/orders、/v3/orders/{id}:updatedAfter/Before 映射到创建时间窗 (沃尔玛没有更新时间过滤),跨度超 180 天本地拒绝 - GET /v3/items、/v3/items/{sku}:limit 上限 200;syncStrategy=FULL_PULL_DIFF, 传更新时间窗直接报错而不是静默忽略 - GET /v3/returns:一个退货单按商品行展开成多个 AfterSale, nextCursor 是整段查询串,翻页时整串拼到路径后 - 扩展查询:getReturn(退货详情)、getShipping(发货信息),沙箱均 404 增量语义拆成两条车道:pull 走创建时间窗语义可预测,老单状态变化由 pullOpenOrders 按行状态对账,不混在一个方法里。 脏数据处理:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页, 也不用假值兜底写脏主键。运费不冒充商品单价,行金额除不尽时 unitPrice 留 null。 【测试】108 个:订单 22、商品 18、售后 13、脏数据 10、扩展查询 12、 状态映射 16、错误 11、门面 5、沙箱探针 1(默认跳过)。 【文档】仅新增 docs/walmart/README.md,以及 README / 操作手册.md 里 沃尔玛相关的两处能力表条目。 Co-Authored-By: Claude Code --- README.md | 2 + .../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 ++++ channel-sdk-walmart/pom.xml | 49 ++ .../common/ecommerce/walmart/WalmartConstants.java | 115 ++++ .../ecommerce/walmart/adapter/WalmartAdapter.java | 642 +++++++++++++++++++++ .../walmart/adapter/WalmartAdapterFactory.java | 63 ++ .../ecommerce/walmart/auth/WalmartTokenClient.java | 127 ++++ .../ecommerce/walmart/dto/WalmartItemDtos.java | 113 ++++ .../ecommerce/walmart/dto/WalmartOrderDtos.java | 377 ++++++++++++ .../ecommerce/walmart/dto/WalmartReturnDtos.java | 396 +++++++++++++ .../ecommerce/walmart/dto/WalmartShipmentDtos.java | 134 +++++ .../ecommerce/walmart/dto/WalmartTokenDtos.java | 33 ++ .../walmart/enums/WalmartOrderStatus.java | 138 +++++ .../walmart/enums/WalmartPublishedStatus.java | 103 ++++ .../ecommerce/walmart/enums/WalmartReturnType.java | 60 ++ .../ecommerce/walmart/http/WalmartErrors.java | 165 ++++++ .../walmart/http/WalmartRequestFactory.java | 130 +++++ .../walmart/mapper/WalmartOrderMapper.java | 422 ++++++++++++++ .../walmart/mapper/WalmartProductMapper.java | 148 +++++ .../walmart/mapper/WalmartReturnMapper.java | 304 ++++++++++ .../walmart/mapper/WalmartShipmentMapper.java | 133 +++++ .../ecommerce/walmart/WalmartFacadeTest.java | 154 +++++ .../walmart/adapter/WalmartDirtyDataTest.java | 209 +++++++ .../walmart/adapter/WalmartExtraQueryTest.java | 171 ++++++ .../walmart/adapter/WalmartOrderTest.java | 346 +++++++++++ .../walmart/adapter/WalmartProductTest.java | 233 ++++++++ .../walmart/adapter/WalmartReturnTest.java | 210 +++++++ .../walmart/enums/WalmartStatusMappingTest.java | 131 +++++ .../ecommerce/walmart/http/WalmartErrorsTest.java | 132 +++++ .../ecommerce/walmart/probe/WalmartProbeTest.java | 319 ++++++++++ .../walmart/support/WalmartTestSupport.java | 112 ++++ .../fixtures/walmart/errors/gateway-404.json | 13 + .../fixtures/walmart/errors/route-404.json | 6 + .../resources/fixtures/walmart/items/list.json | 49 ++ .../resources/fixtures/walmart/orders/detail.json | 56 ++ .../resources/fixtures/walmart/orders/list.json | 330 +++++++++++ .../fixtures/walmart/orders/shipping.json | 59 ++ .../resources/fixtures/walmart/returns/detail.json | 52 ++ .../resources/fixtures/walmart/returns/list.json | 82 +++ .../resources/fixtures/walmart/token/success.json | 5 + docs/walmart/README.md | 186 ++++++ pom.xml | 6 + 操作手册.md | 20 +- 46 files changed, 6976 insertions(+), 10 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 create mode 100644 channel-sdk-walmart/pom.xml create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartShipmentDtos.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartTokenDtos.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartOrderStatus.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartPublishedStatus.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/enums/WalmartReturnType.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartErrors.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/http/WalmartRequestFactory.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartOrderMapper.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartProductMapper.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartReturnMapper.java create mode 100644 channel-sdk-walmart/src/main/java/common/ecommerce/walmart/mapper/WalmartShipmentMapper.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/WalmartFacadeTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartDirtyDataTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartExtraQueryTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartOrderTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartProductTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/adapter/WalmartReturnTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/enums/WalmartStatusMappingTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/http/WalmartErrorsTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/probe/WalmartProbeTest.java create mode 100644 channel-sdk-walmart/src/test/java/common/ecommerce/walmart/support/WalmartTestSupport.java create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/errors/gateway-404.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/errors/route-404.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/items/list.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/detail.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/list.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/orders/shipping.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/detail.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/returns/list.json create mode 100644 channel-sdk-walmart/src/test/resources/fixtures/walmart/token/success.json create mode 100644 docs/walmart/README.md diff --git a/README.md b/README.md index 5379ba7..36c9e25 100644 --- a/README.md +++ b/README.md @@ -139,6 +139,7 @@ sequenceDiagram | `sdk-testkit` | 渠道域测试替身:InMemory SPI、FakeDirectAdapter | | `warehouse-sdk-testkit` | 仓库域测试替身:InMemory 仓仓库 / 落库 / 去重、FakeWarehouseAdapter | | `common-ecommerce-lingxing` | 领星聚合适配器(多子平台)。DTO 用 Lombok 生成访问器 | +| `channel-sdk-walmart` | 沃尔玛 Marketplace **直连**适配器(`DIRECT` + `WALMART_SC`):token / 订单 / 商品 / 售后,只读 | | `warehouse-sdk-yqn` | 运去哪三方仓适配器(P1 出库闭环,组织级固定 token 鉴权) | | `warehouse-sdk-xincang` | 信仓三方仓适配器(登录换 token、商品建档、下单 / 详情 / 删除、转运创建 / 审核 / 详情 / 删除、最优渠道、实时库存 / 库龄、头程预报、仓库 / 承运商资料) | | `warehouse-sdk-hengjian` | 恒健三方仓适配器(组织级双请求头 token;仓库目录 / 物流渠道 / 按仓渠道 / 商品创建编辑 / 出库下单、详情、列表、取消、预判、包裹 / 物流异动单创建与查询 / 仓储费 / 尾程费 / 作业费 / 运费测算 / 地址属性 / 库存查询与流水 / 入库计划创建 / 详情 / 列表 / 调拨 / 退货 / 订单附件 / 销毁 / 箱标) | @@ -149,6 +150,7 @@ channel-sdk-core ──┐ sdk-testkit ───────┼──→ sdk-common warehouse-sdk-core ┘ lingxing ───────────→ channel-sdk-core, sdk-common +channel-sdk-walmart ──→ channel-sdk-core, sdk-common warehouse-sdk-yqn ──→ warehouse-sdk-core, sdk-common warehouse-sdk-xincang ──→ warehouse-sdk-core, sdk-common warehouse-sdk-hengjian ──→ warehouse-sdk-core, sdk-common 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); + } +} diff --git a/channel-sdk-walmart/pom.xml b/channel-sdk-walmart/pom.xml new file mode 100644 index 0000000..fd2529f --- /dev/null +++ b/channel-sdk-walmart/pom.xml @@ -0,0 +1,49 @@ + + + 4.0.0 + + + ecommerce + channel-sdk-parent + 1.0.0-SNAPSHOT + + + channel-sdk-walmart + 沃尔玛 Marketplace 直连适配器(订单 / 商品 / 售后) + + + + ecommerce + sdk-common + + + ecommerce + channel-sdk-core + + + com.fasterxml.jackson.core + jackson-databind + + + com.squareup.okhttp3 + okhttp + + + org.slf4j + slf4j-api + + + + ecommerce + sdk-testkit + test + + + org.junit.jupiter + junit-jupiter + test + + + diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java new file mode 100644 index 0000000..707c6da --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/WalmartConstants.java @@ -0,0 +1,115 @@ +package common.ecommerce.walmart; + +/** + * 沃尔玛 Marketplace 协议常量。 + * + *

端点与路径属于协议的一部分,写在代码里,不做成配置表。 + * 运行时不使用 {@link #PRODUCTION_BASE_URL} / {@link #SANDBOX_BASE_URL}: + * 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定, + * 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。

+ * + *

来源:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱 + * {@code https://sandbox.walmartapis.com} 实测。

+ */ +public final class WalmartConstants { + + /** 适配器标识;注册表与日志用。 */ + public static final String ADAPTER_ID = "walmart-direct"; + + /** 生产端点。 */ + public static final String PRODUCTION_BASE_URL = "https://marketplace.walmartapis.com"; + + /** 沙箱端点。 */ + public static final String SANDBOX_BASE_URL = "https://sandbox.walmartapis.com"; + + // ---------------------------------------------------------------- 路径 + + /** 换取访问令牌;form-urlencoded + Basic Auth。 */ + public static final String PATH_TOKEN = "/v3/token"; + + /** 商品列表;游标分页。 */ + public static final String PATH_ITEMS = "/v3/items"; + + /** 商品详情;路径参数为 URL 编码后的 SKU。 */ + public static final String PATH_ITEM_BY_SKU = "/v3/items/"; + + /** 订单列表;按创建时间窗 + 游标分页。 */ + public static final String PATH_ORDERS = "/v3/orders"; + + /** 订单详情;路径参数为 purchaseOrderId。响应多包一层 {@code {"order": ...}}。 */ + public static final String PATH_ORDER_BY_ID = "/v3/orders/"; + + /** 退货单列表;{@code meta.nextCursor} 本身是一段查询串,翻页时整串拼到路径后面。 */ + public static final String PATH_RETURNS = "/v3/returns"; + + /** 退货单详情;路径参数为 returnOrderId。⚠ 沙箱实测 404。 */ + public static final String PATH_RETURN_BY_ID = "/v3/returns/"; + + /** 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。⚠ 沙箱实测 404。 */ + public static final String PATH_ORDER_SHIPPING = "/shipping"; + + // ---------------------------------------------------------------- 请求头 + + /** 服务名,固定值。 */ + public static final String HEADER_SVC_NAME = "WM_SVC.NAME"; + + /** 服务名的固定取值。 */ + public static final String SVC_NAME_VALUE = "Walmart Marketplace"; + + /** 调用链追踪 ID,每次请求生成一个新的;SDK 用 {@code ChannelContext.requestId()}。 */ + public static final String HEADER_CORRELATION_ID = "WM_QOS.CORRELATION_ID"; + + /** 访问令牌;业务接口用它,不用 Authorization。 */ + public static final String HEADER_ACCESS_TOKEN = "WM_SEC.ACCESS_TOKEN"; + + /** 表单类型,仅令牌接口使用。 */ + public static final String CONTENT_TYPE_FORM = "application/x-www-form-urlencoded"; + + /** JSON 类型,业务接口使用。 */ + public static final String CONTENT_TYPE_JSON = "application/json"; + + // ---------------------------------------------------------------- 限制 + + /** + * 商品列表单页上限(官方值,超了本地截断)。 + * + *

与领星不同,这里是平台硬上限:静默截断是安全的,因为调用方本来 + * 就只能拿到这么多,且用 {@code nextCursor} 翻页。

+ */ + public static final int MAX_ITEM_PAGE_SIZE = 200; + + /** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */ + public static final int DEFAULT_ORDER_PAGE_SIZE = 20; + + /** + * 订单列表单页上限(📖 官方常见取值 200,与商品一致)。 + * + *

文档没给订单的 {@code limit} 上限;这里与商品保持同一策略:超了本地截断, + * 而不是把大值原样发给平台(沙箱 mock 不校验,生产会被拒)。

+ */ + public static final int MAX_ORDER_PAGE_SIZE = 200; + + /** 退货列表默认单页条数;沃尔玛默认 10。 */ + public static final int DEFAULT_RETURN_PAGE_SIZE = 10; + + /** + * 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。 + * + *

超过这个跨度在本地直接拒绝,不做静默截断——静默截断会让宿主以为拉全了。

+ */ + public static final int MAX_ORDER_WINDOW_DAYS = 180; + + /** + * 令牌提前续期秒数。 + * + *

{@code expires_in} 只有 900 秒,且沙箱响应头 {@code x-current-token-count} + * 已达 99(平台对并发有效 token 有上限),必须缓存复用、提前续期。

+ */ + public static final long TOKEN_EARLY_REFRESH_SECONDS = 120L; + + /** 异常里保留的原始响应最大长度;避免整页报文塞进日志。 */ + public static final int RAW_RESPONSE_LIMIT = 1024; + + private WalmartConstants() { + } +} diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java new file mode 100644 index 0000000..b66d5b3 --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapter.java @@ -0,0 +1,642 @@ +package common.ecommerce.walmart.adapter; + +import common.ecommerce.channel.capability.AfterSaleCapable; +import common.ecommerce.channel.capability.PlatformAdapter; +import common.ecommerce.channel.capability.ProductCapable; +import common.ecommerce.channel.capability.SalesOrderCapable; +import common.ecommerce.channel.model.account.ChannelAccount; +import common.ecommerce.channel.model.aftersale.AfterSale; +import common.ecommerce.channel.model.aftersale.AfterSaleQuery; +import common.ecommerce.channel.model.order.SalesOrder; +import common.ecommerce.channel.model.order.SalesOrderQuery; +import common.ecommerce.channel.model.order.SalesOrderRef; +import common.ecommerce.channel.model.product.ProductListing; +import common.ecommerce.channel.model.product.ProductQuery; +import common.ecommerce.channel.model.product.ProductRef; +import common.ecommerce.channel.model.product.ProductSyncStrategy; +import common.ecommerce.channel.sdk.ChannelContext; +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.error.ValidationException; +import common.ecommerce.shared.model.Capability; +import common.ecommerce.shared.model.ChannelProvider; +import common.ecommerce.shared.model.Platform; +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.http.TokenManager; +import common.ecommerce.walmart.WalmartConstants; +import common.ecommerce.walmart.auth.WalmartTokenClient; +import common.ecommerce.walmart.dto.WalmartItemDtos; +import common.ecommerce.walmart.dto.WalmartOrderDtos; +import common.ecommerce.walmart.dto.WalmartReturnDtos; +import common.ecommerce.walmart.dto.WalmartShipmentDtos; +import common.ecommerce.walmart.http.WalmartErrors; +import common.ecommerce.walmart.http.WalmartRequestFactory; +import common.ecommerce.walmart.mapper.WalmartOrderMapper; +import common.ecommerce.walmart.mapper.WalmartProductMapper; +import common.ecommerce.walmart.mapper.WalmartReturnMapper; +import common.ecommerce.walmart.mapper.WalmartShipmentMapper; + +import java.time.Clock; +import java.time.Duration; +import java.time.Instant; +import java.time.ZoneId; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.EnumSet; +import java.util.List; +import java.util.Map; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +/** + * 沃尔玛 Marketplace 直连适配器(只读)。 + * + *

实现三个能力接口:

+ *
    + *
  • {@link SalesOrderCapable}:{@code GET /v3/orders}、{@code GET /v3/orders/{id}}
  • + *
  • {@link ProductCapable}:{@code GET /v3/items}、{@code GET /v3/items/{sku}}
  • + *
  • {@link AfterSaleCapable}:{@code GET /v3/returns}
  • + *
+ * + *

写操作(标发 / 退款 / 商品写入)本期不实现,对应能力位也不声明—— + * 门面调用会显式抛 {@code UnsupportedCapabilityException},不会静默成功。

+ * + *

增量语义

+ *

沃尔玛订单接口只有创建时间过滤({@code createdStartDate/createdEndDate}), + * 没有更新时间。因此 {@link SalesOrderQuery#updatedAfter()} 被解释为创建时间窗; + * 「老单状态变化」需要宿主用 {@link #pullOpenOrders} 单独对账,两者不混在一起, + * 免得 {@code pull} 的语义变得不可预测。

+ */ +public final class WalmartAdapter implements SalesOrderCapable, ProductCapable, AfterSaleCapable { + + private static final Logger LOG = LoggerFactory.getLogger(WalmartAdapter.class); + + /** 沃尔玛日期时间格式:ISO-8601,毫秒精度,UTC。 */ + private static final DateTimeFormatter WALMART_TIME_FORMAT = + DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").withZone(java.time.ZoneOffset.UTC); + + private final HttpTransport transport; + private final JacksonJsonCodec json; + private final WalmartRequestFactory requestFactory; + private final WalmartErrors errors; + private final TokenManager tokenManager; + + public WalmartAdapter(HttpTransport transport, JacksonJsonCodec json, + TokenStore tokenStore, LockProvider lockProvider, Clock clock) { + this.transport = transport; + this.json = json; + this.requestFactory = new WalmartRequestFactory(); + this.errors = new WalmartErrors(json); + final WalmartTokenClient tokenClient = new WalmartTokenClient(transport, json, clock); + // 令牌有效期 900s,提前 120s 续期;沙箱有效令牌数接近上限,必须缓存复用 + this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, + WalmartConstants.TOKEN_EARLY_REFRESH_SECONDS) { + @Override + protected AccessToken refresh(ChannelSecret secret, AccessToken previous) { + return tokenClient.fetch(secret.endpointBaseUrl(), secret.clientId(), secret.clientSecret()); + } + }; + } + + // ---------------------------------------------------------------- PlatformAdapter + + @Override + public String adapterId() { + return WalmartConstants.ADAPTER_ID; + } + + @Override + public ChannelProvider provider() { + return ChannelProvider.DIRECT; + } + + @Override + public java.util.Set platforms() { + return EnumSet.of(Platform.WALMART_SC); + } + + @Override + public EnumSet capabilities() { + return EnumSet.of(Capability.SALES_ORDER, Capability.PRODUCT, Capability.RETURNS); + } + + // ---------------------------------------------------------------- SalesOrderCapable + + /** + * 按创建时间窗拉订单(沃尔玛没有更新时间过滤)。 + * + *

时间窗超过 {@link WalmartConstants#MAX_ORDER_WINDOW_DAYS} 天时本地拒绝, + * 不做静默截断——静默截断会让宿主以为拉全了。

+ */ + @Override + public Page pull(ChannelContext ctx, SalesOrderQuery query) { + ChannelAccount account = ctx.account(); + Instant from = query.updatedAfter(); + Instant to = query.updatedBefore() != null ? query.updatedBefore() : Instant.now(ctx.clock()); + validateWindow(from, to); + + Map queryParams = WalmartRequestFactory.query(); + queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format(from)); + queryParams.put("createdEndDate", WALMART_TIME_FORMAT.format(to)); + queryParams.put("limit", orderPageSize(query.pageSize())); + queryParams.put("nextCursor", query.cursor()); + + HttpResponse response = execute(ctx, "salesOrders.pull", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_ORDERS, + queryParams, t, c, "salesOrders.pull"); + } + }); + + WalmartOrderDtos.OrderListResponse dto = + json.fromJson(response.body(), WalmartOrderDtos.OrderListResponse.class); + List orders = new ArrayList(); + String nextCursor = null; + if (dto != null && dto.list != null) { + if (dto.list.elements != null && dto.list.elements.order != null) { + for (WalmartOrderDtos.Order order : dto.list.elements.order) { + SalesOrder mapped = WalmartOrderMapper.toSalesOrder(order, + account.omsStoreId(), zoneOf(ctx)); + if (mapped != null) { + orders.add(mapped); + } else { + warnSkipped(ctx, "order", order == null ? null : order.purchaseOrderId); + } + } + } + if (dto.list.meta != null) { + nextCursor = dto.list.meta.nextCursor; + } + } + return Page.of(orders, nextCursor); + } + + /** 订单详情;响应比列表多一层 {@code {"order": ...}}。 */ + @Override + public SalesOrder get(ChannelContext ctx, SalesOrderRef ref) { + ChannelAccount account = ctx.account(); + String path = WalmartConstants.PATH_ORDER_BY_ID + + WalmartRequestFactory.pathSegment(ref.channelOrderId()); + HttpResponse response = execute(ctx, "salesOrders.get", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "salesOrders.get"); + } + }); + + WalmartOrderDtos.OrderDetailResponse dto = + json.fromJson(response.body(), WalmartOrderDtos.OrderDetailResponse.class); + SalesOrder order = dto == null ? null + : WalmartOrderMapper.toSalesOrder(dto.order, account.omsStoreId(), zoneOf(ctx)); + if (order == null) { + throw new ValidationException(ChannelException.builder() + .message("walmart order not found or empty: " + ref.channelOrderId()) + .operation("salesOrders.get") + .provider(provider().name()) + .omsStoreId(ctx.omsStoreId()) + .platform(ctx.platform()) + .requestId(ctx.requestId()) + .platformCode(ref.channelOrderId()) + .retryable(false)); + } + return order; + } + + /** + * 开放单对账:按行状态拉 {@code Created} / {@code Acknowledged} 的订单。 + * + *

沃尔玛订单接口只能按创建时间过滤,{@code pull} 拿不到「老单今天发货」这种变化。 + * 宿主在同步任务里追加一次本方法即可补齐,无需改统一模型。

+ * + * @param statuses 行状态列表,如 {@code ["Created","Acknowledged"]};空则用这两个 + * @param createdAfter 创建时间下界;null 表示不限制(平台默认行为) + * @param cursor 游标;首页传 null + */ + public Page pullOpenOrders(ChannelContext ctx, List statuses, + Instant createdAfter, String cursor) { + ChannelAccount account = ctx.account(); + Map queryParams = WalmartRequestFactory.query(); + List effective = statuses == null || statuses.isEmpty() + ? java.util.Arrays.asList("Created", "Acknowledged") : statuses; + queryParams.put("status", joinComma(effective)); + if (createdAfter != null) { + queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format(createdAfter)); + } + queryParams.put("limit", WalmartConstants.DEFAULT_ORDER_PAGE_SIZE); + queryParams.put("nextCursor", cursor); + + HttpResponse response = execute(ctx, "salesOrders.pullOpen", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_ORDERS, + queryParams, t, c, "salesOrders.pullOpen"); + } + }); + + WalmartOrderDtos.OrderListResponse dto = + json.fromJson(response.body(), WalmartOrderDtos.OrderListResponse.class); + List orders = new ArrayList(); + String nextCursor = null; + if (dto != null && dto.list != null) { + if (dto.list.elements != null && dto.list.elements.order != null) { + for (WalmartOrderDtos.Order order : dto.list.elements.order) { + SalesOrder mapped = WalmartOrderMapper.toSalesOrder(order, + account.omsStoreId(), zoneOf(ctx)); + if (mapped != null) { + orders.add(mapped); + } else { + warnSkipped(ctx, "order", order == null ? null : order.purchaseOrderId); + } + } + } + if (dto.list.meta != null) { + nextCursor = dto.list.meta.nextCursor; + } + } + return Page.of(orders, nextCursor); + } + + // ---------------------------------------------------------------- ProductCapable + + /** + * 沃尔玛 items 接口没有更新时间过滤,只能全量拉 + 差分。 + * + * @see ProductSyncStrategy#FULL_PULL_DIFF + */ + @Override + public ProductSyncStrategy syncStrategy() { + return ProductSyncStrategy.FULL_PULL_DIFF; + } + + /** + * 拉商品。 + * + *

时间窗在此适配器里不支持:传了 {@code updatedAfter/updatedBefore} 直接抛 + * {@link ValidationException},而不是静默忽略——静默忽略会让宿主以为做了增量。

+ */ + @Override + public Page pull(ChannelContext ctx, ProductQuery query) { + if (query.updatedAfter() != null || query.updatedBefore() != null) { + throw unsupportedFilter("walmart /v3/items does not support update-time filtering; " + + "use syncStrategy FULL_PULL_DIFF or search by SKU"); + } + if (query.searchField() != null && !query.searchValues().isEmpty()) { + throw unsupportedFilter("walmart /v3/items supports one sku at a time, not multi-value search"); + } + if (query.searchField() == common.ecommerce.channel.model.product.ProductSearchField.LOCAL_SKU) { + throw unsupportedFilter("walmart has no local-sku concept; search by PLATFORM_SKU"); + } + + ChannelAccount account = ctx.account(); + Map queryParams = WalmartRequestFactory.query(); + queryParams.put("limit", Math.min( + query.pageSize() <= 0 ? WalmartConstants.MAX_ITEM_PAGE_SIZE : query.pageSize(), + WalmartConstants.MAX_ITEM_PAGE_SIZE)); + queryParams.put("nextCursor", query.cursor()); + if (query.searchValue() != null) { + queryParams.put("sku", query.searchValue()); + } + + HttpResponse response = execute(ctx, "products.pull", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_ITEMS, + queryParams, t, c, "products.pull"); + } + }); + + WalmartItemDtos.ItemListResponse dto = + json.fromJson(response.body(), WalmartItemDtos.ItemListResponse.class); + List products = new ArrayList(); + String nextCursor = null; + if (dto != null) { + if (dto.itemResponse != null) { + for (WalmartItemDtos.ItemResponse item : dto.itemResponse) { + ProductListing mapped = WalmartProductMapper.toProductListing(item, account.omsStoreId()); + if (mapped != null) { + products.add(mapped); + } else { + warnSkipped(ctx, "item", item == null ? null : item.sku); + } + } + } + nextCursor = dto.nextCursor; + } + return Page.of(products, nextCursor); + } + + /** + * 按 SKU 取单品。 + * + *

⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。

+ */ + @Override + public ProductListing get(ChannelContext ctx, ProductRef ref) { + ChannelAccount account = ctx.account(); + String path = WalmartConstants.PATH_ITEM_BY_SKU + + WalmartRequestFactory.pathSegment(ref.platformSku()); + HttpResponse response = execute(ctx, "products.get", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "products.get"); + } + }); + + WalmartItemDtos.ItemResponse dto = + json.fromJson(response.body(), WalmartItemDtos.ItemResponse.class); + return WalmartProductMapper.toProductListing(dto, account.omsStoreId()); + } + + // ---------------------------------------------------------------- AfterSaleCapable + + /** + * 拉退货单,按商品行展开。 + * + *

分页特殊:{@code meta.nextCursor} 本身是一段查询串 + * (如 {@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面。

+ * + *

时间窗只支持按退货单创建时间;{@code PURCHASE_TIME} / {@code UPDATE_TIME} + * 显式报错,不做「拿售后时间顶替」的静默降级。

+ */ + @Override + public Page pull(ChannelContext ctx, AfterSaleQuery query) { + ChannelAccount account = ctx.account(); + if (query.dateType() != AfterSaleQuery.DateType.AFTER_SALE_TIME) { + throw unsupportedFilter("walmart /v3/returns only filters by return-created date, got " + + query.dateType()); + } + if (!query.channelOrderIds().isEmpty()) { + throw unsupportedFilter("walmart /v3/returns filters one customerOrderId at a time, not a list"); + } + + String cursor = query.cursor(); + if (cursor != null && !cursor.trim().isEmpty()) { + // 平台给的游标本身就是完整查询串,直接拼,不再追加参数 + return executeReturns(ctx, account, "afterSales.pull", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.getWithRawQuery(c.endpointBaseUrl(), + WalmartConstants.PATH_RETURNS, cursor.trim(), t, c, "afterSales.pull"); + } + }); + } + + Map queryParams = WalmartRequestFactory.query(); + queryParams.put("createdStartDate", WALMART_TIME_FORMAT.format( + query.startDate().atStartOfDay(ZoneId.of("UTC")).toInstant())); + queryParams.put("createdEndDate", WALMART_TIME_FORMAT.format( + query.endDate().atStartOfDay(ZoneId.of("UTC")).toInstant())); + queryParams.put("limit", query.pageSize() <= 0 + ? WalmartConstants.DEFAULT_RETURN_PAGE_SIZE : query.pageSize()); + queryParams.put("offset", 0); + + return executeReturns(ctx, account, "afterSales.pull", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), WalmartConstants.PATH_RETURNS, + queryParams, t, c, "afterSales.pull"); + } + }); + } + + private Page executeReturns(ChannelContext ctx, ChannelAccount account, + String operation, GetPlan plan) { + HttpResponse response = execute(ctx, operation, plan); + + WalmartReturnDtos.ReturnListResponse dto = + json.fromJson(response.body(), WalmartReturnDtos.ReturnListResponse.class); + List afterSales = new ArrayList(); + String nextCursor = null; + if (dto != null) { + if (dto.returnOrders != null) { + for (WalmartReturnDtos.ReturnOrder order : dto.returnOrders) { + List lines = WalmartReturnMapper.toAfterSales(order, + account.omsStoreId(), zoneOf(ctx)); + if (lines.isEmpty()) { + warnSkipped(ctx, "return", order == null ? null : order.returnOrderId); + } + afterSales.addAll(lines); + } + } + if (dto.meta != null) { + nextCursor = dto.meta.nextCursor; + } + } + return Page.of(afterSales, nextCursor); + } + + /** + * 退货单详情:{@code GET /v3/returns/{returnOrderId}}。 + * + *

与列表一样按商品行展开:一个退货单可能含多个退货行, + * 返回的 {@link AfterSale#afterSaleId()} 与列表里的完全一致({@code returnOrderId:行号}), + * 可以直接拿去 upsert。

+ * + *

{@link AfterSaleCapable} 没有「取详情」方法——售后以拉取为主, + * 需要单条时用列表的时间窗过滤即可。这里提供它是因为沃尔玛有真实路由, + * 且列表接口的过滤参数在沙箱不生效,生产上按单号回查更快。

+ * + *

⚠ 沙箱实测该路由 404(mock 未实现),只能在生产环境验证。

+ * + * @param returnOrderId 退货单号 + * @return 该退货单展开出的售后行;退货单没有行时返回空列表 + * @throws ChannelException 平台 404 / 其它错误,由 {@link WalmartErrors} 分类 + */ + public List getReturn(ChannelContext ctx, String returnOrderId) { + if (returnOrderId == null || returnOrderId.trim().isEmpty()) { + throw unsupportedFilter("walmart return detail requires returnOrderId"); + } + ChannelAccount account = ctx.account(); + String path = WalmartConstants.PATH_RETURN_BY_ID + + WalmartRequestFactory.pathSegment(returnOrderId.trim()); + + HttpResponse response = execute(ctx, "afterSales.get", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "afterSales.get"); + } + }); + + WalmartReturnDtos.ReturnOrder dto = + json.fromJson(response.body(), WalmartReturnDtos.ReturnOrder.class); + return WalmartReturnMapper.toAfterSales(dto, account.omsStoreId(), zoneOf(ctx)); + } + + // ---------------------------------------------------------------- 发货信息(非能力接口) + + /** + * 查询发货信息:{@code GET /v3/orders/{purchaseOrderId}/shipping}。 + * + *

返回行级发货记录(行号 / 承运商 / 运输方式 / 跟踪号 / 发货时间)。 + * 统一模型没有独立的发货实体——从订单详情的行状态里也能读到同样的 + * {@code trackingInfo},两种方式数据一致;本方法用于只想知道「发了哪些行」的场景。

+ * + *

⚠ 沙箱实测该路由 404(mock 未实现)。生产上若也不可用,改用 + * {@link #get(ChannelContext, SalesOrderRef)} 读订单详情。

+ * + * @param purchaseOrderId 沃尔玛订单号 + * @return 已发货行的记录;未发货时返回空列表 + */ + public List getShipping(ChannelContext ctx, + String purchaseOrderId) { + if (purchaseOrderId == null || purchaseOrderId.trim().isEmpty()) { + throw unsupportedFilter("walmart shipping query requires purchaseOrderId"); + } + String path = WalmartConstants.PATH_ORDER_BY_ID + + WalmartRequestFactory.pathSegment(purchaseOrderId.trim()) + + WalmartConstants.PATH_ORDER_SHIPPING; + + HttpResponse response = execute(ctx, "salesOrders.shipping", new GetPlan() { + @Override + public HttpRequest request(ChannelContext c, AccessToken t) { + return requestFactory.get(c.endpointBaseUrl(), path, null, t, c, "salesOrders.shipping"); + } + }); + + WalmartShipmentDtos.ShipmentResponse dto = + json.fromJson(response.body(), WalmartShipmentDtos.ShipmentResponse.class); + return WalmartShipmentMapper.toShipmentLines(dto); + } + + // ---------------------------------------------------------------- internals + + /** + * 执行一次业务请求,401/403 时强制换 token 重试一次。 + * + *

为什么要重试:沃尔玛 token 的 {@code expires_in} 是 900 秒,但平台可以提前作废 + * (后台重置 secret、并发令牌超限被踢)。缓存里的坏 token 在自然过期前会一直命中, + * 期间所有请求都 401。{@code TokenManager} 有 {@code forceRefresh},但门面层没有 + * 自动重试——重试策略属于适配器,这里只在本模块内实现一次「换 token + 重发」。

+ * + *

重试只做一次,第二次失败原样抛出,交由宿主决定是否停用账户。

+ */ + private HttpResponse execute(ChannelContext ctx, String operation, GetPlan plan) { + AccessToken token = token(ctx); + HttpResponse response = transport.execute(plan.request(ctx, token)); + if (!isAuthFailure(response)) { + errors.throwIfError(response, ctx, operation); + return response; + } + + // 缓存里的 token 已失效:强制换新后重发一次 + ChannelSecret secret = ctx.secret(); + AccessToken refreshed = tokenManager.forceRefresh(tokenKey(secret), secret); + HttpResponse retried = transport.execute(plan.request(ctx, refreshed)); + errors.throwIfError(retried, ctx, operation); + return retried; + } + + /** 401/403 才值得换 token 重试;其它错误交给 {@link WalmartErrors}。 */ + private static boolean isAuthFailure(HttpResponse response) { + return response.statusCode() == 401 || response.statusCode() == 403; + } + + /** 用「当前 token」拼请求;重试时会用新 token 再调一次。 */ + private interface GetPlan { + HttpRequest request(ChannelContext ctx, AccessToken token); + } + + /** + * 取令牌并返回请求要用的 token。 + * + *

缓存维度是 {@code clientId}:一个 clientId 对应一个 seller, + * 同 seller 的多个店铺共用一个令牌,避免触碰平台并发令牌上限。

+ */ + private AccessToken token(ChannelContext ctx) { + ChannelSecret secret = ctx.secret(); + if (isBlank(secret.clientId()) || isBlank(secret.clientSecret())) { + throw new ValidationException(ChannelException.builder() + .message("walmart requires ChannelSecret.clientId and clientSecret") + .operation("token") + .provider(provider().name()) + .omsStoreId(ctx.omsStoreId()) + .platform(ctx.platform()) + .requestId(ctx.requestId()) + .retryable(false)); + } + return tokenManager.getOrRefresh(tokenKey(secret), secret); + } + + /** 令牌缓存键;按 clientId 聚合,同一 seller 的店铺共用。 */ + static String tokenKey(ChannelSecret secret) { + return "walmart:" + secret.clientId(); + } + + /** 市场时区:账户没配时按沃尔玛总部所在时区兜底(美国中部)。 */ + private static ZoneId zoneOf(ChannelContext ctx) { + ChannelAccount account = ctx.account(); + String zone = account == null ? null : account.marketplaceZone(); + return zone == null || zone.trim().isEmpty() ? ZoneId.of("America/Chicago") : ZoneId.of(zone); + } + + /** 时间窗校验:起点必填、终点必须晚于起点、跨度不超过平台上限。 */ + private static void validateWindow(Instant from, Instant to) { + if (from == null) { + throw unsupportedFilter("walmart /v3/orders requires updatedAfter (mapped to createdStartDate)"); + } + if (!to.isAfter(from)) { + throw unsupportedFilter("walmart /v3/orders requires updatedBefore after updatedAfter"); + } + long days = Duration.between(from, to).toDays(); + if (days > WalmartConstants.MAX_ORDER_WINDOW_DAYS) { + throw unsupportedFilter("walmart /v3/orders window is " + days + " days, max " + + WalmartConstants.MAX_ORDER_WINDOW_DAYS + "; split the window instead of truncating"); + } + } + + /** 订单单页条数:0 或负数用默认值,超出上限本地截断(与商品同一策略)。 */ + private static int orderPageSize(int requested) { + if (requested <= 0) { + return WalmartConstants.DEFAULT_ORDER_PAGE_SIZE; + } + return Math.min(requested, WalmartConstants.MAX_ORDER_PAGE_SIZE); + } + + private static String joinComma(List values) { + StringBuilder sb = new StringBuilder(); + for (String v : values) { + if (v == null || v.trim().isEmpty()) { + continue; + } + if (sb.length() > 0) { + sb.append(','); + } + sb.append(v.trim()); + } + return sb.toString(); + } + + /** + * 平台给了一条缺必填字段的记录,映射层丢弃时留痕。 + * + *

不抛异常:一条脏数据不该卡住整页同步;但也不能完全静默——宿主需要知道 + * 「这次少了一条」以及少的是哪个单号。

+ */ + private static void warnSkipped(ChannelContext ctx, String kind, String id) { + LOG.warn("walmart {} skipped: missing required field, id={} store={} requestId={}", + kind, id, ctx.omsStoreId(), ctx.requestId()); + } + + private static boolean isBlank(String v) { + return v == null || v.trim().isEmpty(); + } + + /** 适配器不支持某过滤条件时的统一异常。 */ + private static ValidationException unsupportedFilter(String message) { + return new ValidationException(ChannelException.builder() + .message(message) + .operation("walmart.filter") + .provider(ChannelProvider.DIRECT.name()) + .platform(Platform.WALMART_SC) + .retryable(false)); + } +} diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java new file mode 100644 index 0000000..d7da96b --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/adapter/WalmartAdapterFactory.java @@ -0,0 +1,63 @@ +package common.ecommerce.walmart.adapter; + +import common.ecommerce.channel.capability.PlatformAdapter; +import common.ecommerce.channel.sdk.AdapterFactory; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.shared.model.ChannelProvider; +import common.ecommerce.shared.model.Platform; +import common.ecommerce.shared.spi.LockProvider; +import common.ecommerce.shared.spi.TokenStore; +import common.ecommerce.walmart.WalmartConstants; + +import java.time.Clock; +import java.util.EnumSet; + +/** + * 沃尔玛直连适配器工厂。 + * + *

与领星、三方仓使用同一套注册机制:工厂只装配基础设施, + * 不持有端点与凭据——两者由调用方每次经 {@code ChannelConnection} 传入。

+ * + *
+ * ChannelSdk.builder()
+ *         .accountRepository(repo)
+ *         .register(new WalmartAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
+ *         .build();
+ * 
+ */ +public final class WalmartAdapterFactory implements AdapterFactory { + + private final TokenStore tokenStore; + private final LockProvider lockProvider; + private final Clock clock; + + public WalmartAdapterFactory(TokenStore tokenStore, LockProvider lockProvider, Clock clock) { + this.tokenStore = tokenStore; + this.lockProvider = lockProvider; + this.clock = clock; + } + + @Override + public String adapterId() { + return WalmartConstants.ADAPTER_ID; + } + + @Override + public ChannelProvider provider() { + return ChannelProvider.DIRECT; + } + + @Override + public EnumSet platforms() { + return EnumSet.of(Platform.WALMART_SC); + } + + @Override + public PlatformAdapter create(AdapterConfig config) { + return new WalmartAdapter( + new OkHttpTransport("common-ecommerce/1.0.0 (walmart)"), + new JacksonJsonCodec(), + tokenStore, lockProvider, clock); + } +} diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java new file mode 100644 index 0000000..24d4ad7 --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/auth/WalmartTokenClient.java @@ -0,0 +1,127 @@ +package common.ecommerce.walmart.auth; + +import common.ecommerce.http.HttpRequest; +import common.ecommerce.http.HttpResponse; +import common.ecommerce.http.HttpTransport; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.http.Responses; +import common.ecommerce.shared.error.AuthException; +import common.ecommerce.shared.error.ChannelException; +import common.ecommerce.shared.spi.AccessToken; +import common.ecommerce.walmart.WalmartConstants; +import common.ecommerce.walmart.dto.WalmartTokenDtos; + +import java.nio.charset.StandardCharsets; +import java.time.Clock; +import java.time.Instant; +import java.util.Base64; + +/** + * 沃尔玛令牌接口:{@code POST /v3/token}。 + * + *

请求:Basic Auth({@code clientId:clientSecret})+ form 体 + * {@code grant_type=client_credentials}。

+ * + *

响应:{@code access_token} / {@code token_type=Bearer} / {@code expires_in=900}。 + * 业务接口带 {@code WM_SEC.ACCESS_TOKEN} 头,不再带 Basic Auth(沙箱实测)。

+ * + *

令牌按 {@code clientId} 维度缓存:一个 clientId 对应一个 seller, + * 多店铺共用同一令牌,避免触碰平台的并发有效令牌上限 + * (沙箱 {@code x-current-token-count} 已接近上限)。

+ */ +public final class WalmartTokenClient { + + private static final String OP_FETCH = "token.fetch"; + + /** 平台未返回 expires_in 时的兜底有效期(秒):官方值为 900。 */ + static final long DEFAULT_EXPIRES_IN_SECONDS = 900L; + + private final HttpTransport transport; + private final JacksonJsonCodec json; + private final Clock clock; + + public WalmartTokenClient(HttpTransport transport, JacksonJsonCodec json, Clock clock) { + this.transport = transport; + this.json = json; + this.clock = clock; + } + + /** + * 用 clientId + clientSecret 换新令牌。 + * + * @param baseUrl 端点基址(沙箱或生产),由调用方每次传入 + * @param clientId 沃尔玛 Client ID + * @param clientSecret 沃尔玛 Client Secret + * @throws AuthException clientId / clientSecret 为空,或平台返回 401 / 403 + */ + public AccessToken fetch(String baseUrl, String clientId, String clientSecret) { + if (isBlank(clientId) || isBlank(clientSecret)) { + throw new AuthException(ChannelException.builder() + .message("walmart token requires clientId and clientSecret") + .operation(OP_FETCH) + .provider(WalmartConstants.ADAPTER_ID) + .retryable(false)); + } + + HttpRequest request = HttpRequest.builder() + .method("POST") + .url(baseUrl + WalmartConstants.PATH_TOKEN) + .contentType(WalmartConstants.CONTENT_TYPE_FORM) + .header("Authorization", basicAuth(clientId, clientSecret)) + .header(WalmartConstants.HEADER_SVC_NAME, WalmartConstants.SVC_NAME_VALUE) + .header("Accept", WalmartConstants.CONTENT_TYPE_JSON) + .body("grant_type=client_credentials") + .operation(OP_FETCH) + .build(); + + HttpResponse response = transport.execute(request); + Responses.throwIfNotSuccess(response, OP_FETCH); + + WalmartTokenDtos.TokenResponse dto; + try { + dto = json.fromJson(response.body(), WalmartTokenDtos.TokenResponse.class); + } catch (IllegalArgumentException e) { + throw new AuthException(ChannelException.builder() + .message("walmart token response is not valid json") + .operation(OP_FETCH) + .provider(WalmartConstants.ADAPTER_ID) + .retryable(false) + .rawResponse(truncate(response.body())), + e); + } + if (dto == null || isBlank(dto.accessToken)) { + throw new AuthException(ChannelException.builder() + .message("walmart token response has no access_token") + .operation(OP_FETCH) + .provider(WalmartConstants.ADAPTER_ID) + .retryable(false) + .rawResponse(truncate(response.body()))); + } + + long expiresIn = dto.expiresIn == null || dto.expiresIn <= 0 + ? DEFAULT_EXPIRES_IN_SECONDS : dto.expiresIn.longValue(); + return AccessToken.builder() + .value(dto.accessToken) + .tokenType(isBlank(dto.tokenType) ? "Bearer" : dto.tokenType) + .expiresAt(Instant.now(clock).plusSeconds(expiresIn)) + .build(); + } + + /** Base64(clientId:clientSecret),UTF-8。 */ + static String basicAuth(String clientId, String clientSecret) { + String raw = clientId + ":" + clientSecret; + return "Basic " + Base64.getEncoder().encodeToString(raw.getBytes(StandardCharsets.UTF_8)); + } + + private static boolean isBlank(String v) { + return v == null || v.trim().isEmpty(); + } + + private static String truncate(String body) { + if (body == null) { + return null; + } + return body.length() <= WalmartConstants.RAW_RESPONSE_LIMIT + ? body : body.substring(0, WalmartConstants.RAW_RESPONSE_LIMIT); + } +} diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java new file mode 100644 index 0000000..5d7096c --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartItemDtos.java @@ -0,0 +1,113 @@ +package common.ecommerce.walmart.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; + +import java.math.BigDecimal; +import java.util.List; + +/** + * 沃尔玛报文结构:商品 Listing({@code GET /v3/items}、{@code GET /v3/items/{sku}})。 + * + *

列表字段名是单数 {@code ItemResponse},没有外层包装对象,直接是数组。

+ * + *

{@code shelf} 是JSON 字符串数组(例如 {@code "[\"Home Page\",\"Clothing\"]"}), + * 需要二次解析;{@code UNNAV} 表示未分配到可浏览类目。

+ */ +public final class WalmartItemDtos { + + private WalmartItemDtos() { + } + + /** 商品列表响应。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ItemListResponse { + + /** 商品数组;字段名就是单数 {@code ItemResponse}。 */ + @JsonProperty("ItemResponse") + public List itemResponse; + + /** 商品总数。 */ + @JsonProperty("totalItems") + public Integer totalItems; + + /** 下一页游标;无更多时为 null。 */ + @JsonProperty("nextCursor") + public String nextCursor; + } + + /** 商品。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ItemResponse { + + /** 站点:{@code WALMART_US} / {@code WALMART_CA} / {@code WALMART_MX}。 */ + @JsonProperty("mart") + public String mart; + + /** 卖家 SKU。 */ + @JsonProperty("sku") + public String sku; + + /** 沃尔玛商品 ID(Walmart Product ID)。 */ + @JsonProperty("wpid") + public String wpid; + + /** UPC 编码。 */ + @JsonProperty("upc") + public String upc; + + /** GTIN 编码(14 位,含前导 0)。 */ + @JsonProperty("gtin") + public String gtin; + + /** 商品名称。 */ + @JsonProperty("productName") + public String productName; + + /** 前台类目:JSON 字符串数组,如 {@code "[\"Home Page\",\"Clothing\"]"}。 */ + @JsonProperty("shelf") + public String shelf; + + /** 商品类型 / 类目模板名,如 {@code T-Shirts};{@code default} 表示默认模板。 */ + @JsonProperty("productType") + public String productType; + + /** 价格。 */ + @JsonProperty("price") + public Price price; + + /** 发布状态:{@code PUBLISHED} / {@code UNPUBLISHED} / {@code SYSTEM_PROBLEM} 等。 */ + @JsonProperty("publishedStatus") + public String publishedStatus; + + /** 未发布原因。 */ + @JsonProperty("unpublishedReasons") + public UnpublishedReasons unpublishedReasons; + + /** 生命周期状态:{@code ACTIVE} / {@code ARCHIVED} / {@code RETIRED}。 */ + @JsonProperty("lifecycleStatus") + public String lifecycleStatus; + } + + /** 价格。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Price { + + /** 币种:{@code USD} / {@code CAD} / {@code MXN}。 */ + @JsonProperty("currency") + public String currency; + + /** 售价;用 BigDecimal 接。 */ + @JsonProperty("amount") + public BigDecimal amount; + } + + /** 未发布原因容器。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class UnpublishedReasons { + + /** 原因列表(英文描述)。 */ + @JsonProperty("reason") + public List reason; + } +} diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java new file mode 100644 index 0000000..097a51f --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartOrderDtos.java @@ -0,0 +1,377 @@ +package common.ecommerce.walmart.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; + +import java.math.BigDecimal; +import java.util.List; + +/** + * 沃尔玛报文结构:订单({@code GET /v3/orders}、{@code GET /v3/orders/{id}})。 + * + *

层次陷阱:沃尔玛的 JSON 由旧版 XML Schema 转换而来,数组外层带单数包装对象: + * {@code orderLines.orderLine[]}、{@code orderLineStatuses.orderLineStatus[]}、 + * {@code charges.charge[]}。字段名照抄,不要「优化」成复数。

+ * + *

类型陷阱:金额是 {@code {"currency","amount"}} 且 amount 是数字; + * 数量是 {@code {"unitOfMeasurement","amount"}} 且 amount 是字符串; + * 时间是 epoch 毫秒。三者在退货接口里又都不一样。

+ */ +public final class WalmartOrderDtos { + + private WalmartOrderDtos() { + } + + /** 订单列表响应:{@code list.meta} + {@code list.elements.order[]}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderListResponse { + + /** 列表容器;平台未返回时为 null。 */ + @JsonProperty("list") + public ListWrapper list; + } + + /** 列表容器。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ListWrapper { + + /** 分页元信息。 */ + @JsonProperty("meta") + public Meta meta; + + /** 订单数组容器。 */ + @JsonProperty("elements") + public Elements elements; + } + + /** 分页元信息。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Meta { + + /** 总订单数。 */ + @JsonProperty("totalCount") + public Integer totalCount; + + /** 当前每页条数。 */ + @JsonProperty("limit") + public Integer limit; + + /** 下一页游标;无更多为 null。 */ + @JsonProperty("nextCursor") + public String nextCursor; + } + + /** 订单数组的包装层。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Elements { + + /** 订单数组;字段名就是单数 {@code order}。 */ + @JsonProperty("order") + public List order; + } + + /** + * 订单详情响应:{@code {"order": {...}}}。 + * + *

比列表多包一层,映射时两者共用 {@link Order}。

+ */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderDetailResponse { + + /** 订单本体。 */ + @JsonProperty("order") + public Order order; + } + + /** 订单本体。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Order { + + /** 沃尔玛订单号;标发接口的路径参数。 */ + @JsonProperty("purchaseOrderId") + public String purchaseOrderId; + + /** 平台客户订单号;买家侧看到的是它。 */ + @JsonProperty("customerOrderId") + public String customerOrderId; + + /** 客户邮箱;通常是沃尔玛中转地址({@code @relay.walmart.com})。 */ + @JsonProperty("customerEmailId") + public String customerEmailId; + + /** 下单时间,epoch 毫秒。 */ + @JsonProperty("orderDate") + public Long orderDate; + + /** 配送与收货信息。 */ + @JsonProperty("shippingInfo") + public ShippingInfo shippingInfo; + + /** 订单行容器。 */ + @JsonProperty("orderLines") + public OrderLines orderLines; + + /** 发货节点类型({@code SellerFulfilled} / {@code WalmartFulfilled})。 */ + @JsonProperty("shipNode") + public ShipNode shipNode; + } + + /** 配送与收货信息。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ShippingInfo { + + /** 收件人电话。 */ + @JsonProperty("phone") + public String phone; + + /** 预计发货时间,epoch 毫秒。 */ + @JsonProperty("estimatedShipDate") + public Long estimatedShipDate; + + /** 预计送达时间,epoch 毫秒。 */ + @JsonProperty("estimatedDeliveryDate") + public Long estimatedDeliveryDate; + + /** 订单配送方式({@code Value} / {@code Standard} / {@code TwoDay} 等)。 */ + @JsonProperty("methodCode") + public String methodCode; + + /** 收货地址。 */ + @JsonProperty("postalAddress") + public PostalAddress postalAddress; + } + + /** 收货地址。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class PostalAddress { + + /** 收件人姓名。 */ + @JsonProperty("name") + public String name; + + /** 地址行 1。 */ + @JsonProperty("address1") + public String address1; + + /** 地址行 2;可为 null。 */ + @JsonProperty("address2") + public String address2; + + /** 城市。 */ + @JsonProperty("city") + public String city; + + /** 州。 */ + @JsonProperty("state") + public String state; + + /** 邮编。 */ + @JsonProperty("postalCode") + public String postalCode; + + /** 国家,如 {@code USA}。 */ + @JsonProperty("country") + public String country; + + /** 地址类型:{@code RESIDENTIAL} / {@code OFFICE}。 */ + @JsonProperty("addressType") + public String addressType; + } + + /** 订单行容器。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderLines { + + /** 订单行数组。 */ + @JsonProperty("orderLine") + public List orderLine; + } + + /** 订单行。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderLine { + + /** 行号;标发报文里对应 {@code orderLine.lineNumber}。 */ + @JsonProperty("lineNumber") + public String lineNumber; + + /** 商品信息。 */ + @JsonProperty("item") + public Item item; + + /** 费用明细容器。 */ + @JsonProperty("charges") + public Charges charges; + + /** 数量,amount 是字符串。 */ + @JsonProperty("orderLineQuantity") + public Quantity orderLineQuantity; + + /** 行状态容器。 */ + @JsonProperty("orderLineStatuses") + public OrderLineStatuses orderLineStatuses; + + /** 状态时间,epoch 毫秒。 */ + @JsonProperty("statusDate") + public Long statusDate; + + /** 履约信息;结构未在沙箱覆盖,保留原始节点不映射。 */ + @JsonProperty("fulfillment") + public Object fulfillment; + } + + /** 订单行商品。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Item { + + /** 商品名称。 */ + @JsonProperty("productName") + public String productName; + + /** 卖家 SKU。 */ + @JsonProperty("sku") + public String sku; + } + + /** 费用明细容器。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Charges { + + /** 费用数组。 */ + @JsonProperty("charge") + public List charge; + } + + /** 单条费用。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Charge { + + /** 费用类型:{@code PRODUCT} / {@code FEE} / {@code SHIPPING}。 */ + @JsonProperty("chargeType") + public String chargeType; + + /** 费用名称,如 {@code ItemPrice}、{@code Shipping}。 */ + @JsonProperty("chargeName") + public String chargeName; + + /** 费用金额。 */ + @JsonProperty("chargeAmount") + public Amount chargeAmount; + + /** 税。 */ + @JsonProperty("tax") + public Tax tax; + } + + /** 金额:{@code {"currency","amount"}},amount 是数字。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Amount { + + /** 币种,如 {@code USD}。 */ + @JsonProperty("currency") + public String currency; + + /** 金额;用 BigDecimal 接,避免 double 精度问题。 */ + @JsonProperty("amount") + public BigDecimal amount; + } + + /** 税。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Tax { + + /** 税名。 */ + @JsonProperty("taxName") + public String taxName; + + /** 税额。 */ + @JsonProperty("taxAmount") + public Amount taxAmount; + } + + /** 数量:{@code {"unitOfMeasurement","amount"}},amount 是字符串。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Quantity { + + /** 计量单位,如 {@code EACH}。 */ + @JsonProperty("unitOfMeasurement") + public String unitOfMeasurement; + + /** 数量,字符串(沙箱样例 {@code "1"})。 */ + @JsonProperty("amount") + public String amount; + } + + /** 行状态容器。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderLineStatuses { + + /** 行状态数组。 */ + @JsonProperty("orderLineStatus") + public List orderLineStatus; + } + + /** 行状态。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class OrderLineStatus { + + /** 状态:{@code Created} / {@code Acknowledged} / {@code Shipped} / {@code Delivered} / {@code Cancelled}。 */ + @JsonProperty("status") + public String status; + + /** 该状态对应的数量。 */ + @JsonProperty("statusQuantity") + public Quantity statusQuantity; + + /** 取消原因,仅取消时有值。 */ + @JsonProperty("cancellationReason") + public String cancellationReason; + + /** 物流跟踪信息;未发货时为 null。 */ + @JsonProperty("trackingInfo") + public TrackingInfo trackingInfo; + } + + /** 物流跟踪信息。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class TrackingInfo { + + /** 发货时间,ISO-8601 字符串(与订单其它时间是 epoch 毫秒不同)。 */ + @JsonProperty("shipDateTime") + public String shipDateTime; + + /** 承运商。 */ + @JsonProperty("carrierName") + public CarrierName carrierName; + + /** 运输方式编码。 */ + @JsonProperty("methodCode") + public String methodCode; + + /** 跟踪号。 */ + @JsonProperty("trackingNumber") + public String trackingNumber; + } + + /** 承运商:标准承运商用 {@code carrier},非标准用 {@code otherCarrier},二选一。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CarrierName { + + /** 承运商编码,如 {@code UPS}、{@code FedEx}。 */ + @JsonProperty("carrier") + public String carrier; + + /** 非标准承运商名称。 */ + @JsonProperty("otherCarrier") + public String otherCarrier; + } + + /** 发货节点。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ShipNode { + + /** 发货节点类型:{@code SellerFulfilled} / {@code WalmartFulfilled}。 */ + @JsonProperty("type") + public String type; + } +} diff --git a/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java new file mode 100644 index 0000000..b3ef31e --- /dev/null +++ b/channel-sdk-walmart/src/main/java/common/ecommerce/walmart/dto/WalmartReturnDtos.java @@ -0,0 +1,396 @@ +package common.ecommerce.walmart.dto; + +import com.fasterxml.jackson.annotation.JsonIgnoreProperties; +import com.fasterxml.jackson.annotation.JsonProperty; + +import java.math.BigDecimal; +import java.util.List; + +/** + * 沃尔玛报文结构:售后退货({@code GET /v3/returns}、{@code GET /v3/returns/{id}})。 + * + *

与订单接口的差异(同一个字段三种写法):

+ *
    + *
  • 金额:订单是 {@code {"currency","amount"}},退货是 {@code {"currencyAmount","currencyUnit"}}
  • + *
  • 数量:订单是 {@code {"unitOfMeasurement","amount"(字符串)}}, + * 退货是 {@code {"unitOfMeasure","measurementValue"(数字)}}
  • + *
  • 时间:订单是 epoch 毫秒,退货是 ISO-8601 字符串
  • + *
+ * + *

分页陷阱:{@code meta.nextCursor} 的值本身是一段查询串 + * ({@code "?sellerId=151&limit=10&offset=10"}),翻页时整串拼到 URL 后面, + * 不是普通游标。

+ */ +public final class WalmartReturnDtos { + + private WalmartReturnDtos() { + } + + /** 退货单列表响应。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ReturnListResponse { + + /** 分页元信息。 */ + @JsonProperty("meta") + public Meta meta; + + /** 退货单数组。 */ + @JsonProperty("returnOrders") + public List returnOrders; + } + + /** 分页元信息。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class Meta { + + /** 退货单总数。 */ + @JsonProperty("totalCount") + public Integer totalCount; + + /** 当前每页条数。 */ + @JsonProperty("limit") + public Integer limit; + + /** 下一页查询串;无更多时为 null。 */ + @JsonProperty("nextCursor") + public String nextCursor; + } + + /** 退货单(一个退货单可含多个退货行)。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ReturnOrder { + + /** 退货单号。 */ + @JsonProperty("returnOrderId") + public String returnOrderId; + + /** 客户邮箱(沃尔玛中转邮箱)。 */ + @JsonProperty("customerEmailId") + public String customerEmailId; + + /** 客户姓名。 */ + @JsonProperty("customerName") + public CustomerName customerName; + + /** 平台客户订单号。 */ + @JsonProperty("customerOrderId") + public String customerOrderId; + + /** 退款模式:{@code PRE_DELIVERY} / {@code POST_DELIVERY}。 */ + @JsonProperty("refundMode") + public String refundMode; + + /** 退货单创建时间,ISO-8601 字符串。 */ + @JsonProperty("returnOrderDate") + public String returnOrderDate; + + /** 退货类型:{@code RETURN} / {@code REPLACEMENT}。 */ + @JsonProperty("returnType") + public String returnType; + + /** 换货生成的客户订单号;换货时有值。 */ + @JsonProperty("replacementCustomerOrderId") + public String replacementCustomerOrderId; + + /** 最晚退货时间,ISO-8601。 */ + @JsonProperty("returnByDate") + public String returnByDate; + + /** 应退总金额。 */ + @JsonProperty("totalRefundAmount") + public CurrencyAmount totalRefundAmount; + + /** 退货渠道。 */ + @JsonProperty("returnChannel") + public ReturnChannel returnChannel; + + /** 退货包裹 / 面单分组。 */ + @JsonProperty("returnLineGroups") + public List returnLineGroups; + + /** 退货行数组。 */ + @JsonProperty("returnOrderLines") + public List returnOrderLines; + } + + /** 客户姓名。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CustomerName { + + /** 名。 */ + @JsonProperty("firstName") + public String firstName; + + /** 姓。 */ + @JsonProperty("lastName") + public String lastName; + } + + /** 退货金额:{@code {"currencyAmount","currencyUnit"}};currencyAmount 是数字。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CurrencyAmount { + + /** 金额;用 BigDecimal 接。 */ + @JsonProperty("currencyAmount") + public BigDecimal currencyAmount; + + /** 币种,如 {@code USD}。 */ + @JsonProperty("currencyUnit") + public String currencyUnit; + } + + /** 退货渠道。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ReturnChannel { + + /** 渠道名:{@code IN_STORE}(到店) / {@code ONLINE}(线上)。 */ + @JsonProperty("channelName") + public String channelName; + } + + /** 退货包裹 / 面单分组。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class ReturnLineGroup { + + /** 分组号。 */ + @JsonProperty("groupNo") + public Integer groupNo; + + /** 组内退货行。 */ + @JsonProperty("returnLines") + public List returnLines; + + /** 面单列表。 */ + @JsonProperty("labels") + public List