Browse Source

fix(yqn): 调拨单补齐响应字段并修掉 sourceNo 缺失导致创建失败

API 139 的创建响应有 80 多个字段,之前只取了 9 个,调拨失败时
errorCode / errorReason 直接丢失——status 只告诉你「已驳回」或
「取消异常」,具体原因查不到。补上:

- errorCode / errorReason + hasError() 便捷判断
- orgWarehouseTitle / inOrgWarehouseTitle(调出/调入仓名称)
- carrierCode / totalWeight / totalVolume
- TransferOrder 新增字段全部加 Javadoc 说明「缺失时为 null」

顺带修一个真实 bug:响应不回填 sourceNo 时,toOrder 直接把 null 传给
TransferOrder.transferRequestNo,构造期抛 IllegalArgumentException。
sourceNo 同时是幂等键,不能为空——改为回落到请求侧的 transferRequestNo。
新增 YqnTransferTest 覆盖:出库调拨带 shipTo、响应字段映射、
异常字段、未知状态归 UNKNOWN、type 取自请求侧。

单元体积单位运去哪未标明,按 kg / m³ 命名但不做换算,Javadoc 注明。

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 1 week ago
parent
commit
08b982d8a6
  1. 2
      README.md
  2. 109
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  3. 2
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  4. 17
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
  5. 12
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  6. 203
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTransferTest.java

2
README.md

@ -307,7 +307,7 @@ common.ecommerce @@ -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 /

109
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java

@ -29,6 +29,25 @@ public final class TransferOrder { @@ -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。
*
* <p>调拨失败时这是唯一能定位原因的地方——{@link #status()} 只会告诉你
* 「取消异常 / 已驳回」,具体原因在这里。</p>
*/
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 { @@ -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 { @@ -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 { @@ -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 { @@ -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);
}

2
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -463,7 +463,7 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl @@ -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));
}
// ------------------------------------------------------------------ 退货

17
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java

@ -117,9 +117,11 @@ public final class YqnTransferMapper { @@ -117,9 +117,11 @@ public final class YqnTransferMapper {
* 不从响应猜。</p>
*/
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 { @@ -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);
}

12
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -827,6 +827,18 @@ public final class YqnDtos { @@ -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)。 */

203
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTransferTest.java

@ -0,0 +1,203 @@ @@ -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());
}
}
Loading…
Cancel
Save