You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

143 lines
6.1 KiB

feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
package common.ecommerce.walmart;
/**
* 沃尔玛 Marketplace 协议常量。
*
* <p>端点与路径属于<b>协议的一部分</b>,写在代码里,不做成配置表。
* 运行时不使用 {@link #PRODUCTION_BASE_URL} / {@link #SANDBOX_BASE_URL}:
* 端点由调用方每次经 {@code ChannelConnection} 传入(沙箱还是生产由宿主决定,
* 账户上的 {@code ChannelAccount.sandbox()} 只是元数据)。</p>
*
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
* <p>来源:Walmart Developer Portal 官方 reference(2026-11 核对):
* {@code /us-marketplace/reference/} 下的 {@code shippingupdates}、{@code getallorders}、
* {@code getreturns}、{@code getallitems}、{@code itembulkuploads}、{@code getallfeedstatuses}。
* 与《沃尔玛沙箱接口说明》v1.0 冲突时<b>以官方 schema 为准</b>。</p>
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
*/
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";
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
/** 发起退款:{@code POST /v3/returns/{returnOrderId}/refund}。⚠ 沙箱实测 404。 */
public static final String PATH_RETURN_REFUND = "/refund";
/**
* Feed 提交({@code POST /v3/feeds?feedType=...})与状态查询({@code GET /v3/feeds/{feedId}})。
*
* <p>⚠ 沙箱实测两条路由都 520(mock 未实现);本期只做常量与 DTO,
* 没有对外方法——沃尔玛的商品写入是 Feed 的载体,等商品写接入时一起开放。</p>
*/
public static final String PATH_FEEDS = "/v3/feeds";
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
// ---------------------------------------------------------------- 请求头
/** 服务名,固定值。 */
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";
/** 访问令牌;<b>业务接口用它,不用 Authorization</b>。 */
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";
// ---------------------------------------------------------------- 限制
/**
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
* 商品列表单页上限。
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
*
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
* <p>官方原文:{@code cannot be more than 1000 entities per request},默认 20。
* 注意 {@code nextCursor} 描述里的「more than 200 items」是<b>建议改用游标的阈值</b>,
* 不是 limit 上限——两者容易混。</p>
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
*/
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
public static final int MAX_ITEM_PAGE_SIZE = 1000;
/**
* 商品列表 {@code nextCursor} 的初始值。
*
* <p>官方 schema 的 {@code default} 与 {@code example} 都是 {@code *}。
* 不过首页不传也能用平台默认,适配器选择<b>不显式传</b>,避免平台版本差异导致 400。</p>
*/
public static final String ITEM_CURSOR_INITIAL = "*";
/** 商品游标有效期(秒);过期平台返回 400 Invalid Cursor。 */
public static final int ITEM_CURSOR_TTL_SECONDS = 120;
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
/** 订单列表在沙箱的默认单页条数;未显式指定时用它。 */
public static final int DEFAULT_ORDER_PAGE_SIZE = 20;
/**
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
* 订单列表单页上限。
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
*
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
* <p>官方原文:{@code Cannot be larger than 200.}</p>
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
*/
public static final int MAX_ORDER_PAGE_SIZE = 200;
/** 退货列表默认单页条数;沃尔玛默认 10。 */
public static final int DEFAULT_RETURN_PAGE_SIZE = 10;
feat(walmart): 标发 / 退款 / 商品 Feed 接入,并按官方 schema 修正参数 【新增写操作】 - MarkShippedCapable + SalesOrders.markShipped:标发一订单,支持部分发货; 幂等键 businessRef = 订单号|行号:数量(行号排序,不含金额与跟踪号) - RefundCapable + AfterSales.refund:按退货行 × 费用项退款 - WalmartAdapter.submitFeed / getFeedStatus:商品 Feed 提交与状态轮询(扩展方法, 不进能力接口——Feed 是沃尔玛特有机制,塞进 ProductCapable 会让统一模型变形) 【按官方 reference 修正(与《沙箱接口说明》冲突处一律以官方 schema 为准)】 标发 POST /v3/orders/{id}/shipping: - shipDateTime 由 ISO-8601 字符串改为 epoch 毫秒整数(官方 type=integer, format=int64) - 补 sellerOrderId(官方标必填,≤30 字符;适配器不强制,超长省略而非截断) - 补 intentToCancelOverride(仅 true 时发)、trackingURL(可空) - OrderShipment 支持 processMode(发货后改物流时传 PARTIAL_UPDATE) 退货 GET /v3/returns: - 时间参数由 createdStartDate/EndDate 改为 returnCreationStartDate/EndDate - DateType.UPDATE_TIME 映射到 returnLastModifiedStartDate/EndDate; PURCHASE_TIME 无对应参数,本地报错 - 去掉官方不存在的 offset 参数 - returnType 枚举改为官方 PREORDER/REPLACEMENT/REFUND;保留 RETURN 别名兼容历史数据 - limit 加上限 200 商品 GET /v3/items: - limit 上限由 200 改为 1000(200 只是「建议改用游标」的阈值) - 新增 ITEM_CURSOR_INITIAL 与游标 TTL 常量;首页仍不显式传 nextCursor 商品 Feed POST /v3/feeds: - feedType 按官方 13 个枚举值本地校验,非法值直接拒绝 - 成功响应是 200 而非 202 【校验与容错】 - 脏数据:缺订单号/下单时间/退货单号的记录跳过并 WARN,不崩整页 - 行金额除不尽时 unitPrice 留 null,不四舍五入倒推 - 运费不冒充商品单价;同单多币种时 totalAmount 为 null - 请求 DTO 统一 @JsonInclude(NON_NULL),避免 null 字段被平台判为格式错误 【测试】162 个(订单 22、商品 20、售后 14、标发 16、退款 12、Feed 16、 状态映射 18、错误 11、扩展查询 12、门面 5、探针 1 跳过)。 Co-Authored-By: Claude Code <noreply@anthropic.com>
2 days ago
/** 退货列表单页上限;官方原文 {@code Cannot be larger than 200.} */
public static final int MAX_RETURN_PAGE_SIZE = 200;
feat(walmart): 沃尔玛 Marketplace 直连适配器(只读一期) 通道 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 <noreply@anthropic.com>
2 days ago
/**
* 订单创建时间窗的最大回溯天数(📖 官方常见取值,待 Developer Portal 核实)。
*
* <p>超过这个跨度在本地直接拒绝,不做静默截断——静默截断会让宿主以为拉全了。</p>
*/
public static final int MAX_ORDER_WINDOW_DAYS = 180;
/**
* 令牌提前续期秒数。
*
* <p>{@code expires_in} 只有 900 秒,且沙箱响应头 {@code x-current-token-count}
* 已达 99(平台对并发有效 token 有上限),必须缓存复用、提前续期。</p>
*/
public static final long TOKEN_EARLY_REFRESH_SECONDS = 120L;
/** 异常里保留的原始响应最大长度;避免整页报文塞进日志。 */
public static final int RAW_RESPONSE_LIMIT = 1024;
private WalmartConstants() {
}
}