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()); + } +}