diff --git a/README.md b/README.md
index dde7859..d149e1f 100644
--- a/README.md
+++ b/README.md
@@ -331,8 +331,9 @@ common.ecommerce
└── xincang 信仓三方仓(warehouse-sdk-xincang)
├── XincangConstants 测试基址、路径、query 参数名、单位换算常量、限流
├── auth XincangTokenClient(GET /api.login,无 refresh)
- ├── adapter XincangAdapter / XincangAdapterFactory /
- │ XincangProductMapper / XincangOrderMapper / XincangTransferMapper
+ ├── adapter XincangAdapter / XincangAdapterFactory / XincangProductMapper /
+ │ XincangOrderMapper / XincangOrderDetailMapper /
+ │ XincangTransferMapper / XincangTransferDetailMapper
├── dto XincangDtos(登录 / 商品)
├── enums XincangOrderStatus / XincangTransferState /
│ XincangForecastStatus / XincangOrderType
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
index ff69988..cdfc73a 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
@@ -36,4 +36,21 @@ public interface TransferCapable extends WarehouseAdapter {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
}
+
+ /**
+ * 按仓侧调拨单号查详情。
+ *
+ *
信仓的「获取详情」({@code GET fba.fba_detail})走这里:
+ * {@code providerTransferNo} 传转运单号 {@code order_no}。
+ *
+ * 方法名带 {@code Transfer} 后缀:{@code InboundCapable} 已有同签名的
+ * {@code get(ctx, String)}(返回 {@code InboundOrder}),同一适配器实现两者时
+ * 返回类型冲突、也无法按泛型区分。
+ *
+ * 查不到时由适配器决定语义(可返回 null);未实现查询的仓默认拒绝。
+ */
+ default TransferOrder getTransfer(WarehouseContext ctx, String providerTransferNo) {
+ throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
+ common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
+ }
}
diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
index d60cd51..da005ac 100644
--- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
+++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
@@ -132,6 +132,20 @@ public final class WarehouseOperations {
ref -> ref);
}
+ /**
+ * 按仓侧调拨单号查详情。
+ *
+ * @param providerTransferNo 仓侧调拨单号({@code createTransfer} 返回的
+ * {@code providerTransferNo})
+ */
+ public TransferOrder getTransfer(final String providerTransferNo) {
+ require(WarehouseCapability.TRANSFER, TransferCapable.class);
+ return CallSupport.observe(observer, ctx, "warehouse.transfer.get",
+ CallSupport.params("providerTransferNo", providerTransferNo),
+ o -> o == null ? 0 : 1,
+ () -> ((TransferCapable) adapter).getTransfer(ctx, providerTransferNo));
+ }
+
/** 库存视图。 */
public InventoryView inventory() {
return new InventoryView();
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
index 4551b76..e73c0d8 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/XincangConstants.java
@@ -53,6 +53,9 @@ public final class XincangConstants {
/** 新增订单一单多件({@code multipart/form-data};一票一件请用 {@code api.add_order})。 */
public static final String PATH_ORDER_ADD_MULTIPLE = "/api.add_order_multiple";
+ /** 订单详情;{@code order_no} 与 {@code ckh} 二选一。 */
+ public static final String PATH_ORDER_DETAIL = "/api.get_order";
+
/** 新增转运({@code application/json})。 */
public static final String PATH_TRANSFER_CREATE = "/fba.do_fba";
@@ -62,6 +65,9 @@ public final class XincangConstants {
/** 转运列表。 */
public static final String PATH_TRANSFER_LIST = "/fba.fbalist";
+ /** 转运详情;必填 {@code order_no}(转运单号)。 */
+ public static final String PATH_TRANSFER_DETAIL = "/fba.fba_detail";
+
/** 登录响应里的 token 归入哪个作用域;信仓用 query 参数传递,不是 {@code Authorization} 头。 */
public static final String TOKEN_LOCATION = "query";
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
index 2cbb57c..b91e047 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
@@ -213,9 +213,33 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
return OutboundReceipt.of(cmd.outboundRequestNo(), result.orderNo, null);
}
+ /**
+ * 查订单详情({@code GET api.get_order})。
+ *
+ * 信仓按 {@code order_no}(系统单号)或 {@code ckh}(参考号)二选一查询。
+ * 引用里的 {@code providerOrderId} 优先当作 {@code order_no},
+ * {@code outboundRequestNo} 当作 {@code ckh}——两者都传时以 provider 侧为准,
+ * 因为只有仓单号能唯一定位。
+ *
+ * 查不到时信仓返回 {@code errno != 0},这里作为业务异常抛出,不返回 null——
+ * 「查不到」与「查到了但没有数据」对调用方的意义不同。
+ */
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
- throw XincangUnsupportedOutbound.getUnsupported(ctx);
+ Map params = new LinkedHashMap();
+ if (!blank(ref.providerOrderId())) {
+ params.put("order_no", ref.providerOrderId());
+ } else if (!blank(ref.outboundRequestNo())) {
+ params.put("ckh", ref.outboundRequestNo());
+ }
+ String raw = executeGet(ctx, XincangConstants.PATH_ORDER_DETAIL, params, login(ctx),
+ "warehouse.outbound.get");
+ XincangDtos.OrderDetail detail = json.fromJson(raw, XincangDtos.OrderDetailResponse.class).rst;
+ if (detail == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.outbound.get",
+ "xincang get_order returned no rst");
+ }
+ return XincangOrderDetailMapper.toOrder(detail, ctx);
}
@Override
@@ -283,6 +307,30 @@ public final class XincangAdapter implements WarehouseProductCapable, OutboundCa
"warehouse.transfer.approve");
}
+ /**
+ * 转运详情({@code GET fba.fba_detail})。
+ *
+ * @param providerTransferNo 信仓转运单号 {@code order_no}
+ */
+ @Override
+ public TransferOrder getTransfer(WarehouseContext ctx, String providerTransferNo) {
+ if (blank(providerTransferNo)) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get",
+ "providerTransferNo must not be blank");
+ }
+ Map params = new LinkedHashMap();
+ params.put("order_no", providerTransferNo);
+ String raw = executeGet(ctx, XincangConstants.PATH_TRANSFER_DETAIL, params, login(ctx),
+ "warehouse.transfer.get");
+ XincangDtos.TransferDetail detail =
+ json.fromJson(raw, XincangDtos.TransferDetailResponse.class).rst;
+ if (detail == null) {
+ throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get",
+ "xincang fba_detail returned no rst");
+ }
+ return XincangTransferDetailMapper.toOrder(detail);
+ }
+
// ------------------------------------------------------------------ internals
/** 写接口:JSON 请求体(含 token)+ query token。 */
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
new file mode 100644
index 0000000..6583e83
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderDetailMapper.java
@@ -0,0 +1,203 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.support.Money;
+import common.ecommerce.warehouse.enums.LabelMode;
+import common.ecommerce.warehouse.enums.OutboundStatus;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.OutboundLine;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.ShipTo;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.enums.XincangOrderStatus;
+
+import java.time.Instant;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.time.format.DateTimeParseException;
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * 信仓订单详情报文 → 统一模型({@code GET api.get_order})。
+ *
+ * 平台字段名只出现在本类与 {@link XincangDtos}。
+ * 时间字段是北京时间 {@code yyyy-MM-dd HH:mm:ss},统一折算成 UTC。
+ */
+public final class XincangOrderDetailMapper {
+
+ private static final DateTimeFormatter DATE_TIME =
+ DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
+ private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("yyyy-MM-dd");
+ private static final String CURRENCY_USD = "USD";
+
+ private XincangOrderDetailMapper() {
+ }
+
+ /**
+ * 订单详情 → {@link OutboundOrder}。
+ *
+ * @param detail 详情;调用方保证非 null
+ * @param ctx 本次调用上下文(仓编码兜底)
+ */
+ public static OutboundOrder toOrder(XincangDtos.OrderDetail detail, WarehouseContext ctx) {
+ OutboundStatus status = XincangOrderStatus.toCore(detail.state);
+ return OutboundOrder.builder()
+ .warehouseCode(firstNonBlank(detail.warehouseCode, ctx.providerWarehouseId()))
+ // 双号:信仓详情只回系统单号 order_no;
+ // outboundRequestNo 用它兜底,业务侧参考号进 orderRef
+ .outboundRequestNo(firstNonBlank(detail.orderNo, detail.ckh))
+ .providerOrderId(blankToNull(detail.orderNo))
+ .orderRef(blankToNull(detail.ckh))
+ .labelMode(labelModeOf(detail.orderType))
+ .status(status)
+ .rawStatus(detail.state)
+ .carrierCode(blankToNull(detail.logisticsType))
+ .trackingNumber(blankToNull(detail.trackingNumber))
+ .requestedAt(parseTime(detail.gmtCreate))
+ .shippedAt(parseTime(detail.deliveredTime))
+ .sourceProvider(WarehouseProvider.XINCANG)
+ .lines(toLines(detail))
+ .shipTo(toShipTo(detail))
+ .exceptionCode(blankToNull(detail.apiError))
+ .estimatedShippingFee(parseMoney(detail.totalAmount))
+ .currency(CURRENCY_USD)
+ .build();
+ }
+
+ /**
+ * 面单模式:{@code order_type=wayfair} 是自供面单,其余是仓自有面单。
+ *
+ * {@code LabelMode} 表达的正是「谁出面单」,与信仓 order_type 语义一致。
+ */
+ static LabelMode labelModeOf(String orderType) {
+ return "wayfair".equalsIgnoreCase(orderType) ? LabelMode.PLATFORM_LABEL : LabelMode.WAREHOUSE_LABEL;
+ }
+
+ /**
+ * 商品行。
+ *
+ * 详情同时给了 {@code products[]}(一票多件)和 {@code product_sku} / {@code sku_count}
+ * 单值字段;前者非空时以它为准,为空才退回单值字段。数量缺失或非正的行直接跳过——
+ * {@link OutboundLine} 要求数量为正,保留会在构造期抛异常。
+ */
+ static List toLines(XincangDtos.OrderDetail detail) {
+ List lines = new ArrayList();
+ if (detail.products != null && !detail.products.isEmpty()) {
+ int index = 0;
+ for (XincangDtos.OrderDetailProduct product : detail.products) {
+ if (product == null || blank(product.sku)) {
+ continue;
+ }
+ int qty = parsePositiveInt(product.qty);
+ if (qty <= 0) {
+ continue;
+ }
+ index++;
+ lines.add(OutboundLine.builder()
+ .lineNo(String.valueOf(index))
+ .omsSku(product.sku.trim())
+ .providerSku(product.sku.trim())
+ .quantity(qty)
+ .declareName(blankToNull(product.nameZhCn))
+ .build());
+ }
+ return lines;
+ }
+ int qty = parsePositiveInt(detail.skuCount);
+ if (!blank(detail.productSku) && qty > 0) {
+ lines.add(OutboundLine.builder()
+ .lineNo("1")
+ .omsSku(detail.productSku.trim())
+ .providerSku(detail.productSku.trim())
+ .quantity(qty)
+ .declareName(blankToNull(detail.productName))
+ .build());
+ }
+ return lines;
+ }
+
+ private static ShipTo toShipTo(XincangDtos.OrderDetail detail) {
+ if (blank(detail.country) && blank(detail.address) && blank(detail.receiveUser)) {
+ return null;
+ }
+ return ShipTo.builder()
+ .name(blankToNull(detail.receiveUser))
+ .phone(blankToNull(detail.phone))
+ .email(blankToNull(detail.email))
+ .countryCode(blankToNull(detail.country))
+ .stateOrProvince(blankToNull(detail.province))
+ .city(blankToNull(detail.city))
+ .addressLine1(blankToNull(detail.address))
+ .addressLine2(blankToNull(detail.address2))
+ .postalCode(blankToNull(detail.postcode))
+ .build();
+ }
+
+ /** 北京时间 {@code yyyy-MM-dd HH:mm:ss} → UTC;空值 / 非法返回 null。 */
+ static Instant parseTime(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDateTime.parse(raw.trim(), DATE_TIME)
+ .atZone(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ /** 日期 {@code yyyy-MM-dd} → 北京时间当天 0 点的 UTC 时刻;空值 / 非法返回 null。 */
+ static Instant parseDate(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return LocalDate.parse(raw.trim(), DATE)
+ .atStartOfDay(XincangConstants.SYSTEM_ZONE).toInstant();
+ } catch (DateTimeParseException e) {
+ return null;
+ }
+ }
+
+ /** 金额 → USD;空值 / 非法返回 null(负值保留,费用可能有冲抵)。 */
+ static Money parseMoney(String raw) {
+ if (blank(raw)) {
+ return null;
+ }
+ try {
+ return Money.of(raw.trim(), CURRENCY_USD);
+ } catch (RuntimeException e) {
+ return null;
+ }
+ }
+
+ static int parsePositiveInt(String raw) {
+ if (blank(raw)) {
+ return 0;
+ }
+ try {
+ int v = Integer.parseInt(raw.trim());
+ return v > 0 ? v : 0;
+ } catch (NumberFormatException e) {
+ return 0;
+ }
+ }
+
+ static String firstNonBlank(String a, String b) {
+ if (!blank(a)) {
+ return a.trim();
+ }
+ return blank(b) ? null : b.trim();
+ }
+
+ static String blankToNull(String v) {
+ return blank(v) ? null : v.trim();
+ }
+
+ static boolean blank(String v) {
+ return v == null || v.trim().isEmpty();
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
new file mode 100644
index 0000000..1347435
--- /dev/null
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferDetailMapper.java
@@ -0,0 +1,57 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.warehouse.enums.TransferStatus;
+import common.ecommerce.warehouse.enums.TransferType;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.xincang.dto.XincangDtos;
+import common.ecommerce.xincang.enums.XincangTransferState;
+
+/**
+ * 信仓转运详情报文 → 统一模型({@code GET fba.fba_detail})。
+ *
+ * 信仓的转运 = 从信仓发往平台仓,统一模型里固定为 {@link TransferType#OUTBOUND}。
+ */
+public final class XincangTransferDetailMapper {
+
+ private XincangTransferDetailMapper() {
+ }
+
+ /**
+ * 转运详情 → {@link TransferOrder}。
+ *
+ * @param detail 详情;调用方保证非 null
+ */
+ public static TransferOrder toOrder(XincangDtos.TransferDetail detail) {
+ TransferStatus status = XincangTransferState.toCore(detail.state);
+ return TransferOrder.builder()
+ // 双号:fba_no 是业务侧单号,order_no 是仓侧单号
+ .transferRequestNo(XincangOrderDetailMapper.firstNonBlank(
+ detail.fbaNo, detail.orderNo))
+ .providerTransferNo(XincangOrderDetailMapper.blankToNull(detail.orderNo))
+ .fromWarehouseCode(XincangOrderDetailMapper.blankToNull(detail.fromWarehouseName))
+ .toWarehouseCode(XincangOrderDetailMapper.blankToNull(detail.destWarehouseName))
+ .type(TransferType.OUTBOUND)
+ .status(status)
+ .rawStatus(detail.state)
+ .sourceProvider(WarehouseProvider.XINCANG)
+ .totalQuantity(totalQuantityOf(detail))
+ .estimatedOutboundAt(XincangOrderDetailMapper.parseDate(detail.preSendTime))
+ .remark(XincangOrderDetailMapper.blankToNull(detail.remark))
+ .build();
+ }
+
+ /** 明细件数合计;明细缺失时返回 0(未知,不猜)。 */
+ static int totalQuantityOf(XincangDtos.TransferDetail detail) {
+ if (detail.products == null || detail.products.isEmpty()) {
+ return 0;
+ }
+ int total = 0;
+ for (XincangDtos.TransferDetailProduct product : detail.products) {
+ if (product != null) {
+ total += XincangOrderDetailMapper.parsePositiveInt(product.skuCount);
+ }
+ }
+ return total;
+ }
+}
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
index f6cd414..6cf9bee 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
@@ -9,7 +9,7 @@ import common.ecommerce.warehouse.sdk.WarehouseContext;
/**
* 信仓暂时不支持的出库 / 调拨能力。
*
- * 本轮只接入「新增订单」与「转运创建 / 审核」,查询、取消、包裹都还没接。
+ *
「新增订单」「订单详情」「转运创建 / 审核 / 详情」已接入;列表查询、取消、包裹还没接。
* 这里统一抛 {@link ValidationException}({@code retryable=false}),不返回空集合——
* 静默返回 {@code null} / 空会让调用方以为「仓说没有这单」。
*/
@@ -22,10 +22,6 @@ final class XincangUnsupportedOutbound {
throw unsupported(ctx, "warehouse.outbound.query");
}
- static ValidationException getUnsupported(WarehouseContext ctx) {
- throw unsupported(ctx, "warehouse.outbound.get");
- }
-
static ValidationException checkCancelUnsupported(WarehouseContext ctx) {
throw unsupported(ctx, "warehouse.outbound.checkCancel");
}
@@ -38,6 +34,21 @@ final class XincangUnsupportedOutbound {
throw unsupported(ctx, "warehouse.outbound.packages");
}
+ /**
+ * 查询类接口返回了不可用结果(如报文里没有 {@code rst})。
+ *
+ * 用 {@code ValidationException} 而不是返回 null:调用方需要区分
+ * 「查不到」与「查到了但解析不出」,后者往往是协议变更的信号。
+ */
+ static ValidationException businessError(WarehouseContext ctx, String operation, String message) {
+ return new ValidationException(ChannelException.builder()
+ .message(message)
+ .operation(operation)
+ .provider(WarehouseProvider.XINCANG.name())
+ .requestId(ctx.requestId())
+ .retryable(false));
+ }
+
private static ValidationException unsupported(WarehouseContext ctx, String operation) {
return new ValidationException(ChannelException.builder()
.message("xincang does not implement " + operation + " yet")
diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
index 48f5856..6ecba19 100644
--- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
+++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/dto/XincangDtos.java
@@ -408,6 +408,166 @@ public final class XincangDtos {
public Attachment data;
}
+ /**
+ * 转运单详情({@code GET fba.fba_detail})的 {@code rst}。
+ *
+ * 只声明统一模型用得上的字段与排查必需的字段;附件同时给了对象和
+ * {@code *_url}(签名后可直接下载),这里两者都保留。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferDetail {
+
+ @JsonProperty("id")
+ public String id;
+ /** 转运单号(LTL...);审核与后续查询都用它。 */
+ @JsonProperty("order_no")
+ public String orderNo;
+ /** 业务侧转运单号(我们下发的 {@code fba_no})。 */
+ @JsonProperty("fba_no")
+ public String fbaNo;
+ @JsonProperty("po")
+ public String po;
+
+ /** 发货仓 id / 代码。 */
+ @JsonProperty("from_warehouse")
+ public String fromWarehouseId;
+ @JsonProperty("from_warehouse_name")
+ public String fromWarehouseName;
+ /** 目的仓 id / 代码。 */
+ @JsonProperty("dest_warehouse")
+ public String destWarehouseId;
+ @JsonProperty("dest_warehouse_name")
+ public String destWarehouseName;
+
+ /** 预约发货时间 {@code yyyy-MM-dd}。 */
+ @JsonProperty("pre_send_time")
+ public String preSendTime;
+ /** 状态码,见 {@code XincangTransferState}。 */
+ @JsonProperty("state")
+ public String state;
+ @JsonProperty("state_name")
+ public String stateName;
+
+ /** 是否需要产品贴 / 外箱贴 / 托盘贴:0 否 / 1 是。 */
+ @JsonProperty("is_product_label")
+ public String isProductLabel;
+ @JsonProperty("is_ctn_label")
+ public String isCtnLabel;
+ @JsonProperty("is_pallet_label")
+ public String isPalletLabel;
+ /** 是否打托:0 否 / 1 是。 */
+ @JsonProperty("is_pallet")
+ public String isPallet;
+
+ @JsonProperty("remark")
+ public String remark;
+ @JsonProperty("picking_time")
+ public String pickingTime;
+ @JsonProperty("picked_time")
+ public String pickedTime;
+ @JsonProperty("palleted_time")
+ public String palletedTime;
+ /** 发货时间。 */
+ @JsonProperty("send_time")
+ public String sendTime;
+ @JsonProperty("approve_time")
+ public String approveTime;
+ @JsonProperty("shipping_id")
+ public String shippingId;
+
+ /** 转运类型(字典值)。 */
+ @JsonProperty("delivery_mode")
+ public String deliveryMode;
+ /** 转运方式(字典值)。 */
+ @JsonProperty("delivery_way")
+ public String deliveryWay;
+ /** 订单类型(字典值)。 */
+ @JsonProperty("order_type")
+ public String orderType;
+ @JsonProperty("other_warehouse")
+ public String otherWarehouse;
+ /** 标签需求,逗号分隔。 */
+ @JsonProperty("label_requirement")
+ public String labelRequirement;
+
+ /** 附件对象。 */
+ @JsonProperty("product_label_att")
+ public Attachment productLabelAtt;
+ @JsonProperty("ctn_label_att")
+ public Attachment ctnLabelAtt;
+ @JsonProperty("pallet_label_att")
+ public Attachment palletLabelAtt;
+ @JsonProperty("bol_att")
+ public List bolAtt;
+ @JsonProperty("signature_bol_att")
+ public List signatureBolAtt;
+ @JsonProperty("express_label_att")
+ public Attachment expressLabelAtt;
+ @JsonProperty("other_att")
+ public List otherAtt;
+
+ /** 附件签名 URL(可直接下载)。 */
+ @JsonProperty("product_label_att_url")
+ public String productLabelAttUrl;
+ @JsonProperty("ctn_label_att_url")
+ public String ctnLabelAttUrl;
+ @JsonProperty("pallet_label_att_url")
+ public String palletLabelAttUrl;
+ @JsonProperty("bol_att_url")
+ public String bolAttUrl;
+ @JsonProperty("signature_bol_file")
+ public String signatureBolFile;
+ @JsonProperty("express_label_att_url")
+ public String expressLabelAttUrl;
+ @JsonProperty("other_att_url")
+ public String otherAttUrl;
+
+ /** 总费用。 */
+ @JsonProperty("total_amount")
+ public String totalAmount;
+
+ @JsonProperty("gmt_create")
+ public String gmtCreate;
+ @JsonProperty("gmt_modify")
+ public String gmtModify;
+
+ /** 产品明细。 */
+ @JsonProperty("products")
+ public List products;
+ }
+
+ /** 转运详情里的产品行。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferDetailProduct {
+
+ @JsonProperty("product_no")
+ public String productNo;
+ /** 件数。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+ /** 箱数。 */
+ @JsonProperty("box_count")
+ public String boxCount;
+ @JsonProperty("chn_name")
+ public String chnName;
+ @JsonProperty("packing_rate")
+ public String packingRate;
+ @JsonProperty("remark")
+ public String remark;
+ @JsonProperty("weight_lbs")
+ public String weightLbs;
+ @JsonProperty("weight_kg")
+ public String weightKg;
+ }
+
+ /** 转运详情响应外层。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class TransferDetailResponse {
+
+ @JsonProperty("rst")
+ public TransferDetail rst;
+ }
+
/** 转运单创建结果 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class TransferResult {
@@ -417,6 +577,165 @@ public final class XincangDtos {
public String orderNo;
}
+ /**
+ * 订单详情({@code GET api.get_order})的 {@code rst}。
+ *
+ * 字段名以文档为准;时间均为北京时间 {@code yyyy-MM-dd HH:mm:ss}(日期字段为
+ * {@code yyyy-MM-dd})。空值可能是空串,适配器里统一转 null。
+ */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderDetail {
+
+ /** 订单 id。 */
+ @JsonProperty("id")
+ public String id;
+
+ /** 信仓系统单号(DS-...)。 */
+ @JsonProperty("order_no")
+ public String orderNo;
+
+ /** 订单状态码,见 {@code XincangOrderStatus}。 */
+ @JsonProperty("state")
+ public String state;
+
+ /** 状态名。 */
+ @JsonProperty("state_name")
+ public String stateName;
+
+ /** 仓侧报错信息;正常为空。 */
+ @JsonProperty("api_error")
+ public String apiError;
+
+ /** 跟踪号。 */
+ @JsonProperty("gzh")
+ public String trackingNumber;
+
+ /** 面单 URL。 */
+ @JsonProperty("face_url")
+ public String faceUrl;
+
+ /** 参考号,即我们下发的 {@code ckh}。 */
+ @JsonProperty("ckh")
+ public String ckh;
+
+ /** 订单类型:common / wayfair。 */
+ @JsonProperty("order_type")
+ public String orderType;
+
+ /** 产品明细(一票多件)。 */
+ @JsonProperty("products")
+ public List products;
+
+ /** 件数。 */
+ @JsonProperty("sku_count")
+ public String skuCount;
+
+ @JsonProperty("dim_length")
+ public String dimLength;
+ @JsonProperty("dim_width")
+ public String dimWidth;
+ @JsonProperty("dim_height")
+ public String dimHeight;
+ @JsonProperty("dim_divisor")
+ public String dimDivisor;
+
+ /** 实重(磅)。 */
+ @JsonProperty("weight_lbs")
+ public String weightLbs;
+ /** 计费重(磅)。 */
+ @JsonProperty("billing_weight_lbs")
+ public String billingWeightLbs;
+ /** 体积重(磅)。 */
+ @JsonProperty("volume_weight_lbs")
+ public String volumeWeightLbs;
+
+ @JsonProperty("product_sku")
+ public String productSku;
+ @JsonProperty("product_name")
+ public String productName;
+ @JsonProperty("source_sku")
+ public String sourceSku;
+
+ @JsonProperty("warehouse_id")
+ public String warehouseId;
+ @JsonProperty("warehouse_code")
+ public String warehouseCode;
+
+ @JsonProperty("country")
+ public String country;
+ @JsonProperty("province")
+ public String province;
+ @JsonProperty("city")
+ public String city;
+ @JsonProperty("address")
+ public String address;
+ @JsonProperty("address2")
+ public String address2;
+ @JsonProperty("postcode")
+ public String postcode;
+ @JsonProperty("receive_user")
+ public String receiveUser;
+ @JsonProperty("phone")
+ public String phone;
+ @JsonProperty("email")
+ public String email;
+
+ /** 物流方式字典值。 */
+ @JsonProperty("logistics_type")
+ public String logisticsType;
+ @JsonProperty("is_sign")
+ public String isSign;
+ @JsonProperty("zone")
+ public String zone;
+
+ /** 总费用。 */
+ @JsonProperty("total_amount")
+ public String totalAmount;
+ @JsonProperty("repair_amount")
+ public String repairAmount;
+
+ @JsonProperty("approve_time")
+ public String approveTime;
+ /** 发货时间。 */
+ @JsonProperty("delivered_time")
+ public String deliveredTime;
+ @JsonProperty("shop_name")
+ public String shopName;
+ @JsonProperty("gmt_create")
+ public String gmtCreate;
+ @JsonProperty("gmt_modify")
+ public String gmtModify;
+ @JsonProperty("gmt_cancel")
+ public String gmtCancel;
+ /** 截单时间。 */
+ @JsonProperty("intercept_time")
+ public String interceptTime;
+ }
+
+ /** 订单详情里的产品行。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderDetailProduct {
+
+ @JsonProperty("product_id")
+ public String productId;
+ /** 产品 SKU。 */
+ @JsonProperty("sku")
+ public String sku;
+ /** 数量。 */
+ @JsonProperty("qty")
+ public String qty;
+ @JsonProperty("name_zh_cn")
+ public String nameZhCn;
+ }
+
+ /** 订单详情响应外层,用于取 {@code rst}。 */
+ @JsonIgnoreProperties(ignoreUnknown = true)
+ public static final class OrderDetailResponse {
+
+ @JsonProperty("rst")
+ public OrderDetail rst;
+ }
+
/** 新增订单响应外层,用于取 {@code rst}。 */
@JsonIgnoreProperties(ignoreUnknown = true)
public static final class OrderResponse {
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderDetailTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderDetailTest.java
new file mode 100644
index 0000000..feac2d3
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderDetailTest.java
@@ -0,0 +1,207 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.PlatformBusinessException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+import common.ecommerce.shared.testkit.RecordingTransport;
+import common.ecommerce.shared.testkit.Responses;
+import common.ecommerce.warehouse.enums.LabelMode;
+import common.ecommerce.warehouse.enums.OutboundStatus;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.OutboundOrder;
+import common.ecommerce.warehouse.model.OutboundRef;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 订单详情({@code GET api.get_order})契约测试。
+ */
+class XincangOrderDetailTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ /** 文档「成功示例」原文。 */
+ private static final String DETAIL = "{"
+ + "\"id\":\"126508095093477568\","
+ + "\"order_no\":\"DS-BZY01-26101600001\","
+ + "\"state\":\"0\","
+ + "\"state_name\":\"待审核\","
+ + "\"api_error\":\"验证订单操作失败\","
+ + "\"gzh\":\"\","
+ + "\"face_url\":\"\","
+ + "\"ckh\":\"Ref26101601\","
+ + "\"order_type\":\"common\","
+ + "\"products\":[{\"product_id\":\"1\",\"sku\":\"LSS29BLACK\",\"qty\":\"1\","
+ + "\"name_zh_cn\":\"餐椅\"}],"
+ + "\"sku_count\":\"1\","
+ + "\"dim_length\":\"25.9840\",\"dim_width\":\"18.8976\",\"dim_height\":\"16.9290\","
+ + "\"dim_divisor\":\"250.00\",\"weight_lbs\":\"23.5000\","
+ + "\"billing_weight_lbs\":\"34.00\",\"volume_weight_lbs\":\"34\","
+ + "\"product_sku\":\"LSS29BLACK\",\"product_name\":\"餐椅\",\"source_sku\":\"LSS29BLACK\","
+ + "\"warehouse_id\":\"84047962479824\",\"warehouse_code\":\"NJ-2605\","
+ + "\"country\":\"US\",\"province\":\"GA\",\"city\":\"STONE MOUNTAIN\","
+ + "\"address\":\"5039 LELAND DR\",\"address2\":\"\",\"postcode\":\"30083-6026\","
+ + "\"receive_user\":\"DARA\",\"phone\":\"+1 480-618-5344\",\"email\":\"\","
+ + "\"logistics_type\":\"FEDEX-G\",\"is_sign\":\"0\",\"zone\":\"5\","
+ + "\"total_amount\":\"0\",\"repair_amount\":\"0\","
+ + "\"approve_time\":\"2026-10-16 16:20:46\",\"delivered_time\":\"\","
+ + "\"shop_name\":\"BZY01-shop\",\"gmt_create\":\"2026-10-16 10:18:00\","
+ + "\"gmt_modify\":\"2026-10-16 10:18:00\",\"gmt_cancel\":\"\",\"intercept_time\":\"\""
+ + "}";
+
+ private static final String OK_BODY = "{\"rst\":" + DETAIL
+ + ",\"errno\":0,\"err\":\"\",\"trace_id\":\"t-1\"}";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-10T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-NJ-2605", WarehouseProvider.XINCANG, "NJ-2605",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void getByProviderOrderIdMapsDetail() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-BZY01-26101600001"));
+
+ // 请求:GET + query token + order_no
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("GET", req.method());
+ assertTrue(req.url().contains("/api.get_order?"), req.url());
+ assertTrue(req.url().contains("order_no=DS-BZY01-26101600001"), req.url());
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+ assertFalse(req.url().contains("ckh="), "给了 order_no 就不该再传 ckh");
+
+ // 映射
+ assertEquals("NJ-2605", order.warehouseCode());
+ assertEquals("DS-BZY01-26101600001", order.outboundRequestNo());
+ assertEquals("DS-BZY01-26101600001", order.providerOrderId());
+ assertEquals("Ref26101601", order.orderRef());
+ assertEquals(OutboundStatus.PENDING_REVIEW, order.status());
+ assertEquals("0", order.rawStatus());
+ assertEquals(LabelMode.WAREHOUSE_LABEL, order.labelMode());
+ assertEquals("FEDEX-G", order.carrierCode());
+ assertEquals("验证订单操作失败", order.exceptionCode());
+ assertEquals(WarehouseProvider.XINCANG, order.sourceProvider());
+ // 北京时间 2026-10-16 10:18:00 → UTC 02:18:00
+ assertEquals(Instant.parse("2026-10-16T02:18:00Z"), order.requestedAt());
+ assertNull(order.shippedAt(), "空串的发货时间应为 null");
+
+ assertEquals(1, order.lines().size());
+ assertEquals("LSS29BLACK", order.lines().get(0).omsSku());
+ assertEquals(1, order.lines().get(0).quantity());
+ assertEquals("餐椅", order.lines().get(0).declareName());
+
+ assertEquals("US", order.shipTo().countryCode());
+ assertEquals("GA", order.shipTo().stateOrProvince());
+ assertEquals("DARA", order.shipTo().name());
+ assertNull(order.shipTo().addressLine2(), "空串地址2 应为 null");
+ }
+
+ @Test
+ void getFallsBackToReferenceNumber() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ adapter.get(ctx(), OutboundRef.ofRequestNo("Ref26101601"));
+
+ String url = transport.lastDataRequest().url();
+ assertTrue(url.contains("ckh=Ref26101601"), url);
+ assertFalse(url.contains("order_no="), "没有仓单号时只传 ckh");
+ }
+
+ @Test
+ void wayfairOrderMapsToPlatformLabel() {
+ String wayfair = OK_BODY.replace("\"order_type\":\"common\"", "\"order_type\":\"wayfair\"");
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(wayfair));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1"));
+
+ assertEquals(LabelMode.PLATFORM_LABEL, order.labelMode());
+ }
+
+ @Test
+ void fallsBackToSingleSkuWhenProductsMissing() {
+ String single = OK_BODY.replace(
+ "\"products\":[{\"product_id\":\"1\",\"sku\":\"LSS29BLACK\",\"qty\":\"1\",\"name_zh_cn\":\"餐椅\"}]",
+ "\"products\":[]").replace("\"sku_count\":\"1\"", "\"sku_count\":\"3\"");
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(single));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1"));
+
+ assertEquals(1, order.lines().size());
+ assertEquals("LSS29BLACK", order.lines().get(0).omsSku());
+ assertEquals(3, order.lines().get(0).quantity());
+ }
+
+ @Test
+ void unknownStateIsNotGuessed() {
+ String unknown = OK_BODY.replace("\"state\":\"0\"", "\"state\":\"99\"");
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(unknown));
+
+ OutboundOrder order = adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1"));
+
+ assertEquals(OutboundStatus.UNKNOWN, order.status());
+ assertEquals("99", order.rawStatus());
+ }
+
+ @Test
+ void businessErrorPropagates() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"订单不存在\",\"trace_id\":\"t-err\"}"));
+
+ PlatformBusinessException e = assertThrows(PlatformBusinessException.class,
+ () -> adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-NONE")));
+ assertTrue(e.getMessage().contains("订单不存在"), e.getMessage());
+ }
+
+ @Test
+ void emptyRstIsNotSilentNull() {
+ transport.route(XincangConstants.PATH_ORDER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-empty\"}"));
+
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.get(ctx(), OutboundRef.ofProviderOrderId("DS-1")));
+ assertTrue(e.getMessage().contains("no rst"), e.getMessage());
+ }
+
+ @Test
+ void timeParsingIsBeijingToUtc() {
+ assertEquals(Instant.parse("2026-10-16T02:18:00Z"),
+ XincangOrderDetailMapper.parseTime("2026-10-16 10:18:00"));
+ assertNull(XincangOrderDetailMapper.parseTime(""));
+ assertNull(XincangOrderDetailMapper.parseTime("not-a-time"));
+ assertEquals(Instant.parse("2026-10-15T16:00:00Z"),
+ XincangOrderDetailMapper.parseDate("2026-10-16"));
+ }
+}
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
index 97b9640..3ac6096 100644
--- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
@@ -213,8 +213,7 @@ class XincangOrderTest {
@Test
void queryAndCancelAreExplicitlyUnsupported() {
- assertThrows(common.ecommerce.shared.error.ValidationException.class,
- () -> adapter.get(ctx(), null));
+ // get 已接入(见 XincangOrderDetailTest),这里只断言仍未接入的列表查询
assertThrows(common.ecommerce.shared.error.ValidationException.class,
() -> adapter.query(ctx(), null));
assertFalse(adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY));
diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferDetailTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferDetailTest.java
new file mode 100644
index 0000000..1cd0127
--- /dev/null
+++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferDetailTest.java
@@ -0,0 +1,178 @@
+package common.ecommerce.xincang.adapter;
+
+import common.ecommerce.shared.error.PlatformBusinessException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.shared.testkit.InMemoryLockProvider;
+import common.ecommerce.shared.testkit.InMemoryTokenStore;
+import common.ecommerce.shared.testkit.MutableClock;
+import common.ecommerce.shared.testkit.RecordingTransport;
+import common.ecommerce.shared.testkit.Responses;
+import common.ecommerce.warehouse.enums.TransferStatus;
+import common.ecommerce.warehouse.enums.TransferType;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.model.TransferOrder;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.xincang.XincangConstants;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+import java.time.Clock;
+import java.time.Duration;
+import java.time.Instant;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * 转运详情({@code GET fba.fba_detail})契约测试。
+ */
+class XincangTransferDetailTest {
+
+ private static final String BASE = XincangConstants.TEST_BASE_URL;
+ private static final String APP_KEY = "ak-1";
+
+ /** 文档「成功示例」原文(截取与映射相关的字段)。 */
+ private static final String DETAIL = "{"
+ + "\"id\":\"128064084674485505\","
+ + "\"order_no\":\"LTL2610200000271\","
+ + "\"fba_no\":\"ZYDD20261020001\","
+ + "\"po\":\"ZYDD20261020001\","
+ + "\"from_warehouse\":\"84047962307416\","
+ + "\"from_warehouse_name\":\"CA-15950\","
+ + "\"dest_warehouse\":\"0\","
+ + "\"dest_warehouse_name\":\"123\","
+ + "\"pre_send_time\":\"2026-10-21\","
+ + "\"state\":\"6\","
+ + "\"state_name\":\"已发货\","
+ + "\"remark\":\"\","
+ + "\"is_pallet\":\"1\","
+ + "\"delivery_mode\":\"LTL\","
+ + "\"delivery_way\":\"卡车\","
+ + "\"label_requirement\":\"产品贴,外箱标签,托盘标签\","
+ + "\"total_amount\":\"84.25\","
+ + "\"products\":["
+ + "{\"product_no\":\"BOOK\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"},"
+ + "{\"product_no\":\"FHCP006\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"}"
+ + "]"
+ + "}";
+
+ private static final String OK_BODY = "{\"rst\":" + DETAIL
+ + ",\"errno\":0,\"err\":\"\",\"trace_id\":\"t-1\"}";
+
+ private RecordingTransport transport;
+ private XincangAdapter adapter;
+
+ @BeforeEach
+ void setUp() {
+ transport = RecordingTransport.create();
+ MutableClock clock = MutableClock.atUtc("2026-11-10T00:00:00Z");
+ transport.route(XincangConstants.PATH_LOGIN, req -> Responses.ok(
+ "{\"rst\":{\"id\":\"c-1\",\"token\":\"{T-1}\",\"token_expire_time\":\""
+ + java.time.LocalDateTime.ofInstant(clock.instant().plus(Duration.ofHours(2)),
+ XincangConstants.SYSTEM_ZONE)
+ .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"))
+ + "\"},\"errno\":0,\"err\":\"\",\"trace_id\":\"t-login\"}"));
+ adapter = new XincangAdapter(transport, new common.ecommerce.http.JacksonJsonCodec(),
+ new InMemoryTokenStore(), new InMemoryLockProvider(), clock);
+ }
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of("XC-CA-15950", WarehouseProvider.XINCANG, "CA-15950",
+ WarehouseConnection.of(BASE, ChannelSecret.builder()
+ .appKey(APP_KEY).appSecret("sk").build()),
+ "req-1", Clock.systemUTC());
+ }
+
+ @Test
+ void getMapsTransferDetail() {
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ TransferOrder order = adapter.getTransfer(ctx(), "LTL2610200000271");
+
+ // 请求
+ common.ecommerce.http.HttpRequest req = transport.lastDataRequest();
+ assertEquals("GET", req.method());
+ assertTrue(req.url().contains("/fba.fba_detail?"), req.url());
+ assertTrue(req.url().contains("order_no=LTL2610200000271"), req.url());
+ assertTrue(req.url().contains("token=%7BT-1%7D"), req.url());
+
+ // 双号:fba_no 是业务单号,order_no 是仓单号
+ assertEquals("ZYDD20261020001", order.transferRequestNo());
+ assertEquals("LTL2610200000271", order.providerTransferNo());
+ assertEquals("CA-15950", order.fromWarehouseCode());
+ assertEquals("123", order.toWarehouseCode());
+ assertEquals(TransferType.OUTBOUND, order.type());
+ assertEquals(TransferStatus.SHIPPED, order.status());
+ assertEquals("6", order.rawStatus());
+ assertEquals(WarehouseProvider.XINCANG, order.sourceProvider());
+ assertEquals(20, order.totalQuantity(), "10 + 10");
+ // pre_send_time 2026-10-21 北京时间 0 点 → UTC 前一天 16:00
+ assertEquals(Instant.parse("2026-10-20T16:00:00Z"), order.estimatedOutboundAt());
+ assertNull(order.remark(), "空串备注应为 null");
+ }
+
+ @Test
+ void unknownTransferStateIsNotGuessed() {
+ String unknown = OK_BODY.replace("\"state\":\"6\"", "\"state\":\"99\"");
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(unknown));
+
+ TransferOrder order = adapter.getTransfer(ctx(), "LTL-1");
+
+ assertEquals(TransferStatus.UNKNOWN, order.status());
+ assertEquals("99", order.rawStatus());
+ }
+
+ @Test
+ void outputStateMapsToShipped() {
+ // 信仓 state=6「已发货」→ core SHIPPED,不是 COMPLETED
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(OK_BODY));
+
+ TransferOrder order = adapter.getTransfer(ctx(), "LTL-1");
+
+ assertEquals(TransferStatus.SHIPPED, order.status());
+ assertFalse(order.completed(), "已发货不等于已完成");
+ }
+
+ @Test
+ void missingProductsMeansUnknownQuantity() {
+ String noProducts = OK_BODY.replace(
+ ",\"products\":["
+ + "{\"product_no\":\"BOOK\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"},"
+ + "{\"product_no\":\"FHCP006\",\"sku_count\":\"10\",\"box_count\":\"5\",\"packing_rate\":\"2\"}"
+ + "]", "");
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(noProducts));
+
+ assertEquals(0, adapter.getTransfer(ctx(), "LTL-1").totalQuantity());
+ }
+
+ @Test
+ void blankOrderNoIsRejectedBeforeSending() {
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.getTransfer(ctx(), " "));
+ assertTrue(e.getMessage().contains("providerTransferNo"), e.getMessage());
+ assertFalse(transport.recorded().stream()
+ .anyMatch(r -> r.url().contains(XincangConstants.PATH_TRANSFER_DETAIL)));
+ }
+
+ @Test
+ void businessErrorPropagates() {
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":-1,\"err\":\"转运单不存在\",\"trace_id\":\"t-err\"}"));
+
+ PlatformBusinessException e = assertThrows(PlatformBusinessException.class,
+ () -> adapter.getTransfer(ctx(), "LTL-NONE"));
+ assertTrue(e.getMessage().contains("转运单不存在"), e.getMessage());
+ }
+
+ @Test
+ void emptyRstIsNotSilentNull() {
+ transport.route(XincangConstants.PATH_TRANSFER_DETAIL, req -> Responses.ok(
+ "{\"rst\":null,\"errno\":0,\"err\":\"\",\"trace_id\":\"t-empty\"}"));
+
+ common.ecommerce.shared.error.ValidationException e =
+ assertThrows(common.ecommerce.shared.error.ValidationException.class,
+ () -> adapter.getTransfer(ctx(), "LTL-1"));
+ assertTrue(e.getMessage().contains("no rst"), e.getMessage());
+ }
+}