diff --git a/README.md b/README.md index 5379ba7..9d4d41a 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/docs/walmart/README.md b/docs/walmart/README.md new file mode 100644 index 0000000..aecb497 --- /dev/null +++ b/docs/walmart/README.md @@ -0,0 +1,280 @@ +# 沃尔玛直连接入(channel-sdk-walmart) + +> 模块:`channel-sdk-walmart` 通道:`ChannelProvider.DIRECT` 平台:`Platform.WALMART_SC` +> 协议依据:《沃尔玛沙箱接口说明》v1.0(2026-11-16)+ Walmart Developer Portal 官方文档/reference(2026-11 核对),沙箱 `https://sandbox.walmartapis.com` +> 退货单详情以官方 [Returns Management API overview](https://developer.walmart.com/us-marketplace/docs/returns-and-refunds-api-overview) 为准:该页明确有 `GET /v3/returns/{returnOrderId}`,但 reference 目录未单列响应 schema。 + +已接(共 7 条路由):**`/v3/token` 鉴权 + 商品列表 + 订单列表/详情 + 退货单列表/详情 + 退款 + 标发**。 +未接:商品详情、商品创建/更新(走 Feed,本期不做)、创建退货 / 取消退货(无报文)、 +开放单对账、发货信息查询、`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(1 → N) +│ │ ├── WalmartRefundMapper.java RefundCommand → 退款报文;响应 → RefundResult +│ │ └── WalmartShipmentWriteMapper.java ShipmentCommand → 标发报文;响应 → ShipmentResult +│ ├── 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` 商品列表 | ✅(单品查询未接,`get()` 显式报错) | +| `RETURNS` 退货列表(按行展开) | ✅ | +| 退货单详情 `WalmartAdapter.getReturn` | ✅ `GET /v3/returns/{returnOrderId}`(overview 有定义,reference 未给 schema;兼容单条/列表/裸对象三种响应) | +| `MARK_SHIPPED` 标发 | ✅(⚠ 沙箱 404,见 §7) | +| `REFUND` 退款 | ✅(⚠ 沙箱 404,见 §8) | +| 商品详情 / 创建 / 更新、发货信息查询、开放单对账 | ❌ 本期不接 | + +过滤条件的支持面比领星窄,**不支持的组合一律抛 `ValidationException`**,见 +[`docs/channel/api-reference.md` §15A.6](../channel/api-reference.md#15a6-不支持的过滤条件显式报错)。 + +--- + +## 4. 增量同步 + +沃尔玛订单只有**创建时间**过滤,没有更新时间。`updatedAfter/updatedBefore` 直接映射成 +`createdStartDate/createdEndDate`,`pull` 的语义保持单一可预测;老单状态变化本期不做对账, +需要时用较大的创建时间窗重拉(平台不支持按更新时间过滤)。 + +`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)、未知值、空值 | +| `WalmartReturnDetailTest` | 退货单详情:真实路由、路径段编码、三种响应形状、404 透传 | +| `WalmartFacadeTest` | 门面路由、能力矩阵、未实现写能力被拒、未注册平台报错 | +| `WalmartMarkShippedTest` | 标发报文(单数包装 / 固定状态 / 字符串数量 / ISO 时间)、非标准承运商、响应映射、幂等键稳定性 | +| `WalmartRefundTest` | 退款报文逐字段对齐 §5.3 示例、多行多费用项、非整数行号本地拒绝 | + +### 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`、无面单分组) | +| `errors/*.json` | 文档 §1.5 两种错误格式原文 | +| `token/success.json` | 文档 §2.1 实测结构(token 值为占位) | + +--- + +## 6. 已知问题 + +| 问题 | 状态 | +|---|---| +| `GET /v3/returns/{id}` | 官方 overview 明确列出该路由,但 reference 未单列响应 schema;`getReturn` 已按真实路由实现,沙箱 mock 404,生产再验 | +| 沙箱退款 404 | 已按文档实现,生产再验 | +| 沙箱过滤参数不生效 | 以生产为准 | +| 订单列表 `status` 过滤是否生效 | 探针未覆盖写操作,读侧以生产为准 | +| 订单翻页时是否仍需带时间窗 | **未验证**,退货游标是完整查询串,暗示游标已蕴含条件 | +| `createdStartDate` 最大回溯窗口 | 代码按 180 天硬校验,待探针核实 | +| `x-current-token-count` 实际值 | 待探针核实 | + +--- + +## 7. 标发(MARK_SHIPPED) + +沃尔玛没有批量标发接口,**一次一个订单**;支持部分发货。 + +```java +ShipmentCommand cmd = ShipmentCommand.builder() + .channelOrderId("108816631915371") + .line(ShipmentCommand.Line.builder() + .lineNumber("1") // 必须与订单详情一致 + .quantity(2) // 本次实发 + .carrier("UPS") // 或 carrierName("非标准承运商") + .methodCode("Standard") // 必须与承运商方式对照表匹配 + .trackingNumber("1Z999...") + // .shippedAt(...) // 不传则取 ctx.clock() + .build()) + .build(); + +// 写操作必须包在 sdk.writes() 里 +WriteResult r = sdk.writes().execute( + WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, + "oms-wm-001", "wm-seller-01", "markShipped", cmd.businessRef()), + () -> sdk.salesOrders(key, conn).markShipped(cmd), + ShipmentResult::channelOrderId); +``` + +**幂等键**:`ShipmentCommand.businessRef()` = `订单号|行号:数量,行号:数量`(行号排序)。 +不带金额与跟踪号——换跟踪号属于修正,不应产生新动作;数量不同则是新的一次部分发货。 + +**报文要求**(依据官方 `reference/shippingupdates` schema): + +| 字段 | 要求 | +|---|---| +| `lineNumber` | 与订单详情一致 | +| `status` | 固定 `Shipped` | +| `statusQuantity.unitOfMeasurement` | 固定 `EACH`(官方枚举 `EACH`/`EA`) | +| `statusQuantity.amount` | **字符串** | +| `trackingInfo.shipDateTime` | **epoch 毫秒整数**(官方 `int64`,不是 ISO 字符串) | +| `trackingInfo.carrierName` | `carrier` 与 `otherCarrier` 至少一个 | +| `trackingInfo.methodCode` | 官方枚举:`Standard` / `Express` / `OneDay` / `Freight` / `WhiteGlove` / `Value` | +| `trackingInfo.trackingNumber` | 必填 | +| `trackingInfo.trackingURL` | 可空;用 `otherCarrier` 时建议给 | +| `sellerOrderId` | 官方标必填(≤30 字符,印在退货面单上);适配器**不强制**,超长时省略而不是截断 | +| `intentToCancelOverride` | 客户已申请取消但仍要发货时传 `true`;默认不发 | +| `processMode` | 发货后只更新物流信息时传 `PARTIAL_UPDATE`;首次标发不传 | + +DTO 上标了 `@JsonInclude(NON_NULL)`,未设置字段不会被发成 `null`。 + +--- + +## 8. 退款(REFUND) + +报文按文档 §5.3,细到**退货行 × 费用项**: + +```java +RefundCommand cmd = RefundCommand.builder() + .afterSaleId("103738048909818825") + .line(RefundCommand.Line.builder() + .lineId("1") // 平台退货行号,必须是整数 + .charge(RefundCommand.Charge.builder() + .chargeName("ItemPrice") + .chargeType("PRODUCT") // PRODUCT / FEE / SHIPPING + .amount(Money.of("119.95", "USD")) + .build()) + .build()) + .build(); + +sdk.writes().execute( + WriteScope.of(ChannelProvider.DIRECT, Platform.WALMART_SC, + "oms-wm-001", "wm-seller-01", "refund", "103738048909818825:1"), + () -> sdk.afterSales(key, conn).refund(cmd), + RefundResult::afterSaleId); +``` + +业务规则(文档 §5.3):部分售后由平台自动退款,只有 `currentRefundStatus` 需要卖家处理 +(或 `refundChannels` 含 `SELLER_MANUAL_REFUND`)时才调用;调用前先查详情核对 +`refundedQty` / `cancellableQty`,避免超退。 + +退货列表的官方过滤参数(`reference/getreturns`): + +| 参数 | 说明 | +|---|---| +| `returnCreationStartDate` / `returnCreationEndDate` | 按退货单创建时间(ISO-8601) | +| `returnLastModifiedStartDate` / `returnLastModifiedEndDate` | 按退货单修改时间(ISO-8601) | +| `returnType` | `PREORDER` / `REPLACEMENT` / `REFUND` | +| `status` | `INITIATED` / `DELIVERED` / `COMPLETED` | +| `limit` | 默认 10,上限 200;**没有 `offset`** | + +统一模型 `AfterSaleQuery.DateType` 的映射: + +- `AFTER_SALE_TIME` → `returnCreation*` +- `UPDATE_TIME` → `returnLastModified*` +- `PURCHASE_TIME` → 没有对应参数,本地报错 + +行号不是整数时本地抛 `ValidationException`,不发请求。 + +--- + +## 9. 未接入的接口 + +| 接口 | 原因 | +|---|---| +| `POST /v3/items` 创建商品 | 报文只有「精简示例」,正式对接需按《Item Spec》生成;版本管理未定 | +| `PUT /v3/items/{sku}` 更新商品 | 同上;且 PUT 是覆盖式,需先定「先查后写」的约定 | +| `GET /v3/items/{sku}` 商品详情 | 本期只同步商品列表;`ProductCapable.get()` 显式报错 | +| `GET /v3/orders/{id}/shipping` 发货信息 | 官方只有 POST 标发,没有查询路由 | +| `POST /v3/returns` 创建退货 | **文档只给路径,没有请求报文** | +| `POST /v3/returns/{id}/cancel` 取消退货 | 同上 | diff --git a/操作手册.md b/操作手册.md index 28c0a0b..d4e1750 100644 --- a/操作手册.md +++ b/操作手册.md @@ -138,7 +138,7 @@ ChannelConnection conn = ChannelConnection.of( |:---|:---| | 领星 | `appKey`(= AppID)、`appSecret` | | 亚马逊直连 | `clientId`、`clientSecret`、`refreshToken` | -| 沃尔玛 | `clientId`、`clientSecret` | +| 沃尔玛(领星 / 直连) | `clientId`、`clientSecret` | **安全要求**: @@ -534,16 +534,20 @@ try { ## 附录:当前实现状态 -| 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛 | Temu / SHEIN / eBay / TikTok / Target / AliExpress 等 | Direct | +| 能力 | 亚马逊 SC | 亚马逊 VC | 沃尔玛(领星) | 其他平台(领星) | 沃尔玛直连 | |:---|:---:|:---:|:---:|:---:|:---:| -| 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ❌ | -| 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ❌ | -| 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ❌ | -| 店铺列表 | ✅ | ✅ | ✅ | ✅ | — | +| 订单列表 | ✅ | ✅ | ✅ | ✅(多平台统一订单) | ✅ | +| 订单详情 | ✅(含 FBM) | ✅ | ❌ | ❌ | ✅ | +| 商品 / Listing | ✅ | ✅ | ✅ | ✅(8 个平台) | ✅ | +| 商品详情 | ❌ | ❌ | ❌ | ❌ | ❌ | +| 店铺列表 | ✅ | ✅ | ✅ | ✅ | —(直连无此概念) | | 账单 / 结算 | ✅ | ❌ | ❌ | ❌ | ❌ | -| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ❌ | -| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ❌ | +| 售后(只读) | ✅ | ❌ | ❌ | ❌ | ✅ | +| 快速出库(写) | ✅ | ✅ | ✅ | ✅ | ✅(仅标发) | | 出库单 / 面单 / 审核发货 | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ | | 订单编辑(写) | ✅(ERP 级,全平台共用) | 同左 | 同左 | 同左 | ❌ | +> 「沃尔玛直连」= `ChannelProvider.DIRECT` + `Platform.WALMART_SC`,模块 `channel-sdk-walmart`, +> 详见 [docs/walmart/README.md](docs/walmart/README.md)。 + 写接口没有测试环境,联调时**只跑查询**。