Compare commits
5 Commits
ca6d00ba18
...
86b05dc79d
| Author | SHA1 | Date |
|---|---|---|
|
|
86b05dc79d | 2 weeks ago |
|
|
d2d2f04a45 | 2 weeks ago |
|
|
3338a185e9 | 2 weeks ago |
|
|
06961c6781 | 2 weeks ago |
|
|
a8dfb08e69 | 2 weeks ago |
89 changed files with 2946 additions and 591 deletions
@ -1,49 +0,0 @@
@@ -1,49 +0,0 @@
|
||||
package common.ecommerce.warehouse; |
||||
|
||||
/** |
||||
* 仓库能力位。 |
||||
* |
||||
* <p>能力是事实表,不是推荐:调用方用 {@code WarehouseSdk.capabilities()} 查询, |
||||
* 缺失时抛 {@code WarehouseUnsupportedCapabilityException},不静默降级。</p> |
||||
*/ |
||||
public enum WarehouseCapability { |
||||
|
||||
/** 商品建档 / 更新 */ |
||||
PRODUCT, |
||||
/** 出库单创建 / 查询 / 取消 / 拦截 */ |
||||
OUTBOUND, |
||||
/** 支持把平台面单文件下发给仓打印贴标 */ |
||||
PLATFORM_LABEL_DELIVERY, |
||||
/** 取消前费用预判 */ |
||||
OUTBOUND_CANCEL_FEE_CHECK, |
||||
/** 库存查询 */ |
||||
INVENTORY_QUERY, |
||||
/** 库存调整 / 调拨 */ |
||||
INVENTORY_ADJUST, |
||||
/** 仓间调拨单(移库 / FBA 移入移出) */ |
||||
TRANSFER, |
||||
/** 头程入库单创建 / 查询 */ |
||||
INBOUND, |
||||
/** 退货发起 / 查询 */ |
||||
RETURN, |
||||
/** 退货处理方式(二次上架 / 销毁) */ |
||||
RETURN_DISPOSITION, |
||||
/** 换货(三家均无) */ |
||||
EXCHANGE, |
||||
/** 无头件查询 */ |
||||
UNSHIPPED_ITEM, |
||||
/** BOL 获取 / 传递 */ |
||||
BOL, |
||||
/** 物流轨迹 */ |
||||
TRACKING, |
||||
/** 拆单 */ |
||||
SPLIT, |
||||
/** 销毁 / 报废 */ |
||||
DESTRUCTION, |
||||
/** 费用账单 / 订单费用 / 仓租 / 账户流水 */ |
||||
FEE_SETTLEMENT, |
||||
/** 费用试算 */ |
||||
FEE_ESTIMATE, |
||||
/** 状态回调推送 */ |
||||
WEBHOOK |
||||
} |
||||
@ -1,21 +0,0 @@
@@ -1,21 +0,0 @@
|
||||
package common.ecommerce.warehouse; |
||||
|
||||
/** |
||||
* 三方仓 provider 枚举。 |
||||
* |
||||
* <p>与渠道域的 {@code ChannelProvider} 分开:仓不是平台,两套枚举互不继承, |
||||
* 但幂等、水位线、审计里都以 {@link #name()} 字符串落库,共用同一批 SPI。</p> |
||||
*/ |
||||
public enum WarehouseProvider { |
||||
|
||||
/** 运去哪(打样仓) */ |
||||
YQN, |
||||
/** 信仓(新版接口) */ |
||||
XINCANG, |
||||
/** 易达云 */ |
||||
EDAYUN, |
||||
/** 领星 WMS:预留,本期不实现 */ |
||||
LINGXING, |
||||
/** 其他自建/直连仓 */ |
||||
CUSTOM |
||||
} |
||||
@ -0,0 +1,29 @@
@@ -0,0 +1,29 @@
|
||||
package common.ecommerce.warehouse.capability; |
||||
|
||||
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
||||
import common.ecommerce.warehouse.model.FeeEstimateResult; |
||||
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
|
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 运费试算能力:发货前按包裹 + 地址 + 渠道询价。 |
||||
* |
||||
* <p><b>与 {@link WarehouseFeeCapable} 不是一回事</b>:那个查已发生的结算明细, |
||||
* 这个在发货前给报价。报价仅供参考,实际费用以结算账单为准。</p> |
||||
* |
||||
* <p>按仓库维度返回:一个仓下可能有多个可选渠道。只读操作,无幂等要求。</p> |
||||
*/ |
||||
public interface WarehouseFeeEstimateCapable extends WarehouseAdapter { |
||||
|
||||
/** |
||||
* 试算运费。 |
||||
* |
||||
* @param query 包裹尺寸重量、收件地址与物流渠道;必填项在构造期已校验 |
||||
* @return 每个发货仓一条结果;仓方无可承运渠道时该仓的 {@code carriers()} 为空 |
||||
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException |
||||
* 该仓不声明 {@code FEE_ESTIMATE} |
||||
*/ |
||||
List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query); |
||||
} |
||||
@ -0,0 +1,34 @@
@@ -0,0 +1,34 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 取消资格判定。 |
||||
* |
||||
* <p>仓方能力不齐,有的仓有专门的取消预判接口,有的只能查单状态推断。 |
||||
* SDK 统一映射到这三态;{@link #CHARGED} 必须由调用方显式传 |
||||
* {@code acceptCharge=true} 才执行取消。</p> |
||||
*/ |
||||
public enum CancelEligibility { |
||||
|
||||
/** 可免费取消。 */ |
||||
FREE(10, "可免费取消"), |
||||
/** 可取消但收费;需调用方确认。 */ |
||||
CHARGED(20, "可取消但收费"), |
||||
/** 不可取消(已出库 / 已交运 / 仓不允许)。 */ |
||||
BLOCKED(30, "不可取消"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
CancelEligibility(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,67 @@
@@ -0,0 +1,67 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 入库计划单状态(底层枚举)。 |
||||
* |
||||
* <p>各仓的状态在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里; |
||||
* 本枚举不认识任何仓的码值。</p> |
||||
* |
||||
* <p>未知码归 {@link #UNKNOWN},不猜——猜错会让宿主把未完成的入库当完成。</p> |
||||
*/ |
||||
public enum InboundStatus { |
||||
|
||||
/** 草稿 / 已创建。 */ |
||||
DRAFT(10, "草稿"), |
||||
/** 待审核。 */ |
||||
PENDING_REVIEW(20, "待审核"), |
||||
/** 审核拒绝。 */ |
||||
REJECTED(30, "审核拒绝"), |
||||
/** 待装箱。 */ |
||||
PENDING_PACKING(40, "待装箱"), |
||||
/** 待发货。 */ |
||||
PENDING_SHIPMENT(50, "待发货"), |
||||
/** 已发运 / 在途。 */ |
||||
IN_TRANSIT(60, "在途"), |
||||
/** 收货中。 */ |
||||
RECEIVING(70, "收货中"), |
||||
/** 已收货。 */ |
||||
RECEIVED(80, "已收货"), |
||||
/** 待入库(上架)。 */ |
||||
PENDING_STORAGE(90, "待上架"), |
||||
/** 入库中(上架中)。 */ |
||||
STORING(100, "上架中"), |
||||
/** 已完成。 */ |
||||
COMPLETED(110, "已完成"), |
||||
/** 已取消。 */ |
||||
CANCELLED(120, "已取消"), |
||||
/** 无法识别的状态;码 0 保留给 UNKNOWN,不与任何业务状态冲突。 */ |
||||
UNKNOWN(0, "未知"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
InboundStatus(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ |
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
/** 中文显示名。 */ |
||||
public String label() { |
||||
return label; |
||||
} |
||||
|
||||
/** 按落库码反查。 */ |
||||
public static InboundStatus ofCode(int code) { |
||||
for (InboundStatus s : values()) { |
||||
if (s.code == code) { |
||||
return s; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
} |
||||
@ -0,0 +1,31 @@
@@ -0,0 +1,31 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 库存同步策略。 |
||||
* |
||||
* <p>仓能力不同:有的仓支持按时间增量,有的只能全量拉取后做差异比对。 |
||||
* 具体哪家支持哪种由适配器的 {@code InventoryCapable.syncStrategy()} 声明。</p> |
||||
*/ |
||||
public enum InventorySyncStrategy { |
||||
|
||||
/** 按时间增量查询。 */ |
||||
TIME_WINDOW(10, "按时间增量"), |
||||
/** 全量拉取 + 差异比对。 */ |
||||
FULL_PULL_DIFF(20, "全量比对"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
InventorySyncStrategy(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,32 @@
@@ -0,0 +1,32 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 面单模式。 |
||||
* |
||||
* <p>必须与仓能力匹配:{@link #PLATFORM_LABEL} 要求仓声明 |
||||
* {@link WarehouseCapability#PLATFORM_LABEL_DELIVERY},缺失时 {@code create()} 拒绝, |
||||
* <b>不静默降级</b>为仓自有面单——面单归属直接影响与平台的标发方式。</p> |
||||
*/ |
||||
public enum LabelMode { |
||||
|
||||
/** 仓用自己的承运商账号出单,SDK 只回收面单与运单。 */ |
||||
WAREHOUSE_LABEL(10, "仓自有面单"), |
||||
/** 渠道域先取平台面单,OMS 把面单文件下发给仓打印贴标。 */ |
||||
PLATFORM_LABEL(20, "平台面单"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
LabelMode(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,81 @@
@@ -0,0 +1,81 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 出库单状态(底层枚举)。 |
||||
* |
||||
* <p>各仓的状态在各自模块里先映射成「平台枚举」,再 {@code toCore()} 到这里; |
||||
* 本枚举不认识任何仓的码值或字符串。</p> |
||||
* |
||||
* <p>{@link #CREATED} 与 {@link #SUBMITTED} 不是仓方状态,是 SDK 自己的生命周期: |
||||
* 前者表示 OMS 已建单未下发,后者表示已下发但仓尚未确认。仓方返回的状态只会落在 |
||||
* {@code SUBMITTED} 之后的值上。</p> |
||||
* |
||||
* <p>{@link #UNKNOWN} 是必须项:仓方给出无法识别的状态时归这里,<b>不许猜成别的值</b>, |
||||
* 原值看 {@code rawStatus}。</p> |
||||
* |
||||
* <p>{@link #rank()} 只对仓方状态有意义,用于丢弃乱序回调;{@link #UNKNOWN} |
||||
* 的 rank 为 -1,表示「不参与比较」,宿主应保留记录但不覆盖已有状态。</p> |
||||
*/ |
||||
public enum OutboundStatus { |
||||
|
||||
/** 已创建(OMS 侧),尚未下发。 */ |
||||
CREATED(10, "已创建", 0), |
||||
/** SDK 下发成功,仓未确认。 */ |
||||
SUBMITTED(20, "已下发", 1), |
||||
/** 仓已接单。 */ |
||||
ACCEPTED(30, "仓已接单", 2), |
||||
/** 拣货中。 */ |
||||
PICKING(40, "拣货中", 3), |
||||
/** 已打包。 */ |
||||
PACKED(50, "已打包", 4), |
||||
/** 面单已出。 */ |
||||
LABEL_READY(60, "面单已出", 5), |
||||
/** 已交运。 */ |
||||
SHIPPED(70, "已交运", 6), |
||||
/** 已取消。 */ |
||||
CANCELLED(80, "已取消", 7), |
||||
/** 异常(仓侧拣货失败、地址异常等)。 */ |
||||
EXCEPTION(90, "异常", 8), |
||||
/** 无法识别;原值见 {@code rawStatus},不参与 rank 比较。 */ |
||||
UNKNOWN(0, "未知", -1); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
private final int rank; |
||||
|
||||
OutboundStatus(int code, String label, int rank) { |
||||
this.code = code; |
||||
this.label = label; |
||||
this.rank = rank; |
||||
} |
||||
|
||||
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ |
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
/** 中文显示名。 */ |
||||
public String label() { |
||||
return label; |
||||
} |
||||
|
||||
/** 状态推进序号,越大越靠后;用于丢弃乱序回调。-1 表示不参与比较。 */ |
||||
public int rank() { |
||||
return rank; |
||||
} |
||||
|
||||
/** 是否终态(不会再变)。 */ |
||||
public boolean terminal() { |
||||
return this == SHIPPED || this == CANCELLED; |
||||
} |
||||
|
||||
/** 按落库码反查。 */ |
||||
public static OutboundStatus ofCode(int code) { |
||||
for (OutboundStatus s : values()) { |
||||
if (s.code == code) { |
||||
return s; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
} |
||||
@ -0,0 +1,37 @@
@@ -0,0 +1,37 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 退货预约时的处理方式(业务语义)。 |
||||
* |
||||
* <p>只表达「怎么处理」,不含任何仓方的数字码:各仓码值不同,映射由适配器负责。</p> |
||||
* |
||||
* <p><b>与 {@link ReturnProcessDisposition} 不是一回事</b>:这个是下单时发货人预报的, |
||||
* 那个是仓收货检验之后逐条明细行的最终决定。两者可选值不同,不能互换。</p> |
||||
*/ |
||||
public enum ReturnDealMethod { |
||||
|
||||
/** 客户自提。 */ |
||||
CUSTOMER_PICKUP(10, "客户自提"), |
||||
/** 拍照确认后由客户决定。 */ |
||||
PHOTO_CONFIRM(20, "拍照确认"), |
||||
/** 销毁。 */ |
||||
DESTROY(30, "销毁"), |
||||
/** 仓库确认处理。 */ |
||||
WAREHOUSE_CONFIRM(40, "仓库确认"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
ReturnDealMethod(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,43 @@
@@ -0,0 +1,43 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 退货检验后的处理方式(业务语义)。 |
||||
* |
||||
* <p>只表达「怎么处理」,不含任何仓方的数字码:各仓码值不同,映射由适配器负责。</p> |
||||
* |
||||
* <p><b>与 {@link ReturnDealMethod} 不是一回事</b>:那个是预约时的预报, |
||||
* 这个是仓收货检验之后逐条明细行的最终决定。</p> |
||||
* |
||||
* <p>查询结果也用本枚举:{@link #UNKNOWN} 表示仓方返回的处理方式无法识别, |
||||
* 原值见 {@code WarehouseReturn.rawStatus()}。不再单独建一个查询专用的枚举—— |
||||
* 那只是本枚举的子集,多一个枚举就多一处「到底该用哪个」的困惑。</p> |
||||
*/ |
||||
public enum ReturnProcessDisposition { |
||||
|
||||
/** 客户自提。 */ |
||||
CUSTOMER_PICKUP(10, "客户自提"), |
||||
/** 销毁。 */ |
||||
DESTROY(20, "销毁"), |
||||
/** 上架(良品)。 */ |
||||
RESTOCK(30, "上架"), |
||||
/** 换标后上架(良品)。 */ |
||||
RESTOCK_RELABEL(40, "换标上架"), |
||||
/** 无法识别;0 保留给 UNKNOWN。 */ |
||||
UNKNOWN(0, "未知"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
ReturnProcessDisposition(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,60 @@
@@ -0,0 +1,60 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 调拨单状态(底层枚举)。 |
||||
* |
||||
* <p>各仓的状态码在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里; |
||||
* 本枚举不认识任何仓的码值。未知码归 {@link #UNKNOWN},不猜。</p> |
||||
* |
||||
* <p>取值<b>只追加不合并</b>:新仓有、这里没有的状态就加一个值,已存在的值 |
||||
* 不会再合并回上一级——合并之后宿主就分不出「待审核」和「审核中」了。</p> |
||||
*/ |
||||
public enum TransferStatus { |
||||
|
||||
DRAFT(10, "草稿"), |
||||
REJECTED(20, "已驳回"), |
||||
PENDING_REVIEW(30, "待审核"), |
||||
REVIEWING(40, "审核中"), |
||||
APPROVED(50, "审核通过"), |
||||
PENDING_CONFIRM(60, "待确认"), |
||||
PENDING_PICKING(70, "待备货"), |
||||
PENDING_OUTBOUND(80, "待出库"), |
||||
OUTBOUNDING(90, "出库中"), |
||||
PENDING_INBOUND(100, "待入库"), |
||||
INBOUNDING(110, "入库中"), |
||||
COMPLETED(120, "已完成"), |
||||
CLOSED(130, "已关闭"), |
||||
CANCELLING(140, "取消中"), |
||||
CANCELLED(150, "已取消"), |
||||
CANCEL_EXCEPTION(160, "取消异常"), |
||||
/** 无法识别;0 保留给 UNKNOWN。 */ |
||||
UNKNOWN(0, "未知"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
TransferStatus(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */ |
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
/** 中文显示名。 */ |
||||
public String label() { |
||||
return label; |
||||
} |
||||
|
||||
/** 按落库码反查。 */ |
||||
public static TransferStatus ofCode(int code) { |
||||
for (TransferStatus s : values()) { |
||||
if (s.code == code) { |
||||
return s; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
} |
||||
@ -0,0 +1,35 @@
@@ -0,0 +1,35 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 调拨类型,只表达业务语义。 |
||||
* |
||||
* <p>仓方的类型码由适配器映射(如运去哪 {@code type} 0/1/2/3),core 不认识任何 |
||||
* 仓的码值。创建响应若不回传类型,适配器从请求侧带过来,不猜。</p> |
||||
*/ |
||||
public enum TransferType { |
||||
|
||||
/** 仓到仓调拨。 */ |
||||
WAREHOUSE_TO_WAREHOUSE(10, "仓到仓调拨"), |
||||
/** 调拨出库(发往外部地址或平台仓)。 */ |
||||
OUTBOUND(20, "调拨出库"), |
||||
/** 亚马逊移除订单(FBA 移出)。 */ |
||||
AMAZON_REMOVAL(30, "亚马逊移出"), |
||||
/** 亚马逊移入(FBA 入库)。 */ |
||||
AMAZON_INBOUND(40, "亚马逊移入"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
TransferType(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,65 @@
@@ -0,0 +1,65 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 仓库能力位。 |
||||
* |
||||
* <p>能力是事实表,不是推荐:调用方用 {@code WarehouseSdk.capabilities()} 查询, |
||||
* 缺失时抛 {@code WarehouseUnsupportedCapabilityException},不静默降级。</p> |
||||
*/ |
||||
public enum WarehouseCapability { |
||||
|
||||
/** 商品建档 / 更新 */ |
||||
PRODUCT(10, "商品建档"), |
||||
/** 出库单创建 / 查询 / 取消 / 拦截 */ |
||||
OUTBOUND(20, "出库"), |
||||
/** 支持把平台面单文件下发给仓打印贴标 */ |
||||
PLATFORM_LABEL_DELIVERY(30, "平台面单下发"), |
||||
/** 取消前费用预判 */ |
||||
OUTBOUND_CANCEL_FEE_CHECK(40, "取消费用预判"), |
||||
/** 库存查询 */ |
||||
INVENTORY_QUERY(50, "库存查询"), |
||||
/** 库存调整 / 调拨 */ |
||||
INVENTORY_ADJUST(60, "库存调整"), |
||||
/** 仓间调拨单(移库 / FBA 移入移出) */ |
||||
TRANSFER(70, "仓间调拨"), |
||||
/** 头程入库单创建 / 查询 */ |
||||
INBOUND(80, "入库"), |
||||
/** 退货发起 / 查询 */ |
||||
RETURN(90, "退货"), |
||||
/** 退货处理方式(二次上架 / 销毁) */ |
||||
RETURN_DISPOSITION(100, "退货处理方式"), |
||||
/** 换货 */ |
||||
EXCHANGE(110, "换货"), |
||||
/** 无头件查询 */ |
||||
UNSHIPPED_ITEM(120, "无头件"), |
||||
/** BOL 获取 / 传递 */ |
||||
BOL(130, "BOL"), |
||||
/** 物流轨迹 */ |
||||
TRACKING(140, "物流轨迹"), |
||||
/** 拆单 */ |
||||
SPLIT(150, "拆单"), |
||||
/** 销毁 / 报废 */ |
||||
DESTRUCTION(160, "销毁报废"), |
||||
/** 费用账单 / 订单费用 / 仓租 / 账户流水 */ |
||||
FEE_SETTLEMENT(170, "费用结算"), |
||||
/** 费用试算 */ |
||||
FEE_ESTIMATE(180, "费用试算"), |
||||
/** 状态回调推送 */ |
||||
WEBHOOK(190, "状态回调"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
WarehouseCapability(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,35 @@
@@ -0,0 +1,35 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 仓费用类型,只表达业务语义。 |
||||
* |
||||
* <p>仓方的费用码与分类口径由适配器维护:有的仓给类型码,有的仓只给中文费用名, |
||||
* 后者按名归类,认不出就留 null——对账时宁可不分类,也不能猜错。</p> |
||||
*/ |
||||
public enum WarehouseFeeType { |
||||
|
||||
/** 作业费(出入库操作费)。 */ |
||||
OPERATION(10, "作业费"), |
||||
/** 仓储费 / 仓租。 */ |
||||
STORAGE(20, "仓储费"), |
||||
/** 增值服务费。 */ |
||||
VALUE_ADDED(30, "增值服务费"), |
||||
/** 尾程运费。 */ |
||||
LAST_MILE(40, "尾程运费"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
WarehouseFeeType(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -0,0 +1,39 @@
@@ -0,0 +1,39 @@
|
||||
package common.ecommerce.warehouse.enums; |
||||
|
||||
/** |
||||
* 三方仓 provider 枚举。 |
||||
* |
||||
* <p>与渠道域的 {@code ChannelProvider} 分开:仓不是平台,两套枚举互不继承, |
||||
* 但幂等、水位线、审计里都以 {@link #name()} 字符串落库,共用同一批 SPI。 |
||||
* provider 是<b>接入通道标识</b>而非协议码,因此落库继续用 {@code name()}, |
||||
* 不用 {@link #code()}——换码值会让存量幂等键对不上。</p> |
||||
*/ |
||||
public enum WarehouseProvider { |
||||
|
||||
/** 运去哪(打样仓) */ |
||||
YQN(10, "运去哪"), |
||||
/** 信仓(新版接口) */ |
||||
XINCANG(20, "信仓"), |
||||
/** 易达云 */ |
||||
EDAYUN(30, "易达云"), |
||||
/** 领星 WMS:预留,本期不实现 */ |
||||
LINGXING(40, "领星WMS"), |
||||
/** 其他自建/直连仓 */ |
||||
CUSTOM(90, "自建仓"); |
||||
|
||||
private final int code; |
||||
private final String label; |
||||
|
||||
WarehouseProvider(int code, String label) { |
||||
this.code = code; |
||||
this.label = label; |
||||
} |
||||
|
||||
public int code() { |
||||
return code; |
||||
} |
||||
|
||||
public String label() { |
||||
return label; |
||||
} |
||||
} |
||||
@ -1,17 +0,0 @@
@@ -1,17 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 取消资格判定。 |
||||
* |
||||
* <p>仓方能力不齐:易达云有专门接口,另两家需打样核实。SDK 统一映射到这三态; |
||||
* {@link #CHARGED} 必须由调用方显式传 {@code acceptCharge=true} 才执行取消。</p> |
||||
*/ |
||||
public enum CancelEligibility { |
||||
|
||||
/** 可免费取消。 */ |
||||
FREE, |
||||
/** 可取消但收费;需调用方确认。 */ |
||||
CHARGED, |
||||
/** 不可取消(已出库 / 已交运 / 仓不允许)。 */ |
||||
BLOCKED |
||||
} |
||||
@ -0,0 +1,244 @@
@@ -0,0 +1,244 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import common.ecommerce.shared.support.Money; |
||||
|
||||
import java.math.BigDecimal; |
||||
import java.util.ArrayList; |
||||
import java.util.Collections; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 运费试算条件(下单前的费用预估,<b>不是</b>已发生的账单)。 |
||||
* |
||||
* <p>与 {@link FeeQuery} 是两条不同的路径:{@code FeeQuery} 查已经产生的结算明细, |
||||
* 本类用于<b>发货前</b>按包裹尺寸重量 + 收件地址 + 物流渠道询价。</p> |
||||
* |
||||
* <p>单位写进字段名(cm / g),由适配器换算成仓方要求的单位,避免调用方按仓猜单位。</p> |
||||
* |
||||
* <p>结果是「参考价」:实际费用以出库结算账单为准。</p> |
||||
*/ |
||||
public final class FeeEstimateQuery { |
||||
|
||||
/** 发货仓 code;空表示用账户配置的仓。 */ |
||||
private final List<String> warehouseCodes; |
||||
private final BigDecimal lengthCm; |
||||
private final BigDecimal widthCm; |
||||
private final BigDecimal heightCm; |
||||
private final BigDecimal weightGrams; |
||||
/** 保价货值;null 表示不保价。币种口径由仓方账户决定。 */ |
||||
private final Money insuredValue; |
||||
private final String receiveCountry; |
||||
private final String receiveState; |
||||
private final String receiveCity; |
||||
private final String receivePostal; |
||||
private final String receiveAddress; |
||||
/** 是否住宅地址;null 表示不传(仓方按默认口径)。 */ |
||||
private final Boolean residential; |
||||
/** 物流产品服务码,如 {@code FedEx_FEDEX_GROUND}。取值由各仓定义,适配器不做跨仓归一。 */ |
||||
private final String logisticsServiceCode; |
||||
private final String logisticsProductCode; |
||||
/** 签名服务,如 {@code SIGNATURE}。 */ |
||||
private final String signService; |
||||
|
||||
private FeeEstimateQuery(Builder b) { |
||||
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(b.warehouseCodes)); |
||||
this.lengthCm = requirePositive(b.lengthCm, "lengthCm"); |
||||
this.widthCm = requirePositive(b.widthCm, "widthCm"); |
||||
this.heightCm = requirePositive(b.heightCm, "heightCm"); |
||||
this.weightGrams = requirePositive(b.weightGrams, "weightGrams"); |
||||
this.insuredValue = b.insuredValue; |
||||
this.receiveCountry = require(b.receiveCountry, "receiveCountry"); |
||||
this.receiveState = b.receiveState; |
||||
this.receiveCity = b.receiveCity; |
||||
this.receivePostal = require(b.receivePostal, "receivePostal"); |
||||
this.receiveAddress = b.receiveAddress; |
||||
this.residential = b.residential; |
||||
this.logisticsServiceCode = require(b.logisticsServiceCode, "logisticsServiceCode"); |
||||
this.logisticsProductCode = b.logisticsProductCode; |
||||
this.signService = b.signService; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
/** 发货仓 code 列表;空表示用账户配置的仓。 */ |
||||
public List<String> warehouseCodes() { |
||||
return warehouseCodes; |
||||
} |
||||
|
||||
public BigDecimal lengthCm() { |
||||
return lengthCm; |
||||
} |
||||
|
||||
public BigDecimal widthCm() { |
||||
return widthCm; |
||||
} |
||||
|
||||
public BigDecimal heightCm() { |
||||
return heightCm; |
||||
} |
||||
|
||||
public BigDecimal weightGrams() { |
||||
return weightGrams; |
||||
} |
||||
|
||||
/** 保价货值;null 表示不保价。 */ |
||||
public Money insuredValue() { |
||||
return insuredValue; |
||||
} |
||||
|
||||
/** ISO 3166-1 alpha-2,如 US。 */ |
||||
public String receiveCountry() { |
||||
return receiveCountry; |
||||
} |
||||
|
||||
public String receiveState() { |
||||
return receiveState; |
||||
} |
||||
|
||||
public String receiveCity() { |
||||
return receiveCity; |
||||
} |
||||
|
||||
public String receivePostal() { |
||||
return receivePostal; |
||||
} |
||||
|
||||
public String receiveAddress() { |
||||
return receiveAddress; |
||||
} |
||||
|
||||
/** 是否住宅地址;null 表示不传。 */ |
||||
public Boolean residential() { |
||||
return residential; |
||||
} |
||||
|
||||
/** 物流产品服务码;取值由仓定义。 */ |
||||
public String logisticsServiceCode() { |
||||
return logisticsServiceCode; |
||||
} |
||||
|
||||
public String logisticsProductCode() { |
||||
return logisticsProductCode; |
||||
} |
||||
|
||||
/** 签名服务码。 */ |
||||
public String signService() { |
||||
return signService; |
||||
} |
||||
|
||||
private static BigDecimal requirePositive(BigDecimal v, String name) { |
||||
if (v == null || v.signum() <= 0) { |
||||
throw new IllegalArgumentException(name + " must be positive"); |
||||
} |
||||
return v; |
||||
} |
||||
|
||||
private static String require(String v, String name) { |
||||
if (v == null || v.trim().isEmpty()) { |
||||
throw new IllegalArgumentException(name + " must not be blank"); |
||||
} |
||||
return v.trim(); |
||||
} |
||||
|
||||
public static final class Builder { |
||||
|
||||
private final List<String> warehouseCodes = new ArrayList<String>(); |
||||
private BigDecimal lengthCm; |
||||
private BigDecimal widthCm; |
||||
private BigDecimal heightCm; |
||||
private BigDecimal weightGrams; |
||||
private Money insuredValue; |
||||
private String receiveCountry; |
||||
private String receiveState; |
||||
private String receiveCity; |
||||
private String receivePostal; |
||||
private String receiveAddress; |
||||
private Boolean residential; |
||||
private String logisticsServiceCode; |
||||
private String logisticsProductCode; |
||||
private String signService; |
||||
|
||||
public Builder warehouseCode(String v) { |
||||
if (v != null && !v.trim().isEmpty()) { |
||||
this.warehouseCodes.add(v.trim()); |
||||
} |
||||
return this; |
||||
} |
||||
|
||||
public Builder lengthCm(BigDecimal v) { |
||||
this.lengthCm = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder widthCm(BigDecimal v) { |
||||
this.widthCm = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder heightCm(BigDecimal v) { |
||||
this.heightCm = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder weightGrams(BigDecimal v) { |
||||
this.weightGrams = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder insuredValue(Money v) { |
||||
this.insuredValue = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder receiveCountry(String v) { |
||||
this.receiveCountry = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder receiveState(String v) { |
||||
this.receiveState = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder receiveCity(String v) { |
||||
this.receiveCity = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder receivePostal(String v) { |
||||
this.receivePostal = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder receiveAddress(String v) { |
||||
this.receiveAddress = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder residential(Boolean v) { |
||||
this.residential = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder logisticsServiceCode(String v) { |
||||
this.logisticsServiceCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder logisticsProductCode(String v) { |
||||
this.logisticsProductCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder signService(String v) { |
||||
this.signService = v; |
||||
return this; |
||||
} |
||||
|
||||
public FeeEstimateQuery build() { |
||||
return new FeeEstimateQuery(this); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,190 @@
@@ -0,0 +1,190 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import common.ecommerce.shared.support.Money; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
|
||||
import java.util.ArrayList; |
||||
import java.util.Collections; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 单个发货仓的运费试算结果。 |
||||
* |
||||
* <p>一个仓下可能有多个可选渠道(承运商 + 物流服务),每个渠道一笔总价与若干细分成本。 |
||||
* 这是<b>报价</b>,不是账单:实际费用以出库结算为准,用 {@link BillingDocument} 承载。</p> |
||||
*/ |
||||
public final class FeeEstimateResult { |
||||
|
||||
private final WarehouseProvider sourceProvider; |
||||
private final String shipOrgWarehouseCode; |
||||
private final List<CarrierQuote> carriers; |
||||
|
||||
private FeeEstimateResult(Builder b) { |
||||
this.sourceProvider = b.sourceProvider; |
||||
this.shipOrgWarehouseCode = require(b.shipOrgWarehouseCode, "shipOrgWarehouseCode"); |
||||
this.carriers = Collections.unmodifiableList(new ArrayList<CarrierQuote>(b.carriers)); |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
public WarehouseProvider sourceProvider() { |
||||
return sourceProvider; |
||||
} |
||||
|
||||
/** 发货仓 code(仓方口径)。 */ |
||||
public String shipOrgWarehouseCode() { |
||||
return shipOrgWarehouseCode; |
||||
} |
||||
|
||||
/** 可选渠道报价;可能为空,表示该仓无法承运该包裹。 */ |
||||
public List<CarrierQuote> carriers() { |
||||
return carriers; |
||||
} |
||||
|
||||
private static String require(String v, String name) { |
||||
if (v == null || v.trim().isEmpty()) { |
||||
throw new IllegalArgumentException(name + " must not be blank"); |
||||
} |
||||
return v.trim(); |
||||
} |
||||
|
||||
/** 一个渠道的报价。 */ |
||||
public static final class CarrierQuote { |
||||
|
||||
/** 承运商,如 {@code FEDEX}。 */ |
||||
private final String carrier; |
||||
/** 物流服务码,与查询时的 {@code logisticsServiceCode} 同一套取值。 */ |
||||
private final String logisticsServiceCode; |
||||
/** 总价;仓方未给时为 null。 */ |
||||
private final Money totalRate; |
||||
private final List<CostItem> costItems; |
||||
|
||||
private CarrierQuote(Builder b) { |
||||
this.carrier = b.carrier; |
||||
this.logisticsServiceCode = b.logisticsServiceCode; |
||||
this.totalRate = b.totalRate; |
||||
this.costItems = Collections.unmodifiableList(new ArrayList<CostItem>(b.costItems)); |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
public String carrier() { |
||||
return carrier; |
||||
} |
||||
|
||||
public String logisticsServiceCode() { |
||||
return logisticsServiceCode; |
||||
} |
||||
|
||||
public Money totalRate() { |
||||
return totalRate; |
||||
} |
||||
|
||||
public List<CostItem> costItems() { |
||||
return costItems; |
||||
} |
||||
|
||||
/** 细分成本项,如「尾程运费」「燃油附加费」。 */ |
||||
public static final class CostItem { |
||||
|
||||
private final String costName; |
||||
private final Money estimatedCost; |
||||
|
||||
private CostItem(Builder b) { |
||||
this.costName = b.costName; |
||||
this.estimatedCost = b.estimatedCost; |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
public String costName() { |
||||
return costName; |
||||
} |
||||
|
||||
public Money estimatedCost() { |
||||
return estimatedCost; |
||||
} |
||||
|
||||
public static final class Builder { |
||||
private String costName; |
||||
private Money estimatedCost; |
||||
|
||||
public Builder costName(String v) { |
||||
this.costName = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder estimatedCost(Money v) { |
||||
this.estimatedCost = v; |
||||
return this; |
||||
} |
||||
|
||||
public CostItem build() { |
||||
return new CostItem(this); |
||||
} |
||||
} |
||||
} |
||||
|
||||
public static final class Builder { |
||||
private String carrier; |
||||
private String logisticsServiceCode; |
||||
private Money totalRate; |
||||
private final List<CostItem> costItems = new ArrayList<CostItem>(); |
||||
|
||||
public Builder carrier(String v) { |
||||
this.carrier = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder logisticsServiceCode(String v) { |
||||
this.logisticsServiceCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder totalRate(Money v) { |
||||
this.totalRate = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder costItem(CostItem v) { |
||||
this.costItems.add(v); |
||||
return this; |
||||
} |
||||
|
||||
public CarrierQuote build() { |
||||
return new CarrierQuote(this); |
||||
} |
||||
} |
||||
} |
||||
|
||||
public static final class Builder { |
||||
private WarehouseProvider sourceProvider; |
||||
private String shipOrgWarehouseCode; |
||||
private final List<CarrierQuote> carriers = new ArrayList<CarrierQuote>(); |
||||
|
||||
public Builder sourceProvider(WarehouseProvider v) { |
||||
this.sourceProvider = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder shipOrgWarehouseCode(String v) { |
||||
this.shipOrgWarehouseCode = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder carrier(CarrierQuote v) { |
||||
this.carriers.add(v); |
||||
return this; |
||||
} |
||||
|
||||
public FeeEstimateResult build() { |
||||
return new FeeEstimateResult(this); |
||||
} |
||||
} |
||||
} |
||||
@ -1,32 +0,0 @@
@@ -1,32 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** 入库计划单状态,已归一化。仓方状态值在适配器内映射到这里。 */ |
||||
public enum InboundStatus { |
||||
|
||||
/** 草稿 / 已创建。 */ |
||||
DRAFT, |
||||
/** 待审核。 */ |
||||
PENDING_REVIEW, |
||||
/** 审核拒绝。 */ |
||||
REJECTED, |
||||
/** 待装箱。 */ |
||||
PENDING_PACKING, |
||||
/** 待发货。 */ |
||||
PENDING_SHIPMENT, |
||||
/** 已发运 / 在途。 */ |
||||
IN_TRANSIT, |
||||
/** 收货中。 */ |
||||
RECEIVING, |
||||
/** 已收货。 */ |
||||
RECEIVED, |
||||
/** 待入库(上架)。 */ |
||||
PENDING_STORAGE, |
||||
/** 入库中(上架中)。 */ |
||||
STORING, |
||||
/** 已完成。 */ |
||||
COMPLETED, |
||||
/** 已取消。 */ |
||||
CANCELLED, |
||||
/** 无法识别的状态。 */ |
||||
UNKNOWN |
||||
} |
||||
@ -1,12 +0,0 @@
@@ -1,12 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 库存同步策略。仓能力不同:信仓支持按时间增量,易达云只能全量 diff。 |
||||
*/ |
||||
public enum InventorySyncStrategy { |
||||
|
||||
/** 按时间增量查询。 */ |
||||
TIME_WINDOW, |
||||
/** 全量拉取 + 差异比对。 */ |
||||
FULL_PULL_DIFF |
||||
} |
||||
@ -1,16 +0,0 @@
@@ -1,16 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 面单模式。 |
||||
* |
||||
* <p>必须与仓能力匹配:{@link #PLATFORM_LABEL} 要求仓声明 |
||||
* {@code WarehouseCapability.PLATFORM_LABEL_DELIVERY},缺失时 {@code create()} 拒绝, |
||||
* <b>不静默降级</b>为仓自有面单——面单归属直接影响与平台的标发方式。</p> |
||||
*/ |
||||
public enum LabelMode { |
||||
|
||||
/** 仓用自己的承运商账号出单,SDK 只回收面单与运单。 */ |
||||
WAREHOUSE_LABEL, |
||||
/** 渠道域先取平台面单,OMS 把面单文件下发给仓打印贴标。 */ |
||||
PLATFORM_LABEL |
||||
} |
||||
@ -1,46 +0,0 @@
@@ -1,46 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 出库单状态。仓方状态在适配器内映射到这里,只前进不后退。 |
||||
* |
||||
* <p>回调不保证顺序,宿主按本枚举的 {@link #rank()} 比较:小于当前值的事件记为 |
||||
* {@code OUT_OF_ORDER},保留记录但不覆盖状态。</p> |
||||
*/ |
||||
public enum OutboundStatus { |
||||
|
||||
/** 已创建(OMS 侧),尚未下发。 */ |
||||
CREATED(0), |
||||
/** SDK 下发成功,仓未确认。 */ |
||||
SUBMITTED(1), |
||||
/** 仓已接单。 */ |
||||
ACCEPTED(2), |
||||
/** 拣货中。 */ |
||||
PICKING(3), |
||||
/** 已打包。 */ |
||||
PACKED(4), |
||||
/** 面单已出。 */ |
||||
LABEL_READY(5), |
||||
/** 已交运。 */ |
||||
SHIPPED(6), |
||||
/** 已取消。 */ |
||||
CANCELLED(7), |
||||
/** 异常(仓侧拣货失败、地址异常等)。 */ |
||||
EXCEPTION(8); |
||||
|
||||
/** 状态推进序号,越大越靠后。 */ |
||||
private final int rank; |
||||
|
||||
OutboundStatus(int rank) { |
||||
this.rank = rank; |
||||
} |
||||
|
||||
/** 状态推进序号。 */ |
||||
public int rank() { |
||||
return rank; |
||||
} |
||||
|
||||
/** 是否终态(不会再变)。 */ |
||||
public boolean terminal() { |
||||
return this == SHIPPED || this == CANCELLED; |
||||
} |
||||
} |
||||
@ -0,0 +1,156 @@
@@ -0,0 +1,156 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
import java.time.Instant; |
||||
import java.util.ArrayList; |
||||
import java.util.Collections; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 运单物流轨迹查询结果。 |
||||
* |
||||
* <p>由 {@code TrackingCapable.trackShipment()} 返回:整体是<b>一个运单</b>的当前状态 + |
||||
* 若干节点,比 {@link TrackEvent}(单条事件)多出承运商、最新状态、签收人与预计妥投。</p> |
||||
* |
||||
* <p>状态值保持仓方原始字符串,见 {@link #status()};不做跨仓归一——各承运商的节点 |
||||
* 状态词汇差异太大,强行归一会丢失「派送失败 / 退回中」这类关键区分。</p> |
||||
*/ |
||||
public final class TrackingInfo { |
||||
|
||||
private final String trackingNumber; |
||||
private final String carrier; |
||||
/** 物流服务,如 {@code FedEx_FEDEX_GROUND};仓方未给时为 null。 */ |
||||
private final String carrierService; |
||||
/** 最新状态(仓方原值)。 */ |
||||
private final String status; |
||||
/** 最新状态的详细描述。 */ |
||||
private final String statusDetail; |
||||
/** 预计妥投时间(UTC);仓方未给时为 null。 */ |
||||
private final Instant estimatedDeliveryAt; |
||||
/** 签收人;未签收为 null。 */ |
||||
private final String signedBy; |
||||
/** 承运商侧可公开查询的轨迹页地址。 */ |
||||
private final String publicUrl; |
||||
private final List<TrackEvent> events; |
||||
|
||||
private TrackingInfo(Builder b) { |
||||
this.trackingNumber = require(b.trackingNumber, "trackingNumber"); |
||||
this.carrier = b.carrier; |
||||
this.carrierService = b.carrierService; |
||||
this.status = b.status; |
||||
this.statusDetail = b.statusDetail; |
||||
this.estimatedDeliveryAt = b.estimatedDeliveryAt; |
||||
this.signedBy = b.signedBy; |
||||
this.publicUrl = b.publicUrl; |
||||
this.events = Collections.unmodifiableList(new ArrayList<TrackEvent>(b.events)); |
||||
} |
||||
|
||||
public static Builder builder() { |
||||
return new Builder(); |
||||
} |
||||
|
||||
public String trackingNumber() { |
||||
return trackingNumber; |
||||
} |
||||
|
||||
public String carrier() { |
||||
return carrier; |
||||
} |
||||
|
||||
public String carrierService() { |
||||
return carrierService; |
||||
} |
||||
|
||||
/** 最新状态(仓方原值)。 */ |
||||
public String status() { |
||||
return status; |
||||
} |
||||
|
||||
public String statusDetail() { |
||||
return statusDetail; |
||||
} |
||||
|
||||
public Instant estimatedDeliveryAt() { |
||||
return estimatedDeliveryAt; |
||||
} |
||||
|
||||
public String signedBy() { |
||||
return signedBy; |
||||
} |
||||
|
||||
public String publicUrl() { |
||||
return publicUrl; |
||||
} |
||||
|
||||
/** 轨迹节点,按仓方返回顺序;不可变。 */ |
||||
public List<TrackEvent> events() { |
||||
return events; |
||||
} |
||||
|
||||
private static String require(String v, String name) { |
||||
if (v == null || v.trim().isEmpty()) { |
||||
throw new IllegalArgumentException(name + " must not be blank"); |
||||
} |
||||
return v.trim(); |
||||
} |
||||
|
||||
public static final class Builder { |
||||
private String trackingNumber; |
||||
private String carrier; |
||||
private String carrierService; |
||||
private String status; |
||||
private String statusDetail; |
||||
private Instant estimatedDeliveryAt; |
||||
private String signedBy; |
||||
private String publicUrl; |
||||
private final List<TrackEvent> events = new ArrayList<TrackEvent>(); |
||||
|
||||
public Builder trackingNumber(String v) { |
||||
this.trackingNumber = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder carrier(String v) { |
||||
this.carrier = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder carrierService(String v) { |
||||
this.carrierService = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder status(String v) { |
||||
this.status = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder statusDetail(String v) { |
||||
this.statusDetail = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder estimatedDeliveryAt(Instant v) { |
||||
this.estimatedDeliveryAt = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder signedBy(String v) { |
||||
this.signedBy = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder publicUrl(String v) { |
||||
this.publicUrl = v; |
||||
return this; |
||||
} |
||||
|
||||
public Builder event(TrackEvent v) { |
||||
this.events.add(v); |
||||
return this; |
||||
} |
||||
|
||||
public TrackingInfo build() { |
||||
return new TrackingInfo(this); |
||||
} |
||||
} |
||||
} |
||||
@ -1,29 +0,0 @@
@@ -1,29 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 调拨单状态,已归一化。 |
||||
* |
||||
* <p>运去哪的码:0 草稿 / 3 已驳回 / 5 待审核 / 6 审核中 / 7 审核通过 / 8 待确认 / |
||||
* 9 待备货 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 / |
||||
* 90 已关闭 / 100 取消中 / 110 已取消 / 120 取消异常。</p> |
||||
*/ |
||||
public enum TransferStatus { |
||||
|
||||
DRAFT, |
||||
REJECTED, |
||||
PENDING_REVIEW, |
||||
REVIEWING, |
||||
APPROVED, |
||||
PENDING_CONFIRM, |
||||
PENDING_PICKING, |
||||
PENDING_OUTBOUND, |
||||
OUTBOUNDING, |
||||
PENDING_INBOUND, |
||||
INBOUNDING, |
||||
COMPLETED, |
||||
CLOSED, |
||||
CANCELLING, |
||||
CANCELLED, |
||||
CANCEL_EXCEPTION, |
||||
UNKNOWN |
||||
} |
||||
@ -1,19 +0,0 @@
@@ -1,19 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 调拨类型。 |
||||
* |
||||
* <p>运去哪的 {@code type} 是 0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。 |
||||
* 只保留业务语义,适配器维护到仓方码值的映射。</p> |
||||
*/ |
||||
public enum TransferType { |
||||
|
||||
/** 仓到仓调拨。 */ |
||||
WAREHOUSE_TO_WAREHOUSE, |
||||
/** 调拨出库(发往外部地址或平台仓)。 */ |
||||
OUTBOUND, |
||||
/** 亚马逊移除订单(FBA 移出)。 */ |
||||
AMAZON_REMOVAL, |
||||
/** 亚马逊移入(FBA 入库)。 */ |
||||
AMAZON_INBOUND |
||||
} |
||||
@ -1,19 +0,0 @@
@@ -1,19 +0,0 @@
|
||||
package common.ecommerce.warehouse.model; |
||||
|
||||
/** |
||||
* 仓费用类型。 |
||||
* |
||||
* <p>各仓的枚举值不同,由适配器维护映射;这里只保留业务语义。 |
||||
* 运去哪 API 133 的 {@code costType} 是 1 作业费 / 2 仓储费 / 3 增值服务费 / 4 尾程费用。</p> |
||||
*/ |
||||
public enum WarehouseFeeType { |
||||
|
||||
/** 作业费(出入库操作费)。 */ |
||||
OPERATION, |
||||
/** 仓储费 / 仓租。 */ |
||||
STORAGE, |
||||
/** 增值服务费。 */ |
||||
VALUE_ADDED, |
||||
/** 尾程运费。 */ |
||||
LAST_MILE |
||||
} |
||||
@ -0,0 +1,128 @@
@@ -0,0 +1,128 @@
|
||||
package common.ecommerce.yqn.adapter; |
||||
|
||||
import common.ecommerce.shared.support.Money; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
||||
import common.ecommerce.warehouse.model.FeeEstimateResult; |
||||
import common.ecommerce.yqn.dto.YqnDtos; |
||||
|
||||
import java.math.BigDecimal; |
||||
import java.util.ArrayList; |
||||
import java.util.Collections; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 运去哪运费试算报文映射(API 121,{@code /v1/saleOrder/calculate})。 |
||||
*/ |
||||
public final class YqnFeeEstimateMapper { |
||||
|
||||
/** 尺寸单位:厘米。 */ |
||||
private static final int SIZE_UNIT_CM = 1; |
||||
/** 重量单位:克。 */ |
||||
private static final int WEIGHT_UNIT_GRAM = 2; |
||||
/** 运去哪未给币种时的回退值;文档所有金额均为 USD。 */ |
||||
private static final String DEFAULT_CURRENCY = "USD"; |
||||
|
||||
private YqnFeeEstimateMapper() { |
||||
} |
||||
|
||||
/** |
||||
* 统一试算条件 → 运去哪请求。 |
||||
* |
||||
* @param query 统一条件(cm / g) |
||||
* @param defaultWarehouseCode 调用方未指定仓时的回退仓 code |
||||
*/ |
||||
public static YqnDtos.CalculateRequest toRequest(FeeEstimateQuery query, String defaultWarehouseCode) { |
||||
YqnDtos.CalculateRequest req = new YqnDtos.CalculateRequest(); |
||||
req.sizeUnit = SIZE_UNIT_CM; |
||||
req.length = toDouble(query.lengthCm()); |
||||
req.width = toDouble(query.widthCm()); |
||||
req.height = toDouble(query.heightCm()); |
||||
req.weightUnit = WEIGHT_UNIT_GRAM; |
||||
req.weight = toDouble(query.weightGrams()); |
||||
if (query.insuredValue() != null) { |
||||
req.insuredValue = query.insuredValue().amount().doubleValue(); |
||||
} |
||||
req.warehouseSkuItem = toWarehouseItems(query.warehouseCodes(), defaultWarehouseCode); |
||||
req.receiveCountry = query.receiveCountry(); |
||||
req.receiveState = query.receiveState(); |
||||
req.receiveCity = query.receiveCity(); |
||||
req.receivePostal = query.receivePostal(); |
||||
req.receiveAddress = query.receiveAddress(); |
||||
if (query.residential() != null) { |
||||
req.isResidential = query.residential() ? 1 : 0; |
||||
} |
||||
req.logisticsServiceCode = query.logisticsServiceCode(); |
||||
req.logisticsProductCode = query.logisticsProductCode(); |
||||
req.signService = query.signService(); |
||||
return req; |
||||
} |
||||
|
||||
private static List<YqnDtos.CalculateRequest.CalculateSkuItem> toWarehouseItems( |
||||
List<String> warehouseCodes, String defaultWarehouseCode) { |
||||
List<String> codes = warehouseCodes; |
||||
if (codes == null || codes.isEmpty()) { |
||||
codes = defaultWarehouseCode == null || defaultWarehouseCode.trim().isEmpty() |
||||
? Collections.<String>emptyList() |
||||
: Collections.singletonList(defaultWarehouseCode); |
||||
} |
||||
if (codes.isEmpty()) { |
||||
throw new IllegalArgumentException( |
||||
"yqn fee estimate needs a shipOrgWarehouseCode; none given and account has none"); |
||||
} |
||||
List<YqnDtos.CalculateRequest.CalculateSkuItem> items = |
||||
new ArrayList<YqnDtos.CalculateRequest.CalculateSkuItem>(codes.size()); |
||||
for (String code : codes) { |
||||
YqnDtos.CalculateRequest.CalculateSkuItem item = |
||||
new YqnDtos.CalculateRequest.CalculateSkuItem(); |
||||
item.shipOrgWarehouseCode = code; |
||||
items.add(item); |
||||
} |
||||
return items; |
||||
} |
||||
|
||||
/** 运去哪一条仓库结果 → 统一结果。 */ |
||||
public static FeeEstimateResult toResult(YqnDtos.CalculateResult row) { |
||||
FeeEstimateResult.Builder builder = FeeEstimateResult.builder() |
||||
.sourceProvider(WarehouseProvider.YQN) |
||||
.shipOrgWarehouseCode(row.shipOrgWarehouseCode); |
||||
if (row.calculationCarrierItems != null) { |
||||
for (YqnDtos.CalculateResult.CalculateCarrierItem carrier : row.calculationCarrierItems) { |
||||
builder.carrier(toQuote(carrier)); |
||||
} |
||||
} |
||||
return builder.build(); |
||||
} |
||||
|
||||
private static FeeEstimateResult.CarrierQuote toQuote( |
||||
YqnDtos.CalculateResult.CalculateCarrierItem item) { |
||||
String currency = hasText(item.currency) ? item.currency.trim() : DEFAULT_CURRENCY; |
||||
FeeEstimateResult.CarrierQuote.Builder quote = FeeEstimateResult.CarrierQuote.builder() |
||||
.carrier(item.carrier) |
||||
.logisticsServiceCode(item.logisticsServiceCode) |
||||
.totalRate(item.totalRate == null ? null : money(item.totalRate, currency)); |
||||
if (item.calculationCostItems != null) { |
||||
for (YqnDtos.CalculateResult.CalculateCostItem cost : item.calculationCostItems) { |
||||
quote.costItem(FeeEstimateResult.CarrierQuote.CostItem.builder() |
||||
.costName(cost.costName) |
||||
.estimatedCost(cost.estimatedCost == null ? null |
||||
: money(cost.estimatedCost, |
||||
hasText(cost.currency) ? cost.currency.trim() : currency)) |
||||
.build()); |
||||
} |
||||
} |
||||
return quote.build(); |
||||
} |
||||
|
||||
private static Money money(Double amount, String currency) { |
||||
return Money.of(BigDecimal.valueOf(amount), currency); |
||||
} |
||||
|
||||
private static Double toDouble(BigDecimal v) { |
||||
return v == null ? null : v.doubleValue(); |
||||
} |
||||
|
||||
private static boolean hasText(String v) { |
||||
return v != null && !v.trim().isEmpty(); |
||||
} |
||||
} |
||||
@ -0,0 +1,143 @@
@@ -0,0 +1,143 @@
|
||||
package common.ecommerce.yqn.adapter; |
||||
|
||||
import common.ecommerce.warehouse.model.TrackEvent; |
||||
import common.ecommerce.warehouse.model.TrackingInfo; |
||||
import common.ecommerce.yqn.dto.YqnDtos; |
||||
|
||||
import java.time.Instant; |
||||
import java.time.LocalDateTime; |
||||
import java.time.ZoneId; |
||||
import java.time.ZoneOffset; |
||||
import java.time.format.DateTimeFormatter; |
||||
import java.time.format.DateTimeParseException; |
||||
import java.util.ArrayList; |
||||
import java.util.List; |
||||
|
||||
/** |
||||
* 运去哪物流轨迹映射(API 189)。 |
||||
* |
||||
* <p>状态值一律保持运去哪原话,不做归一:承运商的节点状态词汇差异大, |
||||
* 「派送失败 / 退回中」这类区分归一会丢信息。</p> |
||||
*/ |
||||
public final class YqnTrackingMapper { |
||||
|
||||
/** 仓方给的节点时间没带时区,按目的地习惯优先解析;解析不出再看其它格式。 */ |
||||
private static final DateTimeFormatter[] DATETIME_FORMATS = { |
||||
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"), |
||||
DateTimeFormatter.ISO_LOCAL_DATE_TIME, |
||||
}; |
||||
|
||||
private YqnTrackingMapper() { |
||||
} |
||||
|
||||
/** 响应 → 运单级轨迹。 */ |
||||
public static TrackingInfo toTrackingInfo(YqnDtos.ShipmentTrack track, String requestedTrackingNo, |
||||
ZoneId zone) { |
||||
String trackingNo = hasText(track.trackingCode) ? track.trackingCode.trim() : requestedTrackingNo; |
||||
YqnDtos.ShipmentTrack.CarrierDetail carrierDetail = track.carrierDetail; |
||||
TrackingInfo.Builder builder = TrackingInfo.builder() |
||||
.trackingNumber(trackingNo) |
||||
.carrier(track.carrier) |
||||
.carrierService(carrierDetail == null ? null : carrierDetail.service) |
||||
.status(track.status) |
||||
.statusDetail(track.statusDetail) |
||||
.estimatedDeliveryAt(parseTime(track.estDeliveryDate, zone)) |
||||
.signedBy(track.signedBy) |
||||
.publicUrl(track.publicUrl); |
||||
|
||||
List<YqnDtos.ShipmentTrack.TrackDetail> details = track.trackingDetails; |
||||
if (details != null) { |
||||
for (YqnDtos.ShipmentTrack.TrackDetail detail : details) { |
||||
builder.event(toTrackEvent(detail, trackingNo, track.carrier, zone)); |
||||
} |
||||
} |
||||
return builder.build(); |
||||
} |
||||
|
||||
/** 只取节点明细。 */ |
||||
public static List<TrackEvent> toTrackEvents(YqnDtos.ShipmentTrack track, String requestedTrackingNo, |
||||
ZoneId zone) { |
||||
return toTrackingInfo(track, requestedTrackingNo, zone).events(); |
||||
} |
||||
|
||||
private static TrackEvent toTrackEvent(YqnDtos.ShipmentTrack.TrackDetail detail, String trackingNo, |
||||
String carrier, ZoneId zone) { |
||||
return TrackEvent.builder() |
||||
.trackingNumber(trackingNo) |
||||
.carrier(carrier) |
||||
.status(detail.status) |
||||
.description(hasText(detail.message) ? detail.message : detail.statusDetail) |
||||
.location(locationOf(detail.trackingLocation)) |
||||
.occurredAt(parseTime(detail.datetime, zone)) |
||||
.build(); |
||||
} |
||||
|
||||
/** 位置拼成一行,如 {@code New York, NY, US, 10001};全空返回 null。 */ |
||||
private static String locationOf(YqnDtos.ShipmentTrack.TrackingLocation loc) { |
||||
if (loc == null) { |
||||
return null; |
||||
} |
||||
List<String> parts = new ArrayList<String>(4); |
||||
addIfText(parts, loc.city); |
||||
addIfText(parts, loc.state); |
||||
addIfText(parts, loc.country); |
||||
addIfText(parts, loc.zip); |
||||
return parts.isEmpty() ? null : join(parts); |
||||
} |
||||
|
||||
private static void addIfText(List<String> parts, String v) { |
||||
if (hasText(v)) { |
||||
parts.add(v.trim()); |
||||
} |
||||
} |
||||
|
||||
private static String join(List<String> parts) { |
||||
StringBuilder sb = new StringBuilder(); |
||||
for (int i = 0; i < parts.size(); i++) { |
||||
if (i > 0) { |
||||
sb.append(", "); |
||||
} |
||||
sb.append(parts.get(i)); |
||||
} |
||||
return sb.toString(); |
||||
} |
||||
|
||||
/** |
||||
* 解析仓方时间;失败返回 null,不因时间格式阻断轨迹展示。 |
||||
* |
||||
* <p>文档未给出 {@code datetime} 的格式,因此按「带时区 ISO → 常见本地格式」依次尝试; |
||||
* 都不带时区时按调用方给的 {@code zone} 解释。</p> |
||||
*/ |
||||
static Instant parseTime(String value, ZoneId zone) { |
||||
if (!hasText(value)) { |
||||
return null; |
||||
} |
||||
String v = value.trim(); |
||||
try { |
||||
return Instant.parse(v); |
||||
} catch (DateTimeParseException ignored) { |
||||
// 试本地格式
|
||||
} |
||||
try { |
||||
return java.time.OffsetDateTime.parse(v).toInstant(); |
||||
} catch (DateTimeParseException ignored) { |
||||
// 试本地格式
|
||||
} |
||||
for (DateTimeFormatter fmt : DATETIME_FORMATS) { |
||||
try { |
||||
return LocalDateTime.parse(v, fmt).atZone(zone == null ? ZoneOffset.UTC : zone).toInstant(); |
||||
} catch (DateTimeParseException ignored) { |
||||
// 下一个格式
|
||||
} |
||||
} |
||||
try { |
||||
return java.time.LocalDate.parse(v).atStartOfDay(zone == null ? ZoneOffset.UTC : zone).toInstant(); |
||||
} catch (DateTimeParseException ignored) { |
||||
return null; |
||||
} |
||||
} |
||||
|
||||
private static boolean hasText(String v) { |
||||
return v != null && !v.trim().isEmpty(); |
||||
} |
||||
} |
||||
@ -0,0 +1,73 @@
@@ -0,0 +1,73 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.InboundStatus; |
||||
|
||||
/** |
||||
* 运去哪入库计划状态(API 101 的 {@code inboundPlanOrderStatus})。 |
||||
* |
||||
* <p>运去哪给的是数字字符串。码表来自接口文档,1:1 对应,未知码归 {@link #UNKNOWN}。</p> |
||||
*/ |
||||
public enum YqnInboundStatus { |
||||
|
||||
/** 0 草稿。 */ |
||||
DRAFT("0", InboundStatus.DRAFT), |
||||
/** 5 待审核。 */ |
||||
PENDING_REVIEW("5", InboundStatus.PENDING_REVIEW), |
||||
/** 6 审核驳回。 */ |
||||
REJECTED("6", InboundStatus.REJECTED), |
||||
/** 8 待装箱。 */ |
||||
PENDING_PACKING("8", InboundStatus.PENDING_PACKING), |
||||
/** 10 待发货。 */ |
||||
PENDING_SHIPMENT("10", InboundStatus.PENDING_SHIPMENT), |
||||
/** 16 收货中。 */ |
||||
RECEIVING("16", InboundStatus.RECEIVING), |
||||
/** 17 已收货。 */ |
||||
RECEIVED("17", InboundStatus.RECEIVED), |
||||
/** 20 待上架。 */ |
||||
PENDING_STORAGE("20", InboundStatus.PENDING_STORAGE), |
||||
/** 25 上架中。 */ |
||||
STORING("25", InboundStatus.STORING), |
||||
/** 70 已完成。 */ |
||||
COMPLETED("70", InboundStatus.COMPLETED), |
||||
/** 100 已取消。 */ |
||||
CANCELLED("100", InboundStatus.CANCELLED), |
||||
/** 无法识别。 */ |
||||
UNKNOWN(null, InboundStatus.UNKNOWN); |
||||
|
||||
private final String rawCode; |
||||
private final InboundStatus core; |
||||
|
||||
YqnInboundStatus(String rawCode, InboundStatus core) { |
||||
this.rawCode = rawCode; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 运去哪的状态码;null 表示无法识别。 */ |
||||
public String rawCode() { |
||||
return rawCode; |
||||
} |
||||
|
||||
/** 对应的底层状态。 */ |
||||
public InboundStatus toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** 运去哪状态码 → 平台枚举。 */ |
||||
public static YqnInboundStatus of(String rawStatus) { |
||||
if (rawStatus == null || rawStatus.trim().isEmpty()) { |
||||
return UNKNOWN; |
||||
} |
||||
String s = rawStatus.trim(); |
||||
for (YqnInboundStatus v : values()) { |
||||
if (s.equals(v.rawCode)) { |
||||
return v; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
|
||||
/** 运去哪状态码 → 底层状态。 */ |
||||
public static InboundStatus toCore(String rawStatus) { |
||||
return of(rawStatus).toCore(); |
||||
} |
||||
} |
||||
@ -0,0 +1,76 @@
@@ -0,0 +1,76 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
/** |
||||
* 运去哪物流产品服务码(API 121 的 {@code logisticsServiceCode})。 |
||||
* |
||||
* <p>取值来自接口文档的枚举清单,<b>只有运去哪这一套</b>——core 没有「物流服务渠道」 |
||||
* 的通用枚举,也不打算造一个:各仓的渠道划分口径不同,强行归一必然失真。 |
||||
* 因此本枚举只用来避免调用方手写字符串,不映射到 core。</p> |
||||
* |
||||
* <p>文档把 {@code FedEx_INTERNATIONAL_ECONOMY} 等标注为「国际件」,这只是说明, |
||||
* 不做额外处理。</p> |
||||
*/ |
||||
public enum YqnLogisticsService { |
||||
|
||||
// FedEx
|
||||
FEDEX_GROUND("FedEx_FEDEX_GROUND"), |
||||
FEDEX_GROUND_HOME_DELIVERY("FedEx_GROUND_HOME_DELIVERY"), |
||||
FEDEX_SMART_POST("FedEx_SMART_POST"), |
||||
/** 国际件。 */ |
||||
FEDEX_INTERNATIONAL_ECONOMY("FedEx_INTERNATIONAL_ECONOMY"), |
||||
/** 国际件。 */ |
||||
FEDEX_INTERNATIONAL_PRIORITY("FedEx_INTERNATIONAL_PRIORITY"), |
||||
FEDEX_2_DAY("FedEx_FEDEX_2_DAY"), |
||||
FEDEX_EXPRESS_SAVER("FedEx_FEDEX_EXPRESS_SAVER"), |
||||
FEDEX_PRIORITY_OVERNIGHT("FedEx_PRIORITY_OVERNIGHT"), |
||||
FEDEX_STANDARD_OVERNIGHT("FedEx_STANDARD_OVERNIGHT"), |
||||
FEDEX_FIRST_OVERNIGHT("FedEx_FIRST_OVERNIGHT"), |
||||
|
||||
// UPS
|
||||
UPSA_MAIL_INNOVATIONS("UPSA_Mail_Innovations"), |
||||
UPSA_GROUND("UPSA_GROUND"), |
||||
UPS_GROUND("UPS_Ground"), |
||||
UPS_2DA("UPS_UPS2DAM"), |
||||
UPS_3DAY_SELECT("UPS_3DaySelect"), |
||||
UPS_NEXT_DAY_AIR("UPS_NextDayAir"), |
||||
UPS_NEXT_DAY_AIR_SAVER("UPS_NextDayAirSaver"), |
||||
UPS_NEXT_DAY_AIR_EARLY_AM("UPS_NextDayAirEarlyAM"), |
||||
UPS_2ND_DAY_AIR("UPS_2ndDayAir"), |
||||
/** 国际件。 */ |
||||
UPSCA_XI("UPSCA_XI_UPSGCA_XI"), |
||||
|
||||
// 其它承运商
|
||||
JT_BASIC("JT_Basic"), |
||||
AMAZON_SP_GROUND("AmazonSP_Ground"), |
||||
AMAZON_SP0_GROUND("AmazonSP0_Ground"), |
||||
AMAZON_SP1_GROUND("AmazonSP1_Ground"), |
||||
AMAZON_SP2_GROUND("AmazonSP2_Ground"), |
||||
USPS_GROUND_ADVANTAGE("USPS_Ground_Advantage"), |
||||
USPS_PRIORITY_MAIL("USPS_Priority_Mail"), |
||||
ONTRAC_GROUND("Ontrac_Ground"), |
||||
IMILE_BASIC("iMile_Basic"); |
||||
|
||||
private final String code; |
||||
|
||||
YqnLogisticsService(String code) { |
||||
this.code = code; |
||||
} |
||||
|
||||
/** 运去哪请求里要填的原值。 */ |
||||
public String code() { |
||||
return code; |
||||
} |
||||
|
||||
/** 按码值反查;未知返回 null(调用方可继续用字符串透传未收录的码)。 */ |
||||
public static YqnLogisticsService of(String code) { |
||||
if (code == null) { |
||||
return null; |
||||
} |
||||
for (YqnLogisticsService v : values()) { |
||||
if (v.code.equals(code)) { |
||||
return v; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
} |
||||
@ -0,0 +1,83 @@
@@ -0,0 +1,83 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.OutboundStatus; |
||||
|
||||
/** |
||||
* 运去哪出库单状态(API 128 的 {@code orderStatusEnum})。 |
||||
* |
||||
* <p>运去哪这个字段给的是英文文本而不是数字码,且目前<b>没有公开发布的码表</b>, |
||||
* 所以这里按关键字匹配。匹配不到的归 {@link #UNKNOWN}——<b>不猜</b>, |
||||
* 早先的实现把认不出的当 {@code SUBMITTED}(已下发)是错的。</p> |
||||
* |
||||
* <p>关键字匹配是有损的:{@code UNSHIPPED} 这类名字会命中 {@code SHIP}。 |
||||
* 拿到官方码表后应改成精确匹配。</p> |
||||
*/ |
||||
public enum YqnOutboundStatus { |
||||
|
||||
/** 已取消 / 取消中。 */ |
||||
CANCELLED("CANCEL", OutboundStatus.CANCELLED), |
||||
/** 已交运 / 已发出 / 已妥投。 */ |
||||
SHIPPED("SHIP", OutboundStatus.SHIPPED), |
||||
/** 已妥投(独立关键字,避免只靠 SHIP 覆盖)。 */ |
||||
DELIVERED("DELIVER", OutboundStatus.SHIPPED), |
||||
/** 面单已打印。 */ |
||||
LABEL_READY("LABEL", OutboundStatus.LABEL_READY), |
||||
/** 已打包。 */ |
||||
PACKED("PACK", OutboundStatus.PACKED), |
||||
/** 拣货中。 */ |
||||
PICKING("PICK", OutboundStatus.PICKING), |
||||
/** 仓已接单。 */ |
||||
ACCEPTED("ACCEPT", OutboundStatus.ACCEPTED), |
||||
/** 异常。 */ |
||||
EXCEPTION("EXCEPTION", OutboundStatus.EXCEPTION), |
||||
/** 失败 / 错误。 */ |
||||
FAILED("FAIL", OutboundStatus.EXCEPTION), |
||||
/** 错误码。 */ |
||||
ERROR("ERROR", OutboundStatus.EXCEPTION), |
||||
/** 无法识别。 */ |
||||
UNKNOWN(null, OutboundStatus.UNKNOWN); |
||||
|
||||
private final String keyword; |
||||
private final OutboundStatus core; |
||||
|
||||
YqnOutboundStatus(String keyword, OutboundStatus core) { |
||||
this.keyword = keyword; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 运去哪原始值里的关键字;null 表示「无关键字 / 认不出」。 */ |
||||
public String keyword() { |
||||
return keyword; |
||||
} |
||||
|
||||
/** 对应的底层状态。 */ |
||||
public OutboundStatus toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** |
||||
* 运去哪原始值 → 平台枚举。 |
||||
* |
||||
* <p>空值或匹配不到返回 {@link #UNKNOWN}。按声明顺序匹配,越具体的放越前。</p> |
||||
*/ |
||||
public static YqnOutboundStatus of(String rawStatus) { |
||||
if (rawStatus == null) { |
||||
return UNKNOWN; |
||||
} |
||||
String s = rawStatus.trim().toUpperCase(); |
||||
if (s.isEmpty()) { |
||||
return UNKNOWN; |
||||
} |
||||
for (YqnOutboundStatus v : values()) { |
||||
if (v.keyword != null && s.contains(v.keyword)) { |
||||
return v; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
|
||||
/** 运去哪原始值 → 底层状态。 */ |
||||
public static OutboundStatus toCore(String rawStatus) { |
||||
return of(rawStatus).toCore(); |
||||
} |
||||
} |
||||
@ -0,0 +1,67 @@
@@ -0,0 +1,67 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.ReturnDealMethod; |
||||
|
||||
/** |
||||
* 运去哪「退货预约处理方式」(API 81 的 {@code returnDealMethod})。 |
||||
* |
||||
* <p>码表:0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。</p> |
||||
* |
||||
* <p><b>与 {@link YqnReturnProcessDisposition} 不是一回事</b>:那个是仓收货检验后 |
||||
* 逐条明细行的决定(0/2/3/4),两套码值不能互换。</p> |
||||
*/ |
||||
public enum YqnReturnDealMethod { |
||||
|
||||
/** 0 客户自提。 */ |
||||
CUSTOMER_PICKUP(0, ReturnDealMethod.CUSTOMER_PICKUP), |
||||
/** 1 拍照确认后由客户决定。 */ |
||||
PHOTO_CONFIRM(1, ReturnDealMethod.PHOTO_CONFIRM), |
||||
/** 2 销毁。 */ |
||||
DESTROY(2, ReturnDealMethod.DESTROY), |
||||
/** 5 仓库确认处理。 */ |
||||
WAREHOUSE_CONFIRM(5, ReturnDealMethod.WAREHOUSE_CONFIRM); |
||||
|
||||
private final Integer rawCode; |
||||
private final ReturnDealMethod core; |
||||
|
||||
YqnReturnDealMethod(Integer rawCode, ReturnDealMethod core) { |
||||
this.rawCode = rawCode; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 运去哪码值。 */ |
||||
public Integer rawCode() { |
||||
return rawCode; |
||||
} |
||||
|
||||
/** 对应的底层处理方式。 */ |
||||
public ReturnDealMethod toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** 底层处理方式 → 运去哪码值;null 透传。 */ |
||||
public static Integer codeOf(ReturnDealMethod method) { |
||||
if (method == null) { |
||||
return null; |
||||
} |
||||
for (YqnReturnDealMethod v : values()) { |
||||
if (v.core == method) { |
||||
return v.rawCode; |
||||
} |
||||
} |
||||
throw new IllegalArgumentException("yqn does not support returnDealMethod: " + method); |
||||
} |
||||
|
||||
/** 运去哪码值 → 底层处理方式;未知返回 null。 */ |
||||
public static ReturnDealMethod toCore(Integer rawCode) { |
||||
if (rawCode == null) { |
||||
return null; |
||||
} |
||||
for (YqnReturnDealMethod v : values()) { |
||||
if (rawCode.equals(v.rawCode)) { |
||||
return v.core; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
} |
||||
@ -0,0 +1,67 @@
@@ -0,0 +1,67 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.ReturnProcessDisposition; |
||||
|
||||
/** |
||||
* 运去哪「退货检验后处理方式」(API 77 的 {@code goodsReturnType})。 |
||||
* |
||||
* <p>码表:0 客户自提 / 2 销毁 / 3 上架(良品)/ 4 换标上架(良品)。</p> |
||||
* |
||||
* <p><b>与 {@link YqnReturnDealMethod} 不是一回事</b>:那个是预约时的预报(0/1/2/5), |
||||
* 两套码值不能互换。</p> |
||||
*/ |
||||
public enum YqnReturnProcessDisposition { |
||||
|
||||
/** 0 客户自提。 */ |
||||
CUSTOMER_PICKUP(0, ReturnProcessDisposition.CUSTOMER_PICKUP), |
||||
/** 2 销毁。 */ |
||||
DESTROY(2, ReturnProcessDisposition.DESTROY), |
||||
/** 3 上架(良品)。 */ |
||||
RESTOCK(3, ReturnProcessDisposition.RESTOCK), |
||||
/** 4 换标上架(良品)。 */ |
||||
RESTOCK_RELABEL(4, ReturnProcessDisposition.RESTOCK_RELABEL); |
||||
|
||||
private final Integer rawCode; |
||||
private final ReturnProcessDisposition core; |
||||
|
||||
YqnReturnProcessDisposition(Integer rawCode, ReturnProcessDisposition core) { |
||||
this.rawCode = rawCode; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 运去哪码值。 */ |
||||
public Integer rawCode() { |
||||
return rawCode; |
||||
} |
||||
|
||||
/** 对应的底层处理方式。 */ |
||||
public ReturnProcessDisposition toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** 底层处理方式 → 运去哪码值;null 透传。 */ |
||||
public static Integer codeOf(ReturnProcessDisposition disposition) { |
||||
if (disposition == null) { |
||||
return null; |
||||
} |
||||
for (YqnReturnProcessDisposition v : values()) { |
||||
if (v.core == disposition) { |
||||
return v.rawCode; |
||||
} |
||||
} |
||||
throw new IllegalArgumentException("yqn does not support disposition: " + disposition); |
||||
} |
||||
|
||||
/** 运去哪码值 → 底层处理方式;未知返回 null。 */ |
||||
public static ReturnProcessDisposition toCore(Integer rawCode) { |
||||
if (rawCode == null) { |
||||
return null; |
||||
} |
||||
for (YqnReturnProcessDisposition v : values()) { |
||||
if (rawCode.equals(v.rawCode)) { |
||||
return v.core; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
} |
||||
@ -0,0 +1,82 @@
@@ -0,0 +1,82 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.TransferStatus; |
||||
|
||||
/** |
||||
* 运去哪调拨单状态(API 139 的 {@code transferOutboundPlanStatus})。 |
||||
* |
||||
* <p>码表来自接口文档,1:1 对应;未知码归 {@link #UNKNOWN},不猜。</p> |
||||
*/ |
||||
public enum YqnTransferStatus { |
||||
|
||||
/** 0 草稿。 */ |
||||
DRAFT(0, TransferStatus.DRAFT), |
||||
/** 3 已驳回。 */ |
||||
REJECTED(3, TransferStatus.REJECTED), |
||||
/** 5 待审核。 */ |
||||
PENDING_REVIEW(5, TransferStatus.PENDING_REVIEW), |
||||
/** 6 审核中。 */ |
||||
REVIEWING(6, TransferStatus.REVIEWING), |
||||
/** 7 审核通过。 */ |
||||
APPROVED(7, TransferStatus.APPROVED), |
||||
/** 8 待确认。 */ |
||||
PENDING_CONFIRM(8, TransferStatus.PENDING_CONFIRM), |
||||
/** 9 待备货。 */ |
||||
PENDING_PICKING(9, TransferStatus.PENDING_PICKING), |
||||
/** 10 待出库。 */ |
||||
PENDING_OUTBOUND(10, TransferStatus.PENDING_OUTBOUND), |
||||
/** 15 出库中。 */ |
||||
OUTBOUNDING(15, TransferStatus.OUTBOUNDING), |
||||
/** 20 待入库。 */ |
||||
PENDING_INBOUND(20, TransferStatus.PENDING_INBOUND), |
||||
/** 25 入库中。 */ |
||||
INBOUNDING(25, TransferStatus.INBOUNDING), |
||||
/** 70 已完成。 */ |
||||
COMPLETED(70, TransferStatus.COMPLETED), |
||||
/** 90 已关闭。 */ |
||||
CLOSED(90, TransferStatus.CLOSED), |
||||
/** 100 取消中。 */ |
||||
CANCELLING(100, TransferStatus.CANCELLING), |
||||
/** 110 已取消。 */ |
||||
CANCELLED(110, TransferStatus.CANCELLED), |
||||
/** 120 取消异常。 */ |
||||
CANCEL_EXCEPTION(120, TransferStatus.CANCEL_EXCEPTION), |
||||
/** 无法识别。 */ |
||||
UNKNOWN(null, TransferStatus.UNKNOWN); |
||||
|
||||
private final Integer rawCode; |
||||
private final TransferStatus core; |
||||
|
||||
YqnTransferStatus(Integer rawCode, TransferStatus core) { |
||||
this.rawCode = rawCode; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 运去哪的状态码;null 表示无法识别。 */ |
||||
public Integer rawCode() { |
||||
return rawCode; |
||||
} |
||||
|
||||
/** 对应的底层状态。 */ |
||||
public TransferStatus toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** 运去哪状态码 → 平台枚举。 */ |
||||
public static YqnTransferStatus of(Integer rawStatus) { |
||||
if (rawStatus == null) { |
||||
return UNKNOWN; |
||||
} |
||||
for (YqnTransferStatus v : values()) { |
||||
if (rawStatus.equals(v.rawCode)) { |
||||
return v; |
||||
} |
||||
} |
||||
return UNKNOWN; |
||||
} |
||||
|
||||
/** 运去哪状态码 → 底层状态。 */ |
||||
public static TransferStatus toCore(Integer rawStatus) { |
||||
return of(rawStatus).toCore(); |
||||
} |
||||
} |
||||
@ -0,0 +1,64 @@
@@ -0,0 +1,64 @@
|
||||
package common.ecommerce.yqn.enums; |
||||
|
||||
import common.ecommerce.warehouse.enums.TransferType; |
||||
|
||||
/** |
||||
* 运去哪调拨类型(API 139 的 {@code type})。 |
||||
* |
||||
* <p>码表来自接口文档:0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。</p> |
||||
*/ |
||||
public enum YqnTransferType { |
||||
|
||||
/** 0 亚马逊移出。 */ |
||||
AMAZON_REMOVAL(0, TransferType.AMAZON_REMOVAL), |
||||
/** 1 亚马逊移入。 */ |
||||
AMAZON_INBOUND(1, TransferType.AMAZON_INBOUND), |
||||
/** 2 仓到仓调拨。 */ |
||||
WAREHOUSE_TO_WAREHOUSE(2, TransferType.WAREHOUSE_TO_WAREHOUSE), |
||||
/** 3 调拨出库。 */ |
||||
OUTBOUND(3, TransferType.OUTBOUND); |
||||
|
||||
private final Integer rawCode; |
||||
private final TransferType core; |
||||
|
||||
YqnTransferType(Integer rawCode, TransferType core) { |
||||
this.rawCode = rawCode; |
||||
this.core = core; |
||||
} |
||||
|
||||
/** 运去哪的类型码。 */ |
||||
public Integer rawCode() { |
||||
return rawCode; |
||||
} |
||||
|
||||
/** 对应的底层类型。 */ |
||||
public TransferType toCore() { |
||||
return core; |
||||
} |
||||
|
||||
/** 底层类型 → 运去哪类型码;null 透传。 */ |
||||
public static Integer codeOf(TransferType type) { |
||||
if (type == null) { |
||||
return null; |
||||
} |
||||
for (YqnTransferType v : values()) { |
||||
if (v.core == type) { |
||||
return v.rawCode; |
||||
} |
||||
} |
||||
throw new IllegalArgumentException("yqn does not support transfer type: " + type); |
||||
} |
||||
|
||||
/** 运去哪类型码 → 底层类型;未知码返回 null(与原有行为一致)。 */ |
||||
public static TransferType toCore(Integer rawCode) { |
||||
if (rawCode == null) { |
||||
return null; |
||||
} |
||||
for (YqnTransferType v : values()) { |
||||
if (rawCode.equals(v.rawCode)) { |
||||
return v.core; |
||||
} |
||||
} |
||||
return null; |
||||
} |
||||
} |
||||
@ -0,0 +1,186 @@
@@ -0,0 +1,186 @@
|
||||
package common.ecommerce.yqn.adapter; |
||||
|
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
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.WarehouseCapability; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
||||
import common.ecommerce.warehouse.model.FeeEstimateResult; |
||||
import common.ecommerce.warehouse.sdk.WarehouseConnection; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
import common.ecommerce.yqn.YqnConstants; |
||||
import common.ecommerce.yqn.enums.YqnLogisticsService; |
||||
import org.junit.jupiter.api.Test; |
||||
|
||||
import java.math.BigDecimal; |
||||
import java.time.Clock; |
||||
import java.time.Instant; |
||||
import java.time.ZoneOffset; |
||||
import java.util.List; |
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals; |
||||
import static org.junit.jupiter.api.Assertions.assertFalse; |
||||
import static org.junit.jupiter.api.Assertions.assertNull; |
||||
import static org.junit.jupiter.api.Assertions.assertThrows; |
||||
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||
|
||||
/** |
||||
* 订单测算 / 运费试算(API 121)契约测试。 |
||||
*/ |
||||
class YqnFeeEstimateTest { |
||||
|
||||
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); |
||||
|
||||
private static WarehouseContext ctx() { |
||||
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", |
||||
WarehouseConnection.of(YqnConstants.PR_BASE_URL, |
||||
ChannelSecret.builder().appSecret("key-1").build()), |
||||
"req-estimate", CLOCK); |
||||
} |
||||
|
||||
private static FeeEstimateQuery query() { |
||||
return FeeEstimateQuery.builder() |
||||
.warehouseCode("RF_NY_US") |
||||
.lengthCm(new BigDecimal("30")) |
||||
.widthCm(new BigDecimal("20")) |
||||
.heightCm(new BigDecimal("10")) |
||||
.weightGrams(new BigDecimal("500")) |
||||
.insuredValue(Money.of("100.00", "USD")) |
||||
.receiveCountry("US") |
||||
.receiveState("NY") |
||||
.receiveCity("New York") |
||||
.receivePostal("10001") |
||||
.receiveAddress("1 Main St") |
||||
.residential(true) |
||||
.logisticsServiceCode(YqnLogisticsService.FEDEX_GROUND.code()) |
||||
.signService("SIGNATURE") |
||||
.build(); |
||||
} |
||||
|
||||
@Test |
||||
void sendsUnitsInCmAndGrams() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}")); |
||||
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), query()); |
||||
|
||||
String body = transport.lastDataRequest().body(); |
||||
assertTrue(body.contains("\"sizeUnit\":1"), body); |
||||
assertTrue(body.contains("\"weightUnit\":2"), body); |
||||
assertTrue(body.contains("\"length\":30.0"), body); |
||||
assertTrue(body.contains("\"weight\":500.0"), body); |
||||
assertTrue(body.contains("\"isResidential\":1"), body); |
||||
assertTrue(body.contains("\"shipOrgWarehouseCode\":\"RF_NY_US\""), body); |
||||
assertTrue(body.contains("\"logisticsServiceCode\":\"FedEx_FEDEX_GROUND\""), body); |
||||
assertTrue(body.contains("\"receivePostal\":\"10001\""), body); |
||||
} |
||||
|
||||
@Test |
||||
void omitsResidentialWhenNotGiven() { |
||||
FeeEstimateQuery withoutResidential = FeeEstimateQuery.builder() |
||||
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||
.weightGrams(BigDecimal.ONE) |
||||
.receiveCountry("US").receivePostal("10001") |
||||
.logisticsServiceCode(YqnLogisticsService.UPS_GROUND.code()) |
||||
.build(); |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[]}")); |
||||
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), withoutResidential); |
||||
|
||||
assertFalse(transport.lastDataRequest().body().contains("isResidential")); |
||||
} |
||||
|
||||
@Test |
||||
void fallsBackToAccountWarehouseWhenNoneGiven() { |
||||
FeeEstimateQuery noWarehouse = FeeEstimateQuery.builder() |
||||
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||
.weightGrams(BigDecimal.ONE) |
||||
.receiveCountry("US").receivePostal("10001") |
||||
.logisticsServiceCode(YqnLogisticsService.USPS_PRIORITY_MAIL.code()) |
||||
.build(); |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[]}")); |
||||
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), noWarehouse); |
||||
|
||||
assertTrue(transport.lastDataRequest().body() |
||||
.contains("\"shipOrgWarehouseCode\":\"RF_NY_US\"")); |
||||
} |
||||
|
||||
@Test |
||||
void mapsCarriersAndCostItems() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[" |
||||
+ "{\"shipOrgWarehouseCode\":\"RF_NY_US\",\"calculationCarrierItems\":[" |
||||
+ "{\"carrier\":\"FEDEX\",\"logisticsServiceCode\":\"FedEx_FEDEX_GROUND\"," |
||||
+ "\"currency\":\"USD\",\"totalRate\":12.5," |
||||
+ "\"calculationCostItems\":[" |
||||
+ "{\"costName\":\"尾程运费\",\"estimatedCost\":10.0,\"currency\":\"USD\"}," |
||||
+ "{\"costName\":\"燃油附加费\",\"estimatedCost\":2.5,\"currency\":\"USD\"}]}]}]}")); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
List<FeeEstimateResult> results = adapter.estimate(ctx(), query()); |
||||
|
||||
assertEquals(1, results.size()); |
||||
FeeEstimateResult result = results.get(0); |
||||
assertEquals(WarehouseProvider.YQN, result.sourceProvider()); |
||||
assertEquals("RF_NY_US", result.shipOrgWarehouseCode()); |
||||
assertEquals(1, result.carriers().size()); |
||||
|
||||
FeeEstimateResult.CarrierQuote quote = result.carriers().get(0); |
||||
assertEquals("FEDEX", quote.carrier()); |
||||
assertEquals("FedEx_FEDEX_GROUND", quote.logisticsServiceCode()); |
||||
assertEquals(new BigDecimal("12.5"), quote.totalRate().amount()); |
||||
assertEquals("USD", quote.totalRate().currency().getCurrencyCode()); |
||||
assertEquals(2, quote.costItems().size()); |
||||
assertEquals("尾程运费", quote.costItems().get(0).costName()); |
||||
assertEquals(new BigDecimal("10.0"), quote.costItems().get(0).estimatedCost().amount()); |
||||
} |
||||
|
||||
@Test |
||||
void emptyDataIsNotAnError() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok( |
||||
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}")); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
assertTrue(adapter.estimate(ctx(), query()).isEmpty()); |
||||
} |
||||
|
||||
@Test |
||||
void declaresFeeEstimateCapability() { |
||||
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); |
||||
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_ESTIMATE)); |
||||
// 试算与结算明细是两个能力,互不替代
|
||||
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_SETTLEMENT)); |
||||
} |
||||
|
||||
@Test |
||||
void queryRequiresPositiveDimensions() { |
||||
assertThrows(IllegalArgumentException.class, () -> FeeEstimateQuery.builder() |
||||
.lengthCm(BigDecimal.ZERO).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||
.weightGrams(BigDecimal.ONE) |
||||
.receiveCountry("US").receivePostal("10001") |
||||
.logisticsServiceCode("x") |
||||
.build()); |
||||
assertThrows(IllegalArgumentException.class, () -> FeeEstimateQuery.builder() |
||||
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE) |
||||
.weightGrams(BigDecimal.ONE) |
||||
.receiveCountry("US") |
||||
.logisticsServiceCode("x") |
||||
.build()); |
||||
} |
||||
|
||||
@Test |
||||
void logisticsServiceEnumRoundTrips() { |
||||
assertEquals("iMile_Basic", YqnLogisticsService.IMILE_BASIC.code()); |
||||
assertEquals(YqnLogisticsService.UPS_GROUND, YqnLogisticsService.of("UPS_Ground")); |
||||
assertNull(YqnLogisticsService.of("SOME_NEW_CHANNEL")); |
||||
assertNull(YqnLogisticsService.of(null)); |
||||
} |
||||
} |
||||
@ -0,0 +1,178 @@
@@ -0,0 +1,178 @@
|
||||
package common.ecommerce.yqn.adapter; |
||||
|
||||
import common.ecommerce.http.JacksonJsonCodec; |
||||
import common.ecommerce.shared.spi.ChannelSecret; |
||||
import common.ecommerce.shared.testkit.RecordingTransport; |
||||
import common.ecommerce.shared.testkit.Responses; |
||||
import common.ecommerce.warehouse.enums.WarehouseCapability; |
||||
import common.ecommerce.warehouse.enums.WarehouseProvider; |
||||
import common.ecommerce.warehouse.model.TrackEvent; |
||||
import common.ecommerce.warehouse.model.TrackingInfo; |
||||
import common.ecommerce.warehouse.sdk.WarehouseConnection; |
||||
import common.ecommerce.warehouse.sdk.WarehouseContext; |
||||
import common.ecommerce.warehouse.sdk.WarehouseAdapter; |
||||
import java.util.EnumSet; |
||||
import common.ecommerce.yqn.YqnConstants; |
||||
import org.junit.jupiter.api.Test; |
||||
|
||||
import java.time.Clock; |
||||
import java.time.Instant; |
||||
import java.time.ZoneOffset; |
||||
import java.util.List; |
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals; |
||||
import static org.junit.jupiter.api.Assertions.assertNull; |
||||
import static org.junit.jupiter.api.Assertions.assertThrows; |
||||
import static org.junit.jupiter.api.Assertions.assertTrue; |
||||
|
||||
/** |
||||
* 物流轨迹(API 189)契约测试。 |
||||
* |
||||
* <p>注意这个接口在<b>另一个主机</b>,且成功码是 {@code 1} 而不是 {@code 200}。</p> |
||||
*/ |
||||
class YqnTrackingTest { |
||||
|
||||
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC); |
||||
|
||||
private static ChannelSecret secret() { |
||||
return ChannelSecret.builder().appSecret("key-1").build(); |
||||
} |
||||
|
||||
/** 主基址 + 辅助基址。 */ |
||||
private static WarehouseContext ctx() { |
||||
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", |
||||
WarehouseConnection.of(YqnConstants.PR_BASE_URL, YqnConstants.AUX_BASE_URL_PR, secret()), |
||||
"req-track", CLOCK); |
||||
} |
||||
|
||||
/** 只有主基址。 */ |
||||
private static WarehouseContext ctxWithoutAux() { |
||||
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US", |
||||
WarehouseConnection.of(YqnConstants.PR_BASE_URL, secret()), "req-track", CLOCK); |
||||
} |
||||
|
||||
private static final String OK_BODY = |
||||
"{\"code\":1,\"message\":\"success\",\"data\":{" |
||||
+ "\"id\":9527,\"carrier\":\"FEDEX\",\"trackingCode\":\"TRK123\"," |
||||
+ "\"status\":\"DELIVERED\",\"statusDetail\":\"已签收\"," |
||||
+ "\"estDeliveryDate\":\"2026-11-12T10:00:00Z\"," |
||||
+ "\"signedBy\":\"J SMITH\",\"publicUrl\":\"https://track.example/TRK123\"," |
||||
+ "\"trackingDetails\":[" |
||||
+ "{\"status\":\"IN_TRANSIT\",\"message\":\"已离开分拨中心\"," |
||||
+ "\"datetime\":\"2026-11-09 08:30:00\",\"timeZone\":\"America/New_York\"," |
||||
+ "\"trackingLocation\":{\"city\":\"Newark\",\"state\":\"NJ\"," |
||||
+ "\"country\":\"US\",\"zip\":\"07102\"}}," |
||||
+ "{\"status\":\"DELIVERED\",\"message\":\"delivered\"," |
||||
+ "\"datetime\":\"2026-11-10T15:20:00Z\",\"signedBy\":null}]," |
||||
+ "\"carrierDetail\":{\"service\":\"FedEx_FEDEX_GROUND\"}}}"; |
||||
|
||||
@Test |
||||
void callsAuxiliaryHostNotWarehouseHost() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); |
||||
new YqnAdapter(transport, new JacksonJsonCodec()).trackShipment(ctx(), "TRK123"); |
||||
|
||||
String url = transport.lastDataRequest().url(); |
||||
assertTrue(url.startsWith(YqnConstants.AUX_BASE_URL_PR), url); |
||||
assertTrue(url.contains("/api/v2/orderShipment/track/TRK123"), url); |
||||
} |
||||
|
||||
@Test |
||||
void missingAuxEndpointIsRejectedNotSilentlyRetargeted() { |
||||
RecordingTransport transport = RecordingTransport.create(); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
assertThrows(common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException.class, |
||||
() -> adapter.trackShipment(ctxWithoutAux(), "TRK123")); |
||||
assertTrue(transport.recorded().isEmpty(), "不应该发出任何请求"); |
||||
} |
||||
|
||||
@Test |
||||
void mapsShipmentLevelFields() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
TrackingInfo info = adapter.trackShipment(ctx(), "TRK123"); |
||||
|
||||
assertEquals("TRK123", info.trackingNumber()); |
||||
assertEquals("FEDEX", info.carrier()); |
||||
assertEquals("FedEx_FEDEX_GROUND", info.carrierService()); |
||||
assertEquals("DELIVERED", info.status()); |
||||
assertEquals("已签收", info.statusDetail()); |
||||
assertEquals(Instant.parse("2026-11-12T10:00:00Z"), info.estimatedDeliveryAt()); |
||||
assertEquals("J SMITH", info.signedBy()); |
||||
assertEquals("https://track.example/TRK123", info.publicUrl()); |
||||
assertEquals(2, info.events().size()); |
||||
} |
||||
|
||||
@Test |
||||
void mapsTrackingDetailsAndLocation() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
TrackingInfo info = adapter.trackShipment(ctx(), "TRK123"); |
||||
TrackEvent first = info.events().get(0); |
||||
|
||||
assertEquals("IN_TRANSIT", first.status()); |
||||
assertEquals("已离开分拨中心", first.description()); |
||||
assertEquals("Newark, NJ, US, 07102", first.location()); |
||||
assertEquals("TRK123", first.trackingNumber()); |
||||
assertEquals("FEDEX", first.carrier()); |
||||
// 带时区的直接解析;本地格式按调用时区解释
|
||||
assertEquals(Instant.parse("2026-11-10T15:20:00Z"), info.events().get(1).occurredAt()); |
||||
|
||||
TrackEvent second = info.events().get(1); |
||||
assertEquals("DELIVERED", second.status()); |
||||
assertNull(second.location()); |
||||
} |
||||
|
||||
@Test |
||||
void trackReturnsSameEventsAsTrackShipment() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY)); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
List<TrackEvent> events = adapter.track(ctx(), "TRK123"); |
||||
|
||||
assertEquals(2, events.size()); |
||||
assertEquals("IN_TRANSIT", events.get(0).status()); |
||||
} |
||||
|
||||
/** 成功码是 1;返回 200 之类要按失败处理,不能当成成功去解析 data。 */ |
||||
@Test |
||||
void nonOneCodeIsFailure() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok( |
||||
"{\"code\":200,\"message\":\"ok\",\"data\":{\"trackingCode\":\"TRK123\"}}")); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
RuntimeException ex = assertThrows(RuntimeException.class, |
||||
() -> adapter.trackShipment(ctx(), "TRK123")); |
||||
assertTrue(ex.getMessage().contains("code=200"), ex.getMessage()); |
||||
} |
||||
|
||||
@Test |
||||
void missingCodeIsFailure() { |
||||
RecordingTransport transport = RecordingTransport.create() |
||||
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok( |
||||
"{\"message\":\"oops\"}")); |
||||
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec()); |
||||
|
||||
assertThrows(RuntimeException.class, () -> adapter.trackShipment(ctx(), "TRK123")); |
||||
} |
||||
|
||||
@Test |
||||
void declaresTrackingCapability() { |
||||
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); |
||||
assertTrue(adapter.capabilities().contains(WarehouseCapability.TRACKING)); |
||||
} |
||||
|
||||
@Test |
||||
void blankTrackingNumberRejected() { |
||||
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec()); |
||||
assertThrows(IllegalArgumentException.class, () -> adapter.trackShipment(ctx(), " ")); |
||||
assertThrows(IllegalArgumentException.class, () -> adapter.trackShipment(ctx(), null)); |
||||
} |
||||
} |
||||
Loading…
Reference in new issue