|
|
|
|
|
# 沃尔玛直连接入(channel-sdk-walmart)
|
|
|
|
|
|
|
|
|
|
|
|
> 模块:`channel-sdk-walmart` 通道:`ChannelProvider.DIRECT` 平台:`Platform.WALMART_SC`
|
|
|
|
|
|
> 协议依据:《沃尔玛沙箱接口说明》v1.0(2026-11-16),沙箱 `https://sandbox.walmartapis.com`
|
|
|
|
|
|
|
|
|
|
|
|
只读三件套:**订单 / 商品 / 售后**。标发、退款、商品写入、`WALMART_1P`、结算、Webhook 不在本期。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 1. 目录结构
|
|
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
channel-sdk-walmart/
|
|
|
|
|
|
├── src/main/java/common/ecommerce/walmart/
|
|
|
|
|
|
│ ├── WalmartConstants.java 沙箱/生产端点、路径、请求头名、分页上限、时间窗上限
|
|
|
|
|
|
│ ├── adapter/
|
|
|
|
|
|
│ │ ├── WalmartAdapter.java SalesOrderCapable + ProductCapable + AfterSaleCapable
|
|
|
|
|
|
│ │ └── WalmartAdapterFactory.java DIRECT + WALMART_SC
|
|
|
|
|
|
│ ├── auth/WalmartTokenClient.java POST /v3/token(Basic Auth + form)
|
|
|
|
|
|
│ ├── http/
|
|
|
|
|
|
│ │ ├── WalmartRequestFactory.java 公共头 + token 头 + query 拼接
|
|
|
|
|
|
│ │ └── WalmartErrors.java 两种错误格式 → Auth/Transient/RateLimit/Validation
|
|
|
|
|
|
│ ├── mapper/
|
|
|
|
|
|
│ │ ├── WalmartOrderMapper.java 订单 → SalesOrder(行状态聚合、金额汇总、单价折分)
|
|
|
|
|
|
│ │ ├── WalmartProductMapper.java ItemResponse → ProductListing(shelf 二次解析)
|
|
|
|
|
|
│ │ ├── WalmartReturnMapper.java returnOrder → List<AfterSale>(1 → N)
|
|
|
|
|
|
│ │ └── WalmartShipmentMapper.java shipping 响应 → 行级发货记录
|
|
|
|
|
|
│ ├── enums/
|
|
|
|
|
|
│ │ ├── WalmartOrderStatus.java 行状态 → 订单级状态聚合
|
|
|
|
|
|
│ │ ├── WalmartPublishedStatus.java publishedStatus + lifecycleStatus → ProductStatus
|
|
|
|
|
|
│ │ └── WalmartReturnType.java returnType → AfterSaleType
|
|
|
|
|
|
│ └── dto/ 一个接口一个文件,字段名照抄沃尔玛
|
|
|
|
|
|
└── src/test/
|
|
|
|
|
|
├── java/.../adapter/ 订单 / 商品 / 售后契约测试
|
|
|
|
|
|
├── java/.../http/ 错误解析
|
|
|
|
|
|
├── java/.../enums/ 状态映射边界
|
|
|
|
|
|
├── java/.../WalmartFacadeTest 门面集成
|
|
|
|
|
|
├── java/.../probe/ 沙箱探针(默认跳过)
|
|
|
|
|
|
└── resources/fixtures/walmart/ 夹具,来源见 §5
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 2. 接入
|
|
|
|
|
|
|
|
|
|
|
|
```java
|
|
|
|
|
|
ChannelSdk sdk = ChannelSdk.builder()
|
|
|
|
|
|
.accountRepository(repo)
|
|
|
|
|
|
.callObserver(new Slf4jCallObserver(ZoneId.of("Asia/Shanghai")))
|
|
|
|
|
|
.register(new WalmartAdapterFactory(tokenStore, lockProvider, Clock.systemUTC()))
|
|
|
|
|
|
.build();
|
|
|
|
|
|
|
|
|
|
|
|
AccountKey key = AccountKey.of(ChannelProvider.DIRECT, Platform.WALMART_SC, "oms-wm-001");
|
|
|
|
|
|
|
|
|
|
|
|
ChannelConnection conn = ChannelConnection.of(
|
|
|
|
|
|
"https://sandbox.walmartapis.com",
|
|
|
|
|
|
ChannelSecret.builder()
|
|
|
|
|
|
.clientId("...")
|
|
|
|
|
|
.clientSecret("...")
|
|
|
|
|
|
.build());
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
`ChannelAccount` 上只需要 `marketplaceZone`(订单时间用)、`currency`;`platformCode` 对直连没有意义,
|
|
|
|
|
|
落库用 `ChannelProvider.NO_PLATFORM_CODE`。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 3. 能力与限制
|
|
|
|
|
|
|
|
|
|
|
|
| 能力 | 状态 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `SALES_ORDER` 订单列表 / 详情 | ✅ |
|
|
|
|
|
|
| `PRODUCT` 商品列表 / 详情 | ✅ |
|
|
|
|
|
|
| `RETURNS` 退货列表(按行展开) | ✅ |
|
|
|
|
|
|
| 退货单详情 `WalmartAdapter.getReturn` | ✅(⚠ 沙箱 404) |
|
|
|
|
|
|
| 发货信息 `WalmartAdapter.getShipping` | ✅(⚠ 沙箱 404) |
|
|
|
|
|
|
| `MARK_SHIPPED` 标发 | ❌ 下一期 |
|
|
|
|
|
|
| `REFUND` 退款 | ❌ 沙箱 404 |
|
|
|
|
|
|
| 商品写入(Feed / 单个) | ❌ 沙箱 520 |
|
|
|
|
|
|
|
|
|
|
|
|
过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见
|
|
|
|
|
|
[`docs/channel/api-reference.md` §15A.6](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 4. 增量同步
|
|
|
|
|
|
|
|
|
|
|
|
沃尔玛订单只有**创建时间**过滤,没有更新时间。SDK 给了两条明确的路,不混用:
|
|
|
|
|
|
|
|
|
|
|
|
| 场景 | 调用 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| 拉新单(水位线增量) | `sdk.salesOrders(key, conn).pull(query)`,`updatedAfter/updatedBefore` 即创建时间窗 |
|
|
|
|
|
|
| 老单状态对账 | `WalmartAdapter.pullOpenOrders(ctx, statuses, createdAfter, cursor)`,按 `Created`/`Acknowledged` 拉开放单 |
|
|
|
|
|
|
|
|
|
|
|
|
`SyncEngine` 目前只支持 `syncSalesOrders`;商品的 `FULL_PULL_DIFF` 由宿主自己比对
|
|
|
|
|
|
(`ProductCapable.syncStrategy()` 已声明)。
|
|
|
|
|
|
|
|
|
|
|
|
时间窗上限 180 天(📖 待官方核实),超了本地拒绝,不静默截断。
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 5. 测试与探针
|
|
|
|
|
|
|
|
|
|
|
|
### 5.1 契约测试(无网络)
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
mvn -pl channel-sdk-walmart -am test
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
| 测试 | 覆盖 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `WalmartOrderTest` | 请求头、创建时间窗、游标、token 缓存与 401 重试、行状态聚合、金额汇总、地址映射 |
|
|
|
|
|
|
| `WalmartDirtyDataTest` | 缺单号/下单时间的单被跳过、除不尽时 `unitPrice` 为 null、运费不冒充单价、多币种不给总额、退货缺单号整单丢弃 |
|
|
|
|
|
|
| `WalmartProductTest` | limit 上限、sku 搜索、三种不支持过滤的报错、shelf 解析、状态组合 |
|
|
|
|
|
|
| `WalmartReturnTest` | 1 单拆 N 行、查询串型游标、退款金额回落、脏时间不卡页 |
|
|
|
|
|
|
| `WalmartErrorsTest` | 两种错误格式、401/429/5xx/`SYSTEM_ERROR` 分类、报文截断 |
|
|
|
|
|
|
| `WalmartStatusMappingTest` | 精确匹配(不做 contains)、未知值、空值 |
|
|
|
|
|
|
| `WalmartExtraQueryTest` | 退货详情、发货信息两个扩展查询 |
|
|
|
|
|
|
| `WalmartFacadeTest` | 门面路由、能力矩阵、写能力被拒、未注册平台报错 |
|
|
|
|
|
|
|
|
|
|
|
|
### 5.2 沙箱探针(只读,默认跳过)
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
mvn -pl channel-sdk-walmart -am -DfailIfNoTests=false \
|
|
|
|
|
|
-Dwalmart.probe=true \
|
|
|
|
|
|
-Dwalmart.probe.clientId=你的clientId \
|
|
|
|
|
|
-Dwalmart.probe.clientSecret=你的clientSecret \
|
|
|
|
|
|
-Dtest=WalmartProbeTest test
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
可选参数:`-Dwalmart.probe.baseUrl=...`(打生产,**只读**)、`-Dwalmart.probe.sku=...`。
|
|
|
|
|
|
|
|
|
|
|
|
探针打印每一条请求/响应(token 只打前 12 位),对已知的 404 / 固定条数**不断言失败**,
|
|
|
|
|
|
唯一硬断言是 token 能换到。
|
|
|
|
|
|
|
|
|
|
|
|
探针跑完请核对这几件事,四项都确认后可以把 `WalmartConstants` 里的「📖 待核实」注释去掉:
|
|
|
|
|
|
|
|
|
|
|
|
1. `x-current-token-count` 的实际值(确认缓存复用是否必要)
|
|
|
|
|
|
2. `createdStartDate` 的真实最大回溯窗口
|
|
|
|
|
|
3. `charges` 的真实结构(沙箱样例有 `ItemPrice` + `Shipping` 两条)
|
|
|
|
|
|
4. 退货 `nextCursor` 的形态是否始终是查询串
|
|
|
|
|
|
|
|
|
|
|
|
### 5.3 夹具来源
|
|
|
|
|
|
|
|
|
|
|
|
`src/test/resources/fixtures/walmart/`:
|
|
|
|
|
|
|
|
|
|
|
|
| 文件 | 来源 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `orders/list.json` | 文档 §4.1 实测样例(2 条)+ 补了 3 条:部分发货、已发完仍残留 `Created`、多件(整行金额折单价) |
|
|
|
|
|
|
| `orders/detail.json` | 文档 §4.2 实测样例 |
|
|
|
|
|
|
| `items/list.json` | 文档 §3.1 实测样例 + 补了 `PUBLISHED/ACTIVE` 与 `PUBLISHED/RETIRED` 两条 |
|
|
|
|
|
|
| `returns/list.json` | 文档 §5.1 实测样例 + 补了第二行(覆盖无 `chargeTotals`、无面单分组) |
|
|
|
|
|
|
| `returns/detail.json` | 按文档 §5.2 的「同列表元素」结构构造(沙箱 404,无实测) |
|
|
|
|
|
|
| `orders/shipping.json` | 按文档 §4.4 的 `orderShipment` 结构构造(沙箱 404,无实测;含非标准承运商) |
|
|
|
|
|
|
| `errors/*.json` | 文档 §1.5 两种错误格式原文 |
|
|
|
|
|
|
| `token/success.json` | 文档 §2.1 实测结构(token 值为占位) |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 6. 已知问题
|
|
|
|
|
|
|
|
|
|
|
|
| 问题 | 状态 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| 沙箱商品详情 404 | 生产环境再验 |
|
|
|
|
|
|
| 沙箱退货详情 / 退款 404 | 详情已按文档实现(`getReturn`),退款未实现 |
|
|
|
|
|
|
| 沙箱 Feed 520 | 未实现 |
|
|
|
|
|
|
| 沙箱过滤参数不生效 | 以生产为准 |
|
|
|
|
|
|
| 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 |
|
|
|
|
|
|
| `pullOpenOrders` 的 `status=Created,Acknowledged` 多值是否成立 | **未验证**,文档只给了单值示例;探针跑通后确认 |
|
|
|
|
|
|
| 订单翻页时是否仍需带时间窗 | **未验证**,退货游标是完整查询串,暗示游标已蕴含条件 |
|
|
|
|
|
|
| `createdStartDate` 最大回溯窗口 | 代码按 180 天硬校验,待探针核实 |
|
|
|
|
|
|
| `x-current-token-count` 实际值 | 待探针核实 |
|
|
|
|
|
|
| 标发 | 下一期:新增 `MarkShippedCapable` + `SalesOrders.markShipped(...)` |
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
## 7. 下一期(标发)
|
|
|
|
|
|
|
|
|
|
|
|
设计已定,实现待排:
|
|
|
|
|
|
|
|
|
|
|
|
- core 新增 `MarkShippedCapable`:`ShipmentConfirmation confirm(ChannelContext, ShipmentCommand)`
|
|
|
|
|
|
- 模型:行号 + 数量 + 承运商 + `methodCode` + 跟踪号 + 发货时间(ISO-8601)
|
|
|
|
|
|
- 门面:`sdk.salesOrders(key, conn).markShipped(...)`,写操作由调用方包在 `sdk.writes()` 里
|
|
|
|
|
|
- 幂等键:`action=markShipped`,`businessRef=purchaseOrderId:lineNumber:quantity`
|
|
|
|
|
|
(**不带金额**,符合 `WriteScope` 约定)
|
|
|
|
|
|
- 部分发货:同一行可多次调用,`statusQuantity.amount` 累计;调用前先 `get` 确认行状态与数量
|