Browse Source

refactor(warehouse): 枚举下沉 core + 平台枚举分层映射

枚举原来散在各模型内部(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 <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
a8dfb08e69
  1. 32
      README.md
  2. 49
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java
  3. 21
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java
  4. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
  5. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java
  6. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  7. 8
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
  8. 34
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java
  9. 67
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java
  10. 31
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java
  11. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java
  12. 81
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java
  13. 37
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java
  14. 43
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java
  15. 60
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java
  16. 35
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java
  17. 65
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  18. 35
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java
  19. 39
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java
  20. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java
  21. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java
  22. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java
  23. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java
  24. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  25. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
  26. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java
  27. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java
  28. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java
  29. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
  30. 5
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
  31. 46
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java
  32. 39
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java
  33. 40
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java
  34. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
  35. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  36. 29
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java
  37. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java
  38. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java
  39. 38
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java
  40. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java
  41. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java
  42. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java
  43. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  44. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java
  45. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java
  46. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java
  47. 8
      warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java
  48. 8
      warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java
  49. 4
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  50. 2
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java
  51. 4
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
  52. 2
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java
  53. 10
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  54. 4
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java
  55. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java
  56. 38
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  57. 41
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  58. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  59. 8
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java
  60. 91
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
  61. 64
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  62. 73
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java
  63. 83
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java
  64. 67
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java
  65. 67
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java
  66. 82
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java
  67. 64
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java
  68. 29
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java
  69. 4
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java

32
README.md

@ -295,23 +295,31 @@ common.ecommerce @@ -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 请求头名、限流

49
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java

@ -1,49 +0,0 @@ @@ -1,49 +0,0 @@
package common.ecommerce.warehouse;
/**
* 仓库能力位。
*
* <p>能力是事实表,不是推荐:调用方用 {@code WarehouseSdk.capabilities()} 查询,
* 缺失时抛 {@code WarehouseUnsupportedCapabilityException},不静默降级。</p>
*/
public enum WarehouseCapability {
/** 商品建档 / 更新 */
PRODUCT,
/** 出库单创建 / 查询 / 取消 / 拦截 */
OUTBOUND,
/** 支持把平台面单文件下发给仓打印贴标 */
PLATFORM_LABEL_DELIVERY,
/** 取消前费用预判 */
OUTBOUND_CANCEL_FEE_CHECK,
/** 库存查询 */
INVENTORY_QUERY,
/** 库存调整 / 调拨 */
INVENTORY_ADJUST,
/** 仓间调拨单(移库 / FBA 移入移出) */
TRANSFER,
/** 头程入库单创建 / 查询 */
INBOUND,
/** 退货发起 / 查询 */
RETURN,
/** 退货处理方式(二次上架 / 销毁) */
RETURN_DISPOSITION,
/** 换货(三家均无) */
EXCHANGE,
/** 无头件查询 */
UNSHIPPED_ITEM,
/** BOL 获取 / 传递 */
BOL,
/** 物流轨迹 */
TRACKING,
/** 拆单 */
SPLIT,
/** 销毁 / 报废 */
DESTRUCTION,
/** 费用账单 / 订单费用 / 仓租 / 账户流水 */
FEE_SETTLEMENT,
/** 费用试算 */
FEE_ESTIMATE,
/** 状态回调推送 */
WEBHOOK
}

21
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java

@ -1,21 +0,0 @@ @@ -1,21 +0,0 @@
package common.ecommerce.warehouse;
/**
* 三方仓 provider 枚举。
*
* <p>与渠道域的 {@code ChannelProvider} 分开:仓不是平台,两套枚举互不继承,
* 但幂等、水位线、审计里都以 {@link #name()} 字符串落库,共用同一批 SPI。</p>
*/
public enum WarehouseProvider {
/** 运去哪(打样仓) */
YQN,
/** 信仓(新版接口) */
XINCANG,
/** 易达云 */
EDAYUN,
/** 领星 WMS:预留,本期不实现 */
LINGXING,
/** 其他自建/直连仓 */
CUSTOM
}

4
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java

@ -3,7 +3,7 @@ package common.ecommerce.warehouse.capability; @@ -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 { @@ -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);
}
}

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java

@ -2,7 +2,7 @@ package common.ecommerce.warehouse.capability; @@ -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;

12
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java

@ -1,6 +1,7 @@ @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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;
}

8
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java

@ -1,6 +1,8 @@ @@ -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; @@ -12,8 +14,8 @@ import common.ecommerce.warehouse.sdk.WarehouseContext;
*
* <p>退货链路有两个不同的「处理方式」,别混:</p>
* <ul>
* <li>{@link ReturnCommand.DealMethod} —— 创建退货预约时的预报</li>
* <li>{@link ReturnProcessCommand.Disposition} —— 仓收货检验后按明细行最终决定</li>
* <li>{@link ReturnDealMethod} —— 创建退货预约时的预报</li>
* <li>{@link ReturnProcessDisposition} —— 仓收货检验后按明细行最终决定</li>
* </ul>
*/
public interface WarehouseReturnCapable extends WarehouseAdapter {
@ -45,6 +47,6 @@ 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);
}
}

34
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java

@ -0,0 +1,34 @@ @@ -0,0 +1,34 @@
package common.ecommerce.warehouse.enums;
/**
* 取消资格判定。
*
* <p>仓方能力不齐,有的仓有专门的取消预判接口,有的只能查单状态推断。
* SDK 统一映射到这三态;{@link #CHARGED} 必须由调用方显式传
* {@code acceptCharge=true} 才执行取消。</p>
*/
public enum CancelEligibility {
/** 可免费取消。 */
FREE(10, "可免费取消"),
/** 可取消但收费;需调用方确认。 */
CHARGED(20, "可取消但收费"),
/** 不可取消(已出库 / 已交运 / 仓不允许)。 */
BLOCKED(30, "不可取消");
private final int code;
private final String label;
CancelEligibility(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

67
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java

@ -0,0 +1,67 @@ @@ -0,0 +1,67 @@
package common.ecommerce.warehouse.enums;
/**
* 入库计划单状态(底层枚举)。
*
* <p>各仓的状态在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里;
* 本枚举不认识任何仓的码值。</p>
*
* <p>未知码归 {@link #UNKNOWN},不猜——猜错会让宿主把未完成的入库当完成。</p>
*/
public enum InboundStatus {
/** 草稿 / 已创建。 */
DRAFT(10, "草稿"),
/** 待审核。 */
PENDING_REVIEW(20, "待审核"),
/** 审核拒绝。 */
REJECTED(30, "审核拒绝"),
/** 待装箱。 */
PENDING_PACKING(40, "待装箱"),
/** 待发货。 */
PENDING_SHIPMENT(50, "待发货"),
/** 已发运 / 在途。 */
IN_TRANSIT(60, "在途"),
/** 收货中。 */
RECEIVING(70, "收货中"),
/** 已收货。 */
RECEIVED(80, "已收货"),
/** 待入库(上架)。 */
PENDING_STORAGE(90, "待上架"),
/** 入库中(上架中)。 */
STORING(100, "上架中"),
/** 已完成。 */
COMPLETED(110, "已完成"),
/** 已取消。 */
CANCELLED(120, "已取消"),
/** 无法识别的状态;码 0 保留给 UNKNOWN,不与任何业务状态冲突。 */
UNKNOWN(0, "未知");
private final int code;
private final String label;
InboundStatus(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 按落库码反查。 */
public static InboundStatus ofCode(int code) {
for (InboundStatus s : values()) {
if (s.code == code) {
return s;
}
}
return UNKNOWN;
}
}

31
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java

@ -0,0 +1,31 @@ @@ -0,0 +1,31 @@
package common.ecommerce.warehouse.enums;
/**
* 库存同步策略。
*
* <p>仓能力不同:有的仓支持按时间增量,有的只能全量拉取后做差异比对。
* 具体哪家支持哪种由适配器的 {@code InventoryCapable.syncStrategy()} 声明。</p>
*/
public enum InventorySyncStrategy {
/** 按时间增量查询。 */
TIME_WINDOW(10, "按时间增量"),
/** 全量拉取 + 差异比对。 */
FULL_PULL_DIFF(20, "全量比对");
private final int code;
private final String label;
InventorySyncStrategy(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

32
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java

@ -0,0 +1,32 @@ @@ -0,0 +1,32 @@
package common.ecommerce.warehouse.enums;
/**
* 面单模式。
*
* <p>必须与仓能力匹配:{@link #PLATFORM_LABEL} 要求仓声明
* {@link WarehouseCapability#PLATFORM_LABEL_DELIVERY},缺失时 {@code create()} 拒绝,
* <b>不静默降级</b>为仓自有面单——面单归属直接影响与平台的标发方式。</p>
*/
public enum LabelMode {
/** 仓用自己的承运商账号出单,SDK 只回收面单与运单。 */
WAREHOUSE_LABEL(10, "仓自有面单"),
/** 渠道域先取平台面单,OMS 把面单文件下发给仓打印贴标。 */
PLATFORM_LABEL(20, "平台面单");
private final int code;
private final String label;
LabelMode(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

81
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java

@ -0,0 +1,81 @@ @@ -0,0 +1,81 @@
package common.ecommerce.warehouse.enums;
/**
* 出库单状态(底层枚举)。
*
* <p>各仓的状态在各自模块里先映射成「平台枚举」,再 {@code toCore()} 到这里;
* 本枚举不认识任何仓的码值或字符串。</p>
*
* <p>{@link #CREATED} 与 {@link #SUBMITTED} 不是仓方状态,是 SDK 自己的生命周期:
* 前者表示 OMS 已建单未下发,后者表示已下发但仓尚未确认。仓方返回的状态只会落在
* {@code SUBMITTED} 之后的值上。</p>
*
* <p>{@link #UNKNOWN} 是必须项:仓方给出无法识别的状态时归这里,<b>不许猜成别的值</b>,
* 原值看 {@code rawStatus}。</p>
*
* <p>{@link #rank()} 只对仓方状态有意义,用于丢弃乱序回调;{@link #UNKNOWN}
* 的 rank 为 -1,表示「不参与比较」,宿主应保留记录但不覆盖已有状态。</p>
*/
public enum OutboundStatus {
/** 已创建(OMS 侧),尚未下发。 */
CREATED(10, "已创建", 0),
/** SDK 下发成功,仓未确认。 */
SUBMITTED(20, "已下发", 1),
/** 仓已接单。 */
ACCEPTED(30, "仓已接单", 2),
/** 拣货中。 */
PICKING(40, "拣货中", 3),
/** 已打包。 */
PACKED(50, "已打包", 4),
/** 面单已出。 */
LABEL_READY(60, "面单已出", 5),
/** 已交运。 */
SHIPPED(70, "已交运", 6),
/** 已取消。 */
CANCELLED(80, "已取消", 7),
/** 异常(仓侧拣货失败、地址异常等)。 */
EXCEPTION(90, "异常", 8),
/** 无法识别;原值见 {@code rawStatus},不参与 rank 比较。 */
UNKNOWN(0, "未知", -1);
private final int code;
private final String label;
private final int rank;
OutboundStatus(int code, String label, int rank) {
this.code = code;
this.label = label;
this.rank = rank;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 状态推进序号,越大越靠后;用于丢弃乱序回调。-1 表示不参与比较。 */
public int rank() {
return rank;
}
/** 是否终态(不会再变)。 */
public boolean terminal() {
return this == SHIPPED || this == CANCELLED;
}
/** 按落库码反查。 */
public static OutboundStatus ofCode(int code) {
for (OutboundStatus s : values()) {
if (s.code == code) {
return s;
}
}
return UNKNOWN;
}
}

37
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java

@ -0,0 +1,37 @@ @@ -0,0 +1,37 @@
package common.ecommerce.warehouse.enums;
/**
* 退货预约时的处理方式(业务语义)。
*
* <p>只表达「怎么处理」,不含任何仓方的数字码:各仓码值不同,映射由适配器负责。</p>
*
* <p><b>与 {@link ReturnProcessDisposition} 不是一回事</b>:这个是下单时发货人预报的,
* 那个是仓收货检验之后逐条明细行的最终决定。两者可选值不同,不能互换。</p>
*/
public enum ReturnDealMethod {
/** 客户自提。 */
CUSTOMER_PICKUP(10, "客户自提"),
/** 拍照确认后由客户决定。 */
PHOTO_CONFIRM(20, "拍照确认"),
/** 销毁。 */
DESTROY(30, "销毁"),
/** 仓库确认处理。 */
WAREHOUSE_CONFIRM(40, "仓库确认");
private final int code;
private final String label;
ReturnDealMethod(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

43
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java

@ -0,0 +1,43 @@ @@ -0,0 +1,43 @@
package common.ecommerce.warehouse.enums;
/**
* 退货检验后的处理方式(业务语义)。
*
* <p>只表达「怎么处理」,不含任何仓方的数字码:各仓码值不同,映射由适配器负责。</p>
*
* <p><b>与 {@link ReturnDealMethod} 不是一回事</b>:那个是预约时的预报,
* 这个是仓收货检验之后逐条明细行的最终决定。</p>
*
* <p>查询结果也用本枚举:{@link #UNKNOWN} 表示仓方返回的处理方式无法识别,
* 原值见 {@code WarehouseReturn.rawStatus()}。不再单独建一个查询专用的枚举——
* 那只是本枚举的子集,多一个枚举就多一处「到底该用哪个」的困惑。</p>
*/
public enum ReturnProcessDisposition {
/** 客户自提。 */
CUSTOMER_PICKUP(10, "客户自提"),
/** 销毁。 */
DESTROY(20, "销毁"),
/** 上架(良品)。 */
RESTOCK(30, "上架"),
/** 换标后上架(良品)。 */
RESTOCK_RELABEL(40, "换标上架"),
/** 无法识别;0 保留给 UNKNOWN。 */
UNKNOWN(0, "未知");
private final int code;
private final String label;
ReturnProcessDisposition(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

60
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java

@ -0,0 +1,60 @@ @@ -0,0 +1,60 @@
package common.ecommerce.warehouse.enums;
/**
* 调拨单状态(底层枚举)。
*
* <p>各仓的状态码在各自模块里先映射成平台枚举,再 {@code toCore()} 到这里;
* 本枚举不认识任何仓的码值。未知码归 {@link #UNKNOWN},不猜。</p>
*
* <p>取值<b>只追加不合并</b>:新仓有、这里没有的状态就加一个值,已存在的值
* 不会再合并回上一级——合并之后宿主就分不出「待审核」和「审核中」了。</p>
*/
public enum TransferStatus {
DRAFT(10, "草稿"),
REJECTED(20, "已驳回"),
PENDING_REVIEW(30, "待审核"),
REVIEWING(40, "审核中"),
APPROVED(50, "审核通过"),
PENDING_CONFIRM(60, "待确认"),
PENDING_PICKING(70, "待备货"),
PENDING_OUTBOUND(80, "待出库"),
OUTBOUNDING(90, "出库中"),
PENDING_INBOUND(100, "待入库"),
INBOUNDING(110, "入库中"),
COMPLETED(120, "已完成"),
CLOSED(130, "已关闭"),
CANCELLING(140, "取消中"),
CANCELLED(150, "已取消"),
CANCEL_EXCEPTION(160, "取消异常"),
/** 无法识别;0 保留给 UNKNOWN。 */
UNKNOWN(0, "未知");
private final int code;
private final String label;
TransferStatus(int code, String label) {
this.code = code;
this.label = label;
}
/** 落库用的稳定码;由 SDK 分配,永不复用、永不重排。 */
public int code() {
return code;
}
/** 中文显示名。 */
public String label() {
return label;
}
/** 按落库码反查。 */
public static TransferStatus ofCode(int code) {
for (TransferStatus s : values()) {
if (s.code == code) {
return s;
}
}
return UNKNOWN;
}
}

35
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java

@ -0,0 +1,35 @@ @@ -0,0 +1,35 @@
package common.ecommerce.warehouse.enums;
/**
* 调拨类型,只表达业务语义。
*
* <p>仓方的类型码由适配器映射(如运去哪 {@code type} 0/1/2/3),core 不认识任何
* 仓的码值。创建响应若不回传类型,适配器从请求侧带过来,不猜。</p>
*/
public enum TransferType {
/** 仓到仓调拨。 */
WAREHOUSE_TO_WAREHOUSE(10, "仓到仓调拨"),
/** 调拨出库(发往外部地址或平台仓)。 */
OUTBOUND(20, "调拨出库"),
/** 亚马逊移除订单(FBA 移出)。 */
AMAZON_REMOVAL(30, "亚马逊移出"),
/** 亚马逊移入(FBA 入库)。 */
AMAZON_INBOUND(40, "亚马逊移入");
private final int code;
private final String label;
TransferType(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

65
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java

@ -0,0 +1,65 @@ @@ -0,0 +1,65 @@
package common.ecommerce.warehouse.enums;
/**
* 仓库能力位。
*
* <p>能力是事实表,不是推荐:调用方用 {@code WarehouseSdk.capabilities()} 查询,
* 缺失时抛 {@code WarehouseUnsupportedCapabilityException},不静默降级。</p>
*/
public enum WarehouseCapability {
/** 商品建档 / 更新 */
PRODUCT(10, "商品建档"),
/** 出库单创建 / 查询 / 取消 / 拦截 */
OUTBOUND(20, "出库"),
/** 支持把平台面单文件下发给仓打印贴标 */
PLATFORM_LABEL_DELIVERY(30, "平台面单下发"),
/** 取消前费用预判 */
OUTBOUND_CANCEL_FEE_CHECK(40, "取消费用预判"),
/** 库存查询 */
INVENTORY_QUERY(50, "库存查询"),
/** 库存调整 / 调拨 */
INVENTORY_ADJUST(60, "库存调整"),
/** 仓间调拨单(移库 / FBA 移入移出) */
TRANSFER(70, "仓间调拨"),
/** 头程入库单创建 / 查询 */
INBOUND(80, "入库"),
/** 退货发起 / 查询 */
RETURN(90, "退货"),
/** 退货处理方式(二次上架 / 销毁) */
RETURN_DISPOSITION(100, "退货处理方式"),
/** 换货 */
EXCHANGE(110, "换货"),
/** 无头件查询 */
UNSHIPPED_ITEM(120, "无头件"),
/** BOL 获取 / 传递 */
BOL(130, "BOL"),
/** 物流轨迹 */
TRACKING(140, "物流轨迹"),
/** 拆单 */
SPLIT(150, "拆单"),
/** 销毁 / 报废 */
DESTRUCTION(160, "销毁报废"),
/** 费用账单 / 订单费用 / 仓租 / 账户流水 */
FEE_SETTLEMENT(170, "费用结算"),
/** 费用试算 */
FEE_ESTIMATE(180, "费用试算"),
/** 状态回调推送 */
WEBHOOK(190, "状态回调");
private final int code;
private final String label;
WarehouseCapability(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

35
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java

@ -0,0 +1,35 @@ @@ -0,0 +1,35 @@
package common.ecommerce.warehouse.enums;
/**
* 仓费用类型,只表达业务语义。
*
* <p>仓方的费用码与分类口径由适配器维护:有的仓给类型码,有的仓只给中文费用名,
* 后者按名归类,认不出就留 null——对账时宁可不分类,也不能猜错。</p>
*/
public enum WarehouseFeeType {
/** 作业费(出入库操作费)。 */
OPERATION(10, "作业费"),
/** 仓储费 / 仓租。 */
STORAGE(20, "仓储费"),
/** 增值服务费。 */
VALUE_ADDED(30, "增值服务费"),
/** 尾程运费。 */
LAST_MILE(40, "尾程运费");
private final int code;
private final String label;
WarehouseFeeType(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

39
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java

@ -0,0 +1,39 @@ @@ -0,0 +1,39 @@
package common.ecommerce.warehouse.enums;
/**
* 三方仓 provider 枚举。
*
* <p>与渠道域的 {@code ChannelProvider} 分开:仓不是平台,两套枚举互不继承,
* 但幂等、水位线、审计里都以 {@link #name()} 字符串落库,共用同一批 SPI。
* provider 是<b>接入通道标识</b>而非协议码,因此落库继续用 {@code name()},
* 不用 {@link #code()}——换码值会让存量幂等键对不上。</p>
*/
public enum WarehouseProvider {
/** 运去哪(打样仓) */
YQN(10, "运去哪"),
/** 信仓(新版接口) */
XINCANG(20, "信仓"),
/** 易达云 */
EDAYUN(30, "易达云"),
/** 领星 WMS:预留,本期不实现 */
LINGXING(40, "领星WMS"),
/** 其他自建/直连仓 */
CUSTOM(90, "自建仓");
private final int code;
private final String label;
WarehouseProvider(int code, String label) {
this.code = code;
this.label = label;
}
public int code() {
return code;
}
public String label() {
return label;
}
}

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java

@ -1,6 +1,6 @@ @@ -1,6 +1,6 @@
package common.ecommerce.warehouse.error;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseCapability;
/**
* 该仓不支持此能力;调用方走人工或替代路径。

17
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java

@ -1,5 +1,8 @@ @@ -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; @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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;

17
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java

@ -1,17 +0,0 @@ @@ -1,17 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 取消资格判定。
*
* <p>仓方能力不齐:易达云有专门接口,另两家需打样核实。SDK 统一映射到这三态;
* {@link #CHARGED} 必须由调用方显式传 {@code acceptCharge=true} 才执行取消。</p>
*/
public enum CancelEligibility {
/** 可免费取消。 */
FREE,
/** 可取消但收费;需调用方确认。 */
CHARGED,
/** 不可取消(已出库 / 已交运 / 仓不允许)。 */
BLOCKED
}

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java

@ -1,5 +1,7 @@ @@ -1,5 +1,7 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.shared.support.Money;
/**

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java

@ -1,5 +1,7 @@ @@ -1,5 +1,7 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseFeeType;
import java.time.LocalDate;
/**

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java

@ -1,5 +1,8 @@ @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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;

32
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java

@ -1,32 +0,0 @@ @@ -1,32 +0,0 @@
package common.ecommerce.warehouse.model;
/** 入库计划单状态,已归一化。仓方状态值在适配器内映射到这里。 */
public enum InboundStatus {
/** 草稿 / 已创建。 */
DRAFT,
/** 待审核。 */
PENDING_REVIEW,
/** 审核拒绝。 */
REJECTED,
/** 待装箱。 */
PENDING_PACKING,
/** 待发货。 */
PENDING_SHIPMENT,
/** 已发运 / 在途。 */
IN_TRANSIT,
/** 收货中。 */
RECEIVING,
/** 已收货。 */
RECEIVED,
/** 待入库(上架)。 */
PENDING_STORAGE,
/** 入库中(上架中)。 */
STORING,
/** 已完成。 */
COMPLETED,
/** 已取消。 */
CANCELLED,
/** 无法识别的状态。 */
UNKNOWN
}

12
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java

@ -1,12 +0,0 @@ @@ -1,12 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 库存同步策略。仓能力不同:信仓支持按时间增量,易达云只能全量 diff。
*/
public enum InventorySyncStrategy {
/** 按时间增量查询。 */
TIME_WINDOW,
/** 全量拉取 + 差异比对。 */
FULL_PULL_DIFF
}

16
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java

@ -1,16 +0,0 @@ @@ -1,16 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 面单模式。
*
* <p>必须与仓能力匹配:{@link #PLATFORM_LABEL} 要求仓声明
* {@code WarehouseCapability.PLATFORM_LABEL_DELIVERY},缺失时 {@code create()} 拒绝,
* <b>不静默降级</b>为仓自有面单——面单归属直接影响与平台的标发方式。</p>
*/
public enum LabelMode {
/** 仓用自己的承运商账号出单,SDK 只回收面单与运单。 */
WAREHOUSE_LABEL,
/** 渠道域先取平台面单,OMS 把面单文件下发给仓打印贴标。 */
PLATFORM_LABEL
}

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java

@ -1,5 +1,7 @@ @@ -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;

5
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java

@ -1,7 +1,10 @@ @@ -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;

46
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java

@ -1,46 +0,0 @@ @@ -1,46 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 出库单状态。仓方状态在适配器内映射到这里,只前进不后退。
*
* <p>回调不保证顺序,宿主按本枚举的 {@link #rank()} 比较:小于当前值的事件记为
* {@code OUT_OF_ORDER},保留记录但不覆盖状态。</p>
*/
public enum OutboundStatus {
/** 已创建(OMS 侧),尚未下发。 */
CREATED(0),
/** SDK 下发成功,仓未确认。 */
SUBMITTED(1),
/** 仓已接单。 */
ACCEPTED(2),
/** 拣货中。 */
PICKING(3),
/** 已打包。 */
PACKED(4),
/** 面单已出。 */
LABEL_READY(5),
/** 已交运。 */
SHIPPED(6),
/** 已取消。 */
CANCELLED(7),
/** 异常(仓侧拣货失败、地址异常等)。 */
EXCEPTION(8);
/** 状态推进序号,越大越靠后。 */
private final int rank;
OutboundStatus(int rank) {
this.rank = rank;
}
/** 状态推进序号。 */
public int rank() {
return rank;
}
/** 是否终态(不会再变)。 */
public boolean terminal() {
return this == SHIPPED || this == CANCELLED;
}
}

39
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java

@ -1,5 +1,7 @@ @@ -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; @@ -8,8 +10,8 @@ import java.util.List;
/**
* 退货计划创建命令。<b>写操作</b>,幂等键是 {@link #returnRequestNo()}(仓方的 {@code orderNo})。
*
* <p>运去哪必填:仓、来源单号、关联销售单号、退货运单号、承运商、至少一条商品行;
* 每条商品行还必须给处理方式。</p>
* <p>各仓必填项不同:适配器只校验自己协议要求的字段,core 只保证幂等键与
* 至少一条商品行。</p>
*/
public final class ReturnCommand {
@ -96,16 +98,16 @@ public final class ReturnCommand { @@ -96,16 +98,16 @@ public final class ReturnCommand {
* 退货商品行。
*
* <p>{@link #dealMethod()} 是<b>退货预约时的处理方式</b>,与
* {@code ReturnProcessCommand.Disposition}(检验后处理方式)不是一回事:
* {@code ReturnProcessDisposition}(检验后处理方式)不是一回事:
* 前者是发货人预报,后者是仓收货检验后按明细行最终决定。两套枚举码值也不同。</p>
*/
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 { @@ -125,34 +127,11 @@ public final class ReturnCommand {
return quantity;
}
public DealMethod dealMethod() {
public ReturnDealMethod dealMethod() {
return dealMethod;
}
}
/**
* 退货预约的处理方式(API 81):0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。
*
* <p>注意 API 77 的检验后处理方式码值完全不同(0 自提 / 2 销毁 / 3 上架 / 4 换标上架),
* 两者不能混用。</p>
*/
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 { @@ -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;
}

40
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java

@ -1,17 +1,19 @@ @@ -1,17 +1,19 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
/**
* 退货条目处理命令(API 77 / 检验后决定)。
* 退货条目处理命令(检验后决定)。
*
* <p>与 {@code ReturnCommand.DealMethod}(预约时的预报)不是一回事:
* 这里是仓收货检验之后,逐条明细行最终决定怎么处理。</p>
* <p>与 {@link common.ecommerce.warehouse.enums.ReturnDealMethod}(预约时的预报)
* 不是一回事:这里是仓收货检验之后,逐条明细行最终决定怎么处理。</p>
*/
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 { @@ -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 { @@ -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 { @@ -63,32 +65,10 @@ public final class ReturnProcessCommand {
return remark;
}
/**
* 检验后处理方式(API 77):0 客户自提 / 2 销毁 / 3 上架(良品) / 4 换标上架(良品)。
*
* <p>与预约时的处理方式码值不同,不能混用。</p>
*/
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 { @@ -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;
}

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java

@ -1,5 +1,7 @@ @@ -1,5 +1,7 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.TransferType;
/**
* 调拨单创建命令。<b>写操作</b>,幂等键是 {@link #transferRequestNo()}(仓方的 {@code sourceNo})。
*

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java

@ -1,5 +1,9 @@ @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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;

29
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java

@ -1,29 +0,0 @@ @@ -1,29 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 调拨单状态,已归一化。
*
* <p>运去哪的码:0 草稿 / 3 已驳回 / 5 待审核 / 6 审核中 / 7 审核通过 / 8 待确认 /
* 9 待备货 / 10 待出库 / 15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 /
* 90 已关闭 / 100 取消中 / 110 已取消 / 120 取消异常。</p>
*/
public enum TransferStatus {
DRAFT,
REJECTED,
PENDING_REVIEW,
REVIEWING,
APPROVED,
PENDING_CONFIRM,
PENDING_PICKING,
PENDING_OUTBOUND,
OUTBOUNDING,
PENDING_INBOUND,
INBOUNDING,
COMPLETED,
CLOSED,
CANCELLING,
CANCELLED,
CANCEL_EXCEPTION,
UNKNOWN
}

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java

@ -1,19 +0,0 @@ @@ -1,19 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 调拨类型。
*
* <p>运去哪的 {@code type} 是 0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。
* 只保留业务语义,适配器维护到仓方码值的映射。</p>
*/
public enum TransferType {
/** 仓到仓调拨。 */
WAREHOUSE_TO_WAREHOUSE,
/** 调拨出库(发往外部地址或平台仓)。 */
OUTBOUND,
/** 亚马逊移除订单(FBA 移出)。 */
AMAZON_REMOVAL,
/** 亚马逊移入(FBA 入库)。 */
AMAZON_INBOUND
}

19
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java

@ -1,19 +0,0 @@ @@ -1,19 +0,0 @@
package common.ecommerce.warehouse.model;
/**
* 仓费用类型。
*
* <p>各仓的枚举值不同,由适配器维护映射;这里只保留业务语义。
* 运去哪 API 133 的 {@code costType} 是 1 作业费 / 2 仓储费 / 3 增值服务费 / 4 尾程费用。</p>
*/
public enum WarehouseFeeType {
/** 作业费(出入库操作费)。 */
OPERATION,
/** 仓储费 / 仓租。 */
STORAGE,
/** 增值服务费。 */
VALUE_ADDED,
/** 尾程运费。 */
LAST_MILE
}

38
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java

@ -1,5 +1,8 @@ @@ -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 { @@ -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<ReturnLine> lines;
private final Instant createdAt;
@ -31,7 +38,8 @@ public final class WarehouseReturn { @@ -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<ReturnLine>(b.lines));
this.createdAt = b.createdAt;
}
@ -68,7 +76,7 @@ public final class WarehouseReturn { @@ -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 { @@ -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 { @@ -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 { @@ -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<ReturnLine> lines = new ArrayList<ReturnLine>();
private Instant createdAt;
@ -208,7 +215,12 @@ public final class WarehouseReturn { @@ -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;
}

4
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java

@ -1,7 +1,7 @@ @@ -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;

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java

@ -1,6 +1,6 @@ @@ -1,6 +1,6 @@
package common.ecommerce.warehouse.sdk;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.enums.WarehouseProvider;
/**
* 仓库适配器工厂。新增第 4 家仓只需新增模块 + 实现本接口 + 注册,

2
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java

@ -1,7 +1,7 @@ @@ -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;

6
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java

@ -4,8 +4,8 @@ import common.ecommerce.shared.audit.CallObserver; @@ -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; @@ -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;

6
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java

@ -4,7 +4,7 @@ import common.ecommerce.shared.audit.CallObserver; @@ -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; @@ -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;

6
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java

@ -4,8 +4,8 @@ import common.ecommerce.shared.audit.CallObserver; @@ -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; @@ -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;

12
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java

@ -14,6 +14,18 @@ import common.ecommerce.warehouse.model.WarehouseReturn; @@ -14,6 +14,18 @@ import common.ecommerce.warehouse.model.WarehouseReturn;
* <p>实现方必须按业务键 upsert:同一实体重复同步不得产生两条记录。
* 全部方法默认抛 {@link UnsupportedOperationException},宿主按需实现——
* 只接出库闭环的宿主不必被迫实现费用与销毁。</p>
*
* <h2>落库契约(硬要求)</h2>
* <p>凡是带状态的实体,<b>{@code rawStatus} 必须落库,且必须与 {@code sourceProvider}
* 成对保存</b>。原因:</p>
* <ul>
* <li>{@code rawStatus} 是平台原话,同一个值在不同仓含义不同(运去哪的 {@code "5"}
* 与信仓的 {@code "5"} 不是一回事),单存它无法解释;</li>
* <li>归一化枚举({@code status})与平台码的映射将来可能调整,原始值是唯一能
* 重跑映射、修正历史数据的依据;只存枚举则改映射等于永久污染存量数据。</li>
* </ul>
* <p>建议同时存 {@code status.code()}:跨仓查询用它(一条 SQL),
* 展示与排查用 {@code rawStatus}。</p>
*/
public interface WarehouseSink {

8
warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java

@ -2,21 +2,21 @@ package common.ecommerce.warehouse.testkit; @@ -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;

8
warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java

@ -2,15 +2,15 @@ package common.ecommerce.warehouse.sdk; @@ -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;

4
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java

@ -7,8 +7,8 @@ import common.ecommerce.shared.spi.AccessToken; @@ -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;

2
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java

@ -4,7 +4,7 @@ import common.ecommerce.http.JacksonJsonCodec; @@ -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;

4
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java

@ -6,8 +6,8 @@ import common.ecommerce.shared.testkit.InMemoryTokenStore; @@ -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;

2
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java

@ -9,7 +9,7 @@ import common.ecommerce.shared.testkit.InMemoryLockProvider; @@ -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;

10
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java

@ -6,8 +6,8 @@ import common.ecommerce.http.HttpTransport; @@ -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; @@ -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; @@ -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;

4
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java

@ -21,8 +21,8 @@ public final class YqnAdapterFactory @@ -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

3
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java

@ -3,7 +3,7 @@ package common.ecommerce.yqn.adapter; @@ -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 { @@ -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();
}

38
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java

@ -7,7 +7,7 @@ import common.ecommerce.warehouse.model.InboundCommand; @@ -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 { @@ -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 { @@ -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();
}

41
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java

@ -1,16 +1,16 @@ @@ -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 { @@ -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 { @@ -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()) {

3
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java

@ -2,6 +2,7 @@ package common.ecommerce.yqn.adapter; @@ -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 { @@ -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();

8
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java

@ -3,6 +3,9 @@ package common.ecommerce.yqn.adapter; @@ -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 { @@ -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 { @@ -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 { @@ -75,6 +78,7 @@ public final class YqnReturnMapper {
.orderRef(cmd.saleOrderNo())
.status("SUBMITTED")
.rawStatus(null)
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build();
}

91
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java

@ -4,8 +4,9 @@ import common.ecommerce.warehouse.model.InboundBatch; @@ -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 { @@ -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 { @@ -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 { @@ -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 { @@ -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();
}

64
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java

@ -881,4 +881,68 @@ public final class YqnDtos { @@ -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<CalculateSkuItem> 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<CalculateCarrierItem> 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<CalculateCostItem> calculationCostItems;
}
/** 细分成本项。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CalculateCostItem {
public String costName;
public Double estimatedCost;
public String currency;
}
}
}

73
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java

@ -0,0 +1,73 @@ @@ -0,0 +1,73 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.InboundStatus;
/**
* 运去哪入库计划状态(API 101 的 {@code inboundPlanOrderStatus})。
*
* <p>运去哪给的是数字字符串。码表来自接口文档,1:1 对应,未知码归 {@link #UNKNOWN}。</p>
*/
public enum YqnInboundStatus {
/** 0 草稿。 */
DRAFT("0", InboundStatus.DRAFT),
/** 5 待审核。 */
PENDING_REVIEW("5", InboundStatus.PENDING_REVIEW),
/** 6 审核驳回。 */
REJECTED("6", InboundStatus.REJECTED),
/** 8 待装箱。 */
PENDING_PACKING("8", InboundStatus.PENDING_PACKING),
/** 10 待发货。 */
PENDING_SHIPMENT("10", InboundStatus.PENDING_SHIPMENT),
/** 16 收货中。 */
RECEIVING("16", InboundStatus.RECEIVING),
/** 17 已收货。 */
RECEIVED("17", InboundStatus.RECEIVED),
/** 20 待上架。 */
PENDING_STORAGE("20", InboundStatus.PENDING_STORAGE),
/** 25 上架中。 */
STORING("25", InboundStatus.STORING),
/** 70 已完成。 */
COMPLETED("70", InboundStatus.COMPLETED),
/** 100 已取消。 */
CANCELLED("100", InboundStatus.CANCELLED),
/** 无法识别。 */
UNKNOWN(null, InboundStatus.UNKNOWN);
private final String rawCode;
private final InboundStatus core;
YqnInboundStatus(String rawCode, InboundStatus core) {
this.rawCode = rawCode;
this.core = core;
}
/** 运去哪的状态码;null 表示无法识别。 */
public String rawCode() {
return rawCode;
}
/** 对应的底层状态。 */
public InboundStatus toCore() {
return core;
}
/** 运去哪状态码 → 平台枚举。 */
public static YqnInboundStatus of(String rawStatus) {
if (rawStatus == null || rawStatus.trim().isEmpty()) {
return UNKNOWN;
}
String s = rawStatus.trim();
for (YqnInboundStatus v : values()) {
if (s.equals(v.rawCode)) {
return v;
}
}
return UNKNOWN;
}
/** 运去哪状态码 → 底层状态。 */
public static InboundStatus toCore(String rawStatus) {
return of(rawStatus).toCore();
}
}

83
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java

@ -0,0 +1,83 @@ @@ -0,0 +1,83 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.OutboundStatus;
/**
* 运去哪出库单状态(API 128 的 {@code orderStatusEnum})。
*
* <p>运去哪这个字段给的是英文文本而不是数字码,且目前<b>没有公开发布的码表</b>,
* 所以这里按关键字匹配。匹配不到的归 {@link #UNKNOWN}——<b>不猜</b>,
* 早先的实现把认不出的当 {@code SUBMITTED}(已下发)是错的。</p>
*
* <p>关键字匹配是有损的:{@code UNSHIPPED} 这类名字会命中 {@code SHIP}。
* 拿到官方码表后应改成精确匹配。</p>
*/
public enum YqnOutboundStatus {
/** 已取消 / 取消中。 */
CANCELLED("CANCEL", OutboundStatus.CANCELLED),
/** 已交运 / 已发出 / 已妥投。 */
SHIPPED("SHIP", OutboundStatus.SHIPPED),
/** 已妥投(独立关键字,避免只靠 SHIP 覆盖)。 */
DELIVERED("DELIVER", OutboundStatus.SHIPPED),
/** 面单已打印。 */
LABEL_READY("LABEL", OutboundStatus.LABEL_READY),
/** 已打包。 */
PACKED("PACK", OutboundStatus.PACKED),
/** 拣货中。 */
PICKING("PICK", OutboundStatus.PICKING),
/** 仓已接单。 */
ACCEPTED("ACCEPT", OutboundStatus.ACCEPTED),
/** 异常。 */
EXCEPTION("EXCEPTION", OutboundStatus.EXCEPTION),
/** 失败 / 错误。 */
FAILED("FAIL", OutboundStatus.EXCEPTION),
/** 错误码。 */
ERROR("ERROR", OutboundStatus.EXCEPTION),
/** 无法识别。 */
UNKNOWN(null, OutboundStatus.UNKNOWN);
private final String keyword;
private final OutboundStatus core;
YqnOutboundStatus(String keyword, OutboundStatus core) {
this.keyword = keyword;
this.core = core;
}
/** 运去哪原始值里的关键字;null 表示「无关键字 / 认不出」。 */
public String keyword() {
return keyword;
}
/** 对应的底层状态。 */
public OutboundStatus toCore() {
return core;
}
/**
* 运去哪原始值 → 平台枚举。
*
* <p>空值或匹配不到返回 {@link #UNKNOWN}。按声明顺序匹配,越具体的放越前。</p>
*/
public static YqnOutboundStatus of(String rawStatus) {
if (rawStatus == null) {
return UNKNOWN;
}
String s = rawStatus.trim().toUpperCase();
if (s.isEmpty()) {
return UNKNOWN;
}
for (YqnOutboundStatus v : values()) {
if (v.keyword != null && s.contains(v.keyword)) {
return v;
}
}
return UNKNOWN;
}
/** 运去哪原始值 → 底层状态。 */
public static OutboundStatus toCore(String rawStatus) {
return of(rawStatus).toCore();
}
}

67
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java

@ -0,0 +1,67 @@ @@ -0,0 +1,67 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
/**
* 运去哪「退货预约处理方式」(API 81 的 {@code returnDealMethod})。
*
* <p>码表:0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认。</p>
*
* <p><b>与 {@link YqnReturnProcessDisposition} 不是一回事</b>:那个是仓收货检验后
* 逐条明细行的决定(0/2/3/4),两套码值不能互换。</p>
*/
public enum YqnReturnDealMethod {
/** 0 客户自提。 */
CUSTOMER_PICKUP(0, ReturnDealMethod.CUSTOMER_PICKUP),
/** 1 拍照确认后由客户决定。 */
PHOTO_CONFIRM(1, ReturnDealMethod.PHOTO_CONFIRM),
/** 2 销毁。 */
DESTROY(2, ReturnDealMethod.DESTROY),
/** 5 仓库确认处理。 */
WAREHOUSE_CONFIRM(5, ReturnDealMethod.WAREHOUSE_CONFIRM);
private final Integer rawCode;
private final ReturnDealMethod core;
YqnReturnDealMethod(Integer rawCode, ReturnDealMethod core) {
this.rawCode = rawCode;
this.core = core;
}
/** 运去哪码值。 */
public Integer rawCode() {
return rawCode;
}
/** 对应的底层处理方式。 */
public ReturnDealMethod toCore() {
return core;
}
/** 底层处理方式 → 运去哪码值;null 透传。 */
public static Integer codeOf(ReturnDealMethod method) {
if (method == null) {
return null;
}
for (YqnReturnDealMethod v : values()) {
if (v.core == method) {
return v.rawCode;
}
}
throw new IllegalArgumentException("yqn does not support returnDealMethod: " + method);
}
/** 运去哪码值 → 底层处理方式;未知返回 null。 */
public static ReturnDealMethod toCore(Integer rawCode) {
if (rawCode == null) {
return null;
}
for (YqnReturnDealMethod v : values()) {
if (rawCode.equals(v.rawCode)) {
return v.core;
}
}
return null;
}
}

67
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java

@ -0,0 +1,67 @@ @@ -0,0 +1,67 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
/**
* 运去哪「退货检验后处理方式」(API 77 的 {@code goodsReturnType})。
*
* <p>码表:0 客户自提 / 2 销毁 / 3 上架(良品)/ 4 换标上架(良品)。</p>
*
* <p><b>与 {@link YqnReturnDealMethod} 不是一回事</b>:那个是预约时的预报(0/1/2/5),
* 两套码值不能互换。</p>
*/
public enum YqnReturnProcessDisposition {
/** 0 客户自提。 */
CUSTOMER_PICKUP(0, ReturnProcessDisposition.CUSTOMER_PICKUP),
/** 2 销毁。 */
DESTROY(2, ReturnProcessDisposition.DESTROY),
/** 3 上架(良品)。 */
RESTOCK(3, ReturnProcessDisposition.RESTOCK),
/** 4 换标上架(良品)。 */
RESTOCK_RELABEL(4, ReturnProcessDisposition.RESTOCK_RELABEL);
private final Integer rawCode;
private final ReturnProcessDisposition core;
YqnReturnProcessDisposition(Integer rawCode, ReturnProcessDisposition core) {
this.rawCode = rawCode;
this.core = core;
}
/** 运去哪码值。 */
public Integer rawCode() {
return rawCode;
}
/** 对应的底层处理方式。 */
public ReturnProcessDisposition toCore() {
return core;
}
/** 底层处理方式 → 运去哪码值;null 透传。 */
public static Integer codeOf(ReturnProcessDisposition disposition) {
if (disposition == null) {
return null;
}
for (YqnReturnProcessDisposition v : values()) {
if (v.core == disposition) {
return v.rawCode;
}
}
throw new IllegalArgumentException("yqn does not support disposition: " + disposition);
}
/** 运去哪码值 → 底层处理方式;未知返回 null。 */
public static ReturnProcessDisposition toCore(Integer rawCode) {
if (rawCode == null) {
return null;
}
for (YqnReturnProcessDisposition v : values()) {
if (rawCode.equals(v.rawCode)) {
return v.core;
}
}
return null;
}
}

82
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java

@ -0,0 +1,82 @@ @@ -0,0 +1,82 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.TransferStatus;
/**
* 运去哪调拨单状态(API 139 的 {@code transferOutboundPlanStatus})。
*
* <p>码表来自接口文档,1:1 对应;未知码归 {@link #UNKNOWN},不猜。</p>
*/
public enum YqnTransferStatus {
/** 0 草稿。 */
DRAFT(0, TransferStatus.DRAFT),
/** 3 已驳回。 */
REJECTED(3, TransferStatus.REJECTED),
/** 5 待审核。 */
PENDING_REVIEW(5, TransferStatus.PENDING_REVIEW),
/** 6 审核中。 */
REVIEWING(6, TransferStatus.REVIEWING),
/** 7 审核通过。 */
APPROVED(7, TransferStatus.APPROVED),
/** 8 待确认。 */
PENDING_CONFIRM(8, TransferStatus.PENDING_CONFIRM),
/** 9 待备货。 */
PENDING_PICKING(9, TransferStatus.PENDING_PICKING),
/** 10 待出库。 */
PENDING_OUTBOUND(10, TransferStatus.PENDING_OUTBOUND),
/** 15 出库中。 */
OUTBOUNDING(15, TransferStatus.OUTBOUNDING),
/** 20 待入库。 */
PENDING_INBOUND(20, TransferStatus.PENDING_INBOUND),
/** 25 入库中。 */
INBOUNDING(25, TransferStatus.INBOUNDING),
/** 70 已完成。 */
COMPLETED(70, TransferStatus.COMPLETED),
/** 90 已关闭。 */
CLOSED(90, TransferStatus.CLOSED),
/** 100 取消中。 */
CANCELLING(100, TransferStatus.CANCELLING),
/** 110 已取消。 */
CANCELLED(110, TransferStatus.CANCELLED),
/** 120 取消异常。 */
CANCEL_EXCEPTION(120, TransferStatus.CANCEL_EXCEPTION),
/** 无法识别。 */
UNKNOWN(null, TransferStatus.UNKNOWN);
private final Integer rawCode;
private final TransferStatus core;
YqnTransferStatus(Integer rawCode, TransferStatus core) {
this.rawCode = rawCode;
this.core = core;
}
/** 运去哪的状态码;null 表示无法识别。 */
public Integer rawCode() {
return rawCode;
}
/** 对应的底层状态。 */
public TransferStatus toCore() {
return core;
}
/** 运去哪状态码 → 平台枚举。 */
public static YqnTransferStatus of(Integer rawStatus) {
if (rawStatus == null) {
return UNKNOWN;
}
for (YqnTransferStatus v : values()) {
if (rawStatus.equals(v.rawCode)) {
return v;
}
}
return UNKNOWN;
}
/** 运去哪状态码 → 底层状态。 */
public static TransferStatus toCore(Integer rawStatus) {
return of(rawStatus).toCore();
}
}

64
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java

@ -0,0 +1,64 @@ @@ -0,0 +1,64 @@
package common.ecommerce.yqn.enums;
import common.ecommerce.warehouse.enums.TransferType;
/**
* 运去哪调拨类型(API 139 的 {@code type})。
*
* <p>码表来自接口文档:0 亚马逊移出 / 1 亚马逊移入 / 2 仓-仓调拨 / 3 调拨出库。</p>
*/
public enum YqnTransferType {
/** 0 亚马逊移出。 */
AMAZON_REMOVAL(0, TransferType.AMAZON_REMOVAL),
/** 1 亚马逊移入。 */
AMAZON_INBOUND(1, TransferType.AMAZON_INBOUND),
/** 2 仓到仓调拨。 */
WAREHOUSE_TO_WAREHOUSE(2, TransferType.WAREHOUSE_TO_WAREHOUSE),
/** 3 调拨出库。 */
OUTBOUND(3, TransferType.OUTBOUND);
private final Integer rawCode;
private final TransferType core;
YqnTransferType(Integer rawCode, TransferType core) {
this.rawCode = rawCode;
this.core = core;
}
/** 运去哪的类型码。 */
public Integer rawCode() {
return rawCode;
}
/** 对应的底层类型。 */
public TransferType toCore() {
return core;
}
/** 底层类型 → 运去哪类型码;null 透传。 */
public static Integer codeOf(TransferType type) {
if (type == null) {
return null;
}
for (YqnTransferType v : values()) {
if (v.core == type) {
return v.rawCode;
}
}
throw new IllegalArgumentException("yqn does not support transfer type: " + type);
}
/** 运去哪类型码 → 底层类型;未知码返回 null(与原有行为一致)。 */
public static TransferType toCore(Integer rawCode) {
if (rawCode == null) {
return null;
}
for (YqnTransferType v : values()) {
if (rawCode.equals(v.rawCode)) {
return v.core;
}
}
return null;
}
}

29
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java

@ -5,14 +5,15 @@ import common.ecommerce.http.JacksonJsonCodec; @@ -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 { @@ -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));
}
}

4
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java

@ -5,8 +5,8 @@ import common.ecommerce.shared.spi.ChannelSecret; @@ -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;

Loading…
Cancel
Save