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}恒健按行收金额,没有整单申报额。
*/ 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 toProductItems( List lines, Boolean signatureRequired, String orderNo) { boolean signature = Boolean.TRUE.equals(signatureRequired); List items = new ArrayList(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; } /** * 行总金额。 * *

恒健 {@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 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(); } 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 out = new ArrayList(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; } }