Compare commits

...

5 Commits

Author SHA1 Message Date
chenchuchuan 86b05dc79d Merge remote-tracking branch 'common-ecommerce/feature/supplier-lingxing' into feature/supplier-lingxing 2 weeks ago
chenchuchuan d2d2f04a45 feat(yqn): 按 API 189 对接运单物流轨迹 2 weeks ago
chenchuchuan 3338a185e9 Merge remote-tracking branch 'common-ecommerce/feature/supplier-lingxing' into feature/supplier-lingxing 2 weeks ago
chenchuchuan 06961c6781 feat(yqn): 按 API 121 对接订单测算(运费试算) 2 weeks ago
chenchuchuan a8dfb08e69 refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 2 weeks ago
  1. 33
      README.md
  2. 9
      sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java
  3. 49
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseCapability.java
  4. 21
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/WarehouseProvider.java
  5. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/InventoryCapable.java
  6. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/OutboundCapable.java
  7. 18
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java
  8. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TransferCapable.java
  9. 29
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java
  10. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
  11. 8
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseReturnCapable.java
  12. 34
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/CancelEligibility.java
  13. 67
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InboundStatus.java
  14. 31
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/InventorySyncStrategy.java
  15. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/LabelMode.java
  16. 81
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/OutboundStatus.java
  17. 37
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnDealMethod.java
  18. 43
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/ReturnProcessDisposition.java
  19. 60
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferStatus.java
  20. 35
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/TransferType.java
  21. 65
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseCapability.java
  22. 35
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseFeeType.java
  23. 39
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/enums/WarehouseProvider.java
  24. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/error/WarehouseUnsupportedCapabilityException.java
  25. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/BillingDocument.java
  26. 17
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelEligibility.java
  27. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/CancelResult.java
  28. 244
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java
  29. 190
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java
  30. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeQuery.java
  31. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
  32. 32
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundStatus.java
  33. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InventorySyncStrategy.java
  34. 16
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/LabelMode.java
  35. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundCommand.java
  36. 5
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
  37. 46
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundStatus.java
  38. 39
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnCommand.java
  39. 40
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/ReturnProcessCommand.java
  40. 156
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java
  41. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferCommand.java
  42. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
  43. 29
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferStatus.java
  44. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferType.java
  45. 19
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseFeeType.java
  46. 38
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/WarehouseReturn.java
  47. 4
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapter.java
  48. 2
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseAdapterFactory.java
  49. 34
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseConnection.java
  50. 7
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseContext.java
  51. 46
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOperations.java
  52. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseOutbounds.java
  53. 6
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/sdk/WarehouseSdk.java
  54. 12
      warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/spi/WarehouseSink.java
  55. 8
      warehouse-sdk-testkit/src/main/java/common/ecommerce/warehouse/testkit/FakeWarehouseAdapter.java
  56. 8
      warehouse-sdk-testkit/src/test/java/common/ecommerce/warehouse/sdk/WarehouseSdkTest.java
  57. 6
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapter.java
  58. 2
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangAdapterFactory.java
  59. 2
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangOrderMapper.java
  60. 6
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
  61. 2
      warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangUnsupportedOutbound.java
  62. 4
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangAdapterTest.java
  63. 6
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java
  64. 4
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangProductTest.java
  65. 8
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java
  66. 2
      warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/probe/XincangLoginProbeTest.java
  67. 23
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java
  68. 117
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapter.java
  69. 4
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnAdapterFactory.java
  70. 128
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java
  71. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeMapper.java
  72. 38
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
  73. 41
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnOutboundMapper.java
  74. 3
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
  75. 8
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnReturnMapper.java
  76. 143
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java
  77. 91
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
  78. 141
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/dto/YqnDtos.java
  79. 73
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnInboundStatus.java
  80. 76
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java
  81. 83
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnOutboundStatus.java
  82. 67
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnDealMethod.java
  83. 67
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnReturnProcessDisposition.java
  84. 82
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferStatus.java
  85. 64
      warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnTransferType.java
  86. 29
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnAdapterTest.java
  87. 186
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java
  88. 4
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnProductTest.java
  89. 178
      warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java

33
README.md

@ -295,23 +295,32 @@ common.ecommerce
aeph/ · bestbuy/ · custom/ · echo/ · losdlius/ · michaels/ · mirakl/ · wayfair/ aeph/ · bestbuy/ · custom/ · echo/ · losdlius/ · michaels/ · mirakl/ · wayfair/
│ │
├── warehouse 仓库域(warehouse-sdk-core) ├── warehouse 仓库域(warehouse-sdk-core)
│ ├── WarehouseProvider / WarehouseCapability │ ├── enums (底层枚举,带 SDK 自编 code + 中文名)
│ ├── model OutboundStatus / LabelMode / CancelEligibility / ShipTo / │ │ WarehouseProvider / WarehouseCapability / OutboundStatus /
│ │ OutboundOrder / OutboundCommand / OutboundLine / OutboundQuery / │ │ InboundStatus / TransferStatus / TransferType / LabelMode /
│ │ OutboundRef / OutboundReceipt / PackageResult / WarehouseLabel / │ │ CancelEligibility / InventorySyncStrategy / WarehouseFeeType /
│ │ CancelCommand / CancelResult / InventorySnapshot / InventoryQuery / │ │ ReturnDealMethod / ReturnProcessDisposition
│ │ InventorySyncStrategy / InboundOrder / InboundCommand / InboundLine / │ ├── model ShipTo / OutboundOrder / OutboundCommand / OutboundLine /
│ │ InboundReceipt / WarehouseReturn / BillingDocument / TrackEvent / │ │ OutboundQuery / OutboundRef / OutboundReceipt / OutboundPackageSpec /
│ │ DestructionOrder │ │ PackageResult / WarehouseLabel / CancelCommand / CancelResult /
│ ├── capability WarehouseAdapter(在 sdk 包) / OutboundCapable / InventoryCapable / │ │ InventorySnapshot / InventoryQuery / InboundOrder / InboundOrderLine /
│ │ InboundCapable / WarehouseReturnCapable / WarehouseFeeCapable / │ │ InboundCommand / InboundLine / InboundCarton / InboundBatch /
│ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable │ │ InboundReceipt / ReturnCommand / ReturnProcessCommand /
│ │ WarehouseReturn / TransferCommand / TransferOrder /
│ │ BillingDocument / FeeQuery / FeeEstimateQuery / FeeEstimateResult /
│ │ TrackEvent / TrackingInfo / DestructionOrder
│ ├── capability OutboundCapable / InventoryCapable / InboundCapable /
│ │ WarehouseReturnCapable / WarehouseFeeCapable /
│ │ WarehouseFeeEstimateCapable / TransferCapable /
│ │ TrackingCapable / DestructionCapable / WarehouseWebhookCapable /
│ │ WarehouseProduct / WarehouseProductCapable
│ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired / │ ├── error WarehouseException 及 Unsupported / CancelBlocked / CancelChargeRequired /
│ │ DuplicateOrder / WebhookVerification │ │ DuplicateOrder / WebhookVerification
│ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore / │ ├── spi WarehouseRepository / WarehouseSink / WarehouseWebhookDedupStore /
│ │ UnmatchedCallbackStore │ │ UnmatchedCallbackStore
│ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds / │ └── sdk WarehouseSdk / WarehouseOperations / WarehouseOutbounds /
│ WarehouseContext / WarehouseConnection / WarehouseWriteScope │ WarehouseAdapter / WarehouseAdapterFactory / WarehouseContext /
│ WarehouseConnection(主基址 + 可选辅助基址)/ WarehouseWriteScope
│ │
├── yqn 运去哪三方仓(warehouse-sdk-yqn) ├── yqn 运去哪三方仓(warehouse-sdk-yqn)
│ ├── YqnConstants 端点、路径、固定 token 请求头名、限流 │ ├── YqnConstants 端点、路径、固定 token 请求头名、限流

9
sdk-common/src/main/java/common/ecommerce/http/JacksonJsonCodec.java

@ -71,6 +71,15 @@ public final class JacksonJsonCodec implements JsonCodec {
} }
} }
/** 按点路径取整数值;节点缺失、非数字或为 null 时返回哨兵 {@code missing}。 */
public int intAt(String json, String pointer, int missing) {
JsonNode node = nodeAt(json, pointer);
if (node == null || node.isNull() || !node.canConvertToInt()) {
return missing;
}
return node.asInt();
}
/** 把点路径下的数组节点反序列化为列表。 */ /** 把点路径下的数组节点反序列化为列表。 */
public <T> List<T> listAt(String json, String pointer, Class<T> type) { public <T> List<T> listAt(String json, String pointer, Class<T> type) {
JsonNode node = nodeAt(json, pointer); JsonNode node = nodeAt(json, pointer);

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

@ -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 @@
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;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot; 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.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -24,6 +24,6 @@ public interface InventoryCapable extends WarehouseAdapter {
/** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */ /** 其他出入库 / 调拨;信仓无此能力,会抛 {@code WarehouseUnsupportedCapabilityException}。 */
default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) { default InventorySnapshot adjust(WarehouseContext ctx, InventoryQuery query) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( 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;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.model.CancelCommand; 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.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;

18
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/TrackingCapable.java

@ -1,6 +1,7 @@
package common.ecommerce.warehouse.capability; package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.model.TrackEvent; import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -9,6 +10,21 @@ import java.util.List;
/** 物流轨迹能力。信仓无此接口,整体不实现。 */ /** 物流轨迹能力。信仓无此接口,整体不实现。 */
public interface TrackingCapable extends WarehouseAdapter { public interface TrackingCapable extends WarehouseAdapter {
/** 按跟踪号查轨迹。 */ /**
* 按跟踪号查轨迹节点。
*
* @return 节点列表;仓方无轨迹时为空列表(不是错误——运单可能刚生成还没揽收)
*/
List<TrackEvent> track(WarehouseContext ctx, String trackingNumber); List<TrackEvent> track(WarehouseContext ctx, String trackingNumber);
/**
* 按跟踪号查运单级轨迹:除节点外还带最新状态、承运商、签收人与预计妥投。
*
* <p>与 {@link #track} 的关系:本方法返回 {@link TrackingInfo},其中的
* {@code events()} 就是 {@code track} 的返回内容。宿主做 C 端可视化或异常预警时用这个,
* 只需要节点明细时用 {@code track}。</p>
*
* <p>状态值保持仓方原值,不做跨仓归一。</p>
*/
TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber);
} }

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

@ -34,6 +34,6 @@ public interface TransferCapable extends WarehouseAdapter {
*/ */
default void approve(WarehouseContext ctx, String transferRequestNo) { default void approve(WarehouseContext ctx, String transferRequestNo) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException(
common.ecommerce.warehouse.WarehouseCapability.TRANSFER); common.ecommerce.warehouse.enums.WarehouseCapability.TRANSFER);
} }
} }

29
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseFeeEstimateCapable.java

@ -0,0 +1,29 @@
package common.ecommerce.warehouse.capability;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import java.util.List;
/**
* 运费试算能力:发货前按包裹 + 地址 + 渠道询价。
*
* <p><b>与 {@link WarehouseFeeCapable} 不是一回事</b>:那个查已发生的结算明细,
* 这个在发货前给报价。报价仅供参考,实际费用以结算账单为准。</p>
*
* <p>按仓库维度返回:一个仓下可能有多个可选渠道。只读操作,无幂等要求。</p>
*/
public interface WarehouseFeeEstimateCapable extends WarehouseAdapter {
/**
* 试算运费。
*
* @param query 包裹尺寸重量、收件地址与物流渠道;必填项在构造期已校验
* @return 每个发货仓一条结果;仓方无可承运渠道时该仓的 {@code carriers()} 为空
* @throws common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException
* 该仓不声明 {@code FEE_ESTIMATE}
*/
List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query);
}

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

@ -1,6 +1,7 @@
package common.ecommerce.warehouse.capability; package common.ecommerce.warehouse.capability;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import java.util.Objects; import java.util.Objects;
@ -37,8 +38,8 @@ public final class WarehouseProduct {
private final int requireSn; private final int requireSn;
/** 外包装样式:0 裸包装 / 1 销售包装 / 2 物流包装;-1 表示不传。 */ /** 外包装样式:0 裸包装 / 1 销售包装 / 2 物流包装;-1 表示不传。 */
private final int packageStyle; private final int packageStyle;
/** 客退处理方式:0 客户自提 / 1 拍照确认 / 2 销毁 / 5 仓库确认;-1 表示不传。 */ /** 客退处理方式;null 表示不传。仓方码值由适配器映射。 */
private final int returnDealMethod; private final ReturnDealMethod returnDealMethod;
private final Money declaredValue; private final Money declaredValue;
private final String hsCode; private final String hsCode;
private final String countryOfOrigin; private final String countryOfOrigin;
@ -178,7 +179,8 @@ public final class WarehouseProduct {
return packageStyle; return packageStyle;
} }
public int returnDealMethod() { /** 客退处理方式;null 表示不传。 */
public ReturnDealMethod returnDealMethod() {
return returnDealMethod; return returnDealMethod;
} }
@ -259,7 +261,7 @@ public final class WarehouseProduct {
private double itemHeightCm; private double itemHeightCm;
private int requireSn; private int requireSn;
private int packageStyle = -1; private int packageStyle = -1;
private int returnDealMethod = -1; private ReturnDealMethod returnDealMethod;
private Money declaredValue; private Money declaredValue;
private String hsCode; private String hsCode;
private String countryOfOrigin; private String countryOfOrigin;
@ -361,7 +363,7 @@ public final class WarehouseProduct {
return this; return this;
} }
public Builder returnDealMethod(int v) { public Builder returnDealMethod(ReturnDealMethod v) {
this.returnDealMethod = v; this.returnDealMethod = v;
return this; return this;
} }

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

@ -1,6 +1,8 @@
package common.ecommerce.warehouse.capability; package common.ecommerce.warehouse.capability;
import common.ecommerce.shared.support.Page; 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.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.WarehouseReturn;
@ -12,8 +14,8 @@ import common.ecommerce.warehouse.sdk.WarehouseContext;
* *
* <p>退货链路有两个不同的「处理方式」,别混:</p> * <p>退货链路有两个不同的「处理方式」,别混:</p>
* <ul> * <ul>
* <li>{@link ReturnCommand.DealMethod} —— 创建退货预约时的预报</li> * <li>{@link ReturnDealMethod} —— 创建退货预约时的预报</li>
* <li>{@link ReturnProcessCommand.Disposition} —— 仓收货检验后按明细行最终决定</li> * <li>{@link ReturnProcessDisposition} —— 仓收货检验后按明细行最终决定</li>
* </ul> * </ul>
*/ */
public interface WarehouseReturnCapable extends WarehouseAdapter { public interface WarehouseReturnCapable extends WarehouseAdapter {
@ -45,6 +47,6 @@ public interface WarehouseReturnCapable extends WarehouseAdapter {
/** 取消退货单;仅部分仓支持。 */ /** 取消退货单;仅部分仓支持。 */
default void cancel(WarehouseContext ctx, String returnRequestNo) { default void cancel(WarehouseContext ctx, String returnRequestNo) {
throw new common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException( 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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
package common.ecommerce.warehouse.error; 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 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.WarehouseFeeType;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
import java.time.Instant; import java.time.Instant;
@ -13,6 +16,8 @@ import java.time.Instant;
public final class BillingDocument { public final class BillingDocument {
private final String warehouseCode; private final String warehouseCode;
/** 该单据来自哪家仓;解释原始字段与选择平台枚举时使用。 */
private final WarehouseProvider sourceProvider;
private final String documentNo; private final String documentNo;
/** 仓方费用名称原值,如「尾程运费」「仓储费」。 */ /** 仓方费用名称原值,如「尾程运费」「仓储费」。 */
private final String feeName; private final String feeName;
@ -30,6 +35,7 @@ public final class BillingDocument {
private BillingDocument(Builder b) { private BillingDocument(Builder b) {
this.warehouseCode = require(b.warehouseCode, "warehouseCode"); this.warehouseCode = require(b.warehouseCode, "warehouseCode");
this.sourceProvider = b.sourceProvider;
this.documentNo = b.documentNo; this.documentNo = b.documentNo;
this.feeName = b.feeName; this.feeName = b.feeName;
this.feeType = b.feeType; this.feeType = b.feeType;
@ -48,6 +54,11 @@ public final class BillingDocument {
return warehouseCode; return warehouseCode;
} }
/** 该单据来自哪家仓。 */
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
public String documentNo() { public String documentNo() {
return documentNo; return documentNo;
} }
@ -95,6 +106,7 @@ public final class BillingDocument {
public static final class Builder { public static final class Builder {
private String warehouseCode; private String warehouseCode;
private WarehouseProvider sourceProvider;
private String documentNo; private String documentNo;
private String feeName; private String feeName;
private WarehouseFeeType feeType; private WarehouseFeeType feeType;
@ -109,6 +121,11 @@ public final class BillingDocument {
return this; return this;
} }
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public Builder documentNo(String v) { public Builder documentNo(String v) {
this.documentNo = v; this.documentNo = v;
return this; return this;

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

@ -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 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
/** /**

244
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateQuery.java

@ -0,0 +1,244 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.shared.support.Money;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 运费试算条件(下单前的费用预估,<b>不是</b>已发生的账单)。
*
* <p>与 {@link FeeQuery} 是两条不同的路径:{@code FeeQuery} 查已经产生的结算明细,
* 本类用于<b>发货前</b>按包裹尺寸重量 + 收件地址 + 物流渠道询价。</p>
*
* <p>单位写进字段名(cm / g),由适配器换算成仓方要求的单位,避免调用方按仓猜单位。</p>
*
* <p>结果是「参考价」:实际费用以出库结算账单为准。</p>
*/
public final class FeeEstimateQuery {
/** 发货仓 code;空表示用账户配置的仓。 */
private final List<String> warehouseCodes;
private final BigDecimal lengthCm;
private final BigDecimal widthCm;
private final BigDecimal heightCm;
private final BigDecimal weightGrams;
/** 保价货值;null 表示不保价。币种口径由仓方账户决定。 */
private final Money insuredValue;
private final String receiveCountry;
private final String receiveState;
private final String receiveCity;
private final String receivePostal;
private final String receiveAddress;
/** 是否住宅地址;null 表示不传(仓方按默认口径)。 */
private final Boolean residential;
/** 物流产品服务码,如 {@code FedEx_FEDEX_GROUND}。取值由各仓定义,适配器不做跨仓归一。 */
private final String logisticsServiceCode;
private final String logisticsProductCode;
/** 签名服务,如 {@code SIGNATURE}。 */
private final String signService;
private FeeEstimateQuery(Builder b) {
this.warehouseCodes = Collections.unmodifiableList(new ArrayList<String>(b.warehouseCodes));
this.lengthCm = requirePositive(b.lengthCm, "lengthCm");
this.widthCm = requirePositive(b.widthCm, "widthCm");
this.heightCm = requirePositive(b.heightCm, "heightCm");
this.weightGrams = requirePositive(b.weightGrams, "weightGrams");
this.insuredValue = b.insuredValue;
this.receiveCountry = require(b.receiveCountry, "receiveCountry");
this.receiveState = b.receiveState;
this.receiveCity = b.receiveCity;
this.receivePostal = require(b.receivePostal, "receivePostal");
this.receiveAddress = b.receiveAddress;
this.residential = b.residential;
this.logisticsServiceCode = require(b.logisticsServiceCode, "logisticsServiceCode");
this.logisticsProductCode = b.logisticsProductCode;
this.signService = b.signService;
}
public static Builder builder() {
return new Builder();
}
/** 发货仓 code 列表;空表示用账户配置的仓。 */
public List<String> warehouseCodes() {
return warehouseCodes;
}
public BigDecimal lengthCm() {
return lengthCm;
}
public BigDecimal widthCm() {
return widthCm;
}
public BigDecimal heightCm() {
return heightCm;
}
public BigDecimal weightGrams() {
return weightGrams;
}
/** 保价货值;null 表示不保价。 */
public Money insuredValue() {
return insuredValue;
}
/** ISO 3166-1 alpha-2,如 US。 */
public String receiveCountry() {
return receiveCountry;
}
public String receiveState() {
return receiveState;
}
public String receiveCity() {
return receiveCity;
}
public String receivePostal() {
return receivePostal;
}
public String receiveAddress() {
return receiveAddress;
}
/** 是否住宅地址;null 表示不传。 */
public Boolean residential() {
return residential;
}
/** 物流产品服务码;取值由仓定义。 */
public String logisticsServiceCode() {
return logisticsServiceCode;
}
public String logisticsProductCode() {
return logisticsProductCode;
}
/** 签名服务码。 */
public String signService() {
return signService;
}
private static BigDecimal requirePositive(BigDecimal v, String name) {
if (v == null || v.signum() <= 0) {
throw new IllegalArgumentException(name + " must be positive");
}
return v;
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
public static final class Builder {
private final List<String> warehouseCodes = new ArrayList<String>();
private BigDecimal lengthCm;
private BigDecimal widthCm;
private BigDecimal heightCm;
private BigDecimal weightGrams;
private Money insuredValue;
private String receiveCountry;
private String receiveState;
private String receiveCity;
private String receivePostal;
private String receiveAddress;
private Boolean residential;
private String logisticsServiceCode;
private String logisticsProductCode;
private String signService;
public Builder warehouseCode(String v) {
if (v != null && !v.trim().isEmpty()) {
this.warehouseCodes.add(v.trim());
}
return this;
}
public Builder lengthCm(BigDecimal v) {
this.lengthCm = v;
return this;
}
public Builder widthCm(BigDecimal v) {
this.widthCm = v;
return this;
}
public Builder heightCm(BigDecimal v) {
this.heightCm = v;
return this;
}
public Builder weightGrams(BigDecimal v) {
this.weightGrams = v;
return this;
}
public Builder insuredValue(Money v) {
this.insuredValue = v;
return this;
}
public Builder receiveCountry(String v) {
this.receiveCountry = v;
return this;
}
public Builder receiveState(String v) {
this.receiveState = v;
return this;
}
public Builder receiveCity(String v) {
this.receiveCity = v;
return this;
}
public Builder receivePostal(String v) {
this.receivePostal = v;
return this;
}
public Builder receiveAddress(String v) {
this.receiveAddress = v;
return this;
}
public Builder residential(Boolean v) {
this.residential = v;
return this;
}
public Builder logisticsServiceCode(String v) {
this.logisticsServiceCode = v;
return this;
}
public Builder logisticsProductCode(String v) {
this.logisticsProductCode = v;
return this;
}
public Builder signService(String v) {
this.signService = v;
return this;
}
public FeeEstimateQuery build() {
return new FeeEstimateQuery(this);
}
}
}

190
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/FeeEstimateResult.java

@ -0,0 +1,190 @@
package common.ecommerce.warehouse.model;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 单个发货仓的运费试算结果。
*
* <p>一个仓下可能有多个可选渠道(承运商 + 物流服务),每个渠道一笔总价与若干细分成本。
* 这是<b>报价</b>,不是账单:实际费用以出库结算为准,用 {@link BillingDocument} 承载。</p>
*/
public final class FeeEstimateResult {
private final WarehouseProvider sourceProvider;
private final String shipOrgWarehouseCode;
private final List<CarrierQuote> carriers;
private FeeEstimateResult(Builder b) {
this.sourceProvider = b.sourceProvider;
this.shipOrgWarehouseCode = require(b.shipOrgWarehouseCode, "shipOrgWarehouseCode");
this.carriers = Collections.unmodifiableList(new ArrayList<CarrierQuote>(b.carriers));
}
public static Builder builder() {
return new Builder();
}
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
/** 发货仓 code(仓方口径)。 */
public String shipOrgWarehouseCode() {
return shipOrgWarehouseCode;
}
/** 可选渠道报价;可能为空,表示该仓无法承运该包裹。 */
public List<CarrierQuote> carriers() {
return carriers;
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
/** 一个渠道的报价。 */
public static final class CarrierQuote {
/** 承运商,如 {@code FEDEX}。 */
private final String carrier;
/** 物流服务码,与查询时的 {@code logisticsServiceCode} 同一套取值。 */
private final String logisticsServiceCode;
/** 总价;仓方未给时为 null。 */
private final Money totalRate;
private final List<CostItem> costItems;
private CarrierQuote(Builder b) {
this.carrier = b.carrier;
this.logisticsServiceCode = b.logisticsServiceCode;
this.totalRate = b.totalRate;
this.costItems = Collections.unmodifiableList(new ArrayList<CostItem>(b.costItems));
}
public static Builder builder() {
return new Builder();
}
public String carrier() {
return carrier;
}
public String logisticsServiceCode() {
return logisticsServiceCode;
}
public Money totalRate() {
return totalRate;
}
public List<CostItem> costItems() {
return costItems;
}
/** 细分成本项,如「尾程运费」「燃油附加费」。 */
public static final class CostItem {
private final String costName;
private final Money estimatedCost;
private CostItem(Builder b) {
this.costName = b.costName;
this.estimatedCost = b.estimatedCost;
}
public static Builder builder() {
return new Builder();
}
public String costName() {
return costName;
}
public Money estimatedCost() {
return estimatedCost;
}
public static final class Builder {
private String costName;
private Money estimatedCost;
public Builder costName(String v) {
this.costName = v;
return this;
}
public Builder estimatedCost(Money v) {
this.estimatedCost = v;
return this;
}
public CostItem build() {
return new CostItem(this);
}
}
}
public static final class Builder {
private String carrier;
private String logisticsServiceCode;
private Money totalRate;
private final List<CostItem> costItems = new ArrayList<CostItem>();
public Builder carrier(String v) {
this.carrier = v;
return this;
}
public Builder logisticsServiceCode(String v) {
this.logisticsServiceCode = v;
return this;
}
public Builder totalRate(Money v) {
this.totalRate = v;
return this;
}
public Builder costItem(CostItem v) {
this.costItems.add(v);
return this;
}
public CarrierQuote build() {
return new CarrierQuote(this);
}
}
}
public static final class Builder {
private WarehouseProvider sourceProvider;
private String shipOrgWarehouseCode;
private final List<CarrierQuote> carriers = new ArrayList<CarrierQuote>();
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public Builder shipOrgWarehouseCode(String v) {
this.shipOrgWarehouseCode = v;
return this;
}
public Builder carrier(CarrierQuote v) {
this.carriers.add(v);
return this;
}
public FeeEstimateResult build() {
return new FeeEstimateResult(this);
}
}
}

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

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

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

@ -1,5 +1,8 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.InboundStatus;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.time.Instant; import java.time.Instant;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Collections; import java.util.Collections;
@ -20,8 +23,10 @@ public final class InboundOrder {
private final String warehouseCode; private final String warehouseCode;
/** 单据状态,已归一化。 */ /** 单据状态,已归一化。 */
private final InboundStatus status; private final InboundStatus status;
/** 仓方状态原值,保留便于排查。 */ /** 仓方状态原值,保留便于排查;必须与 {@link #sourceProvider()} 一起落库才有意义。 */
private final String rawStatus; private final String rawStatus;
/** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */
private final WarehouseProvider sourceProvider;
/** 库存类型:0 可售 / 1 不可售。 */ /** 库存类型:0 可售 / 1 不可售。 */
private final int inventoryType; private final int inventoryType;
private final int boxCount; private final int boxCount;
@ -48,6 +53,7 @@ public final class InboundOrder {
this.warehouseCode = require(b.warehouseCode, "warehouseCode"); this.warehouseCode = require(b.warehouseCode, "warehouseCode");
this.status = b.status == null ? InboundStatus.UNKNOWN : b.status; this.status = b.status == null ? InboundStatus.UNKNOWN : b.status;
this.rawStatus = b.rawStatus; this.rawStatus = b.rawStatus;
this.sourceProvider = b.sourceProvider;
this.inventoryType = b.inventoryType; this.inventoryType = b.inventoryType;
this.boxCount = b.boxCount; this.boxCount = b.boxCount;
this.createdAt = b.createdAt; this.createdAt = b.createdAt;
@ -153,6 +159,11 @@ public final class InboundOrder {
return status == InboundStatus.COMPLETED; return status == InboundStatus.COMPLETED;
} }
/** 该单据来自哪家仓。 */
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
private static String require(String v, String n) { private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) { if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank"); throw new IllegalArgumentException(n + " must not be blank");
@ -166,6 +177,7 @@ public final class InboundOrder {
private String warehouseCode; private String warehouseCode;
private InboundStatus status; private InboundStatus status;
private String rawStatus; private String rawStatus;
private WarehouseProvider sourceProvider;
private int inventoryType; private int inventoryType;
private int boxCount; private int boxCount;
private Instant createdAt; private Instant createdAt;
@ -206,6 +218,11 @@ public final class InboundOrder {
return this; return this;
} }
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public Builder inventoryType(int v) { public Builder inventoryType(int v) {
this.inventoryType = v; this.inventoryType = v;
return this; return this;

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

@ -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 @@
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 @@
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 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.model.Platform;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;

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

@ -1,7 +1,10 @@
package common.ecommerce.warehouse.model; 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.shared.support.Money;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.time.Instant; import java.time.Instant;
import java.util.ArrayList; import java.util.ArrayList;

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

@ -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 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnDealMethod;
import java.time.LocalDate; import java.time.LocalDate;
import java.util.ArrayList; import java.util.ArrayList;
import java.util.Collections; import java.util.Collections;
@ -8,8 +10,8 @@ import java.util.List;
/** /**
* 退货计划创建命令。<b>写操作</b>,幂等键是 {@link #returnRequestNo()}(仓方的 {@code orderNo})。 * 退货计划创建命令。<b>写操作</b>,幂等键是 {@link #returnRequestNo()}(仓方的 {@code orderNo})。
* *
* <p>运去哪必填:仓、来源单号、关联销售单号、退货运单号、承运商、至少一条商品行; * <p>各仓必填项不同:适配器只校验自己协议要求的字段,core 只保证幂等键与
* 每条商品行还必须给处理方式。</p> * 至少一条商品行。</p>
*/ */
public final class ReturnCommand { public final class ReturnCommand {
@ -96,16 +98,16 @@ public final class ReturnCommand {
* 退货商品行。 * 退货商品行。
* *
* <p>{@link #dealMethod()} 是<b>退货预约时的处理方式</b>,与 * <p>{@link #dealMethod()} 是<b>退货预约时的处理方式</b>,与
* {@code ReturnProcessCommand.Disposition}(检验后处理方式)不是一回事: * {@code ReturnProcessDisposition}(检验后处理方式)不是一回事:
* 前者是发货人预报,后者是仓收货检验后按明细行最终决定。两套枚举码值也不同。</p> * 前者是发货人预报,后者是仓收货检验后按明细行最终决定。两套枚举码值也不同。</p>
*/ */
public static final class ReturnCommandLine { public static final class ReturnCommandLine {
private final String providerSku; private final String providerSku;
private final int quantity; 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()) { if (providerSku == null || providerSku.trim().isEmpty()) {
throw new IllegalArgumentException("providerSku must not be blank"); throw new IllegalArgumentException("providerSku must not be blank");
} }
@ -125,34 +127,11 @@ public final class ReturnCommand {
return quantity; return quantity;
} }
public DealMethod dealMethod() { public ReturnDealMethod dealMethod() {
return 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 { public static final class Builder {
private String returnRequestNo; private String returnRequestNo;
@ -205,7 +184,7 @@ public final class ReturnCommand {
return this; 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)); this.lines.add(new ReturnCommandLine(providerSku, quantity, dealMethod));
return this; return this;
} }

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

@ -1,17 +1,19 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
/** /**
* 退货条目处理命令(API 77 / 检验后决定)。 * 退货条目处理命令(检验后决定)。
* *
* <p>与 {@code ReturnCommand.DealMethod}(预约时的预报)不是一回事: * <p>与 {@link common.ecommerce.warehouse.enums.ReturnDealMethod}(预约时的预报)
* 这里是仓收货检验之后,逐条明细行最终决定怎么处理。</p> * 不是一回事:这里是仓收货检验之后,逐条明细行最终决定怎么处理。</p>
*/ */
public final class ReturnProcessCommand { public final class ReturnProcessCommand {
private final String providerReturnNo; private final String providerReturnNo;
/** 仓侧明细行 id;来自退货查询接口的 items[].id。 */ /** 仓侧明细行 id;来自退货查询接口的 items[].id。 */
private final long lineId; private final long lineId;
private final Disposition disposition; private final ReturnProcessDisposition disposition;
/** 换标上架时的新 SKU;其它处理方式必须为 null。 */ /** 换标上架时的新 SKU;其它处理方式必须为 null。 */
private final String newSku; private final String newSku;
private final String remark; private final String remark;
@ -26,7 +28,7 @@ public final class ReturnProcessCommand {
} }
this.lineId = b.lineId; this.lineId = b.lineId;
this.disposition = java.util.Objects.requireNonNull(b.disposition, "disposition"); 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())) { if (needsSku && (b.newSku == null || b.newSku.trim().isEmpty())) {
throw new IllegalArgumentException("newSku is required when disposition is RESTOCK_RELABEL"); throw new IllegalArgumentException("newSku is required when disposition is RESTOCK_RELABEL");
} }
@ -51,7 +53,7 @@ public final class ReturnProcessCommand {
return lineId; return lineId;
} }
public Disposition disposition() { public ReturnProcessDisposition disposition() {
return disposition; return disposition;
} }
@ -63,32 +65,10 @@ public final class ReturnProcessCommand {
return remark; 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 { public static final class Builder {
private String providerReturnNo; private String providerReturnNo;
private long lineId; private long lineId;
private Disposition disposition; private ReturnProcessDisposition disposition;
private String newSku; private String newSku;
private String remark; private String remark;
@ -102,7 +82,7 @@ public final class ReturnProcessCommand {
return this; return this;
} }
public Builder disposition(Disposition v) { public Builder disposition(ReturnProcessDisposition v) {
this.disposition = v; this.disposition = v;
return this; return this;
} }

156
warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TrackingInfo.java

@ -0,0 +1,156 @@
package common.ecommerce.warehouse.model;
import java.time.Instant;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 运单物流轨迹查询结果。
*
* <p>由 {@code TrackingCapable.trackShipment()} 返回:整体是<b>一个运单</b>的当前状态 +
* 若干节点,比 {@link TrackEvent}(单条事件)多出承运商、最新状态、签收人与预计妥投。</p>
*
* <p>状态值保持仓方原始字符串,见 {@link #status()};不做跨仓归一——各承运商的节点
* 状态词汇差异太大,强行归一会丢失「派送失败 / 退回中」这类关键区分。</p>
*/
public final class TrackingInfo {
private final String trackingNumber;
private final String carrier;
/** 物流服务,如 {@code FedEx_FEDEX_GROUND};仓方未给时为 null。 */
private final String carrierService;
/** 最新状态(仓方原值)。 */
private final String status;
/** 最新状态的详细描述。 */
private final String statusDetail;
/** 预计妥投时间(UTC);仓方未给时为 null。 */
private final Instant estimatedDeliveryAt;
/** 签收人;未签收为 null。 */
private final String signedBy;
/** 承运商侧可公开查询的轨迹页地址。 */
private final String publicUrl;
private final List<TrackEvent> events;
private TrackingInfo(Builder b) {
this.trackingNumber = require(b.trackingNumber, "trackingNumber");
this.carrier = b.carrier;
this.carrierService = b.carrierService;
this.status = b.status;
this.statusDetail = b.statusDetail;
this.estimatedDeliveryAt = b.estimatedDeliveryAt;
this.signedBy = b.signedBy;
this.publicUrl = b.publicUrl;
this.events = Collections.unmodifiableList(new ArrayList<TrackEvent>(b.events));
}
public static Builder builder() {
return new Builder();
}
public String trackingNumber() {
return trackingNumber;
}
public String carrier() {
return carrier;
}
public String carrierService() {
return carrierService;
}
/** 最新状态(仓方原值)。 */
public String status() {
return status;
}
public String statusDetail() {
return statusDetail;
}
public Instant estimatedDeliveryAt() {
return estimatedDeliveryAt;
}
public String signedBy() {
return signedBy;
}
public String publicUrl() {
return publicUrl;
}
/** 轨迹节点,按仓方返回顺序;不可变。 */
public List<TrackEvent> events() {
return events;
}
private static String require(String v, String name) {
if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(name + " must not be blank");
}
return v.trim();
}
public static final class Builder {
private String trackingNumber;
private String carrier;
private String carrierService;
private String status;
private String statusDetail;
private Instant estimatedDeliveryAt;
private String signedBy;
private String publicUrl;
private final List<TrackEvent> events = new ArrayList<TrackEvent>();
public Builder trackingNumber(String v) {
this.trackingNumber = v;
return this;
}
public Builder carrier(String v) {
this.carrier = v;
return this;
}
public Builder carrierService(String v) {
this.carrierService = v;
return this;
}
public Builder status(String v) {
this.status = v;
return this;
}
public Builder statusDetail(String v) {
this.statusDetail = v;
return this;
}
public Builder estimatedDeliveryAt(Instant v) {
this.estimatedDeliveryAt = v;
return this;
}
public Builder signedBy(String v) {
this.signedBy = v;
return this;
}
public Builder publicUrl(String v) {
this.publicUrl = v;
return this;
}
public Builder event(TrackEvent v) {
this.events.add(v);
return this;
}
public TrackingInfo build() {
return new TrackingInfo(this);
}
}
}

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

@ -1,5 +1,7 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.TransferType;
import java.util.List; import java.util.List;
/** /**

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

@ -1,5 +1,9 @@
package common.ecommerce.warehouse.model; 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; import java.time.Instant;
/** /**
@ -16,7 +20,10 @@ public final class TransferOrder {
private final String toWarehouseCode; private final String toWarehouseCode;
private final TransferType type; private final TransferType type;
private final TransferStatus status; private final TransferStatus status;
/** 仓方状态原值;必须与 {@link #sourceProvider()} 一起落库才有意义。 */
private final String rawStatus; private final String rawStatus;
/** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */
private final WarehouseProvider sourceProvider;
private final int totalQuantity; private final int totalQuantity;
private final Instant estimatedOutboundAt; private final Instant estimatedOutboundAt;
private final Instant estimatedInboundAt; private final Instant estimatedInboundAt;
@ -31,6 +38,7 @@ public final class TransferOrder {
this.type = b.type; this.type = b.type;
this.status = b.status == null ? TransferStatus.UNKNOWN : b.status; this.status = b.status == null ? TransferStatus.UNKNOWN : b.status;
this.rawStatus = b.rawStatus; this.rawStatus = b.rawStatus;
this.sourceProvider = b.sourceProvider;
this.totalQuantity = b.totalQuantity; this.totalQuantity = b.totalQuantity;
this.estimatedOutboundAt = b.estimatedOutboundAt; this.estimatedOutboundAt = b.estimatedOutboundAt;
this.estimatedInboundAt = b.estimatedInboundAt; this.estimatedInboundAt = b.estimatedInboundAt;
@ -97,6 +105,11 @@ public final class TransferOrder {
return status == TransferStatus.COMPLETED; return status == TransferStatus.COMPLETED;
} }
/** 该单据来自哪家仓。 */
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
private static String require(String v, String n) { private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) { if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank"); throw new IllegalArgumentException(n + " must not be blank");
@ -112,6 +125,7 @@ public final class TransferOrder {
private TransferType type; private TransferType type;
private TransferStatus status; private TransferStatus status;
private String rawStatus; private String rawStatus;
private WarehouseProvider sourceProvider;
private int totalQuantity; private int totalQuantity;
private Instant estimatedOutboundAt; private Instant estimatedOutboundAt;
private Instant estimatedInboundAt; private Instant estimatedInboundAt;
@ -153,6 +167,11 @@ public final class TransferOrder {
return this; return this;
} }
public Builder sourceProvider(WarehouseProvider v) {
this.sourceProvider = v;
return this;
}
public Builder totalQuantity(int v) { public Builder totalQuantity(int v) {
this.totalQuantity = v; this.totalQuantity = v;
return this; return this;

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

@ -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 @@
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 @@
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 @@
package common.ecommerce.warehouse.model; package common.ecommerce.warehouse.model;
import common.ecommerce.warehouse.enums.ReturnProcessDisposition;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
import java.time.Instant; import java.time.Instant;
@ -16,10 +19,14 @@ public final class WarehouseReturn {
private final String orderRef; private final String orderRef;
/** 退货类型原值,由适配器解释。 */ /** 退货类型原值,由适配器解释。 */
private final String type; private final String type;
/** 退货单状态;暂无统一枚举(运去哪查询接口未接入),先透传平台值。 */
private final String status; private final String status;
/** 仓方状态原值;必须与 {@link #sourceProvider()} 一起落库才有意义。 */
private final String rawStatus; private final String rawStatus;
/** 处理方式:RESTOCK / DESTROY / UNKNOWN。 */ /** 该单据来自哪家仓;用于解释 {@link #rawStatus()} 及选择平台枚举。 */
private final Disposition disposition; private final WarehouseProvider sourceProvider;
/** 处理方式(检验后的归一化视图);无法识别为 UNKNOWN,原值见 {@link #rawStatus()}。 */
private final ReturnProcessDisposition disposition;
private final List<ReturnLine> lines; private final List<ReturnLine> lines;
private final Instant createdAt; private final Instant createdAt;
@ -31,7 +38,8 @@ public final class WarehouseReturn {
this.type = b.type; this.type = b.type;
this.status = b.status; this.status = b.status;
this.rawStatus = b.rawStatus; 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.lines = Collections.unmodifiableList(new ArrayList<ReturnLine>(b.lines));
this.createdAt = b.createdAt; this.createdAt = b.createdAt;
} }
@ -68,7 +76,7 @@ public final class WarehouseReturn {
return rawStatus; return rawStatus;
} }
public Disposition disposition() { public ReturnProcessDisposition disposition() {
return disposition; return disposition;
} }
@ -80,6 +88,11 @@ public final class WarehouseReturn {
return createdAt; return createdAt;
} }
/** 该单据来自哪家仓。 */
public WarehouseProvider sourceProvider() {
return sourceProvider;
}
private static String require(String v, String n) { private static String require(String v, String n) {
if (v == null || v.trim().isEmpty()) { if (v == null || v.trim().isEmpty()) {
throw new IllegalArgumentException(n + " must not be blank"); throw new IllegalArgumentException(n + " must not be blank");
@ -87,13 +100,6 @@ public final class WarehouseReturn {
return v.trim(); return v.trim();
} }
/** 退货处理方式。 */
public enum Disposition {
RESTOCK,
DESTROY,
UNKNOWN
}
/** 退货明细行。 */ /** 退货明细行。 */
public static final class ReturnLine { public static final class ReturnLine {
@ -169,7 +175,8 @@ public final class WarehouseReturn {
private String type; private String type;
private String status; private String status;
private String rawStatus; private String rawStatus;
private Disposition disposition; private WarehouseProvider sourceProvider;
private ReturnProcessDisposition disposition;
private final List<ReturnLine> lines = new ArrayList<ReturnLine>(); private final List<ReturnLine> lines = new ArrayList<ReturnLine>();
private Instant createdAt; private Instant createdAt;
@ -208,7 +215,12 @@ public final class WarehouseReturn {
return this; 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; this.disposition = v;
return this; return this;
} }

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

@ -1,7 +1,7 @@
package common.ecommerce.warehouse.sdk; package common.ecommerce.warehouse.sdk;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.util.EnumSet; import java.util.EnumSet;

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

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

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

@ -18,14 +18,23 @@ public final class WarehouseConnection {
/** 目标基址,如 {@code https://pr-hwc-open-api.yqn.com};末尾斜杠会被去掉。 */ /** 目标基址,如 {@code https://pr-hwc-open-api.yqn.com};末尾斜杠会被去掉。 */
private final String endpointBaseUrl; private final String endpointBaseUrl;
/**
* 辅助基址:同一仓方把少数接口部署在另一个主机时使用(运去哪的物流轨迹接口在
* {@code pr-ship-api.yqn.com},与仓接口的 {@code pr-hwc-open-api.yqn.com} 不同主机)。
* null 表示未配置,需要它的能力会显式拒绝,<b>不静默退回主基址</b>。
*/
private final String auxEndpointBaseUrl;
/** 凭据。 */ /** 凭据。 */
private final ChannelSecret secret; private final ChannelSecret secret;
private WarehouseConnection(String endpointBaseUrl, ChannelSecret secret) { private WarehouseConnection(String endpointBaseUrl, String auxEndpointBaseUrl, ChannelSecret secret) {
if (endpointBaseUrl == null || endpointBaseUrl.trim().isEmpty()) { if (endpointBaseUrl == null || endpointBaseUrl.trim().isEmpty()) {
throw new IllegalArgumentException("endpointBaseUrl must not be blank"); throw new IllegalArgumentException("endpointBaseUrl must not be blank");
} }
this.endpointBaseUrl = trimTrailingSlash(endpointBaseUrl.trim()); this.endpointBaseUrl = trimTrailingSlash(endpointBaseUrl.trim());
this.auxEndpointBaseUrl = auxEndpointBaseUrl == null || auxEndpointBaseUrl.trim().isEmpty()
? null : trimTrailingSlash(auxEndpointBaseUrl.trim());
Objects.requireNonNull(secret, "secret"); Objects.requireNonNull(secret, "secret");
// 端点写回凭据:需要换 token 的仓,TokenManager 的 refresh 回调只拿得到 ChannelSecret // 端点写回凭据:需要换 token 的仓,TokenManager 的 refresh 回调只拿得到 ChannelSecret
this.secret = ChannelSecret.builder() this.secret = ChannelSecret.builder()
@ -40,7 +49,23 @@ public final class WarehouseConnection {
/** 构造连接:基址去空白、去末尾斜杠,并把基址写回凭据副本。 */ /** 构造连接:基址去空白、去末尾斜杠,并把基址写回凭据副本。 */
public static WarehouseConnection of(String endpointBaseUrl, ChannelSecret secret) { public static WarehouseConnection of(String endpointBaseUrl, ChannelSecret secret) {
return new WarehouseConnection(endpointBaseUrl, secret); return new WarehouseConnection(endpointBaseUrl, null, secret);
}
/**
* 构造带辅助基址的连接。
*
* <p>仅当仓方把部分接口放在另一个主机时使用。不传时,需要辅助基址的能力会抛
* {@code WarehouseUnsupportedCapabilityException},不会退回主基址。</p>
*/
public static WarehouseConnection of(String endpointBaseUrl, String auxEndpointBaseUrl,
ChannelSecret secret) {
return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret);
}
/** 复制一份连接,附加辅助基址。 */
public WarehouseConnection withAuxEndpoint(String auxEndpointBaseUrl) {
return new WarehouseConnection(endpointBaseUrl, auxEndpointBaseUrl, secret);
} }
/** 目标基址,末尾斜杠已去掉。 */ /** 目标基址,末尾斜杠已去掉。 */
@ -48,6 +73,11 @@ public final class WarehouseConnection {
return endpointBaseUrl; return endpointBaseUrl;
} }
/** 辅助基址;未配置时为 null。 */
public String auxEndpointBaseUrl() {
return auxEndpointBaseUrl;
}
/** 凭据;已携带本次调用使用的端点。 */ /** 凭据;已携带本次调用使用的端点。 */
public ChannelSecret secret() { public ChannelSecret secret() {
return secret; return secret;

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

@ -1,7 +1,7 @@
package common.ecommerce.warehouse.sdk; package common.ecommerce.warehouse.sdk;
import common.ecommerce.shared.audit.CallScope; import common.ecommerce.shared.audit.CallScope;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import java.time.Clock; import java.time.Clock;
import java.util.Objects; import java.util.Objects;
@ -82,6 +82,11 @@ public final class WarehouseContext implements CallScope {
return connection.endpointBaseUrl(); return connection.endpointBaseUrl();
} }
/** 辅助基址;仓方把少数接口部署在别的机器时使用,未配置为 null。 */
public String auxEndpointBaseUrl() {
return connection.auxEndpointBaseUrl();
}
/** 本次调用的凭据,SDK 不落盘。 */ /** 本次调用的凭据,SDK 不落盘。 */
public common.ecommerce.shared.spi.ChannelSecret secret() { public common.ecommerce.shared.spi.ChannelSecret secret() {
return connection.secret(); return connection.secret();

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

@ -4,13 +4,16 @@ import common.ecommerce.shared.audit.CallObserver;
import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.idempotency.IdempotencyGuard;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.DestructionCapable; import common.ecommerce.warehouse.capability.DestructionCapable;
import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TrackingCapable; import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
@ -29,8 +32,9 @@ import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt; import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot; 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.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.spi.WarehouseAccount; import common.ecommerce.warehouse.spi.WarehouseAccount;
@ -143,7 +147,11 @@ public final class WarehouseOperations {
return new ReturnView(); return new ReturnView();
} }
/** 轨迹。 */ /**
* 轨迹节点。只读,不走幂等。
*
* @return 节点列表;无轨迹时为空列表
*/
public List<TrackEvent> track(String trackingNumber) { public List<TrackEvent> track(String trackingNumber) {
require(WarehouseCapability.TRACKING, TrackingCapable.class); require(WarehouseCapability.TRACKING, TrackingCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.track", return CallSupport.observe(observer, ctx, "warehouse.track",
@ -152,6 +160,19 @@ public final class WarehouseOperations {
() -> ((TrackingCapable) adapter).track(ctx, trackingNumber)); () -> ((TrackingCapable) adapter).track(ctx, trackingNumber));
} }
/**
* 运单级轨迹:最新状态 + 承运商 + 签收人 + 预计妥投 + 节点明细。
*
* <p>{@code events()} 与 {@link #track(String)} 的返回一致,只多了一层运单信息。</p>
*/
public TrackingInfo trackShipment(String trackingNumber) {
require(WarehouseCapability.TRACKING, TrackingCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.track.shipment",
CallSupport.params("trackingNumber", trackingNumber),
r -> r.events().size(),
() -> ((TrackingCapable) adapter).trackShipment(ctx, trackingNumber));
}
/** 费用视图。 */ /** 费用视图。 */
public FeeView fees() { public FeeView fees() {
return new FeeView(); return new FeeView();
@ -328,6 +349,23 @@ public final class WarehouseOperations {
/** 费用视图。 */ /** 费用视图。 */
public final class FeeView { public final class FeeView {
/**
* 发货前运费试算:按包裹尺寸重量 + 收件地址 + 物流渠道询价。
*
* <p>只读,不走幂等。结果是报价,不是账单——实际费用请用
* {@link #settlements(FeeQuery)} 查结算明细。</p>
*/
public List<FeeEstimateResult> estimate(FeeEstimateQuery query) {
require(WarehouseCapability.FEE_ESTIMATE, WarehouseFeeEstimateCapable.class);
return CallSupport.observe(observer, ctx, "warehouse.fee.estimate",
CallSupport.params("receiveCountry", query.receiveCountry(),
"receivePostal", query.receivePostal(),
"logisticsServiceCode", query.logisticsServiceCode(),
"warehouseCount", query.warehouseCodes().size()),
List::size,
() -> ((WarehouseFeeEstimateCapable) adapter).estimate(ctx, query));
}
/** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */ /** 按条件拉取费用明细(预估与实际用 BillingDocument.estimated() 区分)。 */
public List<BillingDocument> settlements(FeeQuery query) { public List<BillingDocument> settlements(FeeQuery query) {
require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class); require(WarehouseCapability.FEE_SETTLEMENT, WarehouseFeeCapable.class);

6
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.IdempotencyGuard;
import common.ecommerce.shared.idempotency.WriteIdentity; import common.ecommerce.shared.idempotency.WriteIdentity;
import common.ecommerce.shared.spi.IdempotencyStore; 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.capability.OutboundCapable;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundQuery; 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.OutboundRef;
import common.ecommerce.warehouse.model.PackageResult; import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.model.CancelCommand; 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.CancelResult;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.spi.WarehouseAccount; import common.ecommerce.warehouse.spi.WarehouseAccount;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import java.util.List; 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;
import common.ecommerce.shared.audit.CallSupport; import common.ecommerce.shared.audit.CallSupport;
import common.ecommerce.shared.idempotency.IdempotencyGuard; import common.ecommerce.shared.idempotency.IdempotencyGuard;
import common.ecommerce.shared.spi.IdempotencyStore; import common.ecommerce.shared.spi.IdempotencyStore;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.InboundCapable; import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TrackingCapable; 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.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery; import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.InventorySnapshot; 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.TrackEvent;
import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.spi.WarehouseAccount; 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;
* <p>实现方必须按业务键 upsert:同一实体重复同步不得产生两条记录。 * <p>实现方必须按业务键 upsert:同一实体重复同步不得产生两条记录。
* 全部方法默认抛 {@link UnsupportedOperationException},宿主按需实现—— * 全部方法默认抛 {@link UnsupportedOperationException},宿主按需实现——
* 只接出库闭环的宿主不必被迫实现费用与销毁。</p> * 只接出库闭环的宿主不必被迫实现费用与销毁。</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 { 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;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand; 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.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef; 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.model.PackageResult;
import common.ecommerce.warehouse.sdk.WarehouseAdapter; import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseConnection; 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;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException; import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand; 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.CancelResult;
import common.ecommerce.warehouse.model.LabelMode; import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundReceipt;

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

@ -11,15 +11,15 @@ import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.shared.spi.TokenStore;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.model.CancelCommand; import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelEligibility;
import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;

2
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.http.OkHttpTransport;
import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.LockProvider;
import common.ecommerce.shared.spi.TokenStore; 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.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory; import common.ecommerce.warehouse.sdk.WarehouseAdapterFactory;
import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.XincangConstants;

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

@ -4,7 +4,7 @@ import common.ecommerce.http.JsonCodec;
import common.ecommerce.shared.error.ChannelException; import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.error.ValidationException; import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.model.Platform;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.model.ShipTo;

6
warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java

@ -2,12 +2,12 @@ package common.ecommerce.xincang.adapter;
import common.ecommerce.shared.error.ChannelException; import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.error.ValidationException; import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TransferAttachment; import common.ecommerce.warehouse.model.TransferAttachment;
import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.TransferStatus; import common.ecommerce.warehouse.enums.TransferStatus;
import common.ecommerce.warehouse.model.TransferType; import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.dto.XincangDtos; import common.ecommerce.xincang.dto.XincangDtos;

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

@ -2,7 +2,7 @@ package common.ecommerce.xincang.adapter;
import common.ecommerce.shared.error.ChannelException; import common.ecommerce.shared.error.ChannelException;
import common.ecommerce.shared.error.ValidationException; import common.ecommerce.shared.error.ValidationException;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;

4
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.MutableClock;
import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses; import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.XincangConstants;

6
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangOrderTest.java

@ -7,9 +7,9 @@ import common.ecommerce.shared.testkit.MutableClock;
import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses; import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.model.Platform;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.LabelMode; import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt; import common.ecommerce.warehouse.model.OutboundReceipt;

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

@ -7,8 +7,8 @@ import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.shared.testkit.MutableClock; import common.ecommerce.shared.testkit.MutableClock;
import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses; import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.WarehouseProductCapable.ProductResult; import common.ecommerce.warehouse.capability.WarehouseProductCapable.ProductResult;
import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseConnection;

8
warehouse-sdk-xincang/src/test/java/common/ecommerce/xincang/adapter/XincangTransferTest.java

@ -7,13 +7,13 @@ import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.shared.testkit.MutableClock; import common.ecommerce.shared.testkit.MutableClock;
import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses; import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.TransferStatus; import common.ecommerce.warehouse.enums.TransferStatus;
import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.model.TransferType; import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.xincang.XincangConstants; 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;
import common.ecommerce.shared.testkit.InMemoryTokenStore; import common.ecommerce.shared.testkit.InMemoryTokenStore;
import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext; 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.XincangConstants;
import common.ecommerce.xincang.adapter.XincangAdapter; import common.ecommerce.xincang.adapter.XincangAdapter;
import org.junit.jupiter.api.Assumptions; import org.junit.jupiter.api.Assumptions;

23
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/YqnConstants.java

@ -46,10 +46,29 @@ public final class YqnConstants {
public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode"; public static final String PATH_RETURN_PROCESS = "/v3/saleReturn/addProcessMode";
/** 销毁计划。 */ /** 销毁计划。 */
public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate"; public static final String PATH_DESTRUCTION_CREATE = "/destroyplan/DestructionPlanCreate";
/** 物流轨迹。 */ /**
public static final String PATH_TRACKING = "/cloudship/expressdelivery/GetTrackingStatus"; * 物流轨迹(API 189):{@code GET /api/v2/orderShipment/track/{trackingNo}}。
*
* <p><b>注意主机不同</b>:这个接口在 {@code pr-ship-api.yqn.com},不是仓接口的
* {@code pr-hwc-open-api.yqn.com}。调用方需通过
* {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址,
* 未传时适配器显式拒绝而不是打到主基址上。</p>
*/
public static final String PATH_TRACKING = "/api/v2/orderShipment/track/";
/** 轨迹接口的 PR 环境基址;与仓接口不同主机,供调用方填 {@code auxEndpointBaseUrl}。 */
public static final String AUX_BASE_URL_PR = "https://pr-ship-api.yqn.com";
/**
* 轨迹接口的成功码。
*
* <p>文档响应示例是 {@code "code": 1},与仓接口的 {@code 200} 不同,因此单独定义。</p>
*/
public static final int TRACK_SUCCESS_CODE = 1;
/** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */ /** 结算明细(API 133):作业费 / 仓储费 / 增值服务费 / 尾程费。 */
public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail"; public static final String PATH_FEE_DETAIL = "/v1/warehouse/operation/costs/detail";
/** 订单测算 / 运费试算(API 121):发货前按包裹 + 地址 + 渠道询价。 */
public static final String PATH_FEE_ESTIMATE = "/v1/saleOrder/calculate";
/** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */ /** Spec §7.5:三家仓均未公开限流值,保守默认 2 req/s/仓。 */
public static final int PERMITS_PER_SECOND = 2; public static final int PERMITS_PER_SECOND = 2;

117
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.http.JacksonJsonCodec;
import common.ecommerce.shared.error.PlatformBusinessException; import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.support.Page; import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.FeeQuery; import common.ecommerce.warehouse.model.FeeQuery;
@ -22,20 +22,26 @@ import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.WarehouseReturn; import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.InventorySnapshot; 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.WarehouseProduct;
import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable; import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.capability.TrackingCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable; import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException; import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand; 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.CancelResult;
import common.ecommerce.warehouse.model.LabelMode; import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery; import common.ecommerce.warehouse.model.OutboundQuery;
@ -66,8 +72,8 @@ import java.util.Map;
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p> * 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/ */
public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable, public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable,
WarehouseFeeCapable, InventoryCapable, InboundCapable, TransferCapable, WarehouseFeeCapable, WarehouseFeeEstimateCapable, InventoryCapable, InboundCapable,
WarehouseReturnCapable { TransferCapable, WarehouseReturnCapable, TrackingCapable {
/** 运去哪请求里的时间格式;待核对。 */ /** 运去哪请求里的时间格式;待核对。 */
private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
@ -101,11 +107,13 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
WarehouseCapability.OUTBOUND, WarehouseCapability.OUTBOUND,
WarehouseCapability.SPLIT, WarehouseCapability.SPLIT,
WarehouseCapability.FEE_SETTLEMENT, WarehouseCapability.FEE_SETTLEMENT,
WarehouseCapability.FEE_ESTIMATE,
WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INVENTORY_QUERY,
WarehouseCapability.INBOUND, WarehouseCapability.INBOUND,
WarehouseCapability.TRANSFER, WarehouseCapability.TRANSFER,
WarehouseCapability.RETURN, WarehouseCapability.RETURN,
WarehouseCapability.RETURN_DISPOSITION); WarehouseCapability.RETURN_DISPOSITION,
WarehouseCapability.TRACKING);
} }
// ------------------------------------------------------------------ 商品 // ------------------------------------------------------------------ 商品
@ -304,6 +312,25 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
return out; return out;
} }
/**
* 订单测算(API 121):发货前按包裹尺寸重量 + 收件地址 + 物流渠道询价。
*
* <p>读接口,不走幂等。结果按仓库维度返回,一个仓下可能有多个渠道报价。
* 报价仅供参考,实际费用以结算明细(API 133)为准。</p>
*/
@Override
public List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query) {
YqnDtos.CalculateRequest body =
YqnFeeEstimateMapper.toRequest(query, ctx.providerWarehouseId());
String raw = execute(ctx, YqnConstants.PATH_FEE_ESTIMATE, body, "warehouse.fee.estimate");
List<YqnDtos.CalculateResult> rows = json.listAt(raw, "data", YqnDtos.CalculateResult.class);
List<FeeEstimateResult> out = new ArrayList<FeeEstimateResult>(rows.size());
for (YqnDtos.CalculateResult row : rows) {
out.add(YqnFeeEstimateMapper.toResult(row));
}
return out;
}
// ------------------------------------------------------------------ 库存 // ------------------------------------------------------------------ 库存
/** /**
@ -462,6 +489,80 @@ public final class YqnAdapter implements OutboundCapable, WarehouseProductCapabl
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN); throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
} }
// ------------------------------------------------------------------ 物流轨迹
/**
* 运单轨迹(API 189)。
*
* <p>这个接口在<b>另一个主机</b>({@code pr-ship-api.yqn.com}),调用方必须通过
* {@code WarehouseConnection.of(主基址, 辅助基址, 凭据)} 传辅助基址;
* 没传时显式拒绝,不退回主基址,避免把轨迹请求打到仓接口上。</p>
*
* <p>信封的成功码是 {@code 1}(不是其它接口的 {@code 200}),所以不走
* {@code YqnEnvelope},单独解析。</p>
*/
@Override
public TrackingInfo trackShipment(WarehouseContext ctx, String trackingNumber) {
YqnDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber);
return YqnTrackingMapper.toTrackingInfo(track, trackingNumber, zoneOf(ctx));
}
@Override
public List<TrackEvent> track(WarehouseContext ctx, String trackingNumber) {
YqnDtos.ShipmentTrack track = fetchTrack(ctx, trackingNumber);
return YqnTrackingMapper.toTrackEvents(track, trackingNumber, zoneOf(ctx));
}
private YqnDtos.ShipmentTrack fetchTrack(WarehouseContext ctx, String trackingNumber) {
if (trackingNumber == null || trackingNumber.trim().isEmpty()) {
throw new IllegalArgumentException("trackingNumber must not be blank");
}
String baseUrl = ctx.auxEndpointBaseUrl();
if (baseUrl == null || baseUrl.trim().isEmpty()) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.TRACKING);
}
String path = YqnConstants.PATH_TRACKING + urlEncode(trackingNumber.trim());
rateLimiter.acquire(YqnConstants.PATH_TRACKING, YqnConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.get(baseUrl, path, null, ctx.secret(), ctx,
"warehouse.track");
HttpResponse resp = transport.execute(req);
String raw = resp.body();
if (raw == null || raw.trim().isEmpty()) {
throw WarehouseException.builder()
.message("yqn track returned an empty body")
.operation("warehouse.track")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(true)
.build();
}
// 这个接口的成功码是 1,不是 200,不能用 YqnEnvelope
int code = json.intAt(raw, "code", -1);
if (code != YqnConstants.TRACK_SUCCESS_CODE) {
throw WarehouseException.builder()
.message("yqn track failed: code=" + code + ", message=" + json.stringAt(raw, "message"))
.operation("warehouse.track")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.platformCode(String.valueOf(code))
.rawResponse(safeRelay(raw))
.retryable(false)
.build();
}
String data = String.valueOf(json.nodeAt(raw, "data"));
return json.fromJson(data, YqnDtos.ShipmentTrack.class);
}
private static String urlEncode(String v) {
try {
return java.net.URLEncoder.encode(v, "UTF-8");
} catch (java.io.UnsupportedEncodingException e) {
throw new IllegalStateException(e);
}
}
// ------------------------------------------------------------------ internals // ------------------------------------------------------------------ internals
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */ /** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */

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

@ -21,8 +21,8 @@ public final class YqnAdapterFactory
} }
@Override @Override
public common.ecommerce.warehouse.WarehouseProvider provider() { public common.ecommerce.warehouse.enums.WarehouseProvider provider() {
return common.ecommerce.warehouse.WarehouseProvider.YQN; return common.ecommerce.warehouse.enums.WarehouseProvider.YQN;
} }
@Override @Override

128
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnFeeEstimateMapper.java

@ -0,0 +1,128 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.yqn.dto.YqnDtos;
import java.math.BigDecimal;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
/**
* 运去哪运费试算报文映射(API 121,{@code /v1/saleOrder/calculate})。
*/
public final class YqnFeeEstimateMapper {
/** 尺寸单位:厘米。 */
private static final int SIZE_UNIT_CM = 1;
/** 重量单位:克。 */
private static final int WEIGHT_UNIT_GRAM = 2;
/** 运去哪未给币种时的回退值;文档所有金额均为 USD。 */
private static final String DEFAULT_CURRENCY = "USD";
private YqnFeeEstimateMapper() {
}
/**
* 统一试算条件 → 运去哪请求。
*
* @param query 统一条件(cm / g)
* @param defaultWarehouseCode 调用方未指定仓时的回退仓 code
*/
public static YqnDtos.CalculateRequest toRequest(FeeEstimateQuery query, String defaultWarehouseCode) {
YqnDtos.CalculateRequest req = new YqnDtos.CalculateRequest();
req.sizeUnit = SIZE_UNIT_CM;
req.length = toDouble(query.lengthCm());
req.width = toDouble(query.widthCm());
req.height = toDouble(query.heightCm());
req.weightUnit = WEIGHT_UNIT_GRAM;
req.weight = toDouble(query.weightGrams());
if (query.insuredValue() != null) {
req.insuredValue = query.insuredValue().amount().doubleValue();
}
req.warehouseSkuItem = toWarehouseItems(query.warehouseCodes(), defaultWarehouseCode);
req.receiveCountry = query.receiveCountry();
req.receiveState = query.receiveState();
req.receiveCity = query.receiveCity();
req.receivePostal = query.receivePostal();
req.receiveAddress = query.receiveAddress();
if (query.residential() != null) {
req.isResidential = query.residential() ? 1 : 0;
}
req.logisticsServiceCode = query.logisticsServiceCode();
req.logisticsProductCode = query.logisticsProductCode();
req.signService = query.signService();
return req;
}
private static List<YqnDtos.CalculateRequest.CalculateSkuItem> toWarehouseItems(
List<String> warehouseCodes, String defaultWarehouseCode) {
List<String> codes = warehouseCodes;
if (codes == null || codes.isEmpty()) {
codes = defaultWarehouseCode == null || defaultWarehouseCode.trim().isEmpty()
? Collections.<String>emptyList()
: Collections.singletonList(defaultWarehouseCode);
}
if (codes.isEmpty()) {
throw new IllegalArgumentException(
"yqn fee estimate needs a shipOrgWarehouseCode; none given and account has none");
}
List<YqnDtos.CalculateRequest.CalculateSkuItem> items =
new ArrayList<YqnDtos.CalculateRequest.CalculateSkuItem>(codes.size());
for (String code : codes) {
YqnDtos.CalculateRequest.CalculateSkuItem item =
new YqnDtos.CalculateRequest.CalculateSkuItem();
item.shipOrgWarehouseCode = code;
items.add(item);
}
return items;
}
/** 运去哪一条仓库结果 → 统一结果。 */
public static FeeEstimateResult toResult(YqnDtos.CalculateResult row) {
FeeEstimateResult.Builder builder = FeeEstimateResult.builder()
.sourceProvider(WarehouseProvider.YQN)
.shipOrgWarehouseCode(row.shipOrgWarehouseCode);
if (row.calculationCarrierItems != null) {
for (YqnDtos.CalculateResult.CalculateCarrierItem carrier : row.calculationCarrierItems) {
builder.carrier(toQuote(carrier));
}
}
return builder.build();
}
private static FeeEstimateResult.CarrierQuote toQuote(
YqnDtos.CalculateResult.CalculateCarrierItem item) {
String currency = hasText(item.currency) ? item.currency.trim() : DEFAULT_CURRENCY;
FeeEstimateResult.CarrierQuote.Builder quote = FeeEstimateResult.CarrierQuote.builder()
.carrier(item.carrier)
.logisticsServiceCode(item.logisticsServiceCode)
.totalRate(item.totalRate == null ? null : money(item.totalRate, currency));
if (item.calculationCostItems != null) {
for (YqnDtos.CalculateResult.CalculateCostItem cost : item.calculationCostItems) {
quote.costItem(FeeEstimateResult.CarrierQuote.CostItem.builder()
.costName(cost.costName)
.estimatedCost(cost.estimatedCost == null ? null
: money(cost.estimatedCost,
hasText(cost.currency) ? cost.currency.trim() : currency))
.build());
}
}
return quote.build();
}
private static Money money(Double amount, String currency) {
return Money.of(BigDecimal.valueOf(amount), currency);
}
private static Double toDouble(BigDecimal v) {
return v == null ? null : v.doubleValue();
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

3
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.shared.support.Money;
import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.FeeQuery; 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.warehouse.sdk.WarehouseContext;
import common.ecommerce.yqn.dto.YqnDtos; import common.ecommerce.yqn.dto.YqnDtos;
@ -123,6 +123,7 @@ public final class YqnFeeMapper {
.amount(detail.costAmount == null ? Money.zero(CURRENCY) .amount(detail.costAmount == null ? Money.zero(CURRENCY)
: Money.of(java.math.BigDecimal.valueOf(detail.costAmount), CURRENCY)) : Money.of(java.math.BigDecimal.valueOf(detail.costAmount), CURRENCY))
.saleOrderNo(detail.saleOrderNo == null ? null : String.valueOf(detail.saleOrderNo)) .saleOrderNo(detail.saleOrderNo == null ? null : String.valueOf(detail.saleOrderNo))
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build(); .build();
} }

38
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.InboundLine;
import common.ecommerce.warehouse.model.InboundOrder; import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundOrderLine; 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 common.ecommerce.yqn.dto.YqnDtos;
import java.time.Instant; 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)。 */ /** 入库计划详情 → 统一入库单(API 101)。 */
public static InboundOrder toOrder(YqnDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) { public static InboundOrder toOrder(YqnDtos.InboundPlanInfo info, String warehouseCode, ZoneId zone) {
return InboundOrder.builder() return InboundOrder.builder()
.inboundRequestNo(firstNonBlank(info.sourceNo, info.inboundPlanOrderNo)) .inboundRequestNo(firstNonBlank(info.sourceNo, info.inboundPlanOrderNo))
.providerInboundId(info.inboundPlanOrderNo) .providerInboundId(info.inboundPlanOrderNo)
.warehouseCode(firstNonBlank(info.orgWarehouseCode, warehouseCode)) .warehouseCode(firstNonBlank(info.orgWarehouseCode, warehouseCode))
.status(toStatus(info.inboundPlanOrderStatus)) .status(YqnInboundStatus.of(info.inboundPlanOrderStatus).toCore())
.rawStatus(info.inboundPlanOrderStatus) .rawStatus(info.inboundPlanOrderStatus)
.inventoryType(intOf(info.inventoryType)) .inventoryType(intOf(info.inventoryType))
.boxCount(intOf(info.cartonQty)) .boxCount(intOf(info.cartonQty))
@ -212,6 +179,7 @@ public final class YqnInboundMapper {
.totalVolumeCbm(info.totalVolume) .totalVolumeCbm(info.totalVolume)
.remark(info.remark) .remark(info.remark)
.lines(toOrderLines(info.planProductDetailParamList, zone)) .lines(toOrderLines(info.planProductDetailParamList, zone))
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build(); .build();
} }

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

@ -1,16 +1,16 @@
package common.ecommerce.yqn.adapter; package common.ecommerce.yqn.adapter;
import common.ecommerce.shared.support.Money; 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.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundOrder; import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundPackageSpec; 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.PackageResult;
import common.ecommerce.warehouse.model.ShipTo; import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.shared.model.Platform; import common.ecommerce.shared.model.Platform;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.yqn.dto.YqnDtos; import common.ecommerce.yqn.dto.YqnDtos;
import java.time.Instant; import java.time.Instant;
@ -173,7 +173,7 @@ public final class YqnOutboundMapper {
.warehouseCode(firstNonBlank(detail.warehouseCode, warehouseCode)) .warehouseCode(firstNonBlank(detail.warehouseCode, warehouseCode))
.outboundRequestNo(firstNonBlank(detail.orderNo, null)) .outboundRequestNo(firstNonBlank(detail.orderNo, null))
.orderRef(null) // API 128 不返回平台单号 .orderRef(null) // API 128 不返回平台单号
.status(toStatus(detail.orderStatusEnum)) .status(YqnOutboundStatus.of(detail.orderStatusEnum).toCore())
.rawStatus(detail.orderStatusEnum) .rawStatus(detail.orderStatusEnum)
.carrier(packagesCarrierOf(shippedPackages, detail.carrierCode)) .carrier(packagesCarrierOf(shippedPackages, detail.carrierCode))
.trackingNumber(firstTrackingOf(shippedPackages)) .trackingNumber(firstTrackingOf(shippedPackages))
@ -342,39 +342,6 @@ public final class YqnOutboundMapper {
return v != null && !v.trim().isEmpty(); 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,不因时间格式阻断业务。 */ /** 解析运去哪时间;失败返回 null,不因时间格式阻断业务。 */
static Instant parseTime(String value, ZoneId zone) { static Instant parseTime(String value, ZoneId zone) {
if (value == null || value.trim().isEmpty()) { 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;
import common.ecommerce.shared.support.Money; import common.ecommerce.shared.support.Money;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.yqn.enums.YqnReturnDealMethod;
import common.ecommerce.yqn.dto.YqnDtos; import common.ecommerce.yqn.dto.YqnDtos;
import java.util.ArrayList; import java.util.ArrayList;
@ -46,7 +47,7 @@ public final class YqnProductMapper {
req.itemHeight = positiveOrNull(product.itemHeightCm()); req.itemHeight = positiveOrNull(product.itemHeightCm());
req.isRequireSn = product.requireSn(); req.isRequireSn = product.requireSn();
req.packageStyle = product.packageStyle() >= 0 ? product.packageStyle() : null; 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.customName = product.declaredName();
req.customNameEn = product.declaredNameEn(); req.customNameEn = product.declaredNameEn();
req.link = product.link(); 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;
import common.ecommerce.warehouse.model.ReturnCommand; import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand; import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.WarehouseReturn; 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 common.ecommerce.yqn.dto.YqnDtos;
import java.time.LocalDate; import java.time.LocalDate;
@ -45,7 +48,7 @@ public final class YqnReturnMapper {
item.sku = line.providerSku(); item.sku = line.providerSku();
// 运去哪这个字段是 string;数量原样传字符串,不做格式化 // 运去哪这个字段是 string;数量原样传字符串,不做格式化
item.qty = String.valueOf(line.quantity()); item.qty = String.valueOf(line.quantity());
item.returnDealMethod = line.dealMethod().code(); item.returnDealMethod = YqnReturnDealMethod.codeOf(line.dealMethod());
items.add(item); items.add(item);
} }
return items; return items;
@ -56,7 +59,7 @@ public final class YqnReturnMapper {
YqnDtos.SaleReturnProcessRequest req = new YqnDtos.SaleReturnProcessRequest(); YqnDtos.SaleReturnProcessRequest req = new YqnDtos.SaleReturnProcessRequest();
req.saleReturnPlanNo = cmd.providerReturnNo(); req.saleReturnPlanNo = cmd.providerReturnNo();
req.id = cmd.lineId(); req.id = cmd.lineId();
req.goodsReturnType = cmd.disposition().code(); req.goodsReturnType = YqnReturnProcessDisposition.codeOf(cmd.disposition());
req.newSku = cmd.newSku(); req.newSku = cmd.newSku();
req.remark = cmd.remark(); req.remark = cmd.remark();
return req; return req;
@ -75,6 +78,7 @@ public final class YqnReturnMapper {
.orderRef(cmd.saleOrderNo()) .orderRef(cmd.saleOrderNo())
.status("SUBMITTED") .status("SUBMITTED")
.rawStatus(null) .rawStatus(null)
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build(); .build();
} }

143
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTrackingMapper.java

@ -0,0 +1,143 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.yqn.dto.YqnDtos;
import java.time.Instant;
import java.time.LocalDateTime;
import java.time.ZoneId;
import java.time.ZoneOffset;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.List;
/**
* 运去哪物流轨迹映射(API 189)。
*
* <p>状态值一律保持运去哪原话,不做归一:承运商的节点状态词汇差异大,
* 「派送失败 / 退回中」这类区分归一会丢信息。</p>
*/
public final class YqnTrackingMapper {
/** 仓方给的节点时间没带时区,按目的地习惯优先解析;解析不出再看其它格式。 */
private static final DateTimeFormatter[] DATETIME_FORMATS = {
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"),
DateTimeFormatter.ISO_LOCAL_DATE_TIME,
};
private YqnTrackingMapper() {
}
/** 响应 → 运单级轨迹。 */
public static TrackingInfo toTrackingInfo(YqnDtos.ShipmentTrack track, String requestedTrackingNo,
ZoneId zone) {
String trackingNo = hasText(track.trackingCode) ? track.trackingCode.trim() : requestedTrackingNo;
YqnDtos.ShipmentTrack.CarrierDetail carrierDetail = track.carrierDetail;
TrackingInfo.Builder builder = TrackingInfo.builder()
.trackingNumber(trackingNo)
.carrier(track.carrier)
.carrierService(carrierDetail == null ? null : carrierDetail.service)
.status(track.status)
.statusDetail(track.statusDetail)
.estimatedDeliveryAt(parseTime(track.estDeliveryDate, zone))
.signedBy(track.signedBy)
.publicUrl(track.publicUrl);
List<YqnDtos.ShipmentTrack.TrackDetail> details = track.trackingDetails;
if (details != null) {
for (YqnDtos.ShipmentTrack.TrackDetail detail : details) {
builder.event(toTrackEvent(detail, trackingNo, track.carrier, zone));
}
}
return builder.build();
}
/** 只取节点明细。 */
public static List<TrackEvent> toTrackEvents(YqnDtos.ShipmentTrack track, String requestedTrackingNo,
ZoneId zone) {
return toTrackingInfo(track, requestedTrackingNo, zone).events();
}
private static TrackEvent toTrackEvent(YqnDtos.ShipmentTrack.TrackDetail detail, String trackingNo,
String carrier, ZoneId zone) {
return TrackEvent.builder()
.trackingNumber(trackingNo)
.carrier(carrier)
.status(detail.status)
.description(hasText(detail.message) ? detail.message : detail.statusDetail)
.location(locationOf(detail.trackingLocation))
.occurredAt(parseTime(detail.datetime, zone))
.build();
}
/** 位置拼成一行,如 {@code New York, NY, US, 10001};全空返回 null。 */
private static String locationOf(YqnDtos.ShipmentTrack.TrackingLocation loc) {
if (loc == null) {
return null;
}
List<String> parts = new ArrayList<String>(4);
addIfText(parts, loc.city);
addIfText(parts, loc.state);
addIfText(parts, loc.country);
addIfText(parts, loc.zip);
return parts.isEmpty() ? null : join(parts);
}
private static void addIfText(List<String> parts, String v) {
if (hasText(v)) {
parts.add(v.trim());
}
}
private static String join(List<String> parts) {
StringBuilder sb = new StringBuilder();
for (int i = 0; i < parts.size(); i++) {
if (i > 0) {
sb.append(", ");
}
sb.append(parts.get(i));
}
return sb.toString();
}
/**
* 解析仓方时间;失败返回 null,不因时间格式阻断轨迹展示。
*
* <p>文档未给出 {@code datetime} 的格式,因此按「带时区 ISO → 常见本地格式」依次尝试;
* 都不带时区时按调用方给的 {@code zone} 解释。</p>
*/
static Instant parseTime(String value, ZoneId zone) {
if (!hasText(value)) {
return null;
}
String v = value.trim();
try {
return Instant.parse(v);
} catch (DateTimeParseException ignored) {
// 试本地格式
}
try {
return java.time.OffsetDateTime.parse(v).toInstant();
} catch (DateTimeParseException ignored) {
// 试本地格式
}
for (DateTimeFormatter fmt : DATETIME_FORMATS) {
try {
return LocalDateTime.parse(v, fmt).atZone(zone == null ? ZoneOffset.UTC : zone).toInstant();
} catch (DateTimeParseException ignored) {
// 下一个格式
}
}
try {
return java.time.LocalDate.parse(v).atStartOfDay(zone == null ? ZoneOffset.UTC : zone).toInstant();
} catch (DateTimeParseException ignored) {
return null;
}
}
private static boolean hasText(String v) {
return v != null && !v.trim().isEmpty();
}
}

91
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.ShipTo;
import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.TransferStatus; import common.ecommerce.warehouse.enums.TransferType;
import common.ecommerce.warehouse.model.TransferType; import common.ecommerce.yqn.enums.YqnTransferStatus;
import common.ecommerce.yqn.enums.YqnTransferType;
import common.ecommerce.yqn.dto.YqnDtos; import common.ecommerce.yqn.dto.YqnDtos;
import java.time.Instant; import java.time.Instant;
@ -30,7 +31,7 @@ public final class YqnTransferMapper {
/** 统一命令 → 运去哪创建调拨单请求。 */ /** 统一命令 → 运去哪创建调拨单请求。 */
public static YqnDtos.CreateTransferPlanRequest toRequest(TransferCommand cmd) { public static YqnDtos.CreateTransferPlanRequest toRequest(TransferCommand cmd) {
YqnDtos.CreateTransferPlanRequest req = new YqnDtos.CreateTransferPlanRequest(); YqnDtos.CreateTransferPlanRequest req = new YqnDtos.CreateTransferPlanRequest();
req.type = typeOf(cmd.type()); req.type = YqnTransferType.codeOf(cmd.type());
req.orgWarehouseCode = cmd.fromWarehouseCode(); req.orgWarehouseCode = cmd.fromWarehouseCode();
req.inOrgWarehouseCode = cmd.toWarehouseCode(); req.inOrgWarehouseCode = cmd.toWarehouseCode();
req.inventoryType = cmd.inventoryType(); req.inventoryType = cmd.inventoryType();
@ -109,87 +110,6 @@ public final class YqnTransferMapper {
return items; 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) .fromWarehouseCode(resp.orgWarehouseCode)
.toWarehouseCode(resp.inOrgWarehouseCode) .toWarehouseCode(resp.inOrgWarehouseCode)
.type(requestedType) .type(requestedType)
.status(toStatus(resp.transferOutboundPlanStatus)) .status(YqnTransferStatus.toCore(resp.transferOutboundPlanStatus))
.rawStatus(resp.transferOutboundPlanStatus == null ? null .rawStatus(resp.transferOutboundPlanStatus == null ? null
: String.valueOf(resp.transferOutboundPlanStatus)) : String.valueOf(resp.transferOutboundPlanStatus))
.totalQuantity(resp.totalQuantity == null ? 0 : resp.totalQuantity) .totalQuantity(resp.totalQuantity == null ? 0 : resp.totalQuantity)
@ -212,6 +132,7 @@ public final class YqnTransferMapper {
.estimatedInboundAt(parseDate(resp.estimateInboundAt, zone)) .estimatedInboundAt(parseDate(resp.estimateInboundAt, zone))
.trackingNumber(resp.trackingNo) .trackingNumber(resp.trackingNo)
.remark(resp.remark) .remark(resp.remark)
.sourceProvider(common.ecommerce.warehouse.enums.WarehouseProvider.YQN)
.build(); .build();
} }

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

@ -881,4 +881,145 @@ public final class YqnDtos {
public String newSku; public String newSku;
public String remark; 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;
}
}
// ------------------------------------------------------------------ 物流轨迹(API 189)
/**
* 运单轨迹响应(API 189 {@code data})。
*
* <p><b>注意</b>:这个接口的外层信封是 {@code code/message},成功码是
* <b>{@code 1}</b> 而不是其它接口的 {@code 200}(见文档响应示例 {@code "code": 1})。
* 解析在适配器里单独处理,不走 {@code YqnEnvelope}。</p>
*/
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class ShipmentTrack {
/** 运单 id。 */
public Long id;
public String carrier;
public String trackingCode;
/** 最新状态;取值同 {@code trackingDetails[].status}。 */
public String status;
/** 状态详情。 */
public String statusDetail;
/** 预计妥投时间。 */
public String estDeliveryDate;
/** 签收人。 */
public String signedBy;
/** 承运商公开查询地址。 */
public String publicUrl;
public Double weight;
public List<TrackDetail> trackingDetails;
public Parcel parcel;
public CarrierDetail carrierDetail;
/** 一个轨迹节点。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TrackDetail {
public String status;
public String message;
/** 时间点(格式未在文档中给出,按多种格式尝试解析)。 */
public String datetime;
public String statusDetail;
public String timeZone;
public TrackingLocation trackingLocation;
}
/** 节点地理位置。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class TrackingLocation {
public String city;
public String state;
public String country;
public String zip;
}
/** 包裹信息;重量单位 oz、尺寸单位 inch(仓方固定口径)。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class Parcel {
public Double weight;
public Double length;
public Double width;
public Double height;
public String weightUnits;
public String packageDimensionsUnits;
}
/** 承运商明细。 */
@JsonInclude(JsonInclude.Include.NON_NULL)
public static final class CarrierDetail {
/** 物流服务。 */
public String service;
public String containerType;
public String originLocation;
public String destinationLocation;
public String guaranteedDeliveryDate;
public String alternateIdentifier;
public String initialDeliveryAttempt;
}
}
} }

73
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})。
*
* <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();
}
}

76
warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/enums/YqnLogisticsService.java

@ -0,0 +1,76 @@
package common.ecommerce.yqn.enums;
/**
* 运去哪物流产品服务码(API 121 的 {@code logisticsServiceCode})。
*
* <p>取值来自接口文档的枚举清单,<b>只有运去哪这一套</b>——core 没有「物流服务渠道」
* 的通用枚举,也不打算造一个:各仓的渠道划分口径不同,强行归一必然失真。
* 因此本枚举只用来避免调用方手写字符串,不映射到 core。</p>
*
* <p>文档把 {@code FedEx_INTERNATIONAL_ECONOMY} 等标注为「国际件」,这只是说明,
* 不做额外处理。</p>
*/
public enum YqnLogisticsService {
// FedEx
FEDEX_GROUND("FedEx_FEDEX_GROUND"),
FEDEX_GROUND_HOME_DELIVERY("FedEx_GROUND_HOME_DELIVERY"),
FEDEX_SMART_POST("FedEx_SMART_POST"),
/** 国际件。 */
FEDEX_INTERNATIONAL_ECONOMY("FedEx_INTERNATIONAL_ECONOMY"),
/** 国际件。 */
FEDEX_INTERNATIONAL_PRIORITY("FedEx_INTERNATIONAL_PRIORITY"),
FEDEX_2_DAY("FedEx_FEDEX_2_DAY"),
FEDEX_EXPRESS_SAVER("FedEx_FEDEX_EXPRESS_SAVER"),
FEDEX_PRIORITY_OVERNIGHT("FedEx_PRIORITY_OVERNIGHT"),
FEDEX_STANDARD_OVERNIGHT("FedEx_STANDARD_OVERNIGHT"),
FEDEX_FIRST_OVERNIGHT("FedEx_FIRST_OVERNIGHT"),
// UPS
UPSA_MAIL_INNOVATIONS("UPSA_Mail_Innovations"),
UPSA_GROUND("UPSA_GROUND"),
UPS_GROUND("UPS_Ground"),
UPS_2DA("UPS_UPS2DAM"),
UPS_3DAY_SELECT("UPS_3DaySelect"),
UPS_NEXT_DAY_AIR("UPS_NextDayAir"),
UPS_NEXT_DAY_AIR_SAVER("UPS_NextDayAirSaver"),
UPS_NEXT_DAY_AIR_EARLY_AM("UPS_NextDayAirEarlyAM"),
UPS_2ND_DAY_AIR("UPS_2ndDayAir"),
/** 国际件。 */
UPSCA_XI("UPSCA_XI_UPSGCA_XI"),
// 其它承运商
JT_BASIC("JT_Basic"),
AMAZON_SP_GROUND("AmazonSP_Ground"),
AMAZON_SP0_GROUND("AmazonSP0_Ground"),
AMAZON_SP1_GROUND("AmazonSP1_Ground"),
AMAZON_SP2_GROUND("AmazonSP2_Ground"),
USPS_GROUND_ADVANTAGE("USPS_Ground_Advantage"),
USPS_PRIORITY_MAIL("USPS_Priority_Mail"),
ONTRAC_GROUND("Ontrac_Ground"),
IMILE_BASIC("iMile_Basic");
private final String code;
YqnLogisticsService(String code) {
this.code = code;
}
/** 运去哪请求里要填的原值。 */
public String code() {
return code;
}
/** 按码值反查;未知返回 null(调用方可继续用字符串透传未收录的码)。 */
public static YqnLogisticsService of(String code) {
if (code == null) {
return null;
}
for (YqnLogisticsService v : values()) {
if (v.code.equals(code)) {
return v;
}
}
return null;
}
}

83
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})。
*
* <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 @@
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 @@
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 @@
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 @@
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;
import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses; import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.CancelEligibility; import common.ecommerce.warehouse.enums.CancelEligibility;
import common.ecommerce.warehouse.model.LabelMode; import common.ecommerce.warehouse.enums.LabelMode;
import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine; import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundRef; 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.model.ShipTo;
import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;
@ -208,11 +209,19 @@ class YqnAdapterTest {
@Test @Test
void statusMappingCoversKnownValues() { void statusMappingCoversKnownValues() {
assertEquals(OutboundStatus.CANCELLED, YqnOutboundMapper.toStatus("CANCELLED")); assertEquals(OutboundStatus.CANCELLED, YqnOutboundStatus.toCore("CANCELLED"));
assertEquals(OutboundStatus.PICKING, YqnOutboundMapper.toStatus("PICKING")); assertEquals(OutboundStatus.PICKING, YqnOutboundStatus.toCore("PICKING"));
assertEquals(OutboundStatus.LABEL_READY, YqnOutboundMapper.toStatus("LABEL_PRINTED")); assertEquals(OutboundStatus.LABEL_READY, YqnOutboundStatus.toCore("LABEL_PRINTED"));
assertEquals(OutboundStatus.EXCEPTION, YqnOutboundMapper.toStatus("EXCEPTION")); assertEquals(OutboundStatus.SHIPPED, YqnOutboundStatus.toCore("SHIPPED"));
assertEquals(OutboundStatus.SUBMITTED, YqnOutboundMapper.toStatus("UNKNOWN_X")); assertEquals(OutboundStatus.EXCEPTION, YqnOutboundStatus.toCore("EXCEPTION"));
assertNull(YqnOutboundMapper.parseTime("", null)); 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));
}
} }

186
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnFeeEstimateTest.java

@ -0,0 +1,186 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.FeeEstimateQuery;
import common.ecommerce.warehouse.model.FeeEstimateResult;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.yqn.YqnConstants;
import common.ecommerce.yqn.enums.YqnLogisticsService;
import org.junit.jupiter.api.Test;
import java.math.BigDecimal;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 订单测算 / 运费试算(API 121)契约测试。
*/
class YqnFeeEstimateTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC);
private static WarehouseContext ctx() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of(YqnConstants.PR_BASE_URL,
ChannelSecret.builder().appSecret("key-1").build()),
"req-estimate", CLOCK);
}
private static FeeEstimateQuery query() {
return FeeEstimateQuery.builder()
.warehouseCode("RF_NY_US")
.lengthCm(new BigDecimal("30"))
.widthCm(new BigDecimal("20"))
.heightCm(new BigDecimal("10"))
.weightGrams(new BigDecimal("500"))
.insuredValue(Money.of("100.00", "USD"))
.receiveCountry("US")
.receiveState("NY")
.receiveCity("New York")
.receivePostal("10001")
.receiveAddress("1 Main St")
.residential(true)
.logisticsServiceCode(YqnLogisticsService.FEDEX_GROUND.code())
.signService("SIGNATURE")
.build();
}
@Test
void sendsUnitsInCmAndGrams() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}"));
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), query());
String body = transport.lastDataRequest().body();
assertTrue(body.contains("\"sizeUnit\":1"), body);
assertTrue(body.contains("\"weightUnit\":2"), body);
assertTrue(body.contains("\"length\":30.0"), body);
assertTrue(body.contains("\"weight\":500.0"), body);
assertTrue(body.contains("\"isResidential\":1"), body);
assertTrue(body.contains("\"shipOrgWarehouseCode\":\"RF_NY_US\""), body);
assertTrue(body.contains("\"logisticsServiceCode\":\"FedEx_FEDEX_GROUND\""), body);
assertTrue(body.contains("\"receivePostal\":\"10001\""), body);
}
@Test
void omitsResidentialWhenNotGiven() {
FeeEstimateQuery withoutResidential = FeeEstimateQuery.builder()
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE)
.weightGrams(BigDecimal.ONE)
.receiveCountry("US").receivePostal("10001")
.logisticsServiceCode(YqnLogisticsService.UPS_GROUND.code())
.build();
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[]}"));
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), withoutResidential);
assertFalse(transport.lastDataRequest().body().contains("isResidential"));
}
@Test
void fallsBackToAccountWarehouseWhenNoneGiven() {
FeeEstimateQuery noWarehouse = FeeEstimateQuery.builder()
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE)
.weightGrams(BigDecimal.ONE)
.receiveCountry("US").receivePostal("10001")
.logisticsServiceCode(YqnLogisticsService.USPS_PRIORITY_MAIL.code())
.build();
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"data\":[]}"));
new YqnAdapter(transport, new JacksonJsonCodec()).estimate(ctx(), noWarehouse);
assertTrue(transport.lastDataRequest().body()
.contains("\"shipOrgWarehouseCode\":\"RF_NY_US\""));
}
@Test
void mapsCarriersAndCostItems() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":["
+ "{\"shipOrgWarehouseCode\":\"RF_NY_US\",\"calculationCarrierItems\":["
+ "{\"carrier\":\"FEDEX\",\"logisticsServiceCode\":\"FedEx_FEDEX_GROUND\","
+ "\"currency\":\"USD\",\"totalRate\":12.5,"
+ "\"calculationCostItems\":["
+ "{\"costName\":\"尾程运费\",\"estimatedCost\":10.0,\"currency\":\"USD\"},"
+ "{\"costName\":\"燃油附加费\",\"estimatedCost\":2.5,\"currency\":\"USD\"}]}]}]}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
List<FeeEstimateResult> results = adapter.estimate(ctx(), query());
assertEquals(1, results.size());
FeeEstimateResult result = results.get(0);
assertEquals(WarehouseProvider.YQN, result.sourceProvider());
assertEquals("RF_NY_US", result.shipOrgWarehouseCode());
assertEquals(1, result.carriers().size());
FeeEstimateResult.CarrierQuote quote = result.carriers().get(0);
assertEquals("FEDEX", quote.carrier());
assertEquals("FedEx_FEDEX_GROUND", quote.logisticsServiceCode());
assertEquals(new BigDecimal("12.5"), quote.totalRate().amount());
assertEquals("USD", quote.totalRate().currency().getCurrencyCode());
assertEquals(2, quote.costItems().size());
assertEquals("尾程运费", quote.costItems().get(0).costName());
assertEquals(new BigDecimal("10.0"), quote.costItems().get(0).estimatedCost().amount());
}
@Test
void emptyDataIsNotAnError() {
RecordingTransport transport = RecordingTransport.create()
.route(YqnConstants.PATH_FEE_ESTIMATE, req -> Responses.ok(
"{\"statusCode\":200,\"status\":0,\"code\":200,\"message\":\"ok\",\"data\":[]}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertTrue(adapter.estimate(ctx(), query()).isEmpty());
}
@Test
void declaresFeeEstimateCapability() {
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_ESTIMATE));
// 试算与结算明细是两个能力,互不替代
assertTrue(adapter.capabilities().contains(WarehouseCapability.FEE_SETTLEMENT));
}
@Test
void queryRequiresPositiveDimensions() {
assertThrows(IllegalArgumentException.class, () -> FeeEstimateQuery.builder()
.lengthCm(BigDecimal.ZERO).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE)
.weightGrams(BigDecimal.ONE)
.receiveCountry("US").receivePostal("10001")
.logisticsServiceCode("x")
.build());
assertThrows(IllegalArgumentException.class, () -> FeeEstimateQuery.builder()
.lengthCm(BigDecimal.ONE).widthCm(BigDecimal.ONE).heightCm(BigDecimal.ONE)
.weightGrams(BigDecimal.ONE)
.receiveCountry("US")
.logisticsServiceCode("x")
.build());
}
@Test
void logisticsServiceEnumRoundTrips() {
assertEquals("iMile_Basic", YqnLogisticsService.IMILE_BASIC.code());
assertEquals(YqnLogisticsService.UPS_GROUND, YqnLogisticsService.of("UPS_Ground"));
assertNull(YqnLogisticsService.of("SOME_NEW_CHANNEL"));
assertNull(YqnLogisticsService.of(null));
}
}

4
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.support.Money;
import common.ecommerce.shared.testkit.RecordingTransport; import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses; import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider; import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.sdk.WarehouseConnection; import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.warehouse.sdk.WarehouseContext;

178
warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/adapter/YqnTrackingTest.java

@ -0,0 +1,178 @@
package common.ecommerce.yqn.adapter;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.testkit.RecordingTransport;
import common.ecommerce.shared.testkit.Responses;
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
import common.ecommerce.warehouse.model.TrackEvent;
import common.ecommerce.warehouse.model.TrackingInfo;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import java.util.EnumSet;
import common.ecommerce.yqn.YqnConstants;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 物流轨迹(API 189)契约测试。
*
* <p>注意这个接口在<b>另一个主机</b>,且成功码是 {@code 1} 而不是 {@code 200}。</p>
*/
class YqnTrackingTest {
private static final Clock CLOCK = Clock.fixed(Instant.parse("2026-11-10T00:00:00Z"), ZoneOffset.UTC);
private static ChannelSecret secret() {
return ChannelSecret.builder().appSecret("key-1").build();
}
/** 主基址 + 辅助基址。 */
private static WarehouseContext ctx() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of(YqnConstants.PR_BASE_URL, YqnConstants.AUX_BASE_URL_PR, secret()),
"req-track", CLOCK);
}
/** 只有主基址。 */
private static WarehouseContext ctxWithoutAux() {
return WarehouseContext.of("YQN-RF_NY_US", WarehouseProvider.YQN, "RF_NY_US",
WarehouseConnection.of(YqnConstants.PR_BASE_URL, secret()), "req-track", CLOCK);
}
private static final String OK_BODY =
"{\"code\":1,\"message\":\"success\",\"data\":{"
+ "\"id\":9527,\"carrier\":\"FEDEX\",\"trackingCode\":\"TRK123\","
+ "\"status\":\"DELIVERED\",\"statusDetail\":\"已签收\","
+ "\"estDeliveryDate\":\"2026-11-12T10:00:00Z\","
+ "\"signedBy\":\"J SMITH\",\"publicUrl\":\"https://track.example/TRK123\","
+ "\"trackingDetails\":["
+ "{\"status\":\"IN_TRANSIT\",\"message\":\"已离开分拨中心\","
+ "\"datetime\":\"2026-11-09 08:30:00\",\"timeZone\":\"America/New_York\","
+ "\"trackingLocation\":{\"city\":\"Newark\",\"state\":\"NJ\","
+ "\"country\":\"US\",\"zip\":\"07102\"}},"
+ "{\"status\":\"DELIVERED\",\"message\":\"delivered\","
+ "\"datetime\":\"2026-11-10T15:20:00Z\",\"signedBy\":null}],"
+ "\"carrierDetail\":{\"service\":\"FedEx_FEDEX_GROUND\"}}}";
@Test
void callsAuxiliaryHostNotWarehouseHost() {
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY));
new YqnAdapter(transport, new JacksonJsonCodec()).trackShipment(ctx(), "TRK123");
String url = transport.lastDataRequest().url();
assertTrue(url.startsWith(YqnConstants.AUX_BASE_URL_PR), url);
assertTrue(url.contains("/api/v2/orderShipment/track/TRK123"), url);
}
@Test
void missingAuxEndpointIsRejectedNotSilentlyRetargeted() {
RecordingTransport transport = RecordingTransport.create();
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertThrows(common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException.class,
() -> adapter.trackShipment(ctxWithoutAux(), "TRK123"));
assertTrue(transport.recorded().isEmpty(), "不应该发出任何请求");
}
@Test
void mapsShipmentLevelFields() {
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
TrackingInfo info = adapter.trackShipment(ctx(), "TRK123");
assertEquals("TRK123", info.trackingNumber());
assertEquals("FEDEX", info.carrier());
assertEquals("FedEx_FEDEX_GROUND", info.carrierService());
assertEquals("DELIVERED", info.status());
assertEquals("已签收", info.statusDetail());
assertEquals(Instant.parse("2026-11-12T10:00:00Z"), info.estimatedDeliveryAt());
assertEquals("J SMITH", info.signedBy());
assertEquals("https://track.example/TRK123", info.publicUrl());
assertEquals(2, info.events().size());
}
@Test
void mapsTrackingDetailsAndLocation() {
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
TrackingInfo info = adapter.trackShipment(ctx(), "TRK123");
TrackEvent first = info.events().get(0);
assertEquals("IN_TRANSIT", first.status());
assertEquals("已离开分拨中心", first.description());
assertEquals("Newark, NJ, US, 07102", first.location());
assertEquals("TRK123", first.trackingNumber());
assertEquals("FEDEX", first.carrier());
// 带时区的直接解析;本地格式按调用时区解释
assertEquals(Instant.parse("2026-11-10T15:20:00Z"), info.events().get(1).occurredAt());
TrackEvent second = info.events().get(1);
assertEquals("DELIVERED", second.status());
assertNull(second.location());
}
@Test
void trackReturnsSameEventsAsTrackShipment() {
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(OK_BODY));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
List<TrackEvent> events = adapter.track(ctx(), "TRK123");
assertEquals(2, events.size());
assertEquals("IN_TRANSIT", events.get(0).status());
}
/** 成功码是 1;返回 200 之类要按失败处理,不能当成成功去解析 data。 */
@Test
void nonOneCodeIsFailure() {
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(
"{\"code\":200,\"message\":\"ok\",\"data\":{\"trackingCode\":\"TRK123\"}}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
RuntimeException ex = assertThrows(RuntimeException.class,
() -> adapter.trackShipment(ctx(), "TRK123"));
assertTrue(ex.getMessage().contains("code=200"), ex.getMessage());
}
@Test
void missingCodeIsFailure() {
RecordingTransport transport = RecordingTransport.create()
.route("/api/v2/orderShipment/track/TRK123", req -> Responses.ok(
"{\"message\":\"oops\"}"));
YqnAdapter adapter = new YqnAdapter(transport, new JacksonJsonCodec());
assertThrows(RuntimeException.class, () -> adapter.trackShipment(ctx(), "TRK123"));
}
@Test
void declaresTrackingCapability() {
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertTrue(adapter.capabilities().contains(WarehouseCapability.TRACKING));
}
@Test
void blankTrackingNumberRejected() {
YqnAdapter adapter = new YqnAdapter(RecordingTransport.create(), new JacksonJsonCodec());
assertThrows(IllegalArgumentException.class, () -> adapter.trackShipment(ctx(), " "));
assertThrows(IllegalArgumentException.class, () -> adapter.trackShipment(ctx(), null));
}
}
Loading…
Cancel
Save