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 @@ |
|||||||
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 @@ |
|||||||
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
package common.ecommerce.warehouse.model; |
|
||||||
|
|
||||||
/** |
|
||||||
* 取消资格判定。 |
|
||||||
* |
|
||||||
* <p>仓方能力不齐:易达云有专门接口,另两家需打样核实。SDK 统一映射到这三态; |
|
||||||
* {@link #CHARGED} 必须由调用方显式传 {@code acceptCharge=true} 才执行取消。</p> |
|
||||||
*/ |
|
||||||
public enum CancelEligibility { |
|
||||||
|
|
||||||
/** 可免费取消。 */ |
|
||||||
FREE, |
|
||||||
/** 可取消但收费;需调用方确认。 */ |
|
||||||
CHARGED, |
|
||||||
/** 不可取消(已出库 / 已交运 / 仓不允许)。 */ |
|
||||||
BLOCKED |
|
||||||
} |
|
||||||
@ -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 @@ |
|||||||
|
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 @@ |
|||||||
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 @@ |
|||||||
package common.ecommerce.warehouse.model; |
|
||||||
|
|
||||||
/** |
|
||||||
* 库存同步策略。仓能力不同:信仓支持按时间增量,易达云只能全量 diff。 |
|
||||||
*/ |
|
||||||
public enum InventorySyncStrategy { |
|
||||||
|
|
||||||
/** 按时间增量查询。 */ |
|
||||||
TIME_WINDOW, |
|
||||||
/** 全量拉取 + 差异比对。 */ |
|
||||||
FULL_PULL_DIFF |
|
||||||
} |
|
||||||
@ -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 @@ |
|||||||
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 @@ |
|||||||
|
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 @@ |
|||||||
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 @@ |
|||||||
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 @@ |
|||||||
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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 @@ |
|||||||
|
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