diff --git a/README.md b/README.md index be95628..5377aa7 100644 --- a/README.md +++ b/README.md @@ -307,7 +307,7 @@ common.ecommerce │ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine / │ │ InboundCommand / InboundLine / InboundCarton / InboundBatch / │ │ InboundReceipt / ReturnCommand / ReturnProcessCommand / -│ │ WarehouseReturn / TransferCommand / TransferOrder / +│ │ WarehouseReturn / TransferCommand / TransferOrder(含 errorCode/errorReason 等)/ │ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult / │ │ TrackEvent / TrackingInfo / DestructionCommand / DestructionOrder / │ │ BoxLabelCommand / SkuLabelCommand / LabelPrintTask / WarehouseLabel / diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java index 7bc8a9d..37a6650 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java @@ -29,6 +29,25 @@ public final class TransferOrder { private final Instant estimatedInboundAt; private final String trackingNumber; private final String remark; + /** 调出仓名称;仓方给的展示名,便于排查时不用再查仓表。 */ + private final String fromWarehouseTitle; + /** 调入仓名称。 */ + private final String toWarehouseTitle; + /** 承运商 code;未指定承运商时为 null。 */ + private final String carrierCode; + /** 总重量(kg);仓方未给时为 null。 */ + private final Double totalWeightKg; + /** 总体积(m³);仓方未给时为 null。 */ + private final Double totalVolumeCbm; + /** + * 仓方异常码;无异常时为 null。 + * + *
调拨失败时这是唯一能定位原因的地方——{@link #status()} 只会告诉你 + * 「取消异常 / 已驳回」,具体原因在这里。
+ */ + private final String errorCode; + /** 仓方异常原因;无异常时为 null。 */ + private final String errorReason; private TransferOrder(Builder b) { this.transferRequestNo = require(b.transferRequestNo, "transferRequestNo"); @@ -44,6 +63,13 @@ public final class TransferOrder { this.estimatedInboundAt = b.estimatedInboundAt; this.trackingNumber = b.trackingNumber; this.remark = b.remark; + this.fromWarehouseTitle = b.fromWarehouseTitle; + this.toWarehouseTitle = b.toWarehouseTitle; + this.carrierCode = b.carrierCode; + this.totalWeightKg = b.totalWeightKg; + this.totalVolumeCbm = b.totalVolumeCbm; + this.errorCode = b.errorCode; + this.errorReason = b.errorReason; } public static Builder builder() { @@ -101,6 +127,47 @@ public final class TransferOrder { return remark; } + /** 调出仓名称。 */ + public String fromWarehouseTitle() { + return fromWarehouseTitle; + } + + /** 调入仓名称。 */ + public String toWarehouseTitle() { + return toWarehouseTitle; + } + + /** 承运商 code;未指定时为 null。 */ + public String carrierCode() { + return carrierCode; + } + + /** 总重量(kg);仓方未给时为 null。 */ + public Double totalWeightKg() { + return totalWeightKg; + } + + /** 总体积(m³);仓方未给时为 null。 */ + public Double totalVolumeCbm() { + return totalVolumeCbm; + } + + /** 仓方异常码;无异常时为 null。 */ + public String errorCode() { + return errorCode; + } + + /** 仓方异常原因;无异常时为 null。 */ + public String errorReason() { + return errorReason; + } + + /** 是否带仓方异常,便于宿主直接筛「需人工处理」。 */ + public boolean hasError() { + return (errorCode != null && !errorCode.trim().isEmpty()) + || (errorReason != null && !errorReason.trim().isEmpty()); + } + public boolean completed() { return status == TransferStatus.COMPLETED; } @@ -131,6 +198,13 @@ public final class TransferOrder { private Instant estimatedInboundAt; private String trackingNumber; private String remark; + private String fromWarehouseTitle; + private String toWarehouseTitle; + private String carrierCode; + private Double totalWeightKg; + private Double totalVolumeCbm; + private String errorCode; + private String errorReason; public Builder transferRequestNo(String v) { this.transferRequestNo = v; @@ -197,6 +271,41 @@ public final class TransferOrder { return this; } + public Builder fromWarehouseTitle(String v) { + this.fromWarehouseTitle = v; + return this; + } + + public Builder toWarehouseTitle(String v) { + this.toWarehouseTitle = v; + return this; + } + + public Builder carrierCode(String v) { + this.carrierCode = v; + return this; + } + + public Builder totalWeightKg(Double v) { + this.totalWeightKg = v; + return this; + } + + public Builder totalVolumeCbm(Double v) { + this.totalVolumeCbm = v; + return this; + } + + public Builder errorCode(String v) { + this.errorCode = v; + return this; + } + + public Builder errorReason(String v) { + this.errorReason = v; + return this; + } + public TransferOrder build() { return new TransferOrder(this); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index e00ce3e..2a36f0f 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -463,7 +463,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl } YqnDtos.CreateTransferPlanResponse resp = json.fromJson(data.toString(), YqnDtos.CreateTransferPlanResponse.class); - return YqnTransferMapper.toOrder(resp, cmd.type(), zoneOf(ctx)); + return YqnTransferMapper.toOrder(resp, cmd.type(), cmd.transferRequestNo(), zoneOf(ctx)); } // ------------------------------------------------------------------ 退货 diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java index 523010a..2c9c90b 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java @@ -117,9 +117,11 @@ public final class YqnTransferMapper { * 不从响应猜。 */ public static TransferOrder toOrder(YqnDtos.CreateTransferPlanResponse resp, - TransferType requestedType, ZoneId zone) { + TransferType requestedType, String requestedSourceNo, + ZoneId zone) { return TransferOrder.builder() - .transferRequestNo(resp.sourceNo) + // 响应未回 sourceNo 时回落到请求侧:它同时是幂等键,不能为空 + .transferRequestNo(hasText(resp.sourceNo) ? resp.sourceNo.trim() : requestedSourceNo) .providerTransferNo(resp.transferOutboundPlanNo) .fromWarehouseCode(resp.orgWarehouseCode) .toWarehouseCode(resp.inOrgWarehouseCode) @@ -132,10 +134,21 @@ public final class YqnTransferMapper { .estimatedInboundAt(parseDate(resp.estimateInboundAt, zone)) .trackingNumber(resp.trackingNo) .remark(resp.remark) + .fromWarehouseTitle(resp.orgWarehouseTitle) + .toWarehouseTitle(resp.inOrgWarehouseTitle) + .carrierCode(resp.carrierCode) + .totalWeightKg(resp.totalWeight) + .totalVolumeCbm(resp.totalVolume) + .errorCode(resp.errorCode) + .errorReason(resp.errorReason) .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN) .build(); } + private static boolean hasText(String v) { + return v != null && !v.trim().isEmpty(); + } + static String formatDate(LocalDate date) { return date == null ? null : DATE.format(date); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index bb70f61..f292a0c 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -827,6 +827,18 @@ public final class YqnDtos { public String estimateInboundAt; public String trackingNo; public String remark; + /** 调出仓名称。 */ + public String orgWarehouseTitle; + /** 调入仓名称。 */ + public String inOrgWarehouseTitle; + public String carrierCode; + /** 总重量;运去哪未标单位。 */ + public Double totalWeight; + /** 总体积;运去哪未标单位。 */ + public Double totalVolume; + /** 异常 code;调拨失败时定位原因用。 */ + public String errorCode; + public String errorReason; } /** 创建销售退货请求(API 81)。 */ diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTransferTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTransferTest.java new file mode 100644 index 0000000..89b288b --- /dev/null +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTransferTest.java @@ -0,0 +1,203 @@ +package common.ecommerce.yqn.adapter; + +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.spi.ChannelSecret; +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.ShipTo; +import common.ecommerce.warehouse.model.TransferCommand; +import common.ecommerce.warehouse.model.TransferOrder; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.yqn.YqnConstants; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.LocalDate; +import java.time.ZoneOffset; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 创建调拨单(API 139)契约测试。 + */ +class YqnTransferTest { + + private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); + + private static WarehouseContext ctx() { + return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", + WarehouseConnection.of(YqnConstants.PR_BASE_URL, + ChannelSecret.builder().appSecret("key-1").build()), + "req-transfer", CLOCK); + } + + private static TransferCommand command() { + return TransferCommand.builder() + .transferRequestNo("TR-001") + .type(TransferType.WAREHOUSE_TO_WAREHOUSE) + .fromWarehouseCode("RF_NY_US") + .toWarehouseCode("RF_LA_US") + .inventoryType(0) + .carrierType(1) + .transportationType(2) + .estimateOutboundDate(LocalDate.of(2026, 11, 15)) + .estimateInboundDate(LocalDate.of(2026, 11, 20)) + .remark("补货") + .line("DM00001", 10) + .build(); + } + + @Test + void sendsDocumentedShape() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":{" + + "\"transferOutboundPlanNo\":\"TP123\"," + + "\"transferOutboundPlanStatus\":5,\"sourceNo\":\"TR-001\"}}")); + YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); + + TransferOrder order = adapter.create(ctx(), command()); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"type\":2"), body); + assertTrue(body.contains("\"orgWarehouseCode\":\"RF_NY_US\""), body); + assertTrue(body.contains("\"inOrgWarehouseCode\":\"RF_LA_US\""), body); + assertTrue(body.contains("\"sourceNo\":\"TR-001\""), body); + assertTrue(body.contains("\"estimateOutboundAt\":\"2026-11-15\""), body); + assertTrue(body.contains("\"sku\":\"DM00001\""), body); + assertTrue(body.contains("\"qty\":10"), body); + + assertEquals("TR-001", order.transferRequestNo()); + assertEquals("TP123", order.providerTransferNo()); + assertEquals(TransferStatus.PENDING_REVIEW, order.status()); + assertEquals("5", order.rawStatus()); + assertEquals(WarehouseProvider.YQN, order.sourceProvider()); + } + + /** 出库类型必须带收货地址;仓到仓可以不填。 */ + private static TransferCommand outboundCommand() { + return TransferCommand.builder() + .transferRequestNo("TR-OUT-1") + .type(TransferType.OUTBOUND) + .fromWarehouseCode("RF_NY_US") + .toWarehouseCode("Other") + .inventoryType(0) + .carrierType(1) + .transportationType(3) + .estimateOutboundDate(LocalDate.of(2026, 11, 15)) + .estimateInboundDate(LocalDate.of(2026, 11, 20)) + .shipTo(ShipTo.builder() + .name("李四") + .phone("+1-555-0200") + .countryCode("US") + .stateOrProvince("CA") + .city("Los Angeles") + .addressLine1("2 Main St") + .postalCode("90001") + .build()) + .line("DM00001", 5) + .build(); + } + + @Test + void sendsShipToFieldsForOutbound() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{" + + "\"transferOutboundPlanNo\":\"TP1\"}}")); + new YqnAdapter(transport, new JacksonJsonCodec()).create(ctx(), outboundCommand()); + + String body = transport.lastDataRequest().body(); + assertTrue(body.contains("\"type\":3"), body); + assertTrue(body.contains("\"shipToCountry\":\"US\""), body); + assertTrue(body.contains("\"shipToState\":\"CA\""), body); + assertTrue(body.contains("\"shipToCity\":\"Los Angeles\""), body); + assertTrue(body.contains("\"shipToPostal\":\"90001\""), body); + assertTrue(body.contains("\"shipToAddress1\":\"2 Main St\""), body); + assertTrue(body.contains("\"shipToContact\":\"李四\""), body); + assertTrue(body.contains("\"shipToTelephone\":\"+1-555-0200\""), body); + } + + @Test + void mapsTitlesCarrierAndSizes() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{" + + "\"transferOutboundPlanNo\":\"TP1\"," + + "\"transferOutboundPlanStatus\":7," + + "\"orgWarehouseCode\":\"RF_NY_US\"," + + "\"inOrgWarehouseCode\":\"RF_LA_US\"," + + "\"orgWarehouseTitle\":\"纽约仓\"," + + "\"inOrgWarehouseTitle\":\"洛杉矶仓\"," + + "\"carrierCode\":\"UPS\"," + + "\"totalWeight\":12.5," + + "\"totalVolume\":0.8," + + "\"totalQuantity\":10," + + "\"sourceNo\":\"TR-001\"}}")); + TransferOrder order = new YqnAdapter(transport, new JacksonJsonCodec()) + .create(ctx(), command()); + + assertEquals("纽约仓", order.fromWarehouseTitle()); + assertEquals("洛杉矶仓", order.toWarehouseTitle()); + assertEquals("UPS", order.carrierCode()); + assertEquals(Double.valueOf(12.5), order.totalWeightKg()); + assertEquals(Double.valueOf(0.8), order.totalVolumeCbm()); + assertEquals(10, order.totalQuantity()); + assertFalse(order.hasError()); + } + + /** 调拨失败时 errorCode / errorReason 是唯一能定位原因的地方。 */ + @Test + void mapsErrorFields() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{" + + "\"transferOutboundPlanNo\":\"TP1\"," + + "\"transferOutboundPlanStatus\":3," + + "\"sourceNo\":\"TR-001\"," + + "\"errorCode\":\"INSUFFICIENT_STOCK\"," + + "\"errorReason\":\"可售库存不足\"}}")); + TransferOrder order = new YqnAdapter(transport, new JacksonJsonCodec()) + .create(ctx(), command()); + + assertEquals(TransferStatus.REJECTED, order.status()); + assertEquals("INSUFFICIENT_STOCK", order.errorCode()); + assertEquals("可售库存不足", order.errorReason()); + assertTrue(order.hasError()); + } + + @Test + void unknownStatusIsNotGuessed() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{" + + "\"transferOutboundPlanNo\":\"TP1\"," + + "\"transferOutboundPlanStatus\":4242," + + "\"sourceNo\":\"TR-001\"}}")); + TransferOrder order = new YqnAdapter(transport, new JacksonJsonCodec()) + .create(ctx(), command()); + + assertEquals(TransferStatus.UNKNOWN, order.status()); + assertEquals("4242", order.rawStatus()); + } + + /** 响应不回传 type,从请求侧带过来,不猜。 */ + @Test + void typeComesFromRequestNotResponse() { + RecordingTransport transport = RecordingTransport.create() + .route(YqnConstants.PATH_TRANSFER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":{" + + "\"transferOutboundPlanNo\":\"TP1\",\"sourceNo\":\"TR-001\"}}")); + TransferOrder order = new YqnAdapter(transport, new JacksonJsonCodec()) + .create(ctx(), command()); + + assertEquals(TransferType.WAREHOUSE_TO_WAREHOUSE, order.type()); + } +}