Browse Source
三个接口真机均确认存在(无 token 时返回各自的 Unauthorized 文案, 与 404 对照组可区分)。 按 SKU 查 /v1/inventory/getInventory、批量分页 /v2/inventory/get_inventory_by_page - 恒健有两个库存接口且能力不同,统一模型只有一个 query(),按条件分流: 给 providerSkus 走按 SKU(不分页),只给 warehouseCodes 走分页 - 两个都给 → 拒绝(恒健无此接口);都不给 → 拒绝(不退化成整仓全量); 给 updatedAfter / inventoryType / includeZeroStock → 拒绝(不支持) - 分页接口 rows 上限 500(文档明写),超过拒绝不截断 - 字段名两套:字段表写 snake_case、示例写 camelCase,DTO 用 @JsonAlias 同时接住 - data 形状两套:对象(含 content)与数组,用 JsonNode 判形状后分流 - updatedAt 缺失时报错而非填 EPOCH——快照时间是对账对齐依据 - syncStrategy = FULL_PULL_DIFF:两个接口都没有增量入参 库存变动流水 /v1/inventory/task/query - 真机确认 skus / beginDateTime / endDateTime 必填,缺项回 MethodArgumentNotValidException - 日期跨度按「含首尾」口径算:10-01~10-30 合法(30 天),10-01~10-31 非法 - rows 上限 100(文档明写) - 新增 core 模型 InventoryMovement / InventoryMovementQuery / queryMovements() - changeQty 按原值保留不转符号;单据类型与变动方向保留仓方原文不归一 - 单行缺 sku / createTime 时跳过该行而非整页失败 验证:mvn test 全量通过,恒健 203 个用例(+23)通过。 Co-Authored-By: Claude Code <noreply@anthropic.com>master
15 changed files with 1759 additions and 14 deletions
@ -0,0 +1,277 @@
@@ -0,0 +1,277 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
|
||||
import java.time.Instant; |
||||
|
||||
/** |
||||
* 一条库存变动流水(入库 / 出库 / 退货 / 调拨 / 调整)。 |
||||
* |
||||
* <p><b>这是流水,不是余额</b>:{@link #changeQuantity()} 是单笔变动量, |
||||
* 按仓方原值返回、<b>不转正负号</b>(方向看 {@link #changeType()}), |
||||
* 也不代表当前库存。当前库存用 {@link InventorySnapshot}。</p> |
||||
* |
||||
* <p>流水是按<b>业务单据</b>产生的,所以带一堆单号: |
||||
* {@link #planOrderNo()} / {@link #sourceNo()} / {@link #executeOrderNo()} / |
||||
* {@link #platformOrderNo()} / {@link #saleOrderNo()} / {@link #poNumber()}。 |
||||
* 各仓填哪几个不一样,未填的为 null。</p> |
||||
*/ |
||||
public final class InventoryMovement { |
||||
|
||||
private final WarehouseProvider sourceProvider; |
||||
private final String warehouseCode; |
||||
private final String providerSku; |
||||
/** 卖家 / 店铺侧 SKU;仓方未给为 null。 */ |
||||
private final String sellerSku; |
||||
/** 商品名;仓方未给为 null。 */ |
||||
private final String productName; |
||||
/** 库存类型:0 可售 / 1 不可售;null 表示仓方未给。 */ |
||||
private final Integer inventoryType; |
||||
|
||||
/** 单据类型,<b>仓方原值</b>(如「采购入库」「销售出库」);不归一,跨仓口径不同。 */ |
||||
private final String documentType; |
||||
/** 变动方向,<b>仓方原值</b>(如「入库」「出库」)。 */ |
||||
private final String changeType; |
||||
/** 单笔变动量(正数,方向看 {@link #changeType()})。 */ |
||||
private final int changeQuantity; |
||||
/** 调整原因;非调整类流水为 null。 */ |
||||
private final String adjustReason; |
||||
|
||||
private final String planOrderNo; |
||||
private final String sourceNo; |
||||
private final String executeOrderNo; |
||||
private final String platformOrderNo; |
||||
private final String saleOrderNo; |
||||
private final String poNumber; |
||||
|
||||
/** 流水创建时间(UTC)。 */ |
||||
private final Instant createdAt; |
||||
/** 业务操作时间(UTC);仓方未给为 null。 */ |
||||
private final Instant businessAt; |
||||
|
||||
private InventoryMovement(Builder b) { |
||||
this.sourceProvider = b.sourceProvider; |
||||
this.warehouseCode = require(b.warehouseCode, "warehouseCode"); |
||||
this.providerSku = require(b.providerSku, "providerSku"); |
||||
this.sellerSku = b.sellerSku; |
||||
this.productName = b.productName; |
||||
this.inventoryType = b.inventoryType; |
||||
this.documentType = b.documentType; |
||||
this.changeType = b.changeType; |
||||
this.changeQuantity = b.changeQuantity; |
||||
this.adjustReason = b.adjustReason; |
||||
this.planOrderNo = b.planOrderNo; |
||||
this.sourceNo = b.sourceNo; |
||||
this.executeOrderNo = b.executeOrderNo; |
||||
this.platformOrderNo = b.platformOrderNo; |
||||
this.saleOrderNo = b.saleOrderNo; |
||||
this.poNumber = b.poNumber; |
||||
this.createdAt = java.util.Objects.requireNonNull(b.createdAt, "createdAt"); |
||||
this.businessAt = b.businessAt; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
public WarehouseProvider sourceProvider() { |
||||
return sourceProvider; |
||||
} |
||||
|
||||
public String warehouseCode() { |
||||
return warehouseCode; |
||||
} |
||||
|
||||
public String providerSku() { |
||||
return providerSku; |
||||
} |
||||
|
||||
public String sellerSku() { |
||||
return sellerSku; |
||||
} |
||||
|
||||
public String productName() { |
||||
return productName; |
||||
} |
||||
|
||||
/** 库存类型:0 可售 / 1 不可售;null 表示仓方未给。 */ |
||||
public Integer inventoryType() { |
||||
return inventoryType; |
||||
} |
||||
|
||||
/** 单据类型原值。 */ |
||||
public String documentType() { |
||||
return documentType; |
||||
} |
||||
|
||||
/** 变动方向原值(入库 / 出库)。 */ |
||||
public String changeType() { |
||||
return changeType; |
||||
} |
||||
|
||||
/** 单笔变动量;方向看 {@link #changeType()}。 */ |
||||
public int changeQuantity() { |
||||
return changeQuantity; |
||||
} |
||||
|
||||
public String adjustReason() { |
||||
return adjustReason; |
||||
} |
||||
|
||||
public String planOrderNo() { |
||||
return planOrderNo; |
||||
} |
||||
|
||||
public String sourceNo() { |
||||
return sourceNo; |
||||
} |
||||
|
||||
public String executeOrderNo() { |
||||
return executeOrderNo; |
||||
} |
||||
|
||||
public String platformOrderNo() { |
||||
return platformOrderNo; |
||||
} |
||||
|
||||
public String saleOrderNo() { |
||||
return saleOrderNo; |
||||
} |
||||
|
||||
public String poNumber() { |
||||
return poNumber; |
||||
} |
||||
|
||||
public Instant createdAt() { |
||||
return createdAt; |
||||
} |
||||
|
||||
public Instant businessAt() { |
||||
return businessAt; |
||||
} |
||||
|
||||
private static String require(String v, String name) { |
||||
if (v == null || v.trim().isEmpty()) { |
||||
throw new IllegalArgumentException(name + " must not be blank"); |
||||
} |
||||
return v.trim(); |
||||
} |
||||
|
||||
public static final class Builder { |
||||
private WarehouseProvider sourceProvider; |
||||
private String warehouseCode; |
||||
private String providerSku; |
||||
private String sellerSku; |
||||
private String productName; |
||||
private Integer inventoryType; |
||||
private String documentType; |
||||
private String changeType; |
||||
private int changeQuantity; |
||||
private String adjustReason; |
||||
private String planOrderNo; |
||||
private String sourceNo; |
||||
private String executeOrderNo; |
||||
private String platformOrderNo; |
||||
private String saleOrderNo; |
||||
private String poNumber; |
||||
private Instant createdAt; |
||||
private Instant businessAt; |
||||
|
||||
public Builder sourceProvider(WarehouseProvider v) { |
||||
this.sourceProvider = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder warehouseCode(String v) { |
||||
this.warehouseCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder providerSku(String v) { |
||||
this.providerSku = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder sellerSku(String v) { |
||||
this.sellerSku = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder productName(String v) { |
||||
this.productName = v; |
||||
return this; |
||||
} |
||||
|
||||
/** 库存类型:0 可售 / 1 不可售;null 表示仓方未给。 */ |
||||
public Builder inventoryType(Integer v) { |
||||
this.inventoryType = v; |
||||
return this; |
||||
} |
||||
|
||||
/** 单据类型原值。 */ |
||||
public Builder documentType(String v) { |
||||
this.documentType = v; |
||||
return this; |
||||
} |
||||
|
||||
/** 变动方向原值。 */ |
||||
public Builder changeType(String v) { |
||||
this.changeType = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder changeQuantity(int v) { |
||||
this.changeQuantity = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder adjustReason(String v) { |
||||
this.adjustReason = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder planOrderNo(String v) { |
||||
this.planOrderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder sourceNo(String v) { |
||||
this.sourceNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder executeOrderNo(String v) { |
||||
this.executeOrderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder platformOrderNo(String v) { |
||||
this.platformOrderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder saleOrderNo(String v) { |
||||
this.saleOrderNo = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder poNumber(String v) { |
||||
this.poNumber = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder createdAt(Instant v) { |
||||
this.createdAt = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder businessAt(Instant v) { |
||||
this.businessAt = v; |
||||
return this; |
||||
} |
||||
|
||||
public InventoryMovement build() { |
||||
return new InventoryMovement(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,148 @@
@@ -0,0 +1,148 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import java.time.LocalDate; |
||||
import java.util.ArrayList; |
||||
import java.util.Collections; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 库存变动流水查询条件。 |
||||
* |
||||
* <p>与 {@link InventoryQuery} 的区别:那个查<b>当前库存余额</b>,这个查<b>流水</b> |
||||
* (每条是一次入库 / 出库 / 调整)。流水必须限定日期区间——不限定会拉到全部历史。</p> |
||||
* |
||||
* <p>各仓约束不同(恒健要求 SKU + 日期区间都必填、区间 ≤ 30 天), |
||||
* 由适配器在拼请求时按自己的协议校验。</p> |
||||
*/ |
||||
public final class InventoryMovementQuery { |
||||
|
||||
private final List<String> providerSkus; |
||||
private final List<String> warehouseCodes; |
||||
/** 日期区间起点(含当天,UTC 流水创建时间)。 */ |
||||
private final LocalDate startDate; |
||||
/** 日期区间终点(含当天)。 */ |
||||
private final LocalDate endDate; |
||||
private final int pageSize; |
||||
private final String cursor; |
||||
|
||||
private InventoryMovementQuery(Builder b) { |
||||
if (b.startDate == null || b.endDate == null) { |
||||
throw new IllegalArgumentException("startDate and endDate are required"); |
||||
} |
||||
if (b.endDate.isBefore(b.startDate)) { |
||||
throw new IllegalArgumentException("endDate must not be earlier than startDate"); |
||||
} |
||||
this.providerSkus = Collections.unmodifiableList(new ArrayList<String>(b.providerSkus)); |
||||
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(b.warehouseCodes)); |
||||
this.startDate = b.startDate; |
||||
this.endDate = b.endDate; |
||||
this.pageSize = b.pageSize; |
||||
this.cursor = b.cursor; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
/** 产品 SKU 列表;不可变。 */ |
||||
public List<String> providerSkus() { |
||||
return providerSkus; |
||||
} |
||||
|
||||
/** 仓 code 列表;空表示用账户配置的仓(按仓支持的仓)。 */ |
||||
public List<String> warehouseCodes() { |
||||
return warehouseCodes; |
||||
} |
||||
|
||||
/** 日期区间起点(含当天)。 */ |
||||
public LocalDate startDate() { |
||||
return startDate; |
||||
} |
||||
|
||||
/** 日期区间终点(含当天)。 */ |
||||
public LocalDate endDate() { |
||||
return endDate; |
||||
} |
||||
|
||||
public int pageSize() { |
||||
return pageSize; |
||||
} |
||||
|
||||
/** 分页游标;null 表示第一页。 */ |
||||
public String cursor() { |
||||
return cursor; |
||||
} |
||||
|
||||
/** 翻页时只改游标。 */ |
||||
public Builder toBuilder() { |
||||
return builder() |
||||
.skus(providerSkus) |
||||
.warehouseCodes(warehouseCodes) |
||||
.dateRange(startDate, endDate) |
||||
.pageSize(pageSize) |
||||
.cursor(cursor); |
||||
} |
||||
|
||||
public static final class Builder { |
||||
|
||||
private final List<String> providerSkus = new ArrayList<String>(); |
||||
private final List<String> warehouseCodes = new ArrayList<String>(); |
||||
private LocalDate startDate; |
||||
private LocalDate endDate; |
||||
private int pageSize = 100; |
||||
private String cursor; |
||||
|
||||
public Builder sku(String v) { |
||||
if (v != null && !v.trim().isEmpty()) { |
||||
this.providerSkus.add(v.trim()); |
||||
} |
||||
return this; |
||||
} |
||||
|
||||
public Builder skus(List<String> v) { |
||||
if (v != null) { |
||||
for (String one : v) { |
||||
sku(one); |
||||
} |
||||
} |
||||
return this; |
||||
} |
||||
|
||||
public Builder warehouseCode(String v) { |
||||
if (v != null && !v.trim().isEmpty()) { |
||||
this.warehouseCodes.add(v.trim()); |
||||
} |
||||
return this; |
||||
} |
||||
|
||||
public Builder warehouseCodes(List<String> v) { |
||||
if (v != null) { |
||||
for (String one : v) { |
||||
warehouseCode(one); |
||||
} |
||||
} |
||||
return this; |
||||
} |
||||
|
||||
/** 日期区间;两端都必填。 */ |
||||
public Builder dateRange(LocalDate start, LocalDate end) { |
||||
this.startDate = start; |
||||
this.endDate = end; |
||||
return this; |
||||
} |
||||
|
||||
public Builder pageSize(int v) { |
||||
this.pageSize = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder cursor(String v) { |
||||
this.cursor = v; |
||||
return this; |
||||
} |
||||
|
||||
public InventoryMovementQuery build() { |
||||
return new InventoryMovementQuery(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,366 @@
@@ -0,0 +1,366 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import com.fasterxml.jackson.databind.JsonNode; |
||||
import common.ecommerce.hengjian.HengjianConstants; |
||||
import common.ecommerce.hengjian.dto.HengjianInventoryDtos; |
||||
import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; |
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
import common.ecommerce.shared.support.Page; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.InventoryMovement; |
||||
import common.ecommerce.warehouse.model.InventoryMovementQuery; |
||||
import common.ecommerce.warehouse.model.InventoryQuery; |
||||
import common.ecommerce.warehouse.model.InventorySnapshot; |
||||
|
||||
import java.math.BigDecimal; |
||||
import java.time.Instant; |
||||
import java.time.LocalDate; |
||||
import java.time.LocalDateTime; |
||||
import java.time.ZoneOffset; |
||||
import java.time.format.DateTimeFormatter; |
||||
import java.time.format.DateTimeParseException; |
||||
import java.time.temporal.ChronoUnit; |
||||
import java.util.ArrayList; |
||||
import java.util.LinkedHashMap; |
||||
import java.util.List; |
||||
import java.util.Map; |
||||
|
||||
/** |
||||
* 恒健库存报文映射(库存查询 / 批量分页 / 变动流水)。 |
||||
* |
||||
* <h2>两个库存接口的差异</h2> |
||||
* <table border="1"> |
||||
* <tr><th></th><th>{@code getInventory}</th><th>{@code get_inventory_by_page}</th></tr> |
||||
* <tr><td>方法</td><td>POST</td><td>GET</td></tr> |
||||
* <tr><td>过滤</td><td>只按 SKU</td><td>只按仓({@code warehouseCodes} 必填)</td></tr> |
||||
* <tr><td>分页</td><td>不分页</td><td>分页,rows 上限 500</td></tr> |
||||
* </table> |
||||
* <p>统一模型是一个 {@code query()},所以:<b>给了 SKU 走按 SKU 查(无分页); |
||||
* 只给仓走分页查</b>。两条路都给的场景(按仓 + SKU 过滤)恒健没有对应接口, |
||||
* 本地拒绝而不是静默丢掉一个条件。</p> |
||||
* |
||||
* <h2>响应形状</h2> |
||||
* <p>分页接口的文档字段表说 {@code data} 是对象,返回示例却是数组; |
||||
* 这里用 JsonNode 判形状后分流,两种都接住。</p> |
||||
*/ |
||||
public final class HengjianInventoryMapper { |
||||
|
||||
/** 时间格式(文档未标时区,按 UTC 解析,与订单接口同口径假设)。 */ |
||||
private static final DateTimeFormatter TIME_FORMAT = |
||||
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
||||
|
||||
private HengjianInventoryMapper() { |
||||
} |
||||
|
||||
// ================================================================ 库存查询
|
||||
|
||||
/** 按 SKU 查库存的请求;SKU 必填。 */ |
||||
public static HengjianInventoryDtos.QueryBySkuRequest toBySkuRequest(InventoryQuery query) { |
||||
List<String> skus = query.providerSkus(); |
||||
if (skus.isEmpty()) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory-by-sku query requires at least one sku"); |
||||
} |
||||
HengjianInventoryDtos.QueryBySkuRequest req = new HengjianInventoryDtos.QueryBySkuRequest(); |
||||
req.skus = new ArrayList<String>(skus); |
||||
return req; |
||||
} |
||||
|
||||
/** |
||||
* 批量查库存的 GET 参数。 |
||||
* |
||||
* <p>{@code warehouseCodes} 真机必填:调用方指定优先,否则用账户仓; |
||||
* 都没有就拒绝,避免把整个租户的库存拉下来。</p> |
||||
* |
||||
* @throws IllegalArgumentException 没有仓 code |
||||
*/ |
||||
public static Map<String, List<String>> toPageParams(InventoryQuery query, |
||||
String defaultWarehouseCode) { |
||||
List<String> codes = query.warehouseCodes(); |
||||
if (codes.isEmpty() && defaultWarehouseCode != null && !defaultWarehouseCode.trim().isEmpty()) { |
||||
codes = java.util.Collections.singletonList(defaultWarehouseCode.trim()); |
||||
} |
||||
if (codes.isEmpty()) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory page query requires warehouseCodes; " |
||||
+ "none given and account has none"); |
||||
} |
||||
Map<String, List<String>> params = new LinkedHashMap<String, List<String>>(); |
||||
params.put("warehouseCodes", new ArrayList<String>(codes)); |
||||
params.put("page", java.util.Collections.singletonList(String.valueOf(pageOf(query.cursor())))); |
||||
params.put("rows", java.util.Collections.singletonList(String.valueOf(rowsOf(query.pageSize())))); |
||||
params.put("sidx", java.util.Collections.singletonList(HengjianConstants.ORDER_LIST_DEFAULT_SIDX)); |
||||
params.put("sort", java.util.Collections.singletonList(HengjianConstants.ORDER_LIST_DEFAULT_SORT)); |
||||
return params; |
||||
} |
||||
|
||||
/** 页码:游标是字符串化页码,空游标表示第 1 页(入参 1 基)。 */ |
||||
static int pageOf(String cursor) { |
||||
String v = trimToNull(cursor); |
||||
if (v == null) { |
||||
return 1; |
||||
} |
||||
try { |
||||
int page = Integer.parseInt(v); |
||||
return page < 1 ? 1 : page; |
||||
} catch (NumberFormatException e) { |
||||
throw new IllegalArgumentException("hengjian inventory cursor must be a page number, got " + v); |
||||
} |
||||
} |
||||
|
||||
/** 页大小:未指定用默认;超过文档明写的 500 时拒绝(不静默截断)。 */ |
||||
static int rowsOf(int requested) { |
||||
if (requested <= 0) { |
||||
return HengjianConstants.INVENTORY_PAGE_ROWS_DEFAULT; |
||||
} |
||||
if (requested > HengjianConstants.INVENTORY_PAGE_ROWS_MAX) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory page rows must not exceed " |
||||
+ HengjianConstants.INVENTORY_PAGE_ROWS_MAX + ", got " + requested); |
||||
} |
||||
return requested; |
||||
} |
||||
|
||||
/** 行 → 统一快照。 */ |
||||
public static InventorySnapshot toSnapshot(HengjianInventoryDtos.InventoryRow row, |
||||
String fallbackWarehouseCode) { |
||||
String warehouseCode = trimToNull(row.warehouseCode); |
||||
String sku = trimToNull(row.sku); |
||||
if (sku == null) { |
||||
throw new IllegalArgumentException("hengjian inventory row has no sku"); |
||||
} |
||||
Instant asOf = parseTime(row.updatedAt); |
||||
if (asOf == null) { |
||||
// 快照时间必须能对齐;仓方没给就拒绝,而不是填 EPOCH 让对账误判
|
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory row for sku " + sku + " has no updatedAt"); |
||||
} |
||||
return InventorySnapshot.builder() |
||||
.warehouseCode(warehouseCode == null ? fallbackWarehouseCode : warehouseCode) |
||||
.providerSku(sku) |
||||
.available(intOfNumber(row.inventoryAvailable)) |
||||
.reserved(intOfNumber(row.inventoryReserved)) |
||||
.inTransit(intOfText(row.inventoryTransport)) |
||||
.onHand(intOfText(row.inventoryCurrent)) |
||||
.inventoryType(row.inventoryType == null ? 0 : row.inventoryType) |
||||
.asOfUtc(asOf) |
||||
.productName(trimToNull(row.lineName)) |
||||
.build(); |
||||
} |
||||
|
||||
/** 解析分页响应:{@code data} 可能是对象(有 content)也可能是数组。 */ |
||||
public static Page<InventorySnapshot> toPage(JsonNode data, String fallbackWarehouseCode, |
||||
int requestedRows, JacksonJsonCodec json) { |
||||
if (data == null || data.isNull() || data.isMissingNode()) { |
||||
return Page.last(new ArrayList<InventorySnapshot>()); |
||||
} |
||||
List<HengjianInventoryDtos.InventoryRow> rows = new ArrayList<HengjianInventoryDtos.InventoryRow>(); |
||||
boolean last; |
||||
Integer pageNumber = null; |
||||
if (data.isArray()) { |
||||
// 文档示例的形状:data 直接是数组(没有分页信息,按末页处理)
|
||||
for (JsonNode node : data) { |
||||
rows.add(convert(node, json)); |
||||
} |
||||
last = true; |
||||
} else { |
||||
JsonNode content = data.get("content"); |
||||
if (content != null && content.isArray()) { |
||||
for (JsonNode node : content) { |
||||
rows.add(convert(node, json)); |
||||
} |
||||
} |
||||
JsonNode lastNode = data.get("last"); |
||||
JsonNode numberNode = data.get("number"); |
||||
pageNumber = numberNode == null || numberNode.isNull() ? null : numberNode.asInt(); |
||||
last = lastNode == null || lastNode.isNull() |
||||
? rows.size() < requestedRows |
||||
: lastNode.asBoolean(); |
||||
} |
||||
List<InventorySnapshot> out = new ArrayList<InventorySnapshot>(rows.size()); |
||||
for (HengjianInventoryDtos.InventoryRow row : rows) { |
||||
if (row != null) { |
||||
out.add(toSnapshot(row, fallbackWarehouseCode)); |
||||
} |
||||
} |
||||
if (last) { |
||||
return Page.last(out); |
||||
} |
||||
// 响应 number 是 0 基,而请求的 page 是 1 基:当前第 number 页(0 基)
|
||||
// 对应请求的 page = number+1,所以下一页的请求值 = number+2
|
||||
int next = (pageNumber == null ? 0 : pageNumber) + 2; |
||||
return Page.of(out, String.valueOf(next)); |
||||
} |
||||
|
||||
/** 非分页接口:{@code data} 是数组。 */ |
||||
public static List<InventorySnapshot> toSnapshots(List<HengjianInventoryDtos.InventoryRow> rows, |
||||
String fallbackWarehouseCode) { |
||||
List<InventorySnapshot> out = new ArrayList<InventorySnapshot>(); |
||||
if (rows == null) { |
||||
return out; |
||||
} |
||||
for (HengjianInventoryDtos.InventoryRow row : rows) { |
||||
if (row != null) { |
||||
out.add(toSnapshot(row, fallbackWarehouseCode)); |
||||
} |
||||
} |
||||
return out; |
||||
} |
||||
|
||||
// ================================================================ 变动流水
|
||||
|
||||
/** |
||||
* 统一流水条件 → 恒健请求。 |
||||
* |
||||
* @throws IllegalArgumentException SKU 为空,或日期跨度超 30 天 |
||||
*/ |
||||
public static HengjianInventoryMovementDtos.QueryRequest toMovementRequest( |
||||
InventoryMovementQuery query) { |
||||
if (query.providerSkus().isEmpty()) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory movements require at least one sku"); |
||||
} |
||||
// 文档/真机口径是「最多包含 30 个自然日」,起止都含:
|
||||
// 10-01~10-30 合法(30 天),10-01~10-31 不合法(31 天)
|
||||
long inclusiveDays = ChronoUnit.DAYS.between(query.startDate(), query.endDate()) + 1; |
||||
if (inclusiveDays > HengjianConstants.INVENTORY_MOVEMENT_MAX_DAYS) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory movements window must not exceed " |
||||
+ HengjianConstants.INVENTORY_MOVEMENT_MAX_DAYS |
||||
+ " calendar days (inclusive), got " + inclusiveDays); |
||||
} |
||||
HengjianInventoryMovementDtos.QueryRequest req = |
||||
new HengjianInventoryMovementDtos.QueryRequest(); |
||||
req.skus = new ArrayList<String>(query.providerSkus()); |
||||
req.page = pageOf(query.cursor()); |
||||
req.rows = movementRowsOf(query.pageSize()); |
||||
req.beginDateTime = query.startDate().toString(); |
||||
req.endDateTime = query.endDate().toString(); |
||||
return req; |
||||
} |
||||
|
||||
/** 流水页大小:文档 1~100;超过即拒绝。 */ |
||||
static int movementRowsOf(int requested) { |
||||
if (requested <= 0) { |
||||
return HengjianConstants.INVENTORY_MOVEMENT_ROWS_MAX; |
||||
} |
||||
if (requested > HengjianConstants.INVENTORY_MOVEMENT_ROWS_MAX) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory movements rows must not exceed " |
||||
+ HengjianConstants.INVENTORY_MOVEMENT_ROWS_MAX + ", got " + requested); |
||||
} |
||||
return requested; |
||||
} |
||||
|
||||
/** 流水行 → 统一模型。 */ |
||||
public static InventoryMovement toMovement(HengjianInventoryMovementDtos.MovementRow row, |
||||
String fallbackWarehouseCode) { |
||||
String warehouseCode = trimToNull(row.warehouseCode); |
||||
String sku = trimToNull(row.sku); |
||||
if (sku == null) { |
||||
throw new IllegalArgumentException("hengjian inventory movement has no sku"); |
||||
} |
||||
Instant createdAt = parseTime(row.createTime); |
||||
if (createdAt == null) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian inventory movement for sku " + sku + " has no createTime"); |
||||
} |
||||
return InventoryMovement.builder() |
||||
.sourceProvider(WarehouseProvider.HENGJIAN) |
||||
.warehouseCode(warehouseCode == null ? fallbackWarehouseCode : warehouseCode) |
||||
.providerSku(sku) |
||||
.sellerSku(trimToNull(row.sellerSku)) |
||||
.productName(trimToNull(row.lineName)) |
||||
.inventoryType(row.inventoryType) |
||||
.documentType(trimToNull(row.documentType)) |
||||
.changeType(trimToNull(row.inventoryChangeType)) |
||||
.changeQuantity(row.changeQty == null ? 0 : row.changeQty) |
||||
.adjustReason(trimToNull(row.adjustReason)) |
||||
.planOrderNo(trimToNull(row.planOrderNo)) |
||||
.sourceNo(trimToNull(row.sourceNo)) |
||||
.executeOrderNo(trimToNull(row.executeOrderNo)) |
||||
.platformOrderNo(trimToNull(row.platformOrderNo)) |
||||
.saleOrderNo(trimToNull(row.saleOrderNo)) |
||||
.poNumber(trimToNull(row.poNumber)) |
||||
.createdAt(createdAt) |
||||
.businessAt(parseTime(row.businessTime)) |
||||
.build(); |
||||
} |
||||
|
||||
/** 流水分页 → 统一 Page。 */ |
||||
public static Page<InventoryMovement> toMovementPage(HengjianInventoryMovementDtos.PageData data, |
||||
String fallbackWarehouseCode, |
||||
int requestedRows, String cursor) { |
||||
if (data == null) { |
||||
return Page.last(new ArrayList<InventoryMovement>()); |
||||
} |
||||
List<InventoryMovement> out = new ArrayList<InventoryMovement>(); |
||||
if (data.content != null) { |
||||
for (HengjianInventoryMovementDtos.MovementRow row : data.content) { |
||||
if (row == null) { |
||||
continue; |
||||
} |
||||
// 单行数据不完整(缺 sku / createTime)时跳过而不是整页失败:
|
||||
// 流水是明细,跳过一行比拿不到整页更有用。缺的行数由调用方对账发现。
|
||||
try { |
||||
out.add(toMovement(row, fallbackWarehouseCode)); |
||||
} catch (IllegalArgumentException ignored) { |
||||
// skip
|
||||
} |
||||
} |
||||
} |
||||
boolean last = data.last != null ? data.last |
||||
: (data.content == null || data.content.size() < requestedRows); |
||||
// 有下一页时给出页码游标,否则 Page.of(..., null) 会被当成末页
|
||||
return last ? Page.last(out) |
||||
: Page.of(out, String.valueOf(pageOf(cursor) + 1)); |
||||
} |
||||
|
||||
// ================================================================ 工具
|
||||
|
||||
/** JsonNode → 行模型;{@code @JsonAlias} 会同时接 snake_case 与 camelCase。 */ |
||||
static HengjianInventoryDtos.InventoryRow convert(JsonNode node, JacksonJsonCodec json) { |
||||
return json.mapper().convertValue(node, HengjianInventoryDtos.InventoryRow.class); |
||||
} |
||||
|
||||
static Instant parseTime(String value) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
try { |
||||
return LocalDateTime.parse(v, TIME_FORMAT).toInstant(ZoneOffset.UTC); |
||||
} catch (DateTimeParseException e) { |
||||
try { |
||||
return Instant.parse(v); |
||||
} catch (DateTimeParseException ignored) { |
||||
return null; |
||||
} |
||||
} |
||||
} |
||||
|
||||
/** 数量:文档有的字段标 STRING,有的标 INTEGER;统一按文本转。 */ |
||||
static int intOfText(String value) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
return 0; |
||||
} |
||||
try { |
||||
return new BigDecimal(v).intValue(); |
||||
} catch (NumberFormatException e) { |
||||
return 0; |
||||
} |
||||
} |
||||
|
||||
static int intOfNumber(Integer value) { |
||||
return value == null ? 0 : value; |
||||
} |
||||
|
||||
private static String trimToNull(String v) { |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
String t = v.trim(); |
||||
return t.isEmpty() ? null : t; |
||||
} |
||||
} |
||||
@ -0,0 +1,124 @@
@@ -0,0 +1,124 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonAlias; |
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:库存查询(两个接口共用行模型)。 |
||||
* |
||||
* <p><b>两个接口的字段命名不一致,且文档与示例互相矛盾</b>(真机/文档双向核对):</p> |
||||
* <ul> |
||||
* <li>{@code /v1/inventory/getInventory}:请求 {@code {skus:[...]}},<b>不分页</b>; |
||||
* 行是 camelCase({@code warehouseCode} / {@code inventoryAvailable})。</li> |
||||
* <li>{@code /v2/inventory/get_inventory_by_page}:GET,<b>分页</b>; |
||||
* 字段表写 snake_case({@code warehouse_code} / {@code inventory_available}), |
||||
* 但同一页的返回示例又是 camelCase。</li> |
||||
* </ul> |
||||
* <p>因此行字段用 {@link JsonAlias} 同时接两种写法——不多花钱,却能防一次真机翻车。</p> |
||||
* |
||||
* <p><b>{@code data} 的形状两个接口也不一致</b>:分页接口的字段表说 {@code data} 是对象 |
||||
* (含 {@code content} / {@code totalElements}),返回示例却是数组。 |
||||
* 适配器用 JsonNode 判形状后分流,见 {@code HengjianInventoryMapper}。</p> |
||||
*/ |
||||
public final class HengjianInventoryDtos { |
||||
|
||||
private HengjianInventoryDtos() { |
||||
} |
||||
|
||||
/** 按 SKU 查询的请求。 */ |
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class QueryBySkuRequest { |
||||
|
||||
/** 产品 SKU 列表;真机确认必填且不能为空数组。 */ |
||||
public List<String> skus; |
||||
} |
||||
|
||||
/** 一个库存行(两个接口共用)。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class InventoryRow { |
||||
|
||||
/** 仓库 code。 */ |
||||
@JsonProperty("warehouseCode") |
||||
@JsonAlias("warehouse_code") |
||||
public String warehouseCode; |
||||
|
||||
/** 项目名称。 */ |
||||
@JsonProperty("lineName") |
||||
@JsonAlias("line_name") |
||||
public String lineName; |
||||
|
||||
/** 产品 SKU。 */ |
||||
@JsonProperty("sku") |
||||
public String sku; |
||||
|
||||
/** 库存类型:0 可售 / 1 不可售。 */ |
||||
@JsonProperty("inventoryType") |
||||
@JsonAlias("inventory_type") |
||||
public Integer inventoryType; |
||||
|
||||
/** 可用库存。 */ |
||||
@JsonProperty("inventoryAvailable") |
||||
@JsonAlias("inventory_available") |
||||
public Integer inventoryAvailable; |
||||
|
||||
/** 预留库存。 */ |
||||
@JsonProperty("inventoryReserved") |
||||
@JsonAlias("inventory_reserved") |
||||
public Integer inventoryReserved; |
||||
|
||||
/** |
||||
* 在途库存。 |
||||
* |
||||
* <p>文档标 STRING、示例给数字;用 String 接住,解析时再转 int。</p> |
||||
*/ |
||||
@JsonProperty("inventoryTransport") |
||||
@JsonAlias("inventory_transport") |
||||
public String inventoryTransport; |
||||
|
||||
/** 当前总库存;同样按 String 接。 */ |
||||
@JsonProperty("inventoryCurrent") |
||||
@JsonAlias("inventory_current") |
||||
public String inventoryCurrent; |
||||
|
||||
/** |
||||
* 最近更新时间。 |
||||
* |
||||
* <p>文档没写时区。示例形如 {@code 2017-03-24 02:19:56}。按 UTC 解析, |
||||
* 待真机确认(与订单时间同口径假设)。</p> |
||||
*/ |
||||
@JsonProperty("updatedAt") |
||||
@JsonAlias("updated_at") |
||||
public String updatedAt; |
||||
} |
||||
|
||||
/** 分页信封。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PageData { |
||||
|
||||
@JsonProperty("content") |
||||
public List<InventoryRow> content; |
||||
|
||||
@JsonProperty("totalElements") |
||||
public Integer totalElements; |
||||
|
||||
@JsonProperty("totalPages") |
||||
public Integer totalPages; |
||||
|
||||
/** 当前页码,<b>0 基</b>(与订单列表同口径)。 */ |
||||
@JsonProperty("number") |
||||
public Integer number; |
||||
|
||||
@JsonProperty("size") |
||||
public Integer size; |
||||
|
||||
@JsonProperty("last") |
||||
public Boolean last; |
||||
|
||||
@JsonProperty("numberOfElements") |
||||
public Integer numberOfElements; |
||||
} |
||||
} |
||||
@ -0,0 +1,189 @@
@@ -0,0 +1,189 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:库存变动明细查询({@code POST /v1/inventory/task/query})。 |
||||
* |
||||
* <p><b>真机确认的必填项</b>:{@code skus}(非空数组)、{@code beginDateTime}、 |
||||
* {@code endDateTime}({@code yyyy-MM-dd})。缺任一项回 |
||||
* {@code MethodArgumentNotValidException} 并列出所有缺的字段。</p> |
||||
* |
||||
* <p><b>真机确认的约束</b>:日期范围最多 30 个自然日,超了回 |
||||
* {@code 查询日期最多包含30个自然日}。</p> |
||||
* |
||||
* <p>这是<b>流水</b>,不是库存余额:{@code changeQty} 是单笔变动量, |
||||
* 按原值返回、不转正负号,也不代表当前库存。</p> |
||||
*/ |
||||
public final class HengjianInventoryMovementDtos { |
||||
|
||||
private HengjianInventoryMovementDtos() { |
||||
} |
||||
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class QueryRequest { |
||||
|
||||
/** 产品 SKU 列表;必填,元素不能为 null / 空串 / 纯空格。 */ |
||||
public List<String> skus; |
||||
|
||||
/** 页码,从 1 开始;不传默认 1。 */ |
||||
public Integer page; |
||||
|
||||
/** 每页条数,1~100;不传默认 10。 */ |
||||
public Integer rows; |
||||
|
||||
/** 开始日期 {@code yyyy-MM-dd}(UTC 流水创建时间,含当天);必填。 */ |
||||
public String beginDateTime; |
||||
|
||||
/** 结束日期 {@code yyyy-MM-dd}(含当天);必填,不能早于开始日期。 */ |
||||
public String endDateTime; |
||||
} |
||||
|
||||
/** 响应外层。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class QueryResponse { |
||||
|
||||
@JsonProperty("status") |
||||
public Integer status; |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public PageData data; |
||||
} |
||||
|
||||
/** 分页数据。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PageData { |
||||
|
||||
@JsonProperty("content") |
||||
public List<MovementRow> content; |
||||
|
||||
@JsonProperty("totalElements") |
||||
public Integer totalElements; |
||||
|
||||
@JsonProperty("totalPages") |
||||
public Integer totalPages; |
||||
|
||||
@JsonProperty("size") |
||||
public Integer size; |
||||
|
||||
@JsonProperty("first") |
||||
public Boolean first; |
||||
|
||||
@JsonProperty("last") |
||||
public Boolean last; |
||||
} |
||||
|
||||
/** 一条库存流水。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class MovementRow { |
||||
|
||||
/** 仓库编码。 */ |
||||
@JsonProperty("warehouseCode") |
||||
public String warehouseCode; |
||||
|
||||
/** 项目名称。 */ |
||||
@JsonProperty("lineName") |
||||
public String lineName; |
||||
|
||||
/** 流水保存的渠道值。 */ |
||||
@JsonProperty("channel") |
||||
public String channel; |
||||
|
||||
/** 产品 SKU。 */ |
||||
@JsonProperty("sku") |
||||
public String sku; |
||||
|
||||
/** 卖家 SKU。 */ |
||||
@JsonProperty("sellerSku") |
||||
public String sellerSku; |
||||
|
||||
/** 产品类型:1 成品 / 2 配件 / 3 耗材。 */ |
||||
@JsonProperty("productType") |
||||
public Integer productType; |
||||
|
||||
/** 卖家 SKU 类型:简单产品 / 打包产品;无对应类型时为空。 */ |
||||
@JsonProperty("sellerSkuProductType") |
||||
public String sellerSkuProductType; |
||||
|
||||
/** 库存类型:0 可售 / 1 不可售。 */ |
||||
@JsonProperty("inventoryType") |
||||
public Integer inventoryType; |
||||
|
||||
/** 流水保存的计划编号;销售出库场景可能是销售订单内部 ID。 */ |
||||
@JsonProperty("planOrderNo") |
||||
public String planOrderNo; |
||||
|
||||
/** 流水保存的来源编号;可能是业务单号或组合编号。 */ |
||||
@JsonProperty("sourceNo") |
||||
public String sourceNo; |
||||
|
||||
/** 流水保存的执行单号。 */ |
||||
@JsonProperty("executeOrderNo") |
||||
public String executeOrderNo; |
||||
|
||||
/** 平台订单号;未关联到时为空。 */ |
||||
@JsonProperty("platformOrderNo") |
||||
public String platformOrderNo; |
||||
|
||||
/** 流水保存的销售 / 渠道订单号;与 {@link #platformOrderNo} 分别返回。 */ |
||||
@JsonProperty("saleOrderNo") |
||||
public String saleOrderNo; |
||||
|
||||
/** PO Number。 */ |
||||
@JsonProperty("poNumber") |
||||
public String poNumber; |
||||
|
||||
/** 单据类型中文描述,如采购入库 / 销售出库 / 调拨入库 / 库存调整出库。 */ |
||||
@JsonProperty("documentType") |
||||
public String documentType; |
||||
|
||||
/** 调整原因。 */ |
||||
@JsonProperty("adjustReason") |
||||
public String adjustReason; |
||||
|
||||
/** 库存变动方向:入库 / 出库。 */ |
||||
@JsonProperty("inventoryChangeType") |
||||
public String inventoryChangeType; |
||||
|
||||
/** 单笔流水数量;按原值返回,<b>不转正负号</b>,不代表当前库存余额。 */ |
||||
@JsonProperty("changeQty") |
||||
public Integer changeQty; |
||||
|
||||
/** 当前产品资料尺寸(cm)。 */ |
||||
@JsonProperty("length") |
||||
public java.math.BigDecimal length; |
||||
@JsonProperty("width") |
||||
public java.math.BigDecimal width; |
||||
@JsonProperty("height") |
||||
public java.math.BigDecimal height; |
||||
/** 当前产品资料重量(g)。 */ |
||||
@JsonProperty("weight") |
||||
public java.math.BigDecimal weight; |
||||
|
||||
/** 流水保存的销售类型。 */ |
||||
@JsonProperty("saleType") |
||||
public String saleType; |
||||
|
||||
/** 流水创建时间 {@code yyyy-MM-dd HH:mm:ss}。 */ |
||||
@JsonProperty("createTime") |
||||
public String createTime; |
||||
|
||||
/** 流水更新时间。 */ |
||||
@JsonProperty("updateTime") |
||||
public String updateTime; |
||||
|
||||
/** 流水业务操作时间。 */ |
||||
@JsonProperty("businessTime") |
||||
public String businessTime; |
||||
} |
||||
} |
||||
@ -0,0 +1,402 @@
@@ -0,0 +1,402 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import common.ecommerce.hengjian.HengjianConstants; |
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
import common.ecommerce.shared.spi.ChannelSecret; |
||||
import common.ecommerce.shared.support.Page; |
||||
import common.ecommerce.shared.testkit.RecordingTransport; |
||||
import common.ecommerce.shared.testkit.Responses; |
||||
import common.ecommerce.warehouse.enums.InventorySyncStrategy; |
||||
import common.ecommerce.warehouse.enums.WarehouseCapability; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.InventoryMovement; |
||||
import common.ecommerce.warehouse.model.InventoryMovementQuery; |
||||
import common.ecommerce.warehouse.model.InventoryQuery; |
||||
import common.ecommerce.warehouse.model.InventorySnapshot; |
||||
import common.ecommerce.warehouse.sdk.WarehouseConnection; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
import org.junit.jupiter.api.Test; |
||||
|
||||
import java.time.Instant; |
||||
import java.time.LocalDate; |
||||
import java.time.ZoneOffset; |
||||
import java.util.List; |
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals; |
||||
import static org.junit.jupiter.api.Assertions.assertFalse; |
||||
import static org.junit.jupiter.api.Assertions.assertThrows; |
||||
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||
|
||||
/** |
||||
* 库存三个接口的契约测试: |
||||
* 按 SKU 查({@code /v1/inventory/getInventory})、 |
||||
* 按仓分页查({@code /v2/inventory/get_inventory_by_page})、 |
||||
* 变动流水({@code /v1/inventory/task/query})。 |
||||
*/ |
||||
class HengjianInventoryTest { |
||||
|
||||
private static final WarehouseContext CTX = WarehouseContext.of( |
||||
"HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", |
||||
WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, |
||||
ChannelSecret.builder().appSecret("token-1").build()), |
||||
"req-1", java.time.Clock.fixed(Instant.parse("2026-11-16T00:00:00Z"), ZoneOffset.UTC)); |
||||
|
||||
private static HengjianAdapter adapter(RecordingTransport transport) { |
||||
return new HengjianAdapter(transport, new JacksonJsonCodec()); |
||||
} |
||||
|
||||
// ================================================================ 按 SKU 查
|
||||
|
||||
private static final String BY_SKU_BODY = |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":[" |
||||
+ "{\"warehouseCode\":\"EFCA\",\"lineName\":\"Klineo\",\"sku\":\"K150002Y\"," |
||||
+ "\"inventoryType\":0,\"inventoryAvailable\":12,\"inventoryReserved\":3," |
||||
+ "\"inventoryTransport\":0,\"inventoryCurrent\":15," |
||||
+ "\"updatedAt\":\"2026-11-15 02:19:56\"}]}"; |
||||
|
||||
private static RecordingTransport bySku() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_INVENTORY_BY_SKU, req -> Responses.ok(BY_SKU_BODY)); |
||||
} |
||||
|
||||
@Test |
||||
void bySkuPostsSkus() { |
||||
RecordingTransport transport = bySku(); |
||||
adapter(transport).query(CTX, InventoryQuery.builder().sku("K150002Y").build()); |
||||
|
||||
assertEquals("POST", transport.lastDataRequest().method()); |
||||
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inventory/getInventory", |
||||
transport.lastDataRequest().url()); |
||||
assertTrue(transport.lastDataRequest().body().contains("\"skus\":[\"K150002Y\"]")); |
||||
} |
||||
|
||||
@Test |
||||
void bySkuMapsSnapshot() { |
||||
List<InventorySnapshot> items = adapter(bySku()) |
||||
.query(CTX, InventoryQuery.builder().sku("K150002Y").build()).items(); |
||||
|
||||
assertEquals(1, items.size()); |
||||
InventorySnapshot s = items.get(0); |
||||
assertEquals("EFCA", s.warehouseCode()); |
||||
assertEquals("K150002Y", s.providerSku()); |
||||
assertEquals(12, s.available()); |
||||
assertEquals(3, s.reserved()); |
||||
assertEquals(0, s.inTransit()); |
||||
assertEquals(15, s.onHand()); |
||||
assertEquals(0, s.inventoryType()); |
||||
// 文档未标时区,按 UTC 解析(与订单接口同口径假设)
|
||||
assertEquals(Instant.parse("2026-11-15T02:19:56Z"), s.asOfUtc()); |
||||
} |
||||
|
||||
/** 按 SKU 查不分页:结果是末页。 */ |
||||
@Test |
||||
void bySkuIsNotPaginated() { |
||||
Page<InventorySnapshot> page = adapter(bySku()) |
||||
.query(CTX, InventoryQuery.builder().sku("K150002Y").build()); |
||||
|
||||
assertFalse(page.hasMore()); |
||||
} |
||||
|
||||
/** 两个过滤条件都没给时本地拒绝,不退化成「整仓全量」。 */ |
||||
@Test |
||||
void requiresSkuOrWarehouse() { |
||||
RecordingTransport transport = bySku(); |
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).query(CTX, InventoryQuery.builder().build())); |
||||
|
||||
assertTrue(ex.getMessage().contains("providerSkus or warehouseCodes"), ex.getMessage()); |
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
// ================================================================ 按仓分页查
|
||||
|
||||
/** 文档字段表写 snake_case,示例却给 camelCase —— 两种都要接住。 */ |
||||
private static final String PAGE_SNAKE_BODY = |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":{" |
||||
+ "\"last\":true,\"numberOfElements\":1,\"number\":0,\"size\":100," |
||||
+ "\"content\":[{\"warehouse_code\":\"EFCA\",\"line_name\":\"项目A\"," |
||||
+ "\"sku\":\"SKU-A\",\"inventory_type\":1,\"inventory_available\":5," |
||||
+ "\"inventory_reserved\":1,\"inventory_transport\":0," |
||||
+ "\"inventory_current\":6,\"updated_at\":\"2026-11-15 01:00:00\"}]}}"; |
||||
|
||||
private static RecordingTransport byPage(String body) { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_INVENTORY_PAGE, req -> Responses.ok(body)); |
||||
} |
||||
|
||||
@Test |
||||
void byPageSendsRequiredQueryParams() { |
||||
RecordingTransport transport = byPage(PAGE_SNAKE_BODY); |
||||
adapter(transport).query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()); |
||||
|
||||
assertEquals("GET", transport.lastDataRequest().method()); |
||||
String url = transport.lastDataRequest().url(); |
||||
assertTrue(url.contains("/v2/inventory/get_inventory_by_page?"), url); |
||||
assertTrue(url.contains("warehouseCodes=EFCA"), url); |
||||
assertTrue(url.contains("page=1"), url); |
||||
assertTrue(url.contains("sidx=" + HengjianConstants.ORDER_LIST_DEFAULT_SIDX), url); |
||||
assertTrue(url.contains("sort=" + HengjianConstants.ORDER_LIST_DEFAULT_SORT), url); |
||||
} |
||||
|
||||
/** 没给仓时用账户仓。 */ |
||||
@Test |
||||
void byPageFallsBackToAccountWarehouse() { |
||||
RecordingTransport transport = byPage(PAGE_SNAKE_BODY); |
||||
adapter(transport).query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()); |
||||
|
||||
assertTrue(transport.lastDataRequest().url().contains("warehouseCodes=EFCA")); |
||||
} |
||||
|
||||
/** snake_case 与 camelCase 两种字段名都要能反序列化。 */ |
||||
@Test |
||||
void byPageAcceptsSnakeCaseFields() { |
||||
List<InventorySnapshot> items = adapter(byPage(PAGE_SNAKE_BODY)) |
||||
.query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()).items(); |
||||
|
||||
assertEquals(1, items.size()); |
||||
InventorySnapshot s = items.get(0); |
||||
assertEquals("EFCA", s.warehouseCode()); |
||||
assertEquals("SKU-A", s.providerSku()); |
||||
assertEquals(1, s.inventoryType()); |
||||
assertEquals(5, s.available()); |
||||
assertEquals(1, s.reserved()); |
||||
assertEquals(6, s.onHand()); |
||||
assertEquals(Instant.parse("2026-11-15T01:00:00Z"), s.asOfUtc()); |
||||
} |
||||
|
||||
/** 文档示例的 data 是数组(不是分页对象):也要接住,按末页处理。 */ |
||||
@Test |
||||
void byPageAcceptsArrayShapedData() { |
||||
RecordingTransport transport = byPage( |
||||
"{\"code\":200,\"message\":\"ok\",\"data\":[{\"warehouseCode\":\"EFCA\"," |
||||
+ "\"sku\":\"SKU-A\",\"inventoryAvailable\":1,\"inventoryReserved\":0," |
||||
+ "\"inventoryTransport\":0,\"inventoryCurrent\":1," |
||||
+ "\"updatedAt\":\"2026-11-15 01:00:00\"}]}"); |
||||
|
||||
Page<InventorySnapshot> page = adapter(transport) |
||||
.query(CTX, InventoryQuery.builder().warehouseCode("EFCA").build()); |
||||
|
||||
assertEquals(1, page.size()); |
||||
assertFalse(page.hasMore(), "数组形状没有分页信息,按末页处理"); |
||||
} |
||||
|
||||
/** 分页未到末页时给出下一页游标。 */ |
||||
@Test |
||||
void byPageAdvancesCursor() { |
||||
RecordingTransport transport = byPage( |
||||
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":false,\"number\":0," |
||||
+ "\"content\":[{\"warehouseCode\":\"EFCA\",\"sku\":\"SKU-A\"," |
||||
+ "\"inventoryAvailable\":1,\"updatedAt\":\"2026-11-15 01:00:00\"}]}}"); |
||||
|
||||
Page<InventorySnapshot> page = adapter(transport) |
||||
.query(CTX, InventoryQuery.builder().warehouseCode("EFCA").pageSize(1).build()); |
||||
|
||||
assertTrue(page.hasMore()); |
||||
assertEquals("2", page.nextCursor()); |
||||
} |
||||
|
||||
/** 行数超过文档明写的 500 时拒绝,不静默截断。 */ |
||||
@Test |
||||
void byPageRejectsRowsAboveLimit() { |
||||
RecordingTransport transport = byPage(PAGE_SNAKE_BODY); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(transport).query(CTX, |
||||
InventoryQuery.builder().warehouseCode("EFCA").pageSize(1000).build())); |
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
// ================================================================ 分流与拒绝
|
||||
|
||||
/** 两个过滤条件都给:恒健没有这种接口,拒绝而不是丢掉一个。 */ |
||||
@Test |
||||
void rejectsSkuAndWarehouseTogether() { |
||||
RecordingTransport transport = bySku(); |
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).query(CTX, InventoryQuery.builder() |
||||
.sku("SKU-A").warehouseCode("EFCA").build())); |
||||
|
||||
assertTrue(ex.getMessage().contains("combining both"), ex.getMessage()); |
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
/** 更新时间过滤恒健不支持:拒绝(策略是全量比对)。 */ |
||||
@Test |
||||
void rejectsUpdatedAfter() { |
||||
RecordingTransport transport = bySku(); |
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).query(CTX, InventoryQuery.builder() |
||||
.sku("SKU-A").updatedAfter(Instant.parse("2026-11-01T00:00:00Z")).build())); |
||||
|
||||
assertTrue(ex.getMessage().contains("updatedAfter"), ex.getMessage()); |
||||
} |
||||
|
||||
/** 库存类型 / 零库存过滤恒健都不支持:拒绝而不是静默忽略。 */ |
||||
@Test |
||||
void rejectsUnsupportedFilters() { |
||||
RecordingTransport t1 = bySku(); |
||||
assertThrows(RuntimeException.class, () -> adapter(t1).query(CTX, |
||||
InventoryQuery.builder().sku("SKU-A").inventoryType(1).build())); |
||||
|
||||
RecordingTransport t2 = bySku(); |
||||
assertThrows(RuntimeException.class, () -> adapter(t2).query(CTX, |
||||
InventoryQuery.builder().sku("SKU-A").includeZeroStock(true).build())); |
||||
} |
||||
|
||||
@Test |
||||
void syncStrategyIsFullPullDiff() { |
||||
assertEquals(InventorySyncStrategy.FULL_PULL_DIFF, |
||||
adapter(RecordingTransport.create()).syncStrategy()); |
||||
} |
||||
|
||||
// ================================================================ 变动流水
|
||||
|
||||
private static final String MOVEMENT_BODY = |
||||
"{\"status\":0,\"code\":200,\"message\":\"查询成功\",\"data\":{" |
||||
+ "\"totalElements\":1,\"totalPages\":1,\"size\":10,\"first\":true,\"last\":true," |
||||
+ "\"content\":[{\"warehouseCode\":\"EFCA\",\"lineName\":\"项目A\"," |
||||
+ "\"channel\":\"CH-A\",\"sku\":\"SKU-A\",\"sellerSku\":\"SELLER-A\"," |
||||
+ "\"productType\":1,\"inventoryType\":0,\"planOrderNo\":\"1001\"," |
||||
+ "\"sourceNo\":\"1001-2001\",\"executeOrderNo\":\"DELIVER-2001\"," |
||||
+ "\"platformOrderNo\":\"ORDER-1001\",\"saleOrderNo\":\"CHANNEL-ORDER-1001\"," |
||||
+ "\"poNumber\":\"PO-1001\",\"documentType\":\"销售出库\",\"adjustReason\":null," |
||||
+ "\"inventoryChangeType\":\"出库\",\"changeQty\":5," |
||||
+ "\"createTime\":\"2026-10-10 09:00:00\"," |
||||
+ "\"updateTime\":\"2026-10-10 09:00:00\"," |
||||
+ "\"businessTime\":\"2026-10-09 18:00:00\"}]}}"; |
||||
|
||||
private static RecordingTransport movements() { |
||||
return RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_INVENTORY_MOVEMENTS, req -> Responses.ok(MOVEMENT_BODY)); |
||||
} |
||||
|
||||
private static InventoryMovementQuery.Builder movementQuery() { |
||||
return InventoryMovementQuery.builder() |
||||
.sku("SKU-A") |
||||
.dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-20")); |
||||
} |
||||
|
||||
@Test |
||||
void movementsPostRequiredFields() { |
||||
RecordingTransport transport = movements(); |
||||
adapter(transport).queryMovements(CTX, movementQuery().pageSize(10).build()); |
||||
|
||||
assertEquals("POST", transport.lastDataRequest().method()); |
||||
assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/inventory/task/query", |
||||
transport.lastDataRequest().url()); |
||||
String body = transport.lastDataRequest().body(); |
||||
assertTrue(body.contains("\"skus\":[\"SKU-A\"]"), body); |
||||
assertTrue(body.contains("\"beginDateTime\":\"2026-10-01\""), body); |
||||
assertTrue(body.contains("\"endDateTime\":\"2026-10-20\""), body); |
||||
assertTrue(body.contains("\"page\":1"), body); |
||||
assertTrue(body.contains("\"rows\":10"), body); |
||||
} |
||||
|
||||
@Test |
||||
void movementsMapAllFields() { |
||||
List<InventoryMovement> items = adapter(movements()) |
||||
.queryMovements(CTX, movementQuery().build()).items(); |
||||
|
||||
assertEquals(1, items.size()); |
||||
InventoryMovement m = items.get(0); |
||||
assertEquals(WarehouseProvider.HENGJIAN, m.sourceProvider()); |
||||
assertEquals("EFCA", m.warehouseCode()); |
||||
assertEquals("SKU-A", m.providerSku()); |
||||
assertEquals("SELLER-A", m.sellerSku()); |
||||
assertEquals("项目A", m.productName()); |
||||
assertEquals(Integer.valueOf(0), m.inventoryType()); |
||||
assertEquals("销售出库", m.documentType()); |
||||
assertEquals("出库", m.changeType()); |
||||
assertEquals(5, m.changeQuantity()); |
||||
assertEquals("1001", m.planOrderNo()); |
||||
assertEquals("1001-2001", m.sourceNo()); |
||||
assertEquals("DELIVER-2001", m.executeOrderNo()); |
||||
assertEquals("ORDER-1001", m.platformOrderNo()); |
||||
assertEquals("CHANNEL-ORDER-1001", m.saleOrderNo()); |
||||
assertEquals("PO-1001", m.poNumber()); |
||||
assertEquals(Instant.parse("2026-10-10T09:00:00Z"), m.createdAt()); |
||||
assertEquals(Instant.parse("2026-10-09T18:00:00Z"), m.businessAt()); |
||||
} |
||||
|
||||
/** 文档与真机都写:日期跨度最多 30 个自然日。 */ |
||||
@Test |
||||
void movementsRejectWindowOver30Days() { |
||||
RecordingTransport transport = movements(); |
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter(transport).queryMovements(CTX, InventoryMovementQuery.builder() |
||||
.sku("SKU-A") |
||||
.dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-31")) |
||||
.build())); |
||||
|
||||
assertTrue(ex.getMessage().contains("30"), ex.getMessage()); |
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
/** 正好 30 天要放行。 */ |
||||
@Test |
||||
void movementsAcceptExactly30Days() { |
||||
RecordingTransport transport = movements(); |
||||
adapter(transport).queryMovements(CTX, InventoryMovementQuery.builder() |
||||
.sku("SKU-A") |
||||
.dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-30")) |
||||
.build()); |
||||
|
||||
assertEquals(1, transport.dataRequests().size()); |
||||
} |
||||
|
||||
@Test |
||||
void movementsRejectRowsAboveLimit() { |
||||
RecordingTransport transport = movements(); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(transport).queryMovements(CTX, |
||||
movementQuery().pageSize(500).build())); |
||||
assertTrue(transport.dataRequests().isEmpty()); |
||||
} |
||||
|
||||
@Test |
||||
void movementsRequireSkus() { |
||||
RecordingTransport transport = movements(); |
||||
assertThrows(IllegalArgumentException.class, |
||||
() -> adapter(transport).queryMovements(CTX, |
||||
InventoryMovementQuery.builder() |
||||
.dateRange(LocalDate.parse("2026-10-01"), LocalDate.parse("2026-10-20")) |
||||
.build())); |
||||
} |
||||
|
||||
/** 单行数据不完整时跳过该行,不整页失败。 */ |
||||
@Test |
||||
void movementsSkipIncompleteRows() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_INVENTORY_MOVEMENTS, req -> Responses.ok( |
||||
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":true,\"content\":[" |
||||
+ "{\"warehouseCode\":\"EFCA\"}," |
||||
+ "{\"warehouseCode\":\"EFCA\",\"sku\":\"SKU-A\"," |
||||
+ "\"changeQty\":1,\"createTime\":\"2026-10-10 09:00:00\"}]}}")); |
||||
|
||||
List<InventoryMovement> items = adapter(transport) |
||||
.queryMovements(CTX, movementQuery().build()).items(); |
||||
|
||||
assertEquals(1, items.size(), "缺 sku 的行应被跳过,另一行保留"); |
||||
} |
||||
|
||||
/** 未到末页时给出下一页游标。 */ |
||||
@Test |
||||
void movementsAdvanceCursor() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(HengjianConstants.PATH_INVENTORY_MOVEMENTS, req -> Responses.ok( |
||||
"{\"code\":200,\"message\":\"ok\",\"data\":{\"last\":false,\"content\":[" |
||||
+ "{\"warehouseCode\":\"EFCA\",\"sku\":\"SKU-A\",\"changeQty\":1," |
||||
+ "\"createTime\":\"2026-10-10 09:00:00\"}]}}")); |
||||
|
||||
Page<InventoryMovement> page = adapter(transport).queryMovements(CTX, |
||||
movementQuery().pageSize(1).build()); |
||||
|
||||
assertTrue(page.hasMore()); |
||||
assertEquals("2", page.nextCursor()); |
||||
} |
||||
|
||||
@Test |
||||
void declaresInventoryCapability() { |
||||
assertTrue(adapter(RecordingTransport.create()).capabilities() |
||||
.contains(WarehouseCapability.INVENTORY_QUERY)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue