Browse Source
- 新增 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 <noreply@anthropic.com>master
10 changed files with 1168 additions and 44 deletions
@ -0,0 +1,243 @@
@@ -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})。 |
||||
* |
||||
* <p>平台字段名只出现在本类与 {@link HengjianCreateOrderDtos}。</p> |
||||
* |
||||
* <h2>时间</h2> |
||||
* <p>恒健的时间字段是 <b>UTC</b> 的 {@code yyyy-MM-dd HH:mm:ss}(文档明确写了 utc 时间), |
||||
* 所以格式化固定按 {@link ZoneOffset#UTC},<b>不用</b> {@code WarehouseContext.zone()}—— |
||||
* 那个时区是给「仓方回传的无时区本地时间」用的,方向相反。</p> |
||||
* |
||||
* <h2>必填项</h2> |
||||
* <p>{@code createdAt} 在统一模型里没有对应字段,用调用方注入的 {@link Clock} 生成 |
||||
* 「下单时刻」。这是请求侧的时间戳,不是把仓方没给的数据编出来; |
||||
* 幂等重放时它会变,但恒健不拿它做去重。</p> |
||||
* |
||||
* <h2>统一模型里恒健没有对应概念的字段</h2> |
||||
* <table border="1"> |
||||
* <tr><th>字段</th><th>处理</th></tr> |
||||
* <tr><td>{@code salesPlatform}</td> |
||||
* <td>恒健没有平台维度,店铺路由走 {@code channelAccount}。<b>不发</b>, |
||||
* 也不拿它去推断 {@code isDFOrder}——VC 订单里只有一部分是 DF。</td></tr> |
||||
* <tr><td>{@code splitOrder} / {@code packages}</td> |
||||
* <td>恒健没有拆单入参与包裹入参,忽略。</td></tr> |
||||
* <tr><td>{@code estimatedDeliveryTime}</td> |
||||
* <td>恒健只有 {@code expectedShipDate}(要求发货时间),没有送达时间。</td></tr> |
||||
* <tr><td>{@code declaredTotal}</td> |
||||
* <td>恒健按行收金额,没有整单申报额。</td></tr> |
||||
* </table> |
||||
*/ |
||||
public final class HengjianOutboundMapper { |
||||
|
||||
/** 恒健只接受 UTC 的 {@code yyyy-MM-dd HH:mm:ss}。 */ |
||||
private static final DateTimeFormatter TIME_FORMAT = |
||||
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
||||
|
||||
/** 附件类型:面单。 */ |
||||
private static final String ATTACH_TYPE_SHIPPING_LABEL = "0"; |
||||
|
||||
/** 保价 / 签收开关的取值。 */ |
||||
private static final int FLAG_NO = 0; |
||||
private static final int FLAG_YES = 1; |
||||
|
||||
/** 唯一支持的签收类型:直接签收(成人 / 间接签收统一模型表达不了)。 */ |
||||
private static final int SIGNATURE_DIRECT = 1; |
||||
|
||||
private HengjianOutboundMapper() { |
||||
} |
||||
|
||||
/** |
||||
* 统一命令 → 恒健创建订单请求。 |
||||
* |
||||
* @param warehouseCode 仓代码(命令显式指定优先,其次账户配置);null 时由仓方按默认仓处理 |
||||
* @param clock 用于生成必填的 {@code createdAt} |
||||
* @throws IllegalArgumentException 缺少恒健必填但统一模型可空的字段 |
||||
*/ |
||||
public static HengjianCreateOrderDtos.CreateOrderRequest toRequest(OutboundCommand cmd, |
||||
String warehouseCode, |
||||
Clock clock) { |
||||
HengjianCreateOrderDtos.CreateOrderRequest req = new HengjianCreateOrderDtos.CreateOrderRequest(); |
||||
String orderNo = cmd.outboundRequestNo(); |
||||
req.orderNo = orderNo; |
||||
req.warehouseCode = trimToNull(warehouseCode); |
||||
req.carrier = trimToNull(cmd.carrier()); |
||||
req.carrierCode = trimToNull(cmd.carrierCode()); |
||||
// 店铺:仓方按店铺做路由 / 计费;标准模型对应 shopName
|
||||
req.channelAccount = trimToNull(cmd.shopName()); |
||||
req.currency = trimToNull(cmd.currency()); |
||||
req.shipServiceLevel = trimToNull(cmd.shipServiceLevel()); |
||||
// 平台要求发货时间;恒健只在 isDFOrder=1 时强制,但有值就带上
|
||||
req.expectedShipDate = formatTime(cmd.latestShipDate()); |
||||
req.isPrime = flagOf(cmd.sfp()); |
||||
req.createdAt = formatTime(Instant.now(clock)); |
||||
req.customerRemark = trimToNull(cmd.remark()); |
||||
|
||||
ShipTo shipTo = cmd.shipTo(); |
||||
req.shipToCountry = require(shipTo.countryCode(), "shipTo.countryCode", orderNo); |
||||
req.shipToState = require(shipTo.stateOrProvince(), "shipTo.stateOrProvince", orderNo); |
||||
req.shipToPostal = require(shipTo.postalCode(), "shipTo.postalCode", orderNo); |
||||
req.shipToAddress1 = require(shipTo.addressLine1(), "shipTo.addressLine1", orderNo); |
||||
req.shipToContact = require(shipTo.name(), "shipTo.name", orderNo); |
||||
req.shipToTelephone = require(shipTo.phone(), "shipTo.phone", orderNo); |
||||
// 城市:中文页标必填、英文页未标,按必填处理
|
||||
req.shipToCity = require(shipTo.city(), "shipTo.city", orderNo); |
||||
req.shipToAddress2 = trimToNull(shipTo.addressLine2()); |
||||
req.customerEmail = trimToNull(shipTo.email()); |
||||
|
||||
req.productItems = toProductItems(cmd.lines(), cmd.signatureRequired(), orderNo); |
||||
req.attachInfoItems = toAttachInfoItems(cmd, orderNo); |
||||
return req; |
||||
} |
||||
|
||||
/** 仓方仓编码:命令显式指定优先,否则用账户配置。 */ |
||||
public static String resolveWarehouseCode(String fromCommand, String fromAccount) { |
||||
return trimToNull(fromCommand) != null ? trimToNull(fromCommand) : trimToNull(fromAccount); |
||||
} |
||||
|
||||
private static List<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem> toProductItems( |
||||
List<OutboundLine> lines, Boolean signatureRequired, String orderNo) { |
||||
boolean signature = Boolean.TRUE.equals(signatureRequired); |
||||
List<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem> items = |
||||
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.ProductItem>(lines.size()); |
||||
for (OutboundLine line : lines) { |
||||
HengjianCreateOrderDtos.CreateOrderRequest.ProductItem item = |
||||
new HengjianCreateOrderDtos.CreateOrderRequest.ProductItem(); |
||||
item.sku = line.providerSku() != null && !line.providerSku().trim().isEmpty() |
||||
? line.providerSku().trim() : line.omsSku(); |
||||
item.quantity = line.quantity(); |
||||
|
||||
// 保价:统一模型只有「保价金额」,有金额即视为保价
|
||||
boolean insured = line.insuredAmount() != null; |
||||
item.isInsure = insured ? FLAG_YES : FLAG_NO; |
||||
if (insured) { |
||||
item.insureAmount = line.insuredAmount().amount().doubleValue(); |
||||
} |
||||
|
||||
// 签收:恒健的 isSignature 挂在行上,统一模型挂在命令上。
|
||||
// 语义是整单都要 / 都不要,所以取命令上的值套到每一行。
|
||||
// 统一模型只有布尔值,表达不了成人签收(2) / 间接签收(3),
|
||||
// 统一映射成「直接签收(1)」——比静默降成「不签收(0)」安全
|
||||
item.isSignature = signature ? SIGNATURE_DIRECT : FLAG_NO; |
||||
|
||||
item.skuAmount = skuTotalAmount(line); |
||||
items.add(item); |
||||
} |
||||
return items; |
||||
} |
||||
|
||||
/** |
||||
* 行总金额。 |
||||
* |
||||
* <p>恒健 {@code skuAmount} 是「当前 SKU 总金额」,<b>不是单价</b>: |
||||
* 有 {@code totalAmount} 直接用;没有就用申报单价 × 数量, |
||||
* 否则整单金额会少算 quantity 倍(运去哪踩过同样的坑)。</p> |
||||
*/ |
||||
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(); |
||||
} |
||||
|
||||
/** |
||||
* 附件:平台面单随单下发。 |
||||
* |
||||
* <p>恒健把 {@code attachInfoItems} 标为<b>必填</b>,所以没有附件时返回空数组, |
||||
* 不省略该字段——省略会被当成缺必填项。</p> |
||||
* |
||||
* <p>仓自有面单({@link LabelMode#WAREHOUSE_LABEL})时不给附件; |
||||
* 给了面单内容却不是平台面单模式,直接拒绝,不静默丢弃。</p> |
||||
*/ |
||||
private static List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> toAttachInfoItems( |
||||
OutboundCommand cmd, String orderNo) { |
||||
String content = cmd.labelContentBase64(); |
||||
if (content == null || content.trim().isEmpty()) { |
||||
if (cmd.labelMode() == LabelMode.PLATFORM_LABEL) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian order " + orderNo |
||||
+ ": labelContentBase64 is required when labelMode=PLATFORM_LABEL"); |
||||
} |
||||
return new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>(); |
||||
} |
||||
if (cmd.labelMode() != LabelMode.PLATFORM_LABEL) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian order " + orderNo |
||||
+ ": labelContentBase64 requires labelMode=PLATFORM_LABEL"); |
||||
} |
||||
HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem item = |
||||
new HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem(); |
||||
// 文档建议附件名填跟踪号且不带后缀;没有运单号时退回出库单号
|
||||
String tracking = trimToNull(cmd.trackingNumber()); |
||||
item.name = tracking != null ? tracking : orderNo; |
||||
// 恒健同一个字段 url / file 二选一,file 优先;文档没说 file 支持 data URI 头,
|
||||
// 这里统一剥掉,避免把 "data:application/pdf;base64," 当成文件内容解出来
|
||||
item.file = stripDataUri(content); |
||||
item.type = ATTACH_TYPE_SHIPPING_LABEL; |
||||
List<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem> out = |
||||
new ArrayList<HengjianCreateOrderDtos.CreateOrderRequest.AttachInfoItem>(1); |
||||
out.add(item); |
||||
return Collections.unmodifiableList(out); |
||||
} |
||||
|
||||
/** 去掉 {@code data:xxx/base64,} 头;没有头时原样返回。 */ |
||||
static String stripDataUri(String content) { |
||||
if (content == null) { |
||||
return null; |
||||
} |
||||
int comma = content.indexOf(','); |
||||
if (content.startsWith("data:") && comma > 0) { |
||||
return content.substring(comma + 1); |
||||
} |
||||
return content; |
||||
} |
||||
|
||||
/** 时间 → 恒健的 UTC {@code yyyy-MM-dd HH:mm:ss};null 透传。 */ |
||||
static String formatTime(Instant instant) { |
||||
return instant == null ? null : TIME_FORMAT.format(instant.atZone(ZoneOffset.UTC)); |
||||
} |
||||
|
||||
/** 布尔开关 → 0 / 1;null 不发(由仓方按默认否处理)。 */ |
||||
private static Integer flagOf(Boolean flag) { |
||||
return flag == null ? null : (flag ? FLAG_YES : FLAG_NO); |
||||
} |
||||
|
||||
private static String require(String value, String field, String orderNo) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
throw new IllegalArgumentException( |
||||
"hengjian order " + orderNo + " requires " + field + " (恒健下单必填)"); |
||||
} |
||||
return v; |
||||
} |
||||
|
||||
private static String trimToNull(String v) { |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
String trimmed = v.trim(); |
||||
return trimmed.isEmpty() ? null : trimmed; |
||||
} |
||||
} |
||||
@ -0,0 +1,200 @@
@@ -0,0 +1,200 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonInclude; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:创建销售发货单({@code POST /v1/saleOrder/create})。 |
||||
* |
||||
* <p>中英文两页文档描述的是同一个接口,中文页叫「创建销售发货单(带附件的)」, |
||||
* 英文页叫「Create Sale Order With Label」;两页字段表基本一致,差异见各字段注释。</p> |
||||
* |
||||
* <p><b>两页的必填口径不完全一致</b>:中文页把 {@code createdAt} 标为必填、英文页也标 Y; |
||||
* 但中文页没有 {@code isPrime}(只有英文页有),英文页没有 {@code customerRemark} / |
||||
* {@code warehouseRemark}(只有中文页有)。按两页并集实现,必填取两页都要求的字段。</p> |
||||
*/ |
||||
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};不填由仓方取当前时间。 |
||||
* |
||||
* <p>统一模型没有「支付时间」字段,这里通常不传。</p> |
||||
*/ |
||||
public String paidAt; |
||||
|
||||
/** Amazon VC Direct Fulfillment 订单:0 否 / 1 是;不填默认为否。 */ |
||||
public Integer isDFOrder; |
||||
|
||||
/** |
||||
* 是否 SFP 订单:0 否 / 1 是;不填默认为否。 |
||||
* |
||||
* <p><b>文档类型写的是 String,但请求示例给的是数字 {@code "isPrime": 0}</b>。 |
||||
* 这里按示例用 Integer——两页示例一致,且 Spring 后端按数字绑定的可能性更高。 |
||||
* 真机若报类型错,改成 String 即可。</p> |
||||
*/ |
||||
public Integer isPrime; |
||||
|
||||
/** |
||||
* 平台要求发货时间,UTC,{@code yyyy-MM-dd HH:mm:ss}。 |
||||
* |
||||
* <p>文档:{@code isDFOrder=1} 时必填。</p> |
||||
*/ |
||||
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<ProductItem> productItems; |
||||
|
||||
/** |
||||
* 附件信息;<b>两页文档都标必填</b>。 |
||||
* |
||||
* <p>没有附件时发空数组而不是省略该字段——省略会被仓方当成缺必填项。</p> |
||||
*/ |
||||
public List<AttachInfoItem> attachInfoItems; |
||||
|
||||
/** 产品行。 */ |
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class ProductItem { |
||||
|
||||
/** 发货产品 SKU;必填。 */ |
||||
public String sku; |
||||
|
||||
/** 发货数量;必填。 */ |
||||
public Integer quantity; |
||||
|
||||
/** 是否保价:0 否 / 1 是;必填。 */ |
||||
public Integer isInsure; |
||||
|
||||
/** |
||||
* 签收类型:0 否 / 1 直接签收 / 2 成人签收 / 3 间接签收(仅 FedEx);必填。 |
||||
* |
||||
* <p>统一模型只有布尔型的 {@code signatureRequired},表达不了 2 / 3。</p> |
||||
*/ |
||||
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; |
||||
} |
||||
} |
||||
@ -0,0 +1,440 @@
@@ -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)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue