package common.ecommerce.xincang.adapter; import common.ecommerce.http.JsonCodec; import common.ecommerce.shared.error.ChannelException; import common.ecommerce.shared.error.ValidationException; import common.ecommerce.shared.model.Platform; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.dto.XincangDtos; import common.ecommerce.xincang.enums.XincangOrderType; import java.time.Instant; import java.time.LocalDateTime; import java.time.format.DateTimeFormatter; import java.util.ArrayList; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; /** * 信仓出库下单报文映射({@code POST api.add_order_multiple})。 * *

该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON 字符串。 * 平台字段名只出现在本类与 {@link XincangDtos}。

* *

文档没有对应字段的就不发:申报信息(HS / 原产国 / 申报价值)、包裹尺寸等 * 统一模型里有,但信仓这版接口不收,硬塞只会被忽略或报错。

*/ public final class XincangOrderMapper { /** 信仓要求发货时间格式 {@code yyyy-MM-dd HH:mm:ss}(北京时间)。 */ private static final DateTimeFormatter REQUIRED_DELIVERY_TIME = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); /** 地址 1 上限 32 字符,超出部分走 address2。 */ private static final int ADDRESS_MAX = 32; /** 信仓布尔字段统一用「是 / 否」。 */ private static final String YES = "是"; private static final String NO = "否"; /** 签名服务:模型无对应字段,固定否。 */ private static final String SIGN_NOT_REQUIRED = NO; private XincangOrderMapper() { } /** * 统一命令 → 信仓一单多件下单表单。 * * @param ctx 本次调用上下文(取仓编码) * @param cmd 出库命令 * @param json 用于序列化 {@code products} * @throws ValidationException 缺少仓编码或收件人必填项 */ public static Map toForm(WarehouseContext ctx, OutboundCommand cmd, JsonCodec json) { ShipTo shipTo = cmd.shipTo(); requireText(shipTo.name(), "shipTo.name", ctx); requireText(shipTo.phone(), "shipTo.phone", ctx); requireText(shipTo.countryCode(), "shipTo.countryCode", ctx); requireText(shipTo.stateOrProvince(), "shipTo.stateOrProvince", ctx); requireText(shipTo.city(), "shipTo.city", ctx); requireText(shipTo.postalCode(), "shipTo.postalCode", ctx); requireText(shipTo.addressLine1(), "shipTo.addressLine1", ctx); String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId()); requireText(warehouseCode, "warehouseCode", ctx); // 信仓 logistics_type 是必填的物流方式字典值,这里用 carrierCode 承载 requireText(cmd.carrierCode(), "carrierCode (信仓 logistics_type)", ctx); Map form = new LinkedHashMap(); XincangOrderType orderType = orderTypeOf(cmd.salesPlatform()); form.put("order_type", orderType.rawCode()); form.put("warehouse_code", warehouseCode); // ckh = 参考号,信仓要求唯一;用 OMS 出库单号,便于回查 form.put("ckh", cmd.outboundRequestNo()); Address address = splitAddress(shipTo.addressLine1()); form.put("country", shipTo.countryCode().trim()); form.put("province", shipTo.stateOrProvince().trim()); form.put("city", shipTo.city().trim()); form.put("address", address.line1); putIfPresent(form, "address2", address.line2); form.put("postcode", shipTo.postalCode().trim()); form.put("receive_user", shipTo.name().trim()); form.put("phone", shipTo.phone().trim()); putIfPresent(form, "email", shipTo.email()); form.put("logistics_type", cmd.carrierCode().trim()); form.put("is_sign", SIGN_NOT_REQUIRED); form.put("products", productsJson(cmd.lines(), json)); putIfPresent(form, "shop_name", cmd.shopName()); if (cmd.sfp() != null) { form.put("sfp", cmd.sfp() ? YES : NO); } // wayfair(自供面单)时 gzh + face_base64 都是必填,缺了必然被仓拒绝,这里提前挡 if (orderType.requiresSelfLabel()) { requireText(cmd.trackingNumber(), "trackingNumber (信仓 gzh,wayfair 必填)", ctx); requireText(cmd.labelContentBase64(), "labelContentBase64 (信仓 face_base64,wayfair 必填)", ctx); } putIfPresent(form, "gzh", cmd.trackingNumber()); putIfPresent(form, "face_base64", cmd.labelContentBase64()); // 不传 is_split 时信仓默认 1(拆单);只有调用方显式给值才下发 if (cmd.splitOrder() != null) { form.put("is_split", cmd.splitOrder() ? "1" : "0"); } Instant latest = cmd.latestShipDate(); if (latest != null) { form.put("required_delivery_time", REQUIRED_DELIVERY_TIME.format( LocalDateTime.ofInstant(latest, XincangConstants.SYSTEM_ZONE))); } // 该接口的 schema 没有 remark,不发 return form; } /** 商品明细:{@code [{"product_sku":"...","sku_count":"1"}, ...]}。 */ static String productsJson(List lines, JsonCodec json) { List products = new ArrayList(lines.size()); for (OutboundLine line : lines) { XincangDtos.OrderProduct product = new XincangDtos.OrderProduct(); product.productSku = skuOf(line); product.skuCount = String.valueOf(line.quantity()); products.add(product); } return json.toJson(products); } /** 仓侧 SKU 优先;没有映射时用 OMS 主 SKU。 */ static String skuOf(OutboundLine line) { String providerSku = line.providerSku(); if (providerSku != null && !providerSku.trim().isEmpty()) { return providerSku.trim(); } return line.omsSku(); } /** * 销售平台 → 信仓订单类型({@link XincangOrderType})。 * *

Wayfair 渠道走 {@code wayfair};其余平台走 {@code common}。 * 信仓不区分其它平台,不做臆造映射。

*/ static XincangOrderType orderTypeOf(Platform platform) { return platform == Platform.WAYFAIR ? XincangOrderType.WAYFAIR : XincangOrderType.COMMON; } /** 地址超过 32 字符的部分截到 address2,避免被仓侧截断丢信息。 */ static Address splitAddress(String address) { String trimmed = address.trim(); if (trimmed.length() <= ADDRESS_MAX) { return new Address(trimmed, null); } return new Address(trimmed.substring(0, ADDRESS_MAX), trimmed.substring(ADDRESS_MAX)); } /** 拆好的地址。 */ static final class Address { final String line1; final String line2; Address(String line1, String line2) { this.line1 = line1; this.line2 = line2; } } private static void putIfPresent(Map form, String key, String value) { if (value != null && !value.trim().isEmpty()) { form.put(key, value.trim()); } } private static String requireText(String value, String field, WarehouseContext ctx) { if (value == null || value.trim().isEmpty()) { throw new ValidationException(ChannelException.builder() .message("xincang outbound requires " + field) .operation("warehouse.outbound.create") .provider(WarehouseProvider.XINCANG.name()) .requestId(ctx.requestId()) .retryable(false)); } return value.trim(); } private static String firstNonBlank(String a, String b) { if (a != null && !a.trim().isEmpty()) { return a.trim(); } return b == null ? null : b.trim(); } }