You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

190 lines
8.9 KiB

feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
package common.ecommerce.yqn.adapter;
import common.ecommerce.http.HttpResponse;
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.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.model.CancelEligibility;
import common.ecommerce.warehouse.model.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.OutboundStatus;
import common.ecommerce.warehouse.model.ShipTo;
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.ZoneOffset;
import java.util.function.Function;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 运去哪适配器契约测试:请求形状、响应映射、状态与取消判定。
*
* <p>全部基于录制夹具,无网络。</p>
*/
class YqnAdapterTest {
private static final Instant NOW = Instant.parse("2026-11-09T00:00:00Z");
private static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC);
private static final String BASE = "https://pr-hwc-open-api.yqn.com";
private static WarehouseContext ctx() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of(BASE, ChannelSecret.builder().appSecret("token-1").build()),
"req-1", CLOCK);
}
private static OutboundCommand command(String requestNo, LabelMode mode) {
return OutboundCommand.builder()
.outboundRequestNo(requestNo)
.orderRef("SO-1")
.labelMode(mode)
.carrier("WLC-FEDEX")
.warehouseId("RF_NY_US")
.shipTo(ShipTo.builder()
.name("Test") // 测试数据
.phone("000")
.countryCode("US")
.stateOrProvince("NY")
.city("New York")
.addressLine1("1 Test St")
.postalCode("10001")
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("DM00001")
.quantity(2)
.declareName("Sample")
.declareNameEn("Sample")
.declareValue(common.ecommerce.shared.support.Money.of("9.99", "USD"))
.build())
.build();
}
@Test
void createMapsCommandAndReadsProviderOrderId() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"orderNo\":\"YQN202611090001\",\"status\":\"ACCEPTED\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.model.OutboundReceipt receipt =
adapter.create(ctx(), command("OB-1", LabelMode.WAREHOUSE_LABEL));
assertEquals("OB-1", receipt.outboundRequestNo());
assertEquals("YQN202611090001", receipt.providerOrderId());
assertEquals("ACCEPTED", receipt.rawStatus());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"customerOrderNo\":\"OB-1\""), body);
assertTrue(body.contains("\"sku\":\"DM00001\""), body);
assertTrue(body.contains("\"shippingMethod\":\"WLC-FEDEX\""), body);
assertEquals("token-1", transport.recorded().get(0).headers().get(YqnConstants.TOKEN_HEADER));
}
@Test
void platformLabelWithoutCapabilityIsRejected() {
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertFalse(adapter.capabilities().contains(WarehouseCapability.PLATFORM_LABEL_DELIVERY));
RuntimeException ex = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
() -> adapter.create(ctx(), command("OB-2", LabelMode.PLATFORM_LABEL)));
assertTrue(ex.getMessage().contains("PLATFORM_LABEL_DELIVERY"), ex.getMessage());
}
@Test
void getMapsStatusAndTracking() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"orders\":[{\"orderNo\":\"YQN1\","
+ "\"customerOrderNo\":\"OB-3\",\"status\":\"SHIPPED\","
+ "\"trackingNumber\":\"TRK1\",\"carrier\":\"FEDEX\","
+ "\"createTime\":\"2026-11-08 10:00:00\"}]}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.model.OutboundOrder order =
adapter.get(ctx(), OutboundRef.ofRequestNo("OB-3"));
assertEquals("OB-3", order.outboundRequestNo());
assertEquals("YQN1", order.providerOrderId());
assertEquals(OutboundStatus.SHIPPED, order.status());
assertEquals("TRK1", order.trackingNumber());
assertEquals(Instant.parse("2026-11-08T02:00:00Z"), order.requestedAt());
}
@Test
void checkCancelBlocksShippedOrder() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_FIND, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"orders\":[{\"orderNo\":\"YQN1\","
+ "\"customerOrderNo\":\"OB-4\",\"status\":\"SHIPPED\"}]}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertEquals(CancelEligibility.BLOCKED,
adapter.checkCancel(ctx(), OutboundRef.ofRequestNo("OB-4")));
}
@Test
void cancelChargedWithoutAcceptThrows() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CANCEL, req -> Responses.ok(
"{\"code\":\"0\",\"data\":{\"cancelType\":\"CHARGED\","
+ "\"cancelFee\":\"5.00\",\"currency\":\"USD\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
common.ecommerce.warehouse.model.CancelCommand cmd =
common.ecommerce.warehouse.model.CancelCommand.builder()
.outboundRequestNo("OB-5").acceptCharge(false).build();
common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException ex =
org.junit.jupiter.api.Assertions.assertThrows(
common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException.class,
() -> adapter.cancel(ctx(), cmd));
assertEquals("5.00", ex.cancelFee());
}
@Test
void businessErrorCodeBecomesException() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE,
req -> Responses.ok("{\"code\":\"1001\",\"message\":\"sku not found\"}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
RuntimeException ex = org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
() -> adapter.create(ctx(), command("OB-6", LabelMode.WAREHOUSE_LABEL)));
assertTrue(ex.getMessage().contains("1001"), ex.getMessage());
}
@Test
void missingOrderNoIsNotSilentSuccess() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_ORDER_CREATE, req -> Responses.ok("{\"code\":\"0\",\"data\":{}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
org.junit.jupiter.api.Assertions.assertThrows(RuntimeException.class,
() -> adapter.create(ctx(), command("OB-7", LabelMode.WAREHOUSE_LABEL)));
}
@Test
void statusMappingCoversKnownValues() {
assertEquals(OutboundStatus.CANCELLED, YqnOutboundMapper.toStatus("CANCELLED"));
assertEquals(OutboundStatus.PICKING, YqnOutboundMapper.toStatus("PICKING"));
assertEquals(OutboundStatus.LABEL_READY, YqnOutboundMapper.toStatus("LABEL_PRINTED"));
assertEquals(OutboundStatus.EXCEPTION, YqnOutboundMapper.toStatus("EXCEPTION"));
assertEquals(OutboundStatus.SUBMITTED, YqnOutboundMapper.toStatus("UNKNOWN_X"));
assertNull(YqnOutboundMapper.parseTime("", null));
}
}