From 586d9c5eb847be21e54e794a5c6360d8054754c3 Mon Sep 17 00:00:00 2001
From: lml <1297555865@qq.com>
Date: Thu, 12 Nov 2026 17:57:35 +0800
Subject: [PATCH] =?UTF-8?q?feat(hengjian):=20=E5=AF=B9=E6=8E=A5=E5=88=9B?=
=?UTF-8?q?=E5=BB=BA=E9=94=80=E5=94=AE=E5=8F=91=E8=B4=A7=E5=8D=95=20/v1/sa?=
=?UTF-8?q?leOrder/create?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 新增 HengjianCreateOrderDtos + HengjianOutboundMapper,实现 OutboundCapable.create,
声明 OUTBOUND 与 PLATFORM_LABEL_DELIVERY 能力位
- 时间按 UTC 的 yyyy-MM-dd HH:mm:ss 输出(文档明确 utc),不用仓时区——
那个时区是给仓方回传的无时区本地时间用的,方向相反
- skuAmount 取「行总额」:有 totalAmount 直接用,否则申报单价 × 数量
- isSignature 挂在行上且必填:取命令的布尔值套到每一行,成人 / 间接签收
统一映射成直接签收(1),比静默降成 0 安全
- attachInfoItems 必填:无附件发空数组;平台面单剥掉 data: 前缀后进 file
- 必填字段(地址六项 / 城市 / createdAt / 产品行)本地拒绝,不发无效请求
- 响应只回 data.orderId,拿不到即报错——取消接口同时要 orderId 与 orderNo
- 查询 / 取消 / 包裹仍显式拒绝,不返回 null;写探针增加建单用例
- 文档补建单口径与两页文档不一致处
验证:mvn test 全量通过,恒健 74 个用例 + 2 个探针跳过。
Co-Authored-By: Claude Code 响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与
+ * {@code orderNo} 都要,所以调用方必须落库这个 id。
承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一 + * {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。
+ * + *响应只回 {@code data.orderId}(仓内部数字 id,不是字符串单号)。 + * 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id + * 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了, + * 因此拿不到就报错,不静默当成创建成功。
+ */ + @Override + public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { + requirePlatformLabelSupported(cmd); + String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( + cmd.warehouseId(), ctx.providerWarehouseId()); + HengjianCreateOrderDtos.CreateOrderRequest body = + HengjianOutboundMapper.toRequest(cmd, warehouseCode, ctx.clock()); + + String raw = execute(ctx, HengjianConstants.PATH_ORDER_CREATE, body, OP_ORDER_CREATE); + HengjianCreateOrderDtos.CreateOrderResponse resp = + json.fromJson(raw, HengjianCreateOrderDtos.CreateOrderResponse.class); + if (resp == null || resp.data == null || resp.data.orderId == null) { + throw WarehouseException.builder() + .message("hengjian create order returned no data.orderId: " + safeRelay(raw)) + .operation(OP_ORDER_CREATE) + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .rawResponse(safeRelay(raw)) + .build(); + } + return OutboundReceipt.of(cmd.outboundRequestNo(), String.valueOf(resp.data.orderId), + resp.message); + } + + /** 恒健出库查询尚未接入:显式拒绝,不返回 null 让调用方以为「仓说没有这单」。 */ + @Override + public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { + throw unsupportedOutbound("warehouse.outbound.get", ctx); + } + + @Override + public Page恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了 + * {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。
+ */ + private static void requirePlatformLabelSupported(OutboundCommand cmd) { + if (cmd.labelMode() == LabelMode.PLATFORM_LABEL + && (cmd.labelContentBase64() == null || cmd.labelContentBase64().trim().isEmpty())) { + throw new IllegalArgumentException( + "labelContentBase64 is required when labelMode=PLATFORM_LABEL for " + + cmd.outboundRequestNo()); + } + } + + private WarehouseException unsupportedOutbound(String operation, WarehouseContext ctx) { + return WarehouseException.builder() + .message("hengjian does not implement " + operation + " yet") + .operation(operation) + .warehouseCode(ctx.warehouseCode()) + .provider(provider().name()) + .requestId(ctx.requestId()) + .retryable(false) + .build(); + } + + /** 原始响应可能含 PII,异常里只留短片段。 */ + private static String safeRelay(String raw) { + if (raw == null) { + return null; + } + return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; + } + // ------------------------------------------------------------------ 商品 /** diff --git a/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java new file mode 100644 index 0000000..f8de14d --- /dev/null +++ b/warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianOutboundMapper.java @@ -0,0 +1,243 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; +import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.ShipTo; + +import java.math.BigDecimal; +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneOffset; +import java.time.format.DateTimeFormatter; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; + +/** + * 恒健出库报文映射({@code POST /v1/saleOrder/create})。 + * + *平台字段名只出现在本类与 {@link HengjianCreateOrderDtos}。
+ * + *恒健的时间字段是 UTC 的 {@code yyyy-MM-dd HH:mm:ss}(文档明确写了 utc 时间), + * 所以格式化固定按 {@link ZoneOffset#UTC},不用 {@code WarehouseContext.zone()}—— + * 那个时区是给「仓方回传的无时区本地时间」用的,方向相反。
+ * + *{@code createdAt} 在统一模型里没有对应字段,用调用方注入的 {@link Clock} 生成 + * 「下单时刻」。这是请求侧的时间戳,不是把仓方没给的数据编出来; + * 幂等重放时它会变,但恒健不拿它做去重。
+ * + *| 字段 | 处理 |
|---|---|
| {@code salesPlatform} | + *恒健没有平台维度,店铺路由走 {@code channelAccount}。不发, + * 也不拿它去推断 {@code isDFOrder}——VC 订单里只有一部分是 DF。 |
| {@code splitOrder} / {@code packages} | + *恒健没有拆单入参与包裹入参,忽略。 |
| {@code estimatedDeliveryTime} | + *恒健只有 {@code expectedShipDate}(要求发货时间),没有送达时间。 |
| {@code declaredTotal} | + *恒健按行收金额,没有整单申报额。 |
恒健 {@code skuAmount} 是「当前 SKU 总金额」,不是单价: + * 有 {@code totalAmount} 直接用;没有就用申报单价 × 数量, + * 否则整单金额会少算 quantity 倍(运去哪踩过同样的坑)。
+ */ + static Double skuTotalAmount(OutboundLine line) { + Money total = line.totalAmount(); + if (total != null) { + return total.amount().doubleValue(); + } + Money unit = line.declareValue(); + if (unit == null) { + return null; + } + return unit.amount().multiply(BigDecimal.valueOf(line.quantity())).doubleValue(); + } + + /** + * 附件:平台面单随单下发。 + * + *恒健把 {@code attachInfoItems} 标为必填,所以没有附件时返回空数组, + * 不省略该字段——省略会被当成缺必填项。
+ * + *仓自有面单({@link LabelMode#WAREHOUSE_LABEL})时不给附件; + * 给了面单内容却不是平台面单模式,直接拒绝,不静默丢弃。
+ */ + private static List中英文两页文档描述的是同一个接口,中文页叫「创建销售发货单(带附件的)」, + * 英文页叫「Create Sale Order With Label」;两页字段表基本一致,差异见各字段注释。
+ * + *两页的必填口径不完全一致:中文页把 {@code createdAt} 标为必填、英文页也标 Y; + * 但中文页没有 {@code isPrime}(只有英文页有),英文页没有 {@code customerRemark} / + * {@code warehouseRemark}(只有中文页有)。按两页并集实现,必填取两页都要求的字段。
+ */ +public final class HengjianCreateOrderDtos { + + private HengjianCreateOrderDtos() { + } + + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CreateOrderRequest { + + /** 来源单号;必填。用 OMS 的出库单号,也是后续按单号查询 / 取消的锚点。 */ + public String orderNo; + + /** 承运商名称,如 {@code FedEx} / {@code UPS}。 */ + public String carrier; + + /** 承运商服务代码,如 {@code FEDEX_GROUND} / {@code UPS_2DAY}。 */ + public String carrierCode; + + /** 仓库 code;必须已在 Efulfill 系统维护。 */ + public String warehouseCode; + + /** 店铺标识;必须已在 Efulfill 店铺管理中维护。 */ + public String channelAccount; + + /** 币种;不填默认 USD。 */ + public String currency; + + /** + * 支付时间,UTC,{@code yyyy-MM-dd HH:mm:ss};不填由仓方取当前时间。 + * + *统一模型没有「支付时间」字段,这里通常不传。
+ */ + public String paidAt; + + /** Amazon VC Direct Fulfillment 订单:0 否 / 1 是;不填默认为否。 */ + public Integer isDFOrder; + + /** + * 是否 SFP 订单:0 否 / 1 是;不填默认为否。 + * + *文档类型写的是 String,但请求示例给的是数字 {@code "isPrime": 0}。 + * 这里按示例用 Integer——两页示例一致,且 Spring 后端按数字绑定的可能性更高。 + * 真机若报类型错,改成 String 即可。
+ */ + public Integer isPrime; + + /** + * 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。 + * + *文档:{@code isDFOrder=1} 时必填。
+ */ + public String expectedShipDate; + + /** 目的国家,2 位字符;必填。 */ + public String shipToCountry; + + /** 目的州(美国:2 位编码);必填。 */ + public String shipToState; + + /** 目的城市;中文页标必填,英文页未标。 */ + public String shipToCity; + + /** 发运邮编;必填。 */ + public String shipToPostal; + + /** 发运地址 1;必填。 */ + public String shipToAddress1; + + /** 发运地址 2。 */ + public String shipToAddress2; + + /** 发运联系人;必填。 */ + public String shipToContact; + + /** 客户邮箱。 */ + public String customerEmail; + + /** 发运联系电话;必填。 */ + public String shipToTelephone; + + /** third party 账号。 */ + public String thirdPartyAccount; + + /** 发货时效:{@code Standard-48Hours}(标准)/ {@code SameDay ShipOut}(加急);不填为标准。 */ + public String shipServiceLevel; + + /** 创建时间,UTC,{@code yyyy-MM-dd HH:mm:ss};必填。 */ + public String createdAt; + + /** 买家备注。 */ + public String customerRemark; + + /** 仓库备注;传了仓方会参考此信息发货。 */ + public String warehouseRemark; + + /** 产品行;必填。 */ + public List没有附件时发空数组而不是省略该字段——省略会被仓方当成缺必填项。
+ */ + public List统一模型只有布尔型的 {@code signatureRequired},表达不了 2 / 3。
+ */ + public Integer isSignature; + + /** 当前 SKU 总金额(不是单价)。 */ + public Double skuAmount; + + /** 投保金额;{@code isInsure=1} 时必填。 */ + public Double insureAmount; + } + + /** 附件。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class AttachInfoItem { + + /** 附件名称;必填。文档建议填跟踪号且不带后缀。 */ + public String name; + + /** 附件 URL;与 {@link #file} 至少给一个。 */ + public String url; + + /** base64 内容;给了就忽略 {@link #url}。 */ + public String file; + + /** + * 附件类型;必填。文档类型写 STRING: + * 0 Shippinglabel / 1 Packinglist / 2 BOL / 3 Other / + * 4 CartonLabel / 5 PalletLabel / 6 itemlabel。 + */ + public String type; + + /** 备注。 */ + public String remark; + } + } + + /** 创建响应:{@code {statusCode, status, code, message, data:{orderId}}}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CreateOrderResponse { + + @JsonProperty("statusCode") + public Integer statusCode; + + @JsonProperty("code") + public Integer code; + + @JsonProperty("message") + public String message; + + @JsonProperty("data") + public CreateOrderData data; + } + + /** 响应 {@code data}。 */ + @JsonIgnoreProperties(ignoreUnknown = true) + public static final class CreateOrderData { + + /** 仓方订单 id;列表查询的条件,取消时也要带上。 */ + @JsonProperty("orderId") + public Long orderId; + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java index 581d1ec..a0921e6 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianAdapterTest.java @@ -62,15 +62,27 @@ class HengjianAdapterTest { common.ecommerce.warehouse.enums.WarehouseCapability.LOGISTICS_PRODUCT)); } - /** 出库未接入:门面显式拒绝,不返回空列表。 */ + /** + * 下单已接、查询未接:门面能力检查放行 {@code OUTBOUND}, + * 适配器对未实现的 {@code get} 显式抛异常,不返回 null。 + */ @Test - void unimplementedOutboundIsRejected() { + void unimplementedOutboundQueryIsRejected() { WarehouseSdk sdk = sdk(); - assertThrows(WarehouseUnsupportedCapabilityException.class, + assertThrows(common.ecommerce.warehouse.error.WarehouseException.class, () -> sdk.warehouses(WH, conn()).outbound().get(OutboundRef.ofRequestNo("OB-1"))); } + /** 库存 / 入库 / 退货仍未接入:门面按能力位直接拒绝。 */ + @Test + void undeclaredCapabilityIsRejected() { + WarehouseSdk sdk = sdk(); + + assertThrows(WarehouseUnsupportedCapabilityException.class, + () -> sdk.warehouses(WH, conn()).inventory().query(null)); + } + /** 能力矩阵查询本身可用(不触发真实 API)。 */ @Test void capabilityQueryIsOffline() { diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java new file mode 100644 index 0000000..c5becfc --- /dev/null +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianCreateOrderTest.java @@ -0,0 +1,440 @@ +package common.ecommerce.hengjian.adapter; + +import common.ecommerce.hengjian.HengjianConstants; +import common.ecommerce.http.JacksonJsonCodec; +import common.ecommerce.shared.model.Platform; +import common.ecommerce.shared.spi.ChannelSecret; +import common.ecommerce.shared.support.Money; +import common.ecommerce.shared.testkit.RecordingTransport; +import common.ecommerce.shared.testkit.Responses; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.OutboundRef; +import common.ecommerce.warehouse.model.ShipTo; +import common.ecommerce.warehouse.sdk.WarehouseConnection; +import common.ecommerce.warehouse.sdk.WarehouseContext; +import common.ecommerce.warehouse.sdk.WarehouseSdk; +import common.ecommerce.warehouse.spi.WarehouseAccount; +import common.ecommerce.warehouse.testkit.InMemoryWarehouses; +import org.junit.jupiter.api.Test; + +import java.time.Clock; +import java.time.Instant; +import java.time.ZoneId; +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.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 创建销售发货单({@code POST /v1/saleOrder/create})契约测试。 + */ +class HengjianCreateOrderTest { + + private static final Instant NOW = Instant.parse("2026-11-12T03:04:05Z"); + private static final Clock CLOCK = Clock.fixed(NOW, ZoneOffset.UTC); + + private static final String CREATE_BODY = + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"创建订单成功\"," + + "\"data\":{\"orderId\":193252852}}"; + + private static WarehouseContext ctx() { + return ctx(ZoneOffset.UTC); + } + + private static WarehouseContext ctx(ZoneId zone) { + return WarehouseContext.of("HJ-EFCA", WarehouseProvider.HENGJIAN, "EFCA", + WarehouseConnection.of(HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("token-1").build(), zone), + "req-1", CLOCK); + } + + private static HengjianAdapter adapter(RecordingTransport transport) { + return new HengjianAdapter(transport, new JacksonJsonCodec()); + } + + private static RecordingTransport creating() { + return RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok(CREATE_BODY)); + } + + private static ShipTo shipTo() { + return ShipTo.builder() + .name("Test Receiver") + .phone("555-0100") + .email("buyer@example.com") + .countryCode("US") + .stateOrProvince("CA") + .city("Los Angeles") + .addressLine1("1 Test St") + .addressLine2("Suite 2") + .postalCode("90001") + .build(); + } + + private static OutboundCommand.Builder order() { + return OutboundCommand.builder() + .outboundRequestNo("OB-2026-0001") + .orderRef("SO-1") + .salesPlatform(Platform.AMAZON_SC) + .carrier("UPS") + .carrierCode("UPSG_HL") + .shopName("EFCA-STORE") + .shipTo(shipTo()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(2) + .declareValue(Money.of("9.99", "USD")) + .build()); + } + + // ---------------------------------------------------------------- 请求形状 + + @Test + void sendsPostToSaleOrderCreate() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + + assertEquals("POST", transport.lastDataRequest().method()); + assertEquals(HengjianConstants.TEST_BASE_URL + "/v1/saleOrder/create", + transport.lastDataRequest().url()); + } + + /** 文档必填的字段必须全部出现。 */ + @Test + void sendsAllMandatoryFields() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + String[] mandatory = {"orderNo", "shipToCountry", "shipToState", "shipToCity", + "shipToPostal", "shipToAddress1", "shipToContact", "shipToTelephone", + "createdAt", "productItems", "attachInfoItems"}; + for (String field : mandatory) { + assertTrue(body.contains("\"" + field + "\""), "缺少必填字段 " + field + ",body=" + body); + } + } + + /** 产品行里的四个必填子字段都要有。 */ + @Test + void productItemCarriesMandatoryFlags() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + String[] mandatory = {"sku", "quantity", "isInsure", "isSignature"}; + for (String field : mandatory) { + assertTrue(body.contains("\"" + field + "\""), "产品行缺少 " + field + ",body=" + body); + } + assertTrue(body.contains("\"sku\":\"DM00001\""), body); + assertTrue(body.contains("\"quantity\":2"), body); + } + + /** + * 恒健把 {@code attachInfoItems} 标为必填:没有附件时发空数组, + * 不能省略字段。 + */ + @Test + void sendsEmptyAttachmentArrayWhenNoLabel() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"attachInfoItems\":[]"), + "没有附件时应发空数组而不是省略,body=" + body); + } + + /** 平台面单:base64 内容进 file,类型 0,名称优先用跟踪号。 */ + @Test + void sendsPlatformLabelAsAttachment() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order() + .labelMode(LabelMode.PLATFORM_LABEL) + .trackingNumber("1ZXH1234567890") + .labelContentBase64("data:application/pdf;base64,JVBERi0xLjQK") + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"name\":\"1ZXH1234567890\""), body); + // data URI 头必须剥掉,否则仓方会把前缀当文件内容 + assertTrue(body.contains("\"file\":\"JVBERi0xLjQK\""), body); + assertFalse(body.contains("data:application/pdf"), body); + assertTrue(body.contains("\"type\":\"0\""), body); + } + + /** 声明平台面单却不给文件,本地就拒绝——仓没有面单可打等于静默失败。 */ + @Test + void rejectsPlatformLabelWithoutContent() { + RecordingTransport transport = creating(); + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(ctx(), + order().labelMode(LabelMode.PLATFORM_LABEL).build())); + assertTrue(ex.getMessage().contains("labelContentBase64"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty(), "本地校验失败不应发出请求"); + } + + /** 给了面单内容却不是平台面单模式,拒绝而不是静默丢弃。 */ + @Test + void rejectsLabelContentWithoutPlatformMode() { + RecordingTransport transport = creating(); + IllegalArgumentException ex = assertThrows(IllegalArgumentException.class, + () -> adapter(transport).create(ctx(), + order().labelContentBase64("JVBERi0xLjQK").build())); + assertTrue(ex.getMessage().contains("PLATFORM_LABEL"), ex.getMessage()); + assertTrue(transport.dataRequests().isEmpty()); + } + + /** 时间按 UTC 输出,不受调用方传的时区影响。 */ + @Test + void formatsTimesInUtc() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(ZoneId.of("America/Los_Angeles")), + order().latestShipDate(Instant.parse("2026-11-15T23:30:00Z")).build()); + String body = transport.lastDataRequest().body(); + + // createdAt 用注入的固定时钟 + assertTrue(body.contains("\"createdAt\":\"2026-11-12 03:04:05\""), body); + assertTrue(body.contains("\"expectedShipDate\":\"2026-11-15 23:30:00\""), + "恒健要求 UTC,不能按仓所在时区输出,body=" + body); + } + + /** 行金额是「当前 SKU 总金额」,申报单价要乘数量。 */ + @Test + void skuAmountIsLineTotalNotUnitPrice() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + // 9.99 × 2 = 19.98 + assertTrue(body.contains("\"skuAmount\":19.98"), "skuAmount 必须是行总额,body=" + body); + } + + @Test + void usesExplicitTotalAmountWhenGiven() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), OutboundCommand.builder() + .outboundRequestNo("OB-2") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(shipTo()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(3) + .declareValue(Money.of("10.00", "USD")) + .totalAmount(Money.of("28.00", "USD")) + .build()) + .build()); + + assertTrue(transport.lastDataRequest().body().contains("\"skuAmount\":28.0")); + } + + /** 保价由「是否有保价金额」推导;有金额就要带 insureAmount。 */ + @Test + void insuredLineSendsFlagAndAmount() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), OutboundCommand.builder() + .outboundRequestNo("OB-3") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(shipTo()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku("DM00001") + .quantity(1) + .insuredAmount(Money.of("100.00", "USD")) + .build()) + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"isInsure\":1"), body); + assertTrue(body.contains("\"insureAmount\":100.0"), body); + } + + @Test + void uninsuredLineSendsZero() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + + assertTrue(transport.lastDataRequest().body().contains("\"isInsure\":0")); + } + + /** 签收:布尔值映射成 1 / 0;null 视为不签收(恒健必填,不能省略)。 */ + @Test + void signatureFlagIsMandatoryAndMapped() { + RecordingTransport required = creating(); + adapter(required).create(ctx(), order().signatureRequired(true).build()); + assertTrue(required.lastDataRequest().body().contains("\"isSignature\":1")); + + RecordingTransport notRequired = creating(); + adapter(notRequired).create(ctx(), order().build()); + assertTrue(notRequired.lastDataRequest().body().contains("\"isSignature\":0")); + } + + @Test + void mapsShopCurrencyAndCarrier() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order() + .currency("CAD") + .sfp(true) + .remark("买家备注") + .build()); + String body = transport.lastDataRequest().body(); + + assertTrue(body.contains("\"channelAccount\":\"EFCA-STORE\""), body); + assertTrue(body.contains("\"currency\":\"CAD\""), body); + assertTrue(body.contains("\"carrier\":\"UPS\""), body); + assertTrue(body.contains("\"carrierCode\":\"UPSG_HL\""), body); + assertTrue(body.contains("\"isPrime\":1"), body); + assertTrue(body.contains("\"customerRemark\":\"买家备注\""), body); + } + + /** 恒健没有平台维度:salesPlatform 不发,也不拿它推 isDFOrder。 */ + @Test + void doesNotSendSalesPlatformOrInferDfOrder() { + RecordingTransport transport = creating(); + adapter(transport).create(ctx(), order().build()); + String body = transport.lastDataRequest().body(); + + assertFalse(body.contains("salesPlatform"), body); + assertFalse(body.contains("isDFOrder"), body); + } + + /** 仓代码:命令显式指定优先,否则用账户配置。 */ + @Test + void warehouseCodeResolvesFromCommandThenAccount() { + RecordingTransport fromCommand = creating(); + adapter(fromCommand).create(ctx(), order().warehouseId("EFNJ").build()); + assertTrue(fromCommand.lastDataRequest().body().contains("\"warehouseCode\":\"EFNJ\"")); + + RecordingTransport fromAccount = creating(); + adapter(fromAccount).create(ctx(), order().build()); + assertTrue(fromAccount.lastDataRequest().body().contains("\"warehouseCode\":\"EFCA\"")); + } + + // ---------------------------------------------------------------- 本地必填校验 + + @Test + void rejectsMissingShipToFields() { + String[] fields = {"countryCode", "stateOrProvince", "postalCode", "addressLine1", + "name", "phone", "city"}; + for (String field : fields) { + ShipTo.Builder b = ShipTo.builder() + .name("N").phone("P").countryCode("US").stateOrProvince("CA") + .city("C").addressLine1("A").postalCode("Z"); + if ("countryCode".equals(field)) { + b.countryCode(null); + } else if ("stateOrProvince".equals(field)) { + b.stateOrProvince(null); + } else if ("postalCode".equals(field)) { + b.postalCode(null); + } else if ("addressLine1".equals(field)) { + b.addressLine1(null); + } else if ("name".equals(field)) { + b.name(null); + } else if ("phone".equals(field)) { + b.phone(null); + } else { + b.city(null); + } + OutboundCommand cmd = OutboundCommand.builder() + .outboundRequestNo("OB-X") + .salesPlatform(Platform.AMAZON_SC) + .shipTo(b.build()) + .line(OutboundLine.builder().lineNo("1").omsSku("S").quantity(1).build()) + .build(); + assertThrows(IllegalArgumentException.class, + () -> adapter(creating()).create(ctx(), cmd), field); + } + } + + // ---------------------------------------------------------------- 响应 + + @Test + void readsProviderOrderIdFromData() { + RecordingTransport transport = creating(); + OutboundReceipt receipt = adapter(transport).create(ctx(), order().build()); + + assertEquals("OB-2026-0001", receipt.outboundRequestNo()); + assertEquals("193252852", receipt.providerOrderId(), "仓内部数字 id 必须落库,取消时要用"); + assertEquals("创建订单成功", receipt.rawStatus()); + } + + /** 没有 orderId 不能当成功:后续取消需要它。 */ + @Test + void rejectsResponseWithoutOrderId() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok( + "{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(ctx(), order().build())); + assertTrue(ex.getMessage().contains("data.orderId"), ex.getMessage()); + } + + @Test + void businessErrorIsPropagated() { + RecordingTransport transport = RecordingTransport.create() + .route(HengjianConstants.PATH_ORDER_CREATE, req -> Responses.ok( + "{\"code\":500,\"message\":\"仓库不存在\"}")); + + RuntimeException ex = assertThrows(RuntimeException.class, + () -> adapter(transport).create(ctx(), order().build())); + assertTrue(ex.getMessage().contains("仓库不存在"), ex.getMessage()); + } + + // ---------------------------------------------------------------- 能力位与未接入接口 + + @Test + void declaresOutboundAndLabelCapabilities() { + HengjianAdapter adapter = adapter(RecordingTransport.create()); + + assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.PLATFORM_LABEL_DELIVERY)); + } + + /** 查询 / 取消还没接:显式拒绝,不返回 null 或空集合。 */ + @Test + void unimplementedOutboundMethodsThrow() { + HengjianAdapter adapter = adapter(RecordingTransport.create()); + + assertThrows(RuntimeException.class, + () -> adapter.get(ctx(), OutboundRef.ofRequestNo("OB-1"))); + assertThrows(RuntimeException.class, + () -> adapter.packages(ctx(), OutboundRef.ofRequestNo("OB-1"))); + assertThrows(RuntimeException.class, + () -> adapter.checkCancel(ctx(), OutboundRef.ofRequestNo("OB-1"))); + assertThrows(RuntimeException.class, + () -> adapter.cancel(ctx(), common.ecommerce.warehouse.model.CancelCommand.builder() + .outboundRequestNo("OB-1").build())); + } + + /** 未声明的能力位仍然被门面挡住(INVENTORY_QUERY 还没接)。 */ + @Test + void undeclaredCapabilityIsRejectedByFacade() { + WarehouseSdk sdk = WarehouseSdk.builder() + .warehouseRepository(new InMemoryWarehouses().put(WarehouseAccount.builder() + .warehouseCode("HJ-EFCA") + .provider(WarehouseProvider.HENGJIAN.name()) + .providerWarehouseId("EFCA") + .credentialRef("kms://test") + .timeZone("America/Los_Angeles") + .build())) + .clock(CLOCK) + .register(new HengjianAdapterFactory()) + .build(); + + assertThrows(WarehouseUnsupportedCapabilityException.class, + () -> sdk.warehouses("HJ-EFCA", WarehouseConnection.of( + HengjianConstants.TEST_BASE_URL, + ChannelSecret.builder().appSecret("t").build(), + ZoneOffset.UTC)) + .inventory().query(null)); + } +} diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java index 8854855..dde4c2d 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/adapter/HengjianDirectoryTest.java @@ -227,14 +227,14 @@ class HengjianDirectoryTest { // ---------------------------------------------------------------- 能力位 @Test - void declaresDirectoryAndProductCapabilitiesOnly() { + void declaresExpectedCapabilities() { HengjianAdapter adapter = adapter(RecordingTransport.create()); assertTrue(adapter.capabilities().contains(WarehouseCapability.DIRECTORY)); assertTrue(adapter.capabilities().contains(WarehouseCapability.LOGISTICS_PRODUCT)); assertTrue(adapter.capabilities().contains(WarehouseCapability.PRODUCT)); - // 出库 / 库存 / 入库 / 退货都还没接:声明了就必须有实现 - assertTrue(!adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + assertTrue(adapter.capabilities().contains(WarehouseCapability.OUTBOUND)); + // 库存 / 入库 / 退货 / 回调都还没接:声明了就必须有实现 assertTrue(!adapter.capabilities().contains(WarehouseCapability.INVENTORY_QUERY)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.INBOUND)); assertTrue(!adapter.capabilities().contains(WarehouseCapability.RETURN)); diff --git a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java index a272dfb..7feaae8 100644 --- a/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java +++ b/warehouse-sdk-hengjian/src/test/java/common/ecommerce/hengjian/probe/HengjianWriteProbeTest.java @@ -4,11 +4,16 @@ import common.ecommerce.hengjian.HengjianConstants; import common.ecommerce.hengjian.adapter.HengjianAdapter; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.OkHttpTransport; +import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.model.OutboundCommand; +import common.ecommerce.warehouse.model.OutboundLine; +import common.ecommerce.warehouse.model.OutboundReceipt; +import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext; import org.junit.jupiter.api.Assumptions; @@ -123,4 +128,64 @@ class HengjianWriteProbeTest { + " ← 若非幂等保存,这里会报 SKU 已存在"); } } + + // ================================================================ 出库 + + /** + * 建销售发货单:验证必填组合、时间格式与 {@code data.orderId} 是否真回。 + * + *需要 {@code -Dhengjian.probe.postcode};SKU 用 {@link #SKU}, + * 所以要先把商品建出来({@link #probeProductSave})。
+ * + *会在仓方测试环境留一张真实订单。探针不自动取消——取消接口尚未接入。
+ */ + @Test + void probeCreateSaleOrder() { + assumeToken(); + String postcode = opt("hengjian.probe.postcode", ""); + Assumptions.assumeTrue(!postcode.isEmpty(), + "未提供 -Dhengjian.probe.postcode,跳过建单探针"); + System.out.println("\n================ hengjian / v1/saleOrder/create ================"); + System.out.println(" orderNo=" + orderNo() + " warehouse=" + PROVIDER_WAREHOUSE + + " sku=" + SKU + " postcode=" + postcode); + try { + OutboundReceipt receipt = adapter().create(ctx(), command(postcode)); + System.out.println(" [OK] outboundRequestNo=" + receipt.outboundRequestNo() + + " providerOrderId=" + receipt.providerOrderId() + + " rawStatus=" + receipt.rawStatus()); + System.out.println(" ← providerOrderId 是仓内部数字 id,取消接口要同时用它和单号"); + } catch (RuntimeException e) { + System.out.println(" [FAIL] " + e.getClass().getSimpleName() + ": " + e.getMessage()); + } + } + + private static String orderNo() { + return "PROBE-OB-" + System.currentTimeMillis(); + } + + private static OutboundCommand command(String postcode) { + return OutboundCommand.builder() + .outboundRequestNo(orderNo()) + .salesPlatform(Platform.AMAZON_SC) + .carrier("UPS") + .carrierCode(opt("hengjian.probe.carrierCode", "UPSG_HL")) + .shopName(opt("hengjian.probe.shopName", "")) + .currency("USD") + .shipTo(ShipTo.builder() + .name("Probe Receiver") + .phone("5550000000") + .countryCode("US") + .stateOrProvince(opt("hengjian.probe.state", "CA")) + .city(opt("hengjian.probe.city", "Los Angeles")) + .addressLine1("1 Probe St") + .postalCode(postcode) + .build()) + .line(OutboundLine.builder() + .lineNo("1") + .omsSku(SKU) + .quantity(1) + .declareValue(Money.of("1.00", "USD")) + .build()) + .build(); + } }