Browse Source
- 新增 HengjianOrderDetailDtos / HengjianOrderListDtos / HengjianOrderMapper, 实现 OutboundCapable.get / query / checkCancel / packages - 新增 HengjianOrderStatus:8 个 orderStatusEnum 值精确匹配,未识别归 UNKNOWN; core OutboundStatus 追加 REFUNDED(180)——退款与取消语义不同,合并会分不清是否已发货 - 详情不回 orderId:providerOrderId 保持 null,不编造;列表是唯一回 orderId 的接口 - skuAmount 是行总额落 totalAmount;恒健不回申报单价,declareValue 留空 - 列表:时间/单号二者必填其一(否则本地拒绝)、跨度上限 30 天、rows 截断 100、 状态过滤显式拒绝;游标是页码,末页以仓方 last 为准 - 时间按 UTC 解析(文档声明 utc),不用仓时区 - 包裹从详情 shipmentPackages 提取,按 trackingNo 去重且实际包裹优先 - 取消预判按状态推断,查不到单判 BLOCKED 而不是猜 FREE;cancel 仍未接入 - 只读探针补订单详情 / 订单列表用例 验证:mvn test 全量通过,恒健 99 个用例 + 2 个探针跳过。 Co-Authored-By: Claude Code <noreply@anthropic.com>master
13 changed files with 1854 additions and 40 deletions
@ -0,0 +1,411 @@
@@ -0,0 +1,411 @@
|
||||
package common.ecommerce.hengjian.adapter; |
||||
|
||||
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; |
||||
import common.ecommerce.hengjian.dto.HengjianOrderListDtos; |
||||
import common.ecommerce.hengjian.enums.HengjianOrderStatus; |
||||
import common.ecommerce.shared.support.Money; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.OutboundLine; |
||||
import common.ecommerce.warehouse.model.OutboundOrder; |
||||
import common.ecommerce.warehouse.model.ShipTo; |
||||
import common.ecommerce.warehouse.model.WarehouseAttachment; |
||||
|
||||
import java.math.BigDecimal; |
||||
import java.time.Instant; |
||||
import java.time.LocalDateTime; |
||||
import java.time.ZoneOffset; |
||||
import java.time.format.DateTimeFormatter; |
||||
import java.time.format.DateTimeParseException; |
||||
import java.util.ArrayList; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健订单报文 → 统一模型(详情 / 列表共用)。 |
||||
* |
||||
* <p>两个接口回的字段高度重合,行模型也一致;差异只在 |
||||
* {@code orderId} / {@code channelFlag} / {@code amount} / {@code taxPrice} |
||||
* (列表独有)与 {@code estimatedShippingFeeItems}(详情独有)。</p> |
||||
* |
||||
* <h2>时间</h2> |
||||
* <p>恒健声明时间字段是 utc 的 {@code yyyy-MM-dd HH:mm:ss},这里<b>按 UTC 解析</b>, |
||||
* 不用 {@code WarehouseContext.zone()}——那个时区是给「仓方回传的无时区本地时间」用的, |
||||
* 而恒健已经明确是 UTC。</p> |
||||
* |
||||
* <h2>双号</h2> |
||||
* <p>详情<b>只回 {@code orderNo}</b>(我们的来源单号),列表才回 {@code orderId}。 |
||||
* 所以:</p> |
||||
* <ul> |
||||
* <li>{@code outboundRequestNo} = {@code orderNo};</li> |
||||
* <li>{@code providerOrderId} = {@code orderId}(详情查不到时为 null,<b>不编</b>);</li> |
||||
* <li>{@code orderRef} 恒为 null——恒健不回传平台单号。</li> |
||||
* </ul> |
||||
*/ |
||||
public final class HengjianOrderMapper { |
||||
|
||||
/** 恒健时间格式(UTC)。 */ |
||||
private static final DateTimeFormatter TIME_FORMAT = |
||||
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
||||
|
||||
/** 无异常时恒健回的哨兵值。 */ |
||||
private static final String NO_EXCEPTION = "unexception"; |
||||
|
||||
/** 未指定币种时的默认值(与下单接口一致)。 */ |
||||
private static final String DEFAULT_CURRENCY = "USD"; |
||||
|
||||
/** 发货类型:0 实际包裹 / 1 面单信息。 */ |
||||
private static final int PACKAGE_FLAG_ACTUAL = 0; |
||||
|
||||
private HengjianOrderMapper() { |
||||
} |
||||
|
||||
// ================================================================ 详情
|
||||
|
||||
/** 订单详情 → 统一出库单。 */ |
||||
public static OutboundOrder toOrder(HengjianOrderDetailDtos.OrderDetail detail, String warehouseCode) { |
||||
String orderNo = requireOrderNo(detail.orderNo); |
||||
OutboundOrder.Builder builder = OutboundOrder.builder() |
||||
.warehouseCode(warehouseOf(detail.warehouseCode, warehouseCode)) |
||||
.outboundRequestNo(orderNo) |
||||
// 详情接口不回 orderId —— 不给假值,保持 null
|
||||
.providerOrderId(null) |
||||
.orderRef(null) |
||||
.status(HengjianOrderStatus.toCore(detail.orderStatusEnum)) |
||||
.rawStatus(trimToNull(detail.orderStatusEnum)) |
||||
.carrier(trimToNull(detail.carrierCode)) |
||||
.carrierCode(trimToNull(detail.carrierCode)) |
||||
.trackingNumber(firstTrackingOfDetail(detail.shipmentPackages)) |
||||
.currency(trimToNull(detail.currency)) |
||||
.thirdPartyAccount(trimToNull(detail.thirdPartyAccount)) |
||||
.paidAt(parseTime(detail.paidAt)) |
||||
.shippedAt(firstShippedAtOfDetail(detail.shipmentPackages)) |
||||
.signatureRequired(flagOf(detail.isSignature)) |
||||
.insured(flagOf(detail.isInsure)) |
||||
.shipTo(toShipTo(detail.shipToCountry, detail.shipToContact, detail.shipToAddress1, |
||||
detail.shipToAddress2, detail.shipToAddress3, detail.shipToCity, |
||||
detail.shipToState, detail.shipToPostal, detail.shipToTelephone)) |
||||
.exceptionCode(exceptionOf(detail.errorCode)) |
||||
.lines(toDetailLines(detail.productItems)) |
||||
.estimatedShippingFee(moneyOf(detail.estimatedShippingFee, detail.currency)) |
||||
.sourceProvider(WarehouseProvider.HENGJIAN); |
||||
addDetailAttachments(builder, detail.enclosure); |
||||
return builder.build(); |
||||
} |
||||
|
||||
// ================================================================ 列表
|
||||
|
||||
/** |
||||
* 列表行 → 统一出库单。 |
||||
* |
||||
* <p>列表比详情多出 {@code orderId},所以这里的 {@code providerOrderId} 有值; |
||||
* 但列表<b>没有</b>预估费用明细,需要完整信息时还是要按单号再查一次详情。</p> |
||||
*/ |
||||
public static OutboundOrder toOrder(HengjianOrderListDtos.OrderRow row, String warehouseCode) { |
||||
String orderNo = requireOrderNo(row.orderNo); |
||||
OutboundOrder.Builder builder = OutboundOrder.builder() |
||||
.warehouseCode(warehouseOf(row.warehouseCode, warehouseCode)) |
||||
.outboundRequestNo(orderNo) |
||||
.providerOrderId(row.orderId == null ? null : String.valueOf(row.orderId)) |
||||
.providerId(row.orderId == null ? null : String.valueOf(row.orderId)) |
||||
.orderRef(null) |
||||
.status(HengjianOrderStatus.toCore(row.orderStatusEnum)) |
||||
.rawStatus(trimToNull(row.orderStatusEnum)) |
||||
.carrier(trimToNull(row.carrierCode)) |
||||
.carrierCode(trimToNull(row.carrierCode)) |
||||
.trackingNumber(firstTrackingOfList(row.shipmentPackages)) |
||||
.currency(trimToNull(row.currency)) |
||||
.thirdPartyAccount(trimToNull(row.thirdPartyAccount)) |
||||
.paidAt(parseTime(row.paidAt)) |
||||
.shippedAt(firstShippedAtOfList(row.shipmentPackages)) |
||||
.signatureRequired(flagOf(row.isSignature)) |
||||
.insured(flagOf(row.isInsure)) |
||||
.shipTo(toShipTo(row.shipToCountry, row.shipToContact, row.shipToAddress1, |
||||
row.shipToAddress2, row.shipToAddress3, row.shipToCity, |
||||
row.shipToState, row.shipToPostal, row.shipToTelephone)) |
||||
.exceptionCode(exceptionOf(row.errorCode)) |
||||
.lines(toListLines(row.productItems)) |
||||
.estimatedShippingFee(moneyOf(row.estimatedShippingFee, row.currency)) |
||||
.sourceProvider(WarehouseProvider.HENGJIAN); |
||||
// 列表独有:整单销售金额。统一模型没有专门字段,落 totalAmount 并注明口径,
|
||||
// 币种用整单 currency,缺失时才按 USD 兜底。
|
||||
if (row.amount != null) { |
||||
builder.totalAmount(moneyOf(row.amount, row.currency)); |
||||
} |
||||
addListAttachments(builder, row.enclosure); |
||||
return builder.build(); |
||||
} |
||||
|
||||
// ================================================================ 行
|
||||
|
||||
/** |
||||
* 产品行(详情)。 |
||||
* |
||||
* <p>{@code skuAmount} 在恒健是<b>行总额</b>(不是单价),落 |
||||
* {@link OutboundLine#totalAmount()};恒健不回申报单价,所以 |
||||
* {@code declareValue} 留空,避免把总额当单价再乘一次。</p> |
||||
* |
||||
* <p>数量缺失或非正的行直接跳过:{@link OutboundLine} 要求数量为正, |
||||
* 保留会在构造期抛异常,把「一条坏数据」放大成「整单查不出来」。</p> |
||||
*/ |
||||
static List<OutboundLine> toDetailLines(List<HengjianOrderDetailDtos.OrderDetail.ProductItem> items) { |
||||
List<OutboundLine> out = new ArrayList<OutboundLine>(); |
||||
if (items == null) { |
||||
return out; |
||||
} |
||||
for (HengjianOrderDetailDtos.OrderDetail.ProductItem item : items) { |
||||
if (item == null) { |
||||
continue; |
||||
} |
||||
OutboundLine line = lineOf(item.sku, item.quantity, item.skuAmount, item.insureAmount); |
||||
if (line != null) { |
||||
out.add(line); |
||||
} |
||||
} |
||||
return out; |
||||
} |
||||
|
||||
/** 产品行(列表);列表多一个 {@code taxPrice},统一模型没有对应字段,不落。 */ |
||||
static List<OutboundLine> toListLines(List<HengjianOrderListDtos.OrderRow.ProductItem> items) { |
||||
List<OutboundLine> out = new ArrayList<OutboundLine>(); |
||||
if (items == null) { |
||||
return out; |
||||
} |
||||
for (HengjianOrderListDtos.OrderRow.ProductItem item : items) { |
||||
if (item == null) { |
||||
continue; |
||||
} |
||||
OutboundLine line = lineOf(item.sku, item.quantity, item.skuAmount, item.insureAmount); |
||||
if (line != null) { |
||||
out.add(line); |
||||
} |
||||
} |
||||
return out; |
||||
} |
||||
|
||||
private static OutboundLine lineOf(String sku, Integer quantity, Double skuAmount, Double insureAmount) { |
||||
String providerSku = trimToNull(sku); |
||||
if (providerSku == null || quantity == null || quantity <= 0) { |
||||
return null; |
||||
} |
||||
OutboundLine.Builder line = OutboundLine.builder() |
||||
.lineNo(providerSku) |
||||
.omsSku(providerSku) |
||||
.providerSku(providerSku) |
||||
.quantity(quantity); |
||||
if (skuAmount != null) { |
||||
line.totalAmount(moneyOf(skuAmount, null)); |
||||
} |
||||
if (insureAmount != null && insureAmount > 0) { |
||||
line.insuredAmount(moneyOf(insureAmount, null)); |
||||
} |
||||
return line.build(); |
||||
} |
||||
|
||||
// ================================================================ 附件
|
||||
|
||||
private static void addDetailAttachments(OutboundOrder.Builder builder, |
||||
List<HengjianOrderDetailDtos.OrderDetail.Enclosure> enclosures) { |
||||
if (enclosures == null) { |
||||
return; |
||||
} |
||||
for (HengjianOrderDetailDtos.OrderDetail.Enclosure e : enclosures) { |
||||
if (e == null) { |
||||
continue; |
||||
} |
||||
builder.attachment(attachmentOf(e.name, e.type, e.url)); |
||||
} |
||||
} |
||||
|
||||
private static void addListAttachments(OutboundOrder.Builder builder, |
||||
List<HengjianOrderListDtos.OrderRow.Enclosure> enclosures) { |
||||
if (enclosures == null) { |
||||
return; |
||||
} |
||||
for (HengjianOrderListDtos.OrderRow.Enclosure e : enclosures) { |
||||
if (e == null) { |
||||
continue; |
||||
} |
||||
builder.attachment(attachmentOf(e.name, e.type, e.url)); |
||||
} |
||||
} |
||||
|
||||
/** 附件;{@code type} 是仓方原值,不做归一。 */ |
||||
private static WarehouseAttachment attachmentOf(String name, String type, String url) { |
||||
return WarehouseAttachment.builder() |
||||
.name(trimToNull(name)) |
||||
.type(trimToNull(type)) |
||||
.url(trimToNull(url)) |
||||
.build(); |
||||
} |
||||
|
||||
// ================================================================ 其它
|
||||
|
||||
/** |
||||
* 收件地址。 |
||||
* |
||||
* <p>恒健没有邮箱字段;电话在文档示例里带多余空格与分机,文档没说格式, |
||||
* <b>原样保留</b>,不猜着清洗。整组都为空时返回 null, |
||||
* 避免把「空地址」当成真实地址回传给业务。</p> |
||||
*/ |
||||
private static ShipTo toShipTo(String country, String contact, String address1, String address2, |
||||
String address3, String city, String state, String postal, |
||||
String phone) { |
||||
if (blank(country) && blank(address1) && blank(city) && blank(contact)) { |
||||
return null; |
||||
} |
||||
return ShipTo.builder() |
||||
.name(trimToNull(contact)) |
||||
.phone(trimToNull(phone)) |
||||
.countryCode(trimToNull(country)) |
||||
.stateOrProvince(trimToNull(state)) |
||||
.city(trimToNull(city)) |
||||
.addressLine1(trimToNull(address1)) |
||||
.addressLine2(trimToNull(address2)) |
||||
.addressLine3(trimToNull(address3)) |
||||
.postalCode(trimToNull(postal)) |
||||
.build(); |
||||
} |
||||
|
||||
/** 首个实际包裹的发货时间;面单信息行({@code packageFlag=1})不参与。 */ |
||||
private static Instant firstShippedAtOfDetail( |
||||
List<HengjianOrderDetailDtos.OrderDetail.ShipmentPackage> packages) { |
||||
if (packages == null) { |
||||
return null; |
||||
} |
||||
for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : packages) { |
||||
if (p == null || !isActualPackage(p.packageFlag)) { |
||||
continue; |
||||
} |
||||
Instant at = parseTime(p.shipmentDate); |
||||
if (at != null) { |
||||
return at; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
|
||||
private static Instant firstShippedAtOfList(List<HengjianOrderListDtos.OrderRow.ShipmentPackage> packages) { |
||||
if (packages == null) { |
||||
return null; |
||||
} |
||||
for (HengjianOrderListDtos.OrderRow.ShipmentPackage p : packages) { |
||||
if (p == null || !isActualPackage(p.packageFlag)) { |
||||
continue; |
||||
} |
||||
Instant at = parseTime(p.shipmentDate); |
||||
if (at != null) { |
||||
return at; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
|
||||
private static boolean isActualPackage(Integer packageFlag) { |
||||
return packageFlag == null || packageFlag == PACKAGE_FLAG_ACTUAL; |
||||
} |
||||
|
||||
/** 首个实际包裹的跟踪号;面单信息行不参与,避免把「面单信息」当成真实运单。 */ |
||||
private static String firstTrackingOfDetail( |
||||
List<HengjianOrderDetailDtos.OrderDetail.ShipmentPackage> packages) { |
||||
if (packages == null) { |
||||
return null; |
||||
} |
||||
for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : packages) { |
||||
if (p == null || !isActualPackage(p.packageFlag)) { |
||||
continue; |
||||
} |
||||
String tracking = trimToNull(p.trackingNo); |
||||
if (tracking != null) { |
||||
return tracking; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
|
||||
private static String firstTrackingOfList(List<HengjianOrderListDtos.OrderRow.ShipmentPackage> packages) { |
||||
if (packages == null) { |
||||
return null; |
||||
} |
||||
for (HengjianOrderListDtos.OrderRow.ShipmentPackage p : packages) { |
||||
if (p == null || !isActualPackage(p.packageFlag)) { |
||||
continue; |
||||
} |
||||
String tracking = trimToNull(p.trackingNo); |
||||
if (tracking != null) { |
||||
return tracking; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
|
||||
/** 0/1 标记 → Boolean;缺省为 null(表示仓方未给,不是「否」)。 */ |
||||
static Boolean flagOf(Integer flag) { |
||||
return flag == null ? null : flag != 0; |
||||
} |
||||
|
||||
/** {@code unexception} 或空视为无异常。 */ |
||||
static String exceptionOf(String errorCode) { |
||||
String code = trimToNull(errorCode); |
||||
if (code == null || NO_EXCEPTION.equalsIgnoreCase(code)) { |
||||
return null; |
||||
} |
||||
return code; |
||||
} |
||||
|
||||
/** 金额;币种缺失时按 USD(恒健默认币种)。 */ |
||||
static Money moneyOf(Double amount, String currency) { |
||||
if (amount == null) { |
||||
return null; |
||||
} |
||||
String code = trimToNull(currency); |
||||
return Money.of(BigDecimal.valueOf(amount), code == null ? DEFAULT_CURRENCY : code); |
||||
} |
||||
|
||||
/** 解析恒健的 UTC 时间;格式不符返回 null,不因时间格式阻断整单。 */ |
||||
static Instant parseTime(String value) { |
||||
String v = trimToNull(value); |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
try { |
||||
return LocalDateTime.parse(v, TIME_FORMAT).toInstant(ZoneOffset.UTC); |
||||
} catch (DateTimeParseException e) { |
||||
try { |
||||
return Instant.parse(v); |
||||
} catch (DateTimeParseException ignored) { |
||||
return null; |
||||
} |
||||
} |
||||
} |
||||
|
||||
/** 仓编码:报文里的优先,没有才用账户配置。 */ |
||||
private static String warehouseOf(String fromPayload, String fallback) { |
||||
String fromBody = trimToNull(fromPayload); |
||||
return fromBody != null ? fromBody : fallback; |
||||
} |
||||
|
||||
/** |
||||
* 订单号。 |
||||
* |
||||
* <p>{@link OutboundOrder} 要求 {@code outboundRequestNo} 非空,恒健的回包理论上 |
||||
* 一定带 {@code orderNo};不带说明报文结构变了,直接抛而不是造一个空单。</p> |
||||
*/ |
||||
private static String requireOrderNo(String orderNo) { |
||||
String v = trimToNull(orderNo); |
||||
if (v == null) { |
||||
throw new IllegalArgumentException("hengjian order payload has no orderNo"); |
||||
} |
||||
return v; |
||||
} |
||||
|
||||
private static boolean blank(String v) { |
||||
return v == null || v.trim().isEmpty(); |
||||
} |
||||
|
||||
private static String trimToNull(String v) { |
||||
if (v == null) { |
||||
return null; |
||||
} |
||||
String t = v.trim(); |
||||
return t.isEmpty() ? null : t; |
||||
} |
||||
} |
||||
@ -0,0 +1,228 @@
@@ -0,0 +1,228 @@
|
||||
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/findOne})。 |
||||
* |
||||
* <p>请求只有 {@code orderNo}。<b>响应没有 {@code orderId}</b>——那是列表接口才回的字段, |
||||
* 所以按详情查回来的单拿不到仓内部 id,取消时要用的话得靠列表接口补。</p> |
||||
*/ |
||||
public final class HengjianOrderDetailDtos { |
||||
|
||||
private HengjianOrderDetailDtos() { |
||||
} |
||||
|
||||
/** 请求:{@code {"orderNo": "..."}}。 */ |
||||
@JsonInclude(JsonInclude.Include.NON_NULL) |
||||
public static final class FindOneRequest { |
||||
/** 订单号,是我们下单时下发的来源单号。 */ |
||||
public String orderNo; |
||||
} |
||||
|
||||
/** 响应外层。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class FindOneResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public OrderDetail data; |
||||
} |
||||
|
||||
/** |
||||
* 订单详情。 |
||||
* |
||||
* <p>字段名照抄文档。注意 {@code estimatedShippingFeeItems} 是<b>预估费用明细</b> |
||||
* (Basic Rate / Residential / Fuel Surcharge 等),与 {@code estimatedShippingFee} |
||||
* 是同一份钱的不同粒度,不要累加。</p> |
||||
*/ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class OrderDetail { |
||||
|
||||
/** 订单号(来源单号)。 */ |
||||
@JsonProperty("orderNo") |
||||
public String orderNo; |
||||
|
||||
/** |
||||
* 支付时间,{@code yyyy-MM-dd HH:mm:ss}。 |
||||
* |
||||
* <p>文档没写时区;创建接口的 {@code paidAt} 注明是 utc,这里**按 UTC 解析**, |
||||
* 待真机核对。</p> |
||||
*/ |
||||
@JsonProperty("paidAt") |
||||
public String paidAt; |
||||
|
||||
/** 店铺标识(文档字段表未列,响应示例里有)。 */ |
||||
@JsonProperty("channelAccount") |
||||
public String channelAccount; |
||||
|
||||
@JsonProperty("shipToContact") |
||||
public String shipToContact; |
||||
@JsonProperty("shipToAddress1") |
||||
public String shipToAddress1; |
||||
@JsonProperty("shipToAddress2") |
||||
public String shipToAddress2; |
||||
@JsonProperty("shipToAddress3") |
||||
public String shipToAddress3; |
||||
@JsonProperty("shipToCity") |
||||
public String shipToCity; |
||||
@JsonProperty("shipToState") |
||||
public String shipToState; |
||||
@JsonProperty("shipToCountry") |
||||
public String shipToCountry; |
||||
@JsonProperty("shipToPostal") |
||||
public String shipToPostal; |
||||
@JsonProperty("shipToTelephone") |
||||
public String shipToTelephone; |
||||
|
||||
/** 仓库 code。 */ |
||||
@JsonProperty("warehouseCode") |
||||
public String warehouseCode; |
||||
|
||||
/** 物流商服务 code。 */ |
||||
@JsonProperty("carrierCode") |
||||
public String carrierCode; |
||||
|
||||
/** 发货时效等级(响应示例里有)。 */ |
||||
@JsonProperty("shipServiceLevel") |
||||
public String shipServiceLevel; |
||||
|
||||
/** third party 账号。 */ |
||||
@JsonProperty("thirdPartyAccount") |
||||
public String thirdPartyAccount; |
||||
|
||||
/** 币种。 */ |
||||
@JsonProperty("currency") |
||||
public String currency; |
||||
|
||||
/** 是否签收:0 否 / 1 是。 */ |
||||
@JsonProperty("isSignature") |
||||
public Integer isSignature; |
||||
|
||||
/** 是否保价:0 否 / 1 是。 */ |
||||
@JsonProperty("isInsure") |
||||
public Integer isInsure; |
||||
|
||||
/** |
||||
* 订单状态:{@code pending / unshipped / approved / assigned / picked / |
||||
* shipped / canceled / refunded}。 |
||||
*/ |
||||
@JsonProperty("orderStatusEnum") |
||||
public String orderStatusEnum; |
||||
|
||||
/** 预估运费;实际以快递账单为准。 */ |
||||
@JsonProperty("estimatedShippingFee") |
||||
public Double estimatedShippingFee; |
||||
|
||||
/** 预估费用明细;与 {@link #estimatedShippingFee} 是同一份钱的拆分。 */ |
||||
@JsonProperty("estimatedShippingFeeItems") |
||||
public List<EstimatedFeeItem> estimatedShippingFeeItems; |
||||
|
||||
/** |
||||
* 异常码:{@code unexception} 表示无异常,其余见文档 |
||||
* ({@code pickingException} / {@code addressException} / {@code trackingException} 等)。 |
||||
*/ |
||||
@JsonProperty("errorCode") |
||||
public String errorCode; |
||||
|
||||
/** 产品行。 */ |
||||
@JsonProperty("productItems") |
||||
public List<ProductItem> productItems; |
||||
|
||||
/** 附件。 */ |
||||
@JsonProperty("enclosure") |
||||
public List<Enclosure> enclosure; |
||||
|
||||
/** 发货信息。 */ |
||||
@JsonProperty("shipmentPackages") |
||||
public List<ShipmentPackage> shipmentPackages; |
||||
|
||||
/** 一条预估费用。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class EstimatedFeeItem { |
||||
/** 费用项名称,如 {@code Fuel Surcharge}。 */ |
||||
@JsonProperty("costName") |
||||
public String costName; |
||||
@JsonProperty("estimatedCost") |
||||
public Double estimatedCost; |
||||
@JsonProperty("currency") |
||||
public String currency; |
||||
} |
||||
|
||||
/** 产品行。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class ProductItem { |
||||
@JsonProperty("sku") |
||||
public String sku; |
||||
@JsonProperty("quantity") |
||||
public Integer quantity; |
||||
/** 销售金额;<b>是行总额</b>(与下单接口的 skuAmount 同语义)。 */ |
||||
@JsonProperty("skuAmount") |
||||
public Double skuAmount; |
||||
/** 投保金额;不保价为 0。 */ |
||||
@JsonProperty("insureAmount") |
||||
public Double insureAmount; |
||||
} |
||||
|
||||
/** 附件。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class Enclosure { |
||||
/** |
||||
* 附件类型。 |
||||
* |
||||
* <p>详情页标 STRING、列表页标 INTEGER,示例给的是 {@code "Shippinglabel"}; |
||||
* 按 String 读,两种形态都能接住。</p> |
||||
*/ |
||||
@JsonProperty("type") |
||||
public String type; |
||||
@JsonProperty("name") |
||||
public String name; |
||||
@JsonProperty("url") |
||||
public String url; |
||||
} |
||||
|
||||
/** 发货信息。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class ShipmentPackage { |
||||
/** 跟踪号。 */ |
||||
@JsonProperty("trackingNo") |
||||
public String trackingNo; |
||||
/** 发货方式(承运商)。 */ |
||||
@JsonProperty("carrier") |
||||
public String carrier; |
||||
/** 发货产品 SKU。 */ |
||||
@JsonProperty("erpSku") |
||||
public String erpSku; |
||||
/** 成本。 */ |
||||
@JsonProperty("cost") |
||||
public Double cost; |
||||
/** 发货数量。 */ |
||||
@JsonProperty("shipedQuantity") |
||||
public Integer shipedQuantity; |
||||
/** 发货时间(utc),{@code yyyy-MM-dd HH:mm:ss}。 */ |
||||
@JsonProperty("shipmentDate") |
||||
public String shipmentDate; |
||||
/** 装车交接时间(utc)。 */ |
||||
@JsonProperty("departureDate") |
||||
public String departureDate; |
||||
/** 发货类型:0 实际包裹 / 1 面单信息。 */ |
||||
@JsonProperty("packageFlag") |
||||
public Integer packageFlag; |
||||
/** 产品二维码-组织。 */ |
||||
@JsonProperty("qrOrg") |
||||
public String qrOrg; |
||||
/** 产品二维码-PO。 */ |
||||
@JsonProperty("qrPo") |
||||
public String qrPo; |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,219 @@
@@ -0,0 +1,219 @@
|
||||
package common.ecommerce.hengjian.dto; |
||||
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties; |
||||
import com.fasterxml.jackson.annotation.JsonProperty; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 恒健报文结构:订单列表({@code GET /v1/saleOrder/findByPage})。 |
||||
* |
||||
* <p>与详情接口的差异(真机 / 文档双确认):</p> |
||||
* <ul> |
||||
* <li>列表<b>多回 {@code orderId}</b>——取消接口需要它,所以「按单号查列表」是补 |
||||
* {@code orderId} 的正规途径;</li> |
||||
* <li>列表多回 {@code channelFlag} / {@code amount},产品行多回 {@code taxPrice};</li> |
||||
* <li>列表的 {@code enclosure[].type} 文档标 INTEGER,详情页标 STRING(示例是 |
||||
* {@code "Shippinglabel"});这里按 String 读,Jackson 会把数字也转成文本。</li> |
||||
* </ul> |
||||
*/ |
||||
public final class HengjianOrderListDtos { |
||||
|
||||
private HengjianOrderListDtos() { |
||||
} |
||||
|
||||
/** 响应外层(分页信封)。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class ListResponse { |
||||
|
||||
@JsonProperty("code") |
||||
public Integer code; |
||||
|
||||
@JsonProperty("message") |
||||
public String message; |
||||
|
||||
@JsonProperty("data") |
||||
public PageData data; |
||||
} |
||||
|
||||
/** |
||||
* 分页数据。 |
||||
* |
||||
* <p>{@code number} 是<b>0 基</b>页码(示例里请求第 1 页返回 {@code number: 0}), |
||||
* 翻页要用它 + 1 反过来推。</p> |
||||
*/ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class PageData { |
||||
|
||||
@JsonProperty("content") |
||||
public List<OrderRow> content; |
||||
|
||||
/** 总记录数。 */ |
||||
@JsonProperty("totalElements") |
||||
public Integer totalElements; |
||||
|
||||
/** 总页数。 */ |
||||
@JsonProperty("totalPages") |
||||
public Integer totalPages; |
||||
|
||||
/** 当前页记录数。 */ |
||||
@JsonProperty("numberOfElements") |
||||
public Integer numberOfElements; |
||||
|
||||
/** 当前页码,<b>0 基</b>。 */ |
||||
@JsonProperty("number") |
||||
public Integer number; |
||||
|
||||
/** 每页条数。 */ |
||||
@JsonProperty("size") |
||||
public Integer size; |
||||
|
||||
/** 是否第一页。 */ |
||||
@JsonProperty("first") |
||||
public Boolean first; |
||||
|
||||
/** 是否最后一页。 */ |
||||
@JsonProperty("last") |
||||
public Boolean last; |
||||
|
||||
/** 是否为空页。 */ |
||||
@JsonProperty("empty") |
||||
public Boolean empty; |
||||
} |
||||
|
||||
/** 一行订单。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class OrderRow { |
||||
|
||||
/** 仓内部订单 id;取消接口要它。 */ |
||||
@JsonProperty("orderId") |
||||
public Long orderId; |
||||
|
||||
/** 订单号(来源单号)。 */ |
||||
@JsonProperty("orderNo") |
||||
public String orderNo; |
||||
|
||||
@JsonProperty("paidAt") |
||||
public String paidAt; |
||||
|
||||
/** 店铺标识(文档字段表未列,示例里有)。 */ |
||||
@JsonProperty("channelAccount") |
||||
public String channelAccount; |
||||
|
||||
@JsonProperty("shipToContact") |
||||
public String shipToContact; |
||||
@JsonProperty("shipToAddress1") |
||||
public String shipToAddress1; |
||||
@JsonProperty("shipToAddress2") |
||||
public String shipToAddress2; |
||||
@JsonProperty("shipToAddress3") |
||||
public String shipToAddress3; |
||||
@JsonProperty("shipToCity") |
||||
public String shipToCity; |
||||
@JsonProperty("shipToState") |
||||
public String shipToState; |
||||
@JsonProperty("shipToCountry") |
||||
public String shipToCountry; |
||||
@JsonProperty("shipToPostal") |
||||
public String shipToPostal; |
||||
@JsonProperty("shipToTelephone") |
||||
public String shipToTelephone; |
||||
|
||||
@JsonProperty("warehouseCode") |
||||
public String warehouseCode; |
||||
@JsonProperty("carrierCode") |
||||
public String carrierCode; |
||||
@JsonProperty("shipServiceLevel") |
||||
public String shipServiceLevel; |
||||
@JsonProperty("thirdPartyAccount") |
||||
public String thirdPartyAccount; |
||||
@JsonProperty("currency") |
||||
public String currency; |
||||
@JsonProperty("isSignature") |
||||
public Integer isSignature; |
||||
@JsonProperty("isInsure") |
||||
public Integer isInsure; |
||||
|
||||
/** 订单状态,码值与详情一致。 */ |
||||
@JsonProperty("orderStatusEnum") |
||||
public String orderStatusEnum; |
||||
|
||||
/** 渠道标识。 */ |
||||
@JsonProperty("channelFlag") |
||||
public String channelFlag; |
||||
|
||||
/** 销售金额(整单)。 */ |
||||
@JsonProperty("amount") |
||||
public Double amount; |
||||
|
||||
/** 预估运费。 */ |
||||
@JsonProperty("estimatedShippingFee") |
||||
public Double estimatedShippingFee; |
||||
|
||||
@JsonProperty("errorCode") |
||||
public String errorCode; |
||||
|
||||
@JsonProperty("productItems") |
||||
public List<ProductItem> productItems; |
||||
|
||||
@JsonProperty("enclosure") |
||||
public List<Enclosure> enclosure; |
||||
|
||||
@JsonProperty("shipmentPackages") |
||||
public List<ShipmentPackage> shipmentPackages; |
||||
|
||||
/** 产品行。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class ProductItem { |
||||
@JsonProperty("sku") |
||||
public String sku; |
||||
@JsonProperty("quantity") |
||||
public Integer quantity; |
||||
@JsonProperty("skuAmount") |
||||
public Double skuAmount; |
||||
@JsonProperty("insureAmount") |
||||
public Double insureAmount; |
||||
/** 税费;详情接口没有这个字段。 */ |
||||
@JsonProperty("taxPrice") |
||||
public Double taxPrice; |
||||
} |
||||
|
||||
/** 附件。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class Enclosure { |
||||
/** 附件类型;列表页文档标 INTEGER,详情页是字符串,这里统一按文本读。 */ |
||||
@JsonProperty("type") |
||||
public String type; |
||||
@JsonProperty("name") |
||||
public String name; |
||||
@JsonProperty("url") |
||||
public String url; |
||||
} |
||||
|
||||
/** 发货信息。 */ |
||||
@JsonIgnoreProperties(ignoreUnknown = true) |
||||
public static final class ShipmentPackage { |
||||
@JsonProperty("trackingNo") |
||||
public String trackingNo; |
||||
@JsonProperty("carrier") |
||||
public String carrier; |
||||
/** 文档列表页没有 erpSku,示例也没给;接住但不依赖。 */ |
||||
@JsonProperty("erpSku") |
||||
public String erpSku; |
||||
@JsonProperty("cost") |
||||
public Double cost; |
||||
@JsonProperty("shipedQuantity") |
||||
public Integer shipedQuantity; |
||||
@JsonProperty("shipmentDate") |
||||
public String shipmentDate; |
||||
@JsonProperty("departureDate") |
||||
public String departureDate; |
||||
@JsonProperty("packageFlag") |
||||
public Integer packageFlag; |
||||
@JsonProperty("qrOrg") |
||||
public String qrOrg; |
||||
@JsonProperty("qrPo") |
||||
public String qrPo; |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,86 @@
@@ -0,0 +1,86 @@
|
||||
package common.ecommerce.hengjian.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.OutboundStatus; |
||||
|
||||
/** |
||||
* 恒健出库订单状态({@code orderStatusEnum},详情与列表接口共用)。 |
||||
* |
||||
* <p>码表来自《获取订单的详细信息》与《订单--查询列表》两页文档: |
||||
* {@code pending} 未支付 / {@code unshipped} 未发货 / {@code approved} 已审核 / |
||||
* {@code assigned} 已分配 / {@code picked} 已配货 / {@code shipped} 已发货 / |
||||
* {@code canceled} 已取消 / {@code refunded} 已退款。</p> |
||||
* |
||||
* <p><b>与运去哪同名不是巧合也不是同源</b>:两家都是美国仓、同一套英文词, |
||||
* 但码值集合与后续扩展各自独立,必须各建一套枚举,不能互相引用。</p> |
||||
* |
||||
* <p><b>按完整值精确匹配</b>。历史教训:用 {@code contains("SHIP")} 会把 |
||||
* {@code UNSHIPPED}(未发货)判成 {@code SHIPPED}(已交运),下游据此认为货已发出、 |
||||
* 取消被直接锁死。认不出的归 {@link #UNKNOWN},不猜;原值同时写进 |
||||
* {@code OutboundOrder.rawStatus}。</p> |
||||
*/ |
||||
public enum HengjianOrderStatus { |
||||
|
||||
/** 未支付。 */ |
||||
PENDING("pending", OutboundStatus.CREATED), |
||||
/** 未发货(仓已接单但未作业)。 */ |
||||
UNSHIPPED("unshipped", OutboundStatus.SUBMITTED), |
||||
/** 已审核。 */ |
||||
APPROVED("approved", OutboundStatus.ACCEPTED), |
||||
/** 已分配(仓已接单)。 */ |
||||
ASSIGNED("assigned", OutboundStatus.ACCEPTED), |
||||
/** 已配货。 */ |
||||
PICKED("picked", OutboundStatus.PICKING), |
||||
/** 已发货。 */ |
||||
SHIPPED("shipped", OutboundStatus.SHIPPED), |
||||
/** 已取消。 */ |
||||
CANCELLED("canceled", OutboundStatus.CANCELLED), |
||||
/** 已退款。 */ |
||||
REFUNDED("refunded", OutboundStatus.REFUNDED), |
||||
/** 无法识别。 */ |
||||
UNKNOWN(null, OutboundStatus.UNKNOWN); |
||||
|
||||
/** 恒健原始值(小写);null 表示「无关键字 / 认不出」。 */ |
||||
private final String rawValue; |
||||
private final OutboundStatus core; |
||||
|
||||
HengjianOrderStatus(String rawValue, OutboundStatus core) { |
||||
this.rawValue = rawValue; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 恒健原始值;null 表示无法识别。 */ |
||||
public String rawValue() { |
||||
return rawValue; |
||||
} |
||||
|
||||
/** 对应的底层状态。 */ |
||||
public OutboundStatus toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** |
||||
* 恒健原始值 → 平台枚举。<b>精确匹配</b>(只忽略大小写与首尾空白)。 |
||||
* |
||||
* <p>空值、未收录的取值都返回 {@link #UNKNOWN}。</p> |
||||
*/ |
||||
public static HengjianOrderStatus of(String rawStatus) { |
||||
if (rawStatus == null) { |
||||
return UNKNOWN; |
||||
} |
||||
String s = rawStatus.trim(); |
||||
if (s.isEmpty()) { |
||||
return UNKNOWN; |
||||
} |
||||
for (HengjianOrderStatus v : values()) { |
||||
if (v.rawValue != null && s.equalsIgnoreCase(v.rawValue)) { |
||||
return v; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
|
||||
/** 恒健原始值 → 底层状态。 */ |
||||
public static OutboundStatus toCore(String rawStatus) { |
||||
return of(rawStatus).toCore(); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue