From a8dfb08e692998b9e06bb7f034b23011e8e5b744 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Tue, 10 Nov 2026 11:37:37 +0800 Subject: [PATCH] =?UTF-8?q?refactor(warehouse):=20=E6=9E=9A=E4=B8=BE?= =?UTF-8?q?=E4=B8=8B=E6=B2=89=20core=20+=20=E5=B9=B3=E5=8F=B0=E6=9E=9A?= =?UTF-8?q?=E4=B8=BE=E5=88=86=E5=B1=82=E6=98=A0=E5=B0=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude --- README.md | 32 +++++--- .../ecommerce/warehouse/WarehouseCapability.java | 49 ------------ .../ecommerce/warehouse/WarehouseProvider.java | 21 ----- .../warehouse/capability/InventoryCapable.java | 4 +- .../warehouse/capability/OutboundCapable.java | 2 +- .../warehouse/capability/WarehouseProduct.java | 12 +-- .../capability/WarehouseReturnCapable.java | 8 +- .../warehouse/enums/CancelEligibility.java | 34 ++++++++ .../ecommerce/warehouse/enums/InboundStatus.java | 67 ++++++++++++++++ .../warehouse/enums/InventorySyncStrategy.java | 31 ++++++++ .../ecommerce/warehouse/enums/LabelMode.java | 32 ++++++++ .../ecommerce/warehouse/enums/OutboundStatus.java | 81 +++++++++++++++++++ .../warehouse/enums/ReturnDealMethod.java | 37 +++++++++ .../warehouse/enums/ReturnProcessDisposition.java | 43 ++++++++++ .../ecommerce/warehouse/enums/TransferStatus.java | 60 ++++++++++++++ .../ecommerce/warehouse/enums/TransferType.java | 35 +++++++++ .../warehouse/enums/WarehouseCapability.java | 65 ++++++++++++++++ .../warehouse/enums/WarehouseFeeType.java | 35 +++++++++ .../warehouse/enums/WarehouseProvider.java | 39 ++++++++++ .../WarehouseUnsupportedCapabilityException.java | 2 +- .../ecommerce/warehouse/model/BillingDocument.java | 17 ++++ .../warehouse/model/CancelEligibility.java | 17 ---- .../ecommerce/warehouse/model/CancelResult.java | 2 + .../common/ecommerce/warehouse/model/FeeQuery.java | 2 + .../ecommerce/warehouse/model/InboundOrder.java | 19 ++++- .../ecommerce/warehouse/model/InboundStatus.java | 32 -------- .../warehouse/model/InventorySyncStrategy.java | 12 --- .../ecommerce/warehouse/model/LabelMode.java | 16 ---- .../ecommerce/warehouse/model/OutboundCommand.java | 2 + .../ecommerce/warehouse/model/OutboundOrder.java | 5 +- .../ecommerce/warehouse/model/OutboundStatus.java | 46 ----------- .../ecommerce/warehouse/model/ReturnCommand.java | 39 +++------- .../warehouse/model/ReturnProcessCommand.java | 40 +++------- .../ecommerce/warehouse/model/TransferCommand.java | 2 + .../ecommerce/warehouse/model/TransferOrder.java | 19 +++++ .../ecommerce/warehouse/model/TransferStatus.java | 29 ------- .../ecommerce/warehouse/model/TransferType.java | 19 ----- .../warehouse/model/WarehouseFeeType.java | 19 ----- .../ecommerce/warehouse/model/WarehouseReturn.java | 38 +++++---- .../ecommerce/warehouse/sdk/WarehouseAdapter.java | 4 +- .../warehouse/sdk/WarehouseAdapterFactory.java | 2 +- .../ecommerce/warehouse/sdk/WarehouseContext.java | 2 +- .../warehouse/sdk/WarehouseOperations.java | 6 +- .../warehouse/sdk/WarehouseOutbounds.java | 6 +- .../ecommerce/warehouse/sdk/WarehouseSdk.java | 6 +- .../ecommerce/warehouse/spi/WarehouseSink.java | 12 +++ .../warehouse/testkit/FakeWarehouseAdapter.java | 8 +- .../ecommerce/warehouse/sdk/WarehouseSdkTest.java | 8 +- .../ecommerce/xincang/adapter/XincangAdapter.java | 4 +- .../xincang/adapter/XincangAdapterFactory.java | 2 +- .../xincang/adapter/XincangAdapterTest.java | 4 +- .../xincang/probe/XincangLoginProbeTest.java | 2 +- .../common/ecommerce/yqn/adapter/YqnAdapter.java | 10 +-- .../ecommerce/yqn/adapter/YqnAdapterFactory.java | 4 +- .../common/ecommerce/yqn/adapter/YqnFeeMapper.java | 3 +- .../ecommerce/yqn/adapter/YqnInboundMapper.java | 38 +-------- .../ecommerce/yqn/adapter/YqnOutboundMapper.java | 41 +--------- .../ecommerce/yqn/adapter/YqnProductMapper.java | 3 +- .../ecommerce/yqn/adapter/YqnReturnMapper.java | 8 +- .../ecommerce/yqn/adapter/YqnTransferMapper.java | 91 ++-------------------- .../java/common/ecommerce/yqn/dto/YqnDtos.java | 64 +++++++++++++++ .../ecommerce/yqn/enums/YqnInboundStatus.java | 73 +++++++++++++++++ .../ecommerce/yqn/enums/YqnOutboundStatus.java | 83 ++++++++++++++++++++ .../ecommerce/yqn/enums/YqnReturnDealMethod.java | 67 ++++++++++++++++ .../yqn/enums/YqnReturnProcessDisposition.java | 67 ++++++++++++++++ .../ecommerce/yqn/enums/YqnTransferStatus.java | 82 +++++++++++++++++++ .../ecommerce/yqn/enums/YqnTransferType.java | 64 +++++++++++++++ .../ecommerce/yqn/adapter/YqnAdapterTest.java | 29 ++++--- .../ecommerce/yqn/adapter/YqnProductTest.java | 4 +- 69 files changed, 1295 insertions(+), 566 deletions(-) delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java create mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java delete mode 100644 warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java create mode 100644 warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java diff --git a/README.md b/README.md index 3bf5b09..8ff74da 100644 --- a/README.md +++ b/README.md @@ -295,23 +295,31 @@ common.ecommerce aeph/ · bestbuy/ · custom/ · echo/ · losdlius/ · michaels/ · mirakl/ · wayfair/ │ ├── warehouse 仓库域(warehouse-sdk-core) -│ ├── WarehouseProvider / WarehouseCapability -│ ├── model OutboundStatus / LabelMode / CancelEligibility / ShipTo / -│ │ OutboundOrder / OutboundCommand / OutboundLine / OutboundQuery / -│ │ OutboundRef / OutboundReceipt / PackageResult / WarehouseLabel / -│ │ CancelCommand / CancelResult / InventorySnapshot / InventoryQuery / -│ │ InventorySyncStrategy / InboundOrder / InboundCommand / InboundLine / -│ │ InboundReceipt / WarehouseReturn / BillingDocument / TrackEvent / -│ │ DestructionOrder -│ ├── capability WarehouseAdapter(在 sdk 包) / OutboundCapable / InventoryCapable / -│ │ InboundCapable / WarehouseReturnCapable / WarehouseFeeCapable / -│ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable +│ ├── enums (底层枚举,带 SDK 自编 code + 中文名) +│ │ WarehouseProvider / WarehouseCapability / OutboundStatus / +│ │ InboundStatus / TransferStatus / TransferType / LabelMode / +│ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType / +│ │ ReturnDealMethod / ReturnProcessDisposition +│ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine / +│ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec / +│ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult / +│ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine / +│ │ InboundCommand / InboundLine / InboundCarton / InboundBatch / +│ │ InboundReceipt / ReturnCommand / ReturnProcessCommand / +│ │ WarehouseReturn / TransferCommand / TransferOrder / +│ │ BillingDocument / FeeQuery / +│ │ TrackEvent / DestructionOrder +│ ├── capability OutboundCapable / InventoryCapable / InboundCapable / +│ │ WarehouseReturnCapable / WarehouseFeeCapable / TransferCapable / +│ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable / +│ │ WarehouseProduct / WarehouseProductCapable │ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired / │ │ DuplicateOrder / WebhookVerification │ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore / │ │ UnmatchedCallbackStore │ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds / -│ WarehouseContext / WarehouseConnection / WarehouseWriteScope +│ WarehouseAdapter / WarehouseAdapterFactory / WarehouseContext / +│ WarehouseConnection / WarehouseWriteScope │ ├── yqn 运去哪三方仓(warehouse-sdk-yqn) │ ├── YqnConstants 端点、路径、固定 token 请求头名、限流 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java deleted file mode 100644 index e6934a4..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java +++ /dev/null @@ -1,49 +0,0 @@ -package common.ecommerce.warehouse; - -/** - * 仓库能力位。 - * - *

能力是事实表,不是推荐:调用方用 {@code WarehouseSdk.capabilities()} 查询, - * 缺失时抛 {@code WarehouseUnsupportedCapabilityException},不静默降级。

- */ -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 -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java deleted file mode 100644 index b3b4233..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java +++ /dev/null @@ -1,21 +0,0 @@ -package common.ecommerce.warehouse; - -/** - * 三方仓 provider 枚举。 - * - *

与渠道域的 {@code ChannelProvider} 分开:仓不是平台,两套枚举互不继承, - * 但幂等、水位线、审计里都以 {@link #name()} 字符串落库,共用同一批 SPI。

- */ -public enum WarehouseProvider { - - /** 运去哪(打样仓) */ - YQN, - /** 信仓(新版接口) */ - XINCANG, - /** 易达云 */ - EDAYUN, - /** 领星 WMS:预留,本期不实现 */ - LINGXING, - /** 其他自建/直连仓 */ - CUSTOM -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java index cf1916d..748c1e0 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java @@ -3,7 +3,7 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; -import common.ecommerce.warehouse.model.InventorySyncStrategy; +import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -24,6 +24,6 @@ public interface InventoryCapable extends WarehouseAdapter { /** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */ default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) { throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( - common.ecommerce.warehouse.WarehouseCapability.INVENTORY_ADJUST); + common.ecommerce.warehouse.enums.WarehouseCapability.INVENTORY_ADJUST); } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java index 858e1e5..3b9f696 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java @@ -2,7 +2,7 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.model.CancelCommand; -import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java index 793a91b..41bf3f5 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java @@ -1,6 +1,7 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.shared.support.Money; +import common.ecommerce.warehouse.enums.ReturnDealMethod; import java.util.Objects; @@ -37,8 +38,8 @@ public final class WarehouseProduct { private final int requireSn; /** 外包装样式:0 裸包装 / 1 销售包装 / 2 物流包装;-1 表示不传。 */ private final int packageStyle; - /** 客退处理方式:0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认;-1 表示不传。 */ - private final int returnDealMethod; + /** 客退处理方式;null 表示不传。仓方码值由适配器映射。 */ + private final ReturnDealMethod returnDealMethod; private final Money declaredValue; private final String hsCode; private final String countryOfOrigin; @@ -178,7 +179,8 @@ public final class WarehouseProduct { return packageStyle; } - public int returnDealMethod() { + /** 客退处理方式;null 表示不传。 */ + public ReturnDealMethod returnDealMethod() { return returnDealMethod; } @@ -259,7 +261,7 @@ public final class WarehouseProduct { private double itemHeightCm; private int requireSn; private int packageStyle = -1; - private int returnDealMethod = -1; + private ReturnDealMethod returnDealMethod; private Money declaredValue; private String hsCode; private String countryOfOrigin; @@ -361,7 +363,7 @@ public final class WarehouseProduct { return this; } - public Builder returnDealMethod(int v) { + public Builder returnDealMethod(ReturnDealMethod v) { this.returnDealMethod = v; return this; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java index 3667f70..93c1a26 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java @@ -1,6 +1,8 @@ package common.ecommerce.warehouse.capability; import common.ecommerce.shared.support.Page; +import common.ecommerce.warehouse.enums.ReturnDealMethod; +import common.ecommerce.warehouse.enums.ReturnProcessDisposition; import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.WarehouseReturn; @@ -12,8 +14,8 @@ import common.ecommerce.warehouse.sdk.WarehouseContext; * *

退货链路有两个不同的「处理方式」,别混:

* */ public interface WarehouseReturnCapable extends WarehouseAdapter { @@ -45,6 +47,6 @@ public interface WarehouseReturnCapable extends WarehouseAdapter { /** 取消退货单;仅部分仓支持。 */ default void cancel(WarehouseContext ctx, String returnRequestNo) { throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( - common.ecommerce.warehouse.WarehouseCapability.RETURN); + common.ecommerce.warehouse.enums.WarehouseCapability.RETURN); } } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java new file mode 100644 index 0000000..6b62cc8 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java @@ -0,0 +1,34 @@ +package common.ecommerce.warehouse.enums; + +/** + * 取消资格判定。 + * + *

仓方能力不齐,有的仓有专门的取消预判接口,有的只能查单状态推断。 + * SDK 统一映射到这三态;{@link #CHARGED} 必须由调用方显式传 + * {@code acceptCharge=true} 才执行取消。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java new file mode 100644 index 0000000..c821ca1 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java @@ -0,0 +1,67 @@ +package common.ecommerce.warehouse.enums; + +/** + * 入库计划单状态(底层枚举)。 + * + *

各仓的状态在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里; + * 本枚举不认识任何仓的码值。

+ * + *

未知码归 {@link #UNKNOWN},不猜——猜错会让宿主把未完成的入库当完成。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java new file mode 100644 index 0000000..b82a432 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java @@ -0,0 +1,31 @@ +package common.ecommerce.warehouse.enums; + +/** + * 库存同步策略。 + * + *

仓能力不同:有的仓支持按时间增量,有的只能全量拉取后做差异比对。 + * 具体哪家支持哪种由适配器的 {@code InventoryCapable.syncStrategy()} 声明。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java new file mode 100644 index 0000000..3f58503 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java @@ -0,0 +1,32 @@ +package common.ecommerce.warehouse.enums; + +/** + * 面单模式。 + * + *

必须与仓能力匹配:{@link #PLATFORM_LABEL} 要求仓声明 + * {@link WarehouseCapability#PLATFORM_LABEL_DELIVERY},缺失时 {@code create()} 拒绝, + * 不静默降级为仓自有面单——面单归属直接影响与平台的标发方式。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java new file mode 100644 index 0000000..4214aee --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java @@ -0,0 +1,81 @@ +package common.ecommerce.warehouse.enums; + +/** + * 出库单状态(底层枚举)。 + * + *

各仓的状态在各自模块里先映射成「平台枚举」,再 {@code toCore()} 到这里; + * 本枚举不认识任何仓的码值或字符串。

+ * + *

{@link #CREATED} 与 {@link #SUBMITTED} 不是仓方状态,是 SDK 自己的生命周期: + * 前者表示 OMS 已建单未下发,后者表示已下发但仓尚未确认。仓方返回的状态只会落在 + * {@code SUBMITTED} 之后的值上。

+ * + *

{@link #UNKNOWN} 是必须项:仓方给出无法识别的状态时归这里,不许猜成别的值, + * 原值看 {@code rawStatus}。

+ * + *

{@link #rank()} 只对仓方状态有意义,用于丢弃乱序回调;{@link #UNKNOWN} + * 的 rank 为 -1,表示「不参与比较」,宿主应保留记录但不覆盖已有状态。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java new file mode 100644 index 0000000..a20d317 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java @@ -0,0 +1,37 @@ +package common.ecommerce.warehouse.enums; + +/** + * 退货预约时的处理方式(业务语义)。 + * + *

只表达「怎么处理」,不含任何仓方的数字码:各仓码值不同,映射由适配器负责。

+ * + *

与 {@link ReturnProcessDisposition} 不是一回事:这个是下单时发货人预报的, + * 那个是仓收货检验之后逐条明细行的最终决定。两者可选值不同,不能互换。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java new file mode 100644 index 0000000..e1ec3e5 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java @@ -0,0 +1,43 @@ +package common.ecommerce.warehouse.enums; + +/** + * 退货检验后的处理方式(业务语义)。 + * + *

只表达「怎么处理」,不含任何仓方的数字码:各仓码值不同,映射由适配器负责。

+ * + *

与 {@link ReturnDealMethod} 不是一回事:那个是预约时的预报, + * 这个是仓收货检验之后逐条明细行的最终决定。

+ * + *

查询结果也用本枚举:{@link #UNKNOWN} 表示仓方返回的处理方式无法识别, + * 原值见 {@code WarehouseReturn.rawStatus()}。不再单独建一个查询专用的枚举—— + * 那只是本枚举的子集,多一个枚举就多一处「到底该用哪个」的困惑。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java new file mode 100644 index 0000000..cc4b41e --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java @@ -0,0 +1,60 @@ +package common.ecommerce.warehouse.enums; + +/** + * 调拨单状态(底层枚举)。 + * + *

各仓的状态码在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里; + * 本枚举不认识任何仓的码值。未知码归 {@link #UNKNOWN},不猜。

+ * + *

取值只追加不合并:新仓有、这里没有的状态就加一个值,已存在的值 + * 不会再合并回上一级——合并之后宿主就分不出「待审核」和「审核中」了。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java new file mode 100644 index 0000000..ff67ddb --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java @@ -0,0 +1,35 @@ +package common.ecommerce.warehouse.enums; + +/** + * 调拨类型,只表达业务语义。 + * + *

仓方的类型码由适配器映射(如运去哪 {@code type} 0/1/2/3),core 不认识任何 + * 仓的码值。创建响应若不回传类型,适配器从请求侧带过来,不猜。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java new file mode 100644 index 0000000..f0e082d --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java @@ -0,0 +1,65 @@ +package common.ecommerce.warehouse.enums; + +/** + * 仓库能力位。 + * + *

能力是事实表,不是推荐:调用方用 {@code WarehouseSdk.capabilities()} 查询, + * 缺失时抛 {@code WarehouseUnsupportedCapabilityException},不静默降级。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java new file mode 100644 index 0000000..783177d --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java @@ -0,0 +1,35 @@ +package common.ecommerce.warehouse.enums; + +/** + * 仓费用类型,只表达业务语义。 + * + *

仓方的费用码与分类口径由适配器维护:有的仓给类型码,有的仓只给中文费用名, + * 后者按名归类,认不出就留 null——对账时宁可不分类,也不能猜错。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java new file mode 100644 index 0000000..51d9314 --- /dev/null +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java @@ -0,0 +1,39 @@ +package common.ecommerce.warehouse.enums; + +/** + * 三方仓 provider 枚举。 + * + *

与渠道域的 {@code ChannelProvider} 分开:仓不是平台,两套枚举互不继承, + * 但幂等、水位线、审计里都以 {@link #name()} 字符串落库,共用同一批 SPI。 + * provider 是接入通道标识而非协议码,因此落库继续用 {@code name()}, + * 不用 {@link #code()}——换码值会让存量幂等键对不上。

+ */ +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; + } +} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java index 5601744..d8a645c 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java @@ -1,6 +1,6 @@ package common.ecommerce.warehouse.error; -import common.ecommerce.warehouse.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseCapability; /** * 该仓不支持此能力;调用方走人工或替代路径。 diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java index 4350c98..d0d2235 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java @@ -1,5 +1,8 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.WarehouseFeeType; +import common.ecommerce.warehouse.enums.WarehouseProvider; + import common.ecommerce.shared.support.Money; import java.time.Instant; @@ -13,6 +16,8 @@ import java.time.Instant; public final class BillingDocument { private final String warehouseCode; + /** 该单据来自哪家仓;解释原始字段与选择平台枚举时使用。 */ + private final WarehouseProvider sourceProvider; private final String documentNo; /** 仓方费用名称原值,如「尾程运费」「仓储费」。 */ private final String feeName; @@ -30,6 +35,7 @@ public final class BillingDocument { private BillingDocument(Builder b) { this.warehouseCode = require(b.warehouseCode, "warehouseCode"); + this.sourceProvider = b.sourceProvider; this.documentNo = b.documentNo; this.feeName = b.feeName; this.feeType = b.feeType; @@ -48,6 +54,11 @@ public final class BillingDocument { return warehouseCode; } + /** 该单据来自哪家仓。 */ + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + public String documentNo() { return documentNo; } @@ -95,6 +106,7 @@ public final class BillingDocument { public static final class Builder { private String warehouseCode; + private WarehouseProvider sourceProvider; private String documentNo; private String feeName; private WarehouseFeeType feeType; @@ -109,6 +121,11 @@ public final class BillingDocument { return this; } + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + public Builder documentNo(String v) { this.documentNo = v; return this; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java deleted file mode 100644 index 16f7130..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java +++ /dev/null @@ -1,17 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 取消资格判定。 - * - *

仓方能力不齐:易达云有专门接口,另两家需打样核实。SDK 统一映射到这三态; - * {@link #CHARGED} 必须由调用方显式传 {@code acceptCharge=true} 才执行取消。

- */ -public enum CancelEligibility { - - /** 可免费取消。 */ - FREE, - /** 可取消但收费;需调用方确认。 */ - CHARGED, - /** 不可取消(已出库 / 已交运 / 仓不允许)。 */ - BLOCKED -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java index 9ccce71..157089f 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java @@ -1,5 +1,7 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.CancelEligibility; + import common.ecommerce.shared.support.Money; /** diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java index e8fdf23..2713800 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java @@ -1,5 +1,7 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.WarehouseFeeType; + import java.time.LocalDate; /** diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java index 7b14048..04e8808 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java @@ -1,5 +1,8 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.InboundStatus; +import common.ecommerce.warehouse.enums.WarehouseProvider; + import java.time.Instant; import java.util.ArrayList; import java.util.Collections; @@ -20,8 +23,10 @@ public final class InboundOrder { private final String warehouseCode; /** 单据状态,已归一化。 */ private final InboundStatus status; - /** 仓方状态原值,保留便于排查。 */ + /** 仓方状态原值,保留便于排查;必须与 {@link #sourceProvider()} 一起落库才有意义。 */ private final String rawStatus; + /** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */ + private final WarehouseProvider sourceProvider; /** 库存类型:0 可售 / 1 不可售。 */ private final int inventoryType; private final int boxCount; @@ -48,6 +53,7 @@ public final class InboundOrder { this.warehouseCode = require(b.warehouseCode, "warehouseCode"); this.status = b.status == null ? InboundStatus.UNKNOWN : b.status; this.rawStatus = b.rawStatus; + this.sourceProvider = b.sourceProvider; this.inventoryType = b.inventoryType; this.boxCount = b.boxCount; this.createdAt = b.createdAt; @@ -153,6 +159,11 @@ public final class InboundOrder { return status == InboundStatus.COMPLETED; } + /** 该单据来自哪家仓。 */ + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + private static String require(String v, String n) { if (v == null || v.trim().isEmpty()) { throw new IllegalArgumentException(n + " must not be blank"); @@ -166,6 +177,7 @@ public final class InboundOrder { private String warehouseCode; private InboundStatus status; private String rawStatus; + private WarehouseProvider sourceProvider; private int inventoryType; private int boxCount; private Instant createdAt; @@ -206,6 +218,11 @@ public final class InboundOrder { return this; } + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + public Builder inventoryType(int v) { this.inventoryType = v; return this; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java deleted file mode 100644 index 06da686..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java +++ /dev/null @@ -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 -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java deleted file mode 100644 index 70c8a67..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java +++ /dev/null @@ -1,12 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 库存同步策略。仓能力不同:信仓支持按时间增量,易达云只能全量 diff。 - */ -public enum InventorySyncStrategy { - - /** 按时间增量查询。 */ - TIME_WINDOW, - /** 全量拉取 + 差异比对。 */ - FULL_PULL_DIFF -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java deleted file mode 100644 index ed1df49..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java +++ /dev/null @@ -1,16 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 面单模式。 - * - *

必须与仓能力匹配:{@link #PLATFORM_LABEL} 要求仓声明 - * {@code WarehouseCapability.PLATFORM_LABEL_DELIVERY},缺失时 {@code create()} 拒绝, - * 不静默降级为仓自有面单——面单归属直接影响与平台的标发方式。

- */ -public enum LabelMode { - - /** 仓用自己的承运商账号出单,SDK 只回收面单与运单。 */ - WAREHOUSE_LABEL, - /** 渠道域先取平台面单,OMS 把面单文件下发给仓打印贴标。 */ - PLATFORM_LABEL -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java index af0e062..f056693 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java @@ -1,5 +1,7 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.LabelMode; + import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.support.Money; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java index 49493b4..6639f28 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java @@ -1,7 +1,10 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.LabelMode; +import common.ecommerce.warehouse.enums.OutboundStatus; + import common.ecommerce.shared.support.Money; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; import java.time.Instant; import java.util.ArrayList; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java deleted file mode 100644 index 6ba5624..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java +++ /dev/null @@ -1,46 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 出库单状态。仓方状态在适配器内映射到这里,只前进不后退。 - * - *

回调不保证顺序,宿主按本枚举的 {@link #rank()} 比较:小于当前值的事件记为 - * {@code OUT_OF_ORDER},保留记录但不覆盖状态。

- */ -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; - } -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java index 2e77980..6e67a7d 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java @@ -1,5 +1,7 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.ReturnDealMethod; + import java.time.LocalDate; import java.util.ArrayList; import java.util.Collections; @@ -8,8 +10,8 @@ import java.util.List; /** * 退货计划创建命令。写操作,幂等键是 {@link #returnRequestNo()}(仓方的 {@code orderNo})。 * - *

运去哪必填:仓、来源单号、关联销售单号、退货运单号、承运商、至少一条商品行; - * 每条商品行还必须给处理方式。

+ *

各仓必填项不同:适配器只校验自己协议要求的字段,core 只保证幂等键与 + * 至少一条商品行。

*/ public final class ReturnCommand { @@ -96,16 +98,16 @@ public final class ReturnCommand { * 退货商品行。 * *

{@link #dealMethod()} 是退货预约时的处理方式,与 - * {@code ReturnProcessCommand.Disposition}(检验后处理方式)不是一回事: + * {@code ReturnProcessDisposition}(检验后处理方式)不是一回事: * 前者是发货人预报,后者是仓收货检验后按明细行最终决定。两套枚举码值也不同。

*/ public static final class ReturnCommandLine { private final String providerSku; private final int quantity; - private final DealMethod dealMethod; + private final ReturnDealMethod dealMethod; - public ReturnCommandLine(String providerSku, int quantity, DealMethod dealMethod) { + public ReturnCommandLine(String providerSku, int quantity, ReturnDealMethod dealMethod) { if (providerSku == null || providerSku.trim().isEmpty()) { throw new IllegalArgumentException("providerSku must not be blank"); } @@ -125,34 +127,11 @@ public final class ReturnCommand { return quantity; } - public DealMethod dealMethod() { + public ReturnDealMethod dealMethod() { return dealMethod; } } - /** - * 退货预约的处理方式(API 81):0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。 - * - *

注意 API 77 的检验后处理方式码值完全不同(0 自提 / 2 销毁 / 3 上架 / 4 换标上架), - * 两者不能混用。

- */ - public enum DealMethod { - CUSTOMER_PICKUP(0), - PHOTO_CONFIRM(1), - DESTROY(2), - WAREHOUSE_CONFIRM(5); - - private final int code; - - DealMethod(int code) { - this.code = code; - } - - public int code() { - return code; - } - } - public static final class Builder { private String returnRequestNo; @@ -205,7 +184,7 @@ public final class ReturnCommand { return this; } - public Builder line(String providerSku, int quantity, DealMethod dealMethod) { + public Builder line(String providerSku, int quantity, ReturnDealMethod dealMethod) { this.lines.add(new ReturnCommandLine(providerSku, quantity, dealMethod)); return this; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java index 2a67ebb..38f35d1 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java @@ -1,17 +1,19 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.ReturnProcessDisposition; + /** - * 退货条目处理命令(API 77 / 检验后决定)。 + * 退货条目处理命令(检验后决定)。 * - *

与 {@code ReturnCommand.DealMethod}(预约时的预报)不是一回事: - * 这里是仓收货检验之后,逐条明细行最终决定怎么处理。

+ *

与 {@link common.ecommerce.warehouse.enums.ReturnDealMethod}(预约时的预报) + * 不是一回事:这里是仓收货检验之后,逐条明细行最终决定怎么处理。

*/ public final class ReturnProcessCommand { private final String providerReturnNo; /** 仓侧明细行 id;来自退货查询接口的 items[].id。 */ private final long lineId; - private final Disposition disposition; + private final ReturnProcessDisposition disposition; /** 换标上架时的新 SKU;其它处理方式必须为 null。 */ private final String newSku; private final String remark; @@ -26,7 +28,7 @@ public final class ReturnProcessCommand { } this.lineId = b.lineId; this.disposition = java.util.Objects.requireNonNull(b.disposition, "disposition"); - boolean needsSku = b.disposition == Disposition.RESTOCK_RELABEL; + boolean needsSku = b.disposition == ReturnProcessDisposition.RESTOCK_RELABEL; if (needsSku && (b.newSku == null || b.newSku.trim().isEmpty())) { throw new IllegalArgumentException("newSku is required when disposition is RESTOCK_RELABEL"); } @@ -51,7 +53,7 @@ public final class ReturnProcessCommand { return lineId; } - public Disposition disposition() { + public ReturnProcessDisposition disposition() { return disposition; } @@ -63,32 +65,10 @@ public final class ReturnProcessCommand { return remark; } - /** - * 检验后处理方式(API 77):0 客户自提 / 2 销毁 / 3 上架(良品) / 4 换标上架(良品)。 - * - *

与预约时的处理方式码值不同,不能混用。

- */ - public enum Disposition { - CUSTOMER_PICKUP(0), - DESTROY(2), - RESTOCK(3), - RESTOCK_RELABEL(4); - - private final int code; - - Disposition(int code) { - this.code = code; - } - - public int code() { - return code; - } - } - public static final class Builder { private String providerReturnNo; private long lineId; - private Disposition disposition; + private ReturnProcessDisposition disposition; private String newSku; private String remark; @@ -102,7 +82,7 @@ public final class ReturnProcessCommand { return this; } - public Builder disposition(Disposition v) { + public Builder disposition(ReturnProcessDisposition v) { this.disposition = v; return this; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java index 33d36a1..cbedd86 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java @@ -1,5 +1,7 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.TransferType; + /** * 调拨单创建命令。写操作,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。 * diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java index d84d8ff..7bc8a9d 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java @@ -1,5 +1,9 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.TransferStatus; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.enums.TransferType; + import java.time.Instant; /** @@ -16,7 +20,10 @@ public final class TransferOrder { private final String toWarehouseCode; private final TransferType type; private final TransferStatus status; + /** 仓方状态原值;必须与 {@link #sourceProvider()} 一起落库才有意义。 */ private final String rawStatus; + /** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */ + private final WarehouseProvider sourceProvider; private final int totalQuantity; private final Instant estimatedOutboundAt; private final Instant estimatedInboundAt; @@ -31,6 +38,7 @@ public final class TransferOrder { this.type = b.type; this.status = b.status == null ? TransferStatus.UNKNOWN : b.status; this.rawStatus = b.rawStatus; + this.sourceProvider = b.sourceProvider; this.totalQuantity = b.totalQuantity; this.estimatedOutboundAt = b.estimatedOutboundAt; this.estimatedInboundAt = b.estimatedInboundAt; @@ -97,6 +105,11 @@ public final class TransferOrder { return status == TransferStatus.COMPLETED; } + /** 该单据来自哪家仓。 */ + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + private static String require(String v, String n) { if (v == null || v.trim().isEmpty()) { throw new IllegalArgumentException(n + " must not be blank"); @@ -112,6 +125,7 @@ public final class TransferOrder { private TransferType type; private TransferStatus status; private String rawStatus; + private WarehouseProvider sourceProvider; private int totalQuantity; private Instant estimatedOutboundAt; private Instant estimatedInboundAt; @@ -153,6 +167,11 @@ public final class TransferOrder { return this; } + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + public Builder totalQuantity(int v) { this.totalQuantity = v; return this; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java deleted file mode 100644 index 353a21d..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java +++ /dev/null @@ -1,29 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 调拨单状态,已归一化。 - * - *

运去哪的码:0 草稿 / 3 已驳回 / 5 待审核 / 6 审核中 / 7 审核通过 / 8 待确认 / - * 9 待备货 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 / - * 90 已关闭 / 100 取消中 / 110 已取消 / 120 取消异常。

- */ -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 -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java deleted file mode 100644 index 73ce5d5..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java +++ /dev/null @@ -1,19 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 调拨类型。 - * - *

运去哪的 {@code type} 是 0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。 - * 只保留业务语义,适配器维护到仓方码值的映射。

- */ -public enum TransferType { - - /** 仓到仓调拨。 */ - WAREHOUSE_TO_WAREHOUSE, - /** 调拨出库(发往外部地址或平台仓)。 */ - OUTBOUND, - /** 亚马逊移除订单(FBA 移出)。 */ - AMAZON_REMOVAL, - /** 亚马逊移入(FBA 入库)。 */ - AMAZON_INBOUND -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java deleted file mode 100644 index 439ba50..0000000 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java +++ /dev/null @@ -1,19 +0,0 @@ -package common.ecommerce.warehouse.model; - -/** - * 仓费用类型。 - * - *

各仓的枚举值不同,由适配器维护映射;这里只保留业务语义。 - * 运去哪 API 133 的 {@code costType} 是 1 作业费 / 2 仓储费 / 3 增值服务费 / 4 尾程费用。

- */ -public enum WarehouseFeeType { - - /** 作业费(出入库操作费)。 */ - OPERATION, - /** 仓储费 / 仓租。 */ - STORAGE, - /** 增值服务费。 */ - VALUE_ADDED, - /** 尾程运费。 */ - LAST_MILE -} diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java index 88d3e0f..3c5936a 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java @@ -1,5 +1,8 @@ package common.ecommerce.warehouse.model; +import common.ecommerce.warehouse.enums.ReturnProcessDisposition; +import common.ecommerce.warehouse.enums.WarehouseProvider; + import common.ecommerce.shared.support.Money; import java.time.Instant; @@ -16,10 +19,14 @@ public final class WarehouseReturn { private final String orderRef; /** 退货类型原值,由适配器解释。 */ private final String type; + /** 退货单状态;暂无统一枚举(运去哪查询接口未接入),先透传平台值。 */ private final String status; + /** 仓方状态原值;必须与 {@link #sourceProvider()} 一起落库才有意义。 */ private final String rawStatus; - /** 处理方式:RESTOCK / DESTROY / UNKNOWN。 */ - private final Disposition disposition; + /** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */ + private final WarehouseProvider sourceProvider; + /** 处理方式(检验后的归一化视图);无法识别为 UNKNOWN,原值见 {@link #rawStatus()}。 */ + private final ReturnProcessDisposition disposition; private final List lines; private final Instant createdAt; @@ -31,7 +38,8 @@ public final class WarehouseReturn { this.type = b.type; this.status = b.status; this.rawStatus = b.rawStatus; - this.disposition = b.disposition == null ? Disposition.UNKNOWN : b.disposition; + this.sourceProvider = b.sourceProvider; + this.disposition = b.disposition == null ? ReturnProcessDisposition.UNKNOWN : b.disposition; this.lines = Collections.unmodifiableList(new ArrayList(b.lines)); this.createdAt = b.createdAt; } @@ -68,7 +76,7 @@ public final class WarehouseReturn { return rawStatus; } - public Disposition disposition() { + public ReturnProcessDisposition disposition() { return disposition; } @@ -80,6 +88,11 @@ public final class WarehouseReturn { return createdAt; } + /** 该单据来自哪家仓。 */ + public WarehouseProvider sourceProvider() { + return sourceProvider; + } + private static String require(String v, String n) { if (v == null || v.trim().isEmpty()) { throw new IllegalArgumentException(n + " must not be blank"); @@ -87,13 +100,6 @@ public final class WarehouseReturn { return v.trim(); } - /** 退货处理方式。 */ - public enum Disposition { - RESTOCK, - DESTROY, - UNKNOWN - } - /** 退货明细行。 */ public static final class ReturnLine { @@ -169,7 +175,8 @@ public final class WarehouseReturn { private String type; private String status; private String rawStatus; - private Disposition disposition; + private WarehouseProvider sourceProvider; + private ReturnProcessDisposition disposition; private final List lines = new ArrayList(); private Instant createdAt; @@ -208,7 +215,12 @@ public final class WarehouseReturn { return this; } - public Builder disposition(Disposition v) { + public Builder sourceProvider(WarehouseProvider v) { + this.sourceProvider = v; + return this; + } + + public Builder disposition(ReturnProcessDisposition v) { this.disposition = v; return this; } diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java index b7b3383..10b9ec1 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java @@ -1,7 +1,7 @@ package common.ecommerce.warehouse.sdk; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import java.util.EnumSet; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java index 4e80d8c..fd8024c 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java @@ -1,6 +1,6 @@ package common.ecommerce.warehouse.sdk; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; /** * 仓库适配器工厂。新增第 4 家仓只需新增模块 + 实现本接口 + 注册, diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java index da13c1a..e0adff8 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java @@ -1,7 +1,7 @@ package common.ecommerce.warehouse.sdk; import common.ecommerce.shared.audit.CallScope; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; import java.time.Clock; import java.util.Objects; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java index e482497..0734815 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java @@ -4,8 +4,8 @@ import common.ecommerce.shared.audit.CallObserver; import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.support.Page; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; @@ -29,7 +29,7 @@ import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; -import common.ecommerce.warehouse.model.InventorySyncStrategy; +import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.spi.WarehouseAccount; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java index 2ee1c32..46c4be3 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java @@ -4,7 +4,7 @@ import common.ecommerce.shared.audit.CallObserver; import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.idempotency.WriteIdentity; import common.ecommerce.shared.spi.IdempotencyStore; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundQuery; @@ -12,11 +12,11 @@ import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundRef; import common.ecommerce.warehouse.model.PackageResult; import common.ecommerce.warehouse.model.CancelCommand; -import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.spi.WarehouseAccount; -import common.ecommerce.warehouse.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import java.util.List; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java index 68f7bd1..ca4440a 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java @@ -4,8 +4,8 @@ import common.ecommerce.shared.audit.CallObserver; import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.spi.IdempotencyStore; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TrackingCapable; @@ -22,7 +22,7 @@ import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventorySnapshot; -import common.ecommerce.warehouse.model.InventorySyncStrategy; +import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.spi.WarehouseAccount; diff --git a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java index ed180a9..35ede12 100644 --- a/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java +++ b/warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java @@ -14,6 +14,18 @@ import common.ecommerce.warehouse.model.WarehouseReturn; *

实现方必须按业务键 upsert:同一实体重复同步不得产生两条记录。 * 全部方法默认抛 {@link UnsupportedOperationException},宿主按需实现—— * 只接出库闭环的宿主不必被迫实现费用与销毁。

+ * + *

落库契约(硬要求)

+ *

凡是带状态的实体,{@code rawStatus} 必须落库,且必须与 {@code sourceProvider} + * 成对保存。原因:

+ *
    + *
  • {@code rawStatus} 是平台原话,同一个值在不同仓含义不同(运去哪的 {@code "5"} + * 与信仓的 {@code "5"} 不是一回事),单存它无法解释;
  • + *
  • 归一化枚举({@code status})与平台码的映射将来可能调整,原始值是唯一能 + * 重跑映射、修正历史数据的依据;只存枚举则改映射等于永久污染存量数据。
  • + *
+ *

建议同时存 {@code status.code()}:跨仓查询用它(一条 SQL), + * 展示与排查用 {@code rawStatus}。

*/ public interface WarehouseSink { diff --git a/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java b/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java index 31511e8..4efe786 100644 --- a/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java +++ b/warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java @@ -2,21 +2,21 @@ package common.ecommerce.warehouse.testkit; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.support.Page; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.CancelCommand; -import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundRef; -import common.ecommerce.warehouse.model.OutboundStatus; +import common.ecommerce.warehouse.enums.OutboundStatus; import common.ecommerce.warehouse.model.PackageResult; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseConnection; diff --git a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java index f53656f..29544d8 100644 --- a/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java +++ b/warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java @@ -2,15 +2,15 @@ package common.ecommerce.warehouse.sdk; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.support.Money; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.CancelCommand; -import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.model.CancelResult; -import common.ecommerce.warehouse.model.LabelMode; +import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundReceipt; diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java index 809ae36..1b94bcc 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java @@ -7,8 +7,8 @@ import common.ecommerce.shared.spi.AccessToken; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.TokenStore; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.xincang.XincangConstants; diff --git a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java index d884817..da1bf37 100644 --- a/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java +++ b/warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java @@ -4,7 +4,7 @@ import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.OkHttpTransport; import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.TokenStore; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; import common.ecommerce.xincang.XincangConstants; diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java index 47edd41..5dc13ad 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java @@ -6,8 +6,8 @@ import common.ecommerce.shared.testkit.InMemoryTokenStore; import common.ecommerce.shared.testkit.MutableClock; import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.Responses; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.xincang.XincangConstants; diff --git a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java index b2625c3..0cad648 100644 --- a/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java +++ b/warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java @@ -9,7 +9,7 @@ import common.ecommerce.shared.testkit.InMemoryLockProvider; import common.ecommerce.shared.testkit.InMemoryTokenStore; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.adapter.XincangAdapter; import org.junit.jupiter.api.Assumptions; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java index 26d82c4..30c04ad 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java @@ -6,8 +6,8 @@ import common.ecommerce.http.HttpTransport; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.shared.error.PlatformBusinessException; import common.ecommerce.shared.support.Page; -import common.ecommerce.warehouse.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.FeeQuery; @@ -22,7 +22,7 @@ import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.InventorySnapshot; -import common.ecommerce.warehouse.model.InventorySyncStrategy; +import common.ecommerce.warehouse.enums.InventorySyncStrategy; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.TransferCapable; @@ -33,9 +33,9 @@ import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.model.CancelCommand; -import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.model.CancelResult; -import common.ecommerce.warehouse.model.LabelMode; +import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundQuery; diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java index d78b484..ac16d24 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java @@ -21,8 +21,8 @@ public final class YqnAdapterFactory } @Override - public common.ecommerce.warehouse.WarehouseProvider provider() { - return common.ecommerce.warehouse.WarehouseProvider.YQN; + public common.ecommerce.warehouse.enums.WarehouseProvider provider() { + return common.ecommerce.warehouse.enums.WarehouseProvider.YQN; } @Override diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java index 9565d0d..c4827a1 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java @@ -3,7 +3,7 @@ package common.ecommerce.yqn.adapter; import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.FeeQuery; -import common.ecommerce.warehouse.model.WarehouseFeeType; +import common.ecommerce.warehouse.enums.WarehouseFeeType; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.yqn.dto.YqnDtos; @@ -123,6 +123,7 @@ public final class YqnFeeMapper { .amount(detail.costAmount == null ? Money.zero(CURRENCY) : Money.of(java.math.BigDecimal.valueOf(detail.costAmount), CURRENCY)) .saleOrderNo(detail.saleOrderNo == null ? null : String.valueOf(detail.saleOrderNo)) + .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN) .build(); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java index 3ea40ea..1640c5d 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java @@ -7,7 +7,7 @@ import common.ecommerce.warehouse.model.InboundCommand; import common.ecommerce.warehouse.model.InboundLine; import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundOrderLine; -import common.ecommerce.warehouse.model.InboundStatus; +import common.ecommerce.yqn.enums.YqnInboundStatus; import common.ecommerce.yqn.dto.YqnDtos; import java.time.Instant; @@ -157,46 +157,13 @@ public final class YqnInboundMapper { // ------------------------------------------------------------------ 查询 - /** 运去哪入库状态码 → 统一状态。未知码归 {@link InboundStatus#UNKNOWN},不猜。 */ - static InboundStatus toStatus(String rawStatus) { - if (rawStatus == null || rawStatus.trim().isEmpty()) { - return InboundStatus.UNKNOWN; - } - switch (rawStatus.trim()) { - case "0": - return InboundStatus.DRAFT; - case "5": - return InboundStatus.PENDING_REVIEW; - case "6": - return InboundStatus.REJECTED; - case "8": - return InboundStatus.PENDING_PACKING; - case "10": - return InboundStatus.PENDING_SHIPMENT; - case "16": - return InboundStatus.RECEIVING; - case "17": - return InboundStatus.RECEIVED; - case "20": - return InboundStatus.PENDING_STORAGE; - case "25": - return InboundStatus.STORING; - case "70": - return InboundStatus.COMPLETED; - case "100": - return InboundStatus.CANCELLED; - default: - return InboundStatus.UNKNOWN; - } - } - /** 入库计划详情 → 统一入库单(API 101)。 */ public static InboundOrder toOrder(YqnDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) { return InboundOrder.builder() .inboundRequestNo(firstNonBlank(info.sourceNo, info.inboundPlanOrderNo)) .providerInboundId(info.inboundPlanOrderNo) .warehouseCode(firstNonBlank(info.orgWarehouseCode, warehouseCode)) - .status(toStatus(info.inboundPlanOrderStatus)) + .status(YqnInboundStatus.of(info.inboundPlanOrderStatus).toCore()) .rawStatus(info.inboundPlanOrderStatus) .inventoryType(intOf(info.inventoryType)) .boxCount(intOf(info.cartonQty)) @@ -212,6 +179,7 @@ public final class YqnInboundMapper { .totalVolumeCbm(info.totalVolume) .remark(info.remark) .lines(toOrderLines(info.planProductDetailParamList, zone)) + .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN) .build(); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java index ed03fa0..0f2499a 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java @@ -1,16 +1,16 @@ package common.ecommerce.yqn.adapter; import common.ecommerce.shared.support.Money; -import common.ecommerce.warehouse.model.CancelEligibility; +import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundPackageSpec; -import common.ecommerce.warehouse.model.OutboundStatus; +import common.ecommerce.yqn.enums.YqnOutboundStatus; import common.ecommerce.warehouse.model.PackageResult; import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.shared.model.Platform; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.yqn.dto.YqnDtos; import java.time.Instant; @@ -173,7 +173,7 @@ public final class YqnOutboundMapper { .warehouseCode(firstNonBlank(detail.warehouseCode, warehouseCode)) .outboundRequestNo(firstNonBlank(detail.orderNo, null)) .orderRef(null) // API 128 不返回平台单号 - .status(toStatus(detail.orderStatusEnum)) + .status(YqnOutboundStatus.of(detail.orderStatusEnum).toCore()) .rawStatus(detail.orderStatusEnum) .carrier(packagesCarrierOf(shippedPackages, detail.carrierCode)) .trackingNumber(firstTrackingOf(shippedPackages)) @@ -342,39 +342,6 @@ public final class YqnOutboundMapper { return v != null && !v.trim().isEmpty(); } - /** 运去哪状态 → 统一状态;未知按 {@link OutboundStatus#SUBMITTED}。待打样核对映射表。 */ - public static OutboundStatus toStatus(String rawStatus) { - if (rawStatus == null) { - return OutboundStatus.SUBMITTED; - } - String s = rawStatus.trim().toUpperCase(); - if (s.isEmpty()) { - return OutboundStatus.SUBMITTED; - } - if (s.contains("CANCEL")) { - return OutboundStatus.CANCELLED; - } - if (s.contains("SHIP") || s.contains("SENT") || s.contains("DELIVER")) { - return OutboundStatus.SHIPPED; - } - if (s.contains("LABEL")) { - return OutboundStatus.LABEL_READY; - } - if (s.contains("PACK")) { - return OutboundStatus.PACKED; - } - if (s.contains("PICK")) { - return OutboundStatus.PICKING; - } - if (s.contains("ACCEPT")) { - return OutboundStatus.ACCEPTED; - } - if (s.contains("ERROR") || s.contains("EXCEPTION") || s.contains("FAIL")) { - return OutboundStatus.EXCEPTION; - } - return OutboundStatus.SUBMITTED; - } - /** 解析运去哪时间;失败返回 null,不因时间格式阻断业务。 */ static Instant parseTime(String value, ZoneId zone) { if (value == null || value.trim().isEmpty()) { diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java index c5bf3f7..45a214e 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java @@ -2,6 +2,7 @@ package common.ecommerce.yqn.adapter; import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.capability.WarehouseProduct; +import common.ecommerce.yqn.enums.YqnReturnDealMethod; import common.ecommerce.yqn.dto.YqnDtos; import java.util.ArrayList; @@ -46,7 +47,7 @@ public final class YqnProductMapper { req.itemHeight = positiveOrNull(product.itemHeightCm()); req.isRequireSn = product.requireSn(); req.packageStyle = product.packageStyle() >= 0 ? product.packageStyle() : null; - req.returnDealMethod = product.returnDealMethod() >= 0 ? product.returnDealMethod() : null; + req.returnDealMethod = YqnReturnDealMethod.codeOf(product.returnDealMethod()); req.customName = product.declaredName(); req.customNameEn = product.declaredNameEn(); req.link = product.link(); diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java index a27ae87..c752fe9 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java @@ -3,6 +3,9 @@ package common.ecommerce.yqn.adapter; import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.WarehouseReturn; +import common.ecommerce.yqn.enums.YqnReturnDealMethod; +import common.ecommerce.warehouse.enums.ReturnProcessDisposition; +import common.ecommerce.yqn.enums.YqnReturnProcessDisposition; import common.ecommerce.yqn.dto.YqnDtos; import java.time.LocalDate; @@ -45,7 +48,7 @@ public final class YqnReturnMapper { item.sku = line.providerSku(); // 运去哪这个字段是 string;数量原样传字符串,不做格式化 item.qty = String.valueOf(line.quantity()); - item.returnDealMethod = line.dealMethod().code(); + item.returnDealMethod = YqnReturnDealMethod.codeOf(line.dealMethod()); items.add(item); } return items; @@ -56,7 +59,7 @@ public final class YqnReturnMapper { YqnDtos.SaleReturnProcessRequest req = new YqnDtos.SaleReturnProcessRequest(); req.saleReturnPlanNo = cmd.providerReturnNo(); req.id = cmd.lineId(); - req.goodsReturnType = cmd.disposition().code(); + req.goodsReturnType = YqnReturnProcessDisposition.codeOf(cmd.disposition()); req.newSku = cmd.newSku(); req.remark = cmd.remark(); return req; @@ -75,6 +78,7 @@ public final class YqnReturnMapper { .orderRef(cmd.saleOrderNo()) .status("SUBMITTED") .rawStatus(null) + .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN) .build(); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java index a51fa26..523010a 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java @@ -4,8 +4,9 @@ import common.ecommerce.warehouse.model.InboundBatch; import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferOrder; -import common.ecommerce.warehouse.model.TransferStatus; -import common.ecommerce.warehouse.model.TransferType; +import common.ecommerce.warehouse.enums.TransferType; +import common.ecommerce.yqn.enums.YqnTransferStatus; +import common.ecommerce.yqn.enums.YqnTransferType; import common.ecommerce.yqn.dto.YqnDtos; import java.time.Instant; @@ -30,7 +31,7 @@ public final class YqnTransferMapper { /** 统一命令 → 运去哪创建调拨单请求。 */ public static YqnDtos.CreateTransferPlanRequest toRequest(TransferCommand cmd) { YqnDtos.CreateTransferPlanRequest req = new YqnDtos.CreateTransferPlanRequest(); - req.type = typeOf(cmd.type()); + req.type = YqnTransferType.codeOf(cmd.type()); req.orgWarehouseCode = cmd.fromWarehouseCode(); req.inOrgWarehouseCode = cmd.toWarehouseCode(); req.inventoryType = cmd.inventoryType(); @@ -109,87 +110,6 @@ public final class YqnTransferMapper { return items; } - /** 业务类型 → 运去哪 type:0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓 / 3 调拨出库。 */ - static Integer typeOf(TransferType type) { - if (type == null) { - return null; - } - switch (type) { - case AMAZON_REMOVAL: - return 0; - case AMAZON_INBOUND: - return 1; - case WAREHOUSE_TO_WAREHOUSE: - return 2; - case OUTBOUND: - return 3; - default: - return null; - } - } - - /** 运去哪 type → 业务类型。 */ - static TransferType typeOf(Integer code) { - if (code == null) { - return null; - } - switch (code) { - case 0: - return TransferType.AMAZON_REMOVAL; - case 1: - return TransferType.AMAZON_INBOUND; - case 2: - return TransferType.WAREHOUSE_TO_WAREHOUSE; - case 3: - return TransferType.OUTBOUND; - default: - return null; - } - } - - /** 运去哪调拨状态码 → 统一状态;未知码归 UNKNOWN,不猜。 */ - static TransferStatus toStatus(Integer rawStatus) { - if (rawStatus == null) { - return TransferStatus.UNKNOWN; - } - switch (rawStatus) { - case 0: - return TransferStatus.DRAFT; - case 3: - return TransferStatus.REJECTED; - case 5: - return TransferStatus.PENDING_REVIEW; - case 6: - return TransferStatus.REVIEWING; - case 7: - return TransferStatus.APPROVED; - case 8: - return TransferStatus.PENDING_CONFIRM; - case 9: - return TransferStatus.PENDING_PICKING; - case 10: - return TransferStatus.PENDING_OUTBOUND; - case 15: - return TransferStatus.OUTBOUNDING; - case 20: - return TransferStatus.PENDING_INBOUND; - case 25: - return TransferStatus.INBOUNDING; - case 70: - return TransferStatus.COMPLETED; - case 90: - return TransferStatus.CLOSED; - case 100: - return TransferStatus.CANCELLING; - case 110: - return TransferStatus.CANCELLED; - case 120: - return TransferStatus.CANCEL_EXCEPTION; - default: - return TransferStatus.UNKNOWN; - } - } - /** * 创建响应 → 统一调拨单。 * @@ -204,7 +124,7 @@ public final class YqnTransferMapper { .fromWarehouseCode(resp.orgWarehouseCode) .toWarehouseCode(resp.inOrgWarehouseCode) .type(requestedType) - .status(toStatus(resp.transferOutboundPlanStatus)) + .status(YqnTransferStatus.toCore(resp.transferOutboundPlanStatus)) .rawStatus(resp.transferOutboundPlanStatus == null ? null : String.valueOf(resp.transferOutboundPlanStatus)) .totalQuantity(resp.totalQuantity == null ? 0 : resp.totalQuantity) @@ -212,6 +132,7 @@ public final class YqnTransferMapper { .estimatedInboundAt(parseDate(resp.estimateInboundAt, zone)) .trackingNumber(resp.trackingNo) .remark(resp.remark) + .sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN) .build(); } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java index bab2cd2..e387b81 100644 --- a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java @@ -881,4 +881,68 @@ public final class YqnDtos { public String newSku; public String remark; } + + // ------------------------------------------------------------------ 运费试算(API 121) + + /** 订单测算请求(API 121,{@code /v1/saleOrder/calculate})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CalculateRequest { + + /** 尺寸单位:0 英寸 / 1 厘米。 */ + public Integer sizeUnit; + public Double length; + public Double width; + public Double height; + /** 重量单位:0 磅 / 1 盎司 / 2 克。 */ + public Integer weightUnit; + public Double weight; + /** 保价货值。 */ + public Double insuredValue; + public List warehouseSkuItem; + public String receiveCountry; + public String receiveState; + public String receiveCity; + public String receivePostal; + public String receiveAddress; + /** 1 住宅地址 / 0 商业地址。 */ + public Integer isResidential; + /** 物流产品服务,如 FedEx_FEDEX_GROUND。 */ + public String logisticsServiceCode; + public String logisticsProductCode; + /** 签名服务:NO_SIGNATURE / ADULT_SIGNATURE / SIGNATURE / INDIRECT_SIGNATURE。 */ + public String signService; + + /** 发货仓库。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CalculateSkuItem { + /** 发货仓库 code,必填。 */ + public String shipOrgWarehouseCode; + } + } + + /** 订单测算响应(API 121 {@code data[]})。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CalculateResult { + + public String shipOrgWarehouseCode; + public List calculationCarrierItems; + + /** 一个渠道的报价。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CalculateCarrierItem { + public String carrier; + public String logisticsServiceCode; + public String currency; + public Double totalRate; + public List calculationCostItems; + } + + /** 细分成本项。 */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public static final class CalculateCostItem { + public String costName; + public Double estimatedCost; + public String currency; + } + } } diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java new file mode 100644 index 0000000..22f7f51 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java @@ -0,0 +1,73 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.InboundStatus; + +/** + * 运去哪入库计划状态(API 101 的 {@code inboundPlanOrderStatus})。 + * + *

运去哪给的是数字字符串。码表来自接口文档,1:1 对应,未知码归 {@link #UNKNOWN}。

+ */ +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(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java new file mode 100644 index 0000000..8de38a2 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java @@ -0,0 +1,83 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.OutboundStatus; + +/** + * 运去哪出库单状态(API 128 的 {@code orderStatusEnum})。 + * + *

运去哪这个字段给的是英文文本而不是数字码,且目前没有公开发布的码表, + * 所以这里按关键字匹配。匹配不到的归 {@link #UNKNOWN}——不猜, + * 早先的实现把认不出的当 {@code SUBMITTED}(已下发)是错的。

+ * + *

关键字匹配是有损的:{@code UNSHIPPED} 这类名字会命中 {@code SHIP}。 + * 拿到官方码表后应改成精确匹配。

+ */ +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; + } + + /** + * 运去哪原始值 → 平台枚举。 + * + *

空值或匹配不到返回 {@link #UNKNOWN}。按声明顺序匹配,越具体的放越前。

+ */ + 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(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java new file mode 100644 index 0000000..bdccc6c --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java @@ -0,0 +1,67 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.ReturnDealMethod; + +/** + * 运去哪「退货预约处理方式」(API 81 的 {@code returnDealMethod})。 + * + *

码表:0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。

+ * + *

与 {@link YqnReturnProcessDisposition} 不是一回事:那个是仓收货检验后 + * 逐条明细行的决定(0/2/3/4),两套码值不能互换。

+ */ +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; + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java new file mode 100644 index 0000000..c331502 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java @@ -0,0 +1,67 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.ReturnProcessDisposition; + +/** + * 运去哪「退货检验后处理方式」(API 77 的 {@code goodsReturnType})。 + * + *

码表:0 客户自提 / 2 销毁 / 3 上架(良品)/ 4 换标上架(良品)。

+ * + *

与 {@link YqnReturnDealMethod} 不是一回事:那个是预约时的预报(0/1/2/5), + * 两套码值不能互换。

+ */ +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; + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java new file mode 100644 index 0000000..2e3c7e7 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java @@ -0,0 +1,82 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.TransferStatus; + +/** + * 运去哪调拨单状态(API 139 的 {@code transferOutboundPlanStatus})。 + * + *

码表来自接口文档,1:1 对应;未知码归 {@link #UNKNOWN},不猜。

+ */ +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(); + } +} diff --git a/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java new file mode 100644 index 0000000..6d96ac4 --- /dev/null +++ b/warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java @@ -0,0 +1,64 @@ +package common.ecommerce.yqn.enums; + +import common.ecommerce.warehouse.enums.TransferType; + +/** + * 运去哪调拨类型(API 139 的 {@code type})。 + * + *

码表来自接口文档:0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。

+ */ +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; + } +} diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java index f69d52c..f966419 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java @@ -5,14 +5,15 @@ 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.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; -import common.ecommerce.warehouse.model.CancelEligibility; -import common.ecommerce.warehouse.model.LabelMode; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; +import common.ecommerce.warehouse.enums.CancelEligibility; +import common.ecommerce.warehouse.enums.LabelMode; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundRef; -import common.ecommerce.warehouse.model.OutboundStatus; +import common.ecommerce.warehouse.enums.OutboundStatus; +import common.ecommerce.yqn.enums.YqnOutboundStatus; import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext; @@ -208,11 +209,19 @@ class YqnAdapterTest { @Test void statusMappingCoversKnownValues() { - assertEquals(OutboundStatus.CANCELLED, YqnOutboundMapper.toStatus("CANCELLED")); - assertEquals(OutboundStatus.PICKING, YqnOutboundMapper.toStatus("PICKING")); - assertEquals(OutboundStatus.LABEL_READY, YqnOutboundMapper.toStatus("LABEL_PRINTED")); - assertEquals(OutboundStatus.EXCEPTION, YqnOutboundMapper.toStatus("EXCEPTION")); - assertEquals(OutboundStatus.SUBMITTED, YqnOutboundMapper.toStatus("UNKNOWN_X")); + assertEquals(OutboundStatus.CANCELLED, YqnOutboundStatus.toCore("CANCELLED")); + assertEquals(OutboundStatus.PICKING, YqnOutboundStatus.toCore("PICKING")); + assertEquals(OutboundStatus.LABEL_READY, YqnOutboundStatus.toCore("LABEL_PRINTED")); + assertEquals(OutboundStatus.SHIPPED, YqnOutboundStatus.toCore("SHIPPED")); + assertEquals(OutboundStatus.EXCEPTION, YqnOutboundStatus.toCore("EXCEPTION")); assertNull(YqnOutboundMapper.parseTime("", null)); } + + /** 认不出的状态必须归 UNKNOWN,不能猜成 SUBMITTED(已下发)。 */ + @Test + void unknownStatusIsNotGuessed() { + assertEquals(OutboundStatus.UNKNOWN, YqnOutboundStatus.toCore("UNKNOWN_X")); + assertEquals(OutboundStatus.UNKNOWN, YqnOutboundStatus.toCore("")); + assertEquals(OutboundStatus.UNKNOWN, YqnOutboundStatus.toCore(null)); + } } diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java index 475b056..7707a9a 100644 --- a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java +++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java @@ -5,8 +5,8 @@ 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.WarehouseCapability; -import common.ecommerce.warehouse.WarehouseProvider; +import common.ecommerce.warehouse.enums.WarehouseCapability; +import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseContext;