You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

172 lines
7.0 KiB

feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
package common.ecommerce.warehouse.sdk;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Money;
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
import common.ecommerce.warehouse.enums.WarehouseCapability;
import common.ecommerce.warehouse.enums.WarehouseProvider;
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
import common.ecommerce.warehouse.enums.CancelEligibility;
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
import common.ecommerce.warehouse.model.CancelResult;
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射 枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在 ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层: - 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名, 不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。 - 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。 运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。 Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。 顺带修两处会误导下游的问题: - OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。 补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正, 新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。 - InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺 sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段, 运去哪的 Mapper 全部标注 YQN。 落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存, 它是映射调整后唯一能重跑、修正历史数据的依据。 删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够, 不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加 UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
import common.ecommerce.warehouse.enums.LabelMode;
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundLine;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.shared.testkit.InMemoryIdempotencyStore;
import common.ecommerce.warehouse.model.ShipTo;
import common.ecommerce.warehouse.testkit.FakeWarehouseAdapter;
import common.ecommerce.warehouse.testkit.InMemoryWarehouses;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 仓库门面:能力检查、写操作强制幂等、收费取消拦截。
*/
class WarehouseSdkTest {
private static final Instant T0 = Instant.parse("2026-11-09T00:00:00Z");
private static final Clock CLOCK = Clock.fixed(T0, ZoneOffset.UTC);
private static final String WH = "YQN-RF_NY_US";
private FakeWarehouseAdapter adapter;
private InMemoryIdempotencyStore idempotency;
private WarehouseSdk sdk;
@BeforeEach
void setUp() {
adapter = new FakeWarehouseAdapter();
idempotency = new InMemoryIdempotencyStore();
InMemoryWarehouses repo = new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
sdk = WarehouseSdk.builder()
.warehouseRepository(repo)
.idempotencyStore(idempotency)
.clock(CLOCK)
.register(adapter)
.build();
}
private static OutboundCommand cmd(String requestNo) {
return OutboundCommand.builder()
.outboundRequestNo(requestNo)
.orderRef("SO-1")
.labelMode(LabelMode.WAREHOUSE_LABEL)
.salesPlatform(common.ecommerce.shared.model.Platform.WALMART_SC)
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环 按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。 warehouse-sdk-core: - 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common 上共享幂等 / 水位线 / 审计 / HTTP - 主键是 OMS 下发的 warehouseCode,出库单双号 outboundRequestNo(SDK 生成)+ providerOrderId(仓生成) - 17 个能力位、9 个能力接口;未实现的能力显式抛 WarehouseUnsupportedCapabilityException,不静默返回空 - 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge, 否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行 - 出库创建强制经 IdempotencyGuard,幂等键 warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败, 调用方无法绕过 - 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市 warehouse-sdk-testkit: - InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档 - FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径 warehouse-sdk-yqn(运去哪 P1): - 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1) - 出库 create / get / query / checkCancel / cancel / packages - 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝, 不静默降级为仓自有面单 - 默认 2 req/s/仓令牌桶(三家仓均未公开限流值) 待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持 外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos / YqnEnvelope,核实后只改这三处。 测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。 Co-Authored-By: Claude <noreply@anthropic.com>
2 weeks ago
.shipTo(ShipTo.builder()
.name("B") // 测试数据
.countryCode("US")
.city("New York")
.addressLine1("1 Test St")
.build())
.line(OutboundLine.builder()
.lineNo("1")
.omsSku("DM00001")
.quantity(1)
.declareName("Sample")
.declareValue(Money.of("10.00", "USD"))
.build())
.build();
}
@Test
void createIsIdempotent() {
WarehouseOperations ops = sdk.warehouses(WH, FakeWarehouseAdapter.connection());
OutboundReceipt first = ops.outbound().create(cmd("OB-1"));
assertEquals("WH1", first.providerOrderId());
assertEquals(1, adapter.createCallCount());
OutboundReceipt again = ops.outbound().create(cmd("OB-1"));
assertEquals("WH1", again.providerOrderId());
assertEquals(1, adapter.createCallCount(), "第二次不应再调仓");
}
@Test
void retryableFailureAllowsRerun() {
adapter.failNextCreate();
WarehouseOperations ops = sdk.warehouses(WH, FakeWarehouseAdapter.connection());
assertThrows(RuntimeException.class, () -> ops.outbound().create(cmd("OB-2")));
assertEquals(0, adapter.createCallCount());
OutboundReceipt receipt = ops.outbound().create(cmd("OB-2"));
assertNotNull(receipt.providerOrderId());
assertEquals(1, adapter.createCallCount());
}
@Test
void chargedCancelRequiresExplicitAccept() {
adapter.chargeCancel("5.00");
WarehouseOperations ops = sdk.warehouses(WH, FakeWarehouseAdapter.connection());
ops.outbound().create(cmd("OB-3"));
assertEquals(CancelEligibility.CHARGED,
ops.outbound().checkCancel(OutboundRef.ofRequestNo("OB-3")));
assertThrows(OutboundCancelChargeRequiredException.class,
() -> ops.outbound().cancel(CancelCommand.builder()
.outboundRequestNo("OB-3").build()));
CancelResult ok = ops.outbound().cancel(CancelCommand.builder()
.outboundRequestNo("OB-3").acceptCharge(true).build());
assertTrue(ok.cancelled());
assertEquals(CancelEligibility.CHARGED, ok.eligibility());
}
@Test
void blockedCancelThrows() {
adapter.blockCancel();
WarehouseOperations ops = sdk.warehouses(WH, FakeWarehouseAdapter.connection());
ops.outbound().create(cmd("OB-4"));
assertThrows(OutboundCancelBlockedException.class,
() -> ops.outbound().cancel(CancelCommand.builder()
.outboundRequestNo("OB-4").acceptCharge(true).build()));
}
@Test
void unimplementedCapabilityIsRejected() {
WarehouseOperations ops = sdk.warehouses(WH, FakeWarehouseAdapter.connection());
assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> ops.inventory().query(
common.ecommerce.warehouse.model.InventoryQuery.builder().build()));
assertThrows(WarehouseUnsupportedCapabilityException.class,
() -> ops.inbound().get("INB-1"));
assertEquals(false, sdk.capabilities(WH).supports(WarehouseCapability.INVENTORY_QUERY));
assertEquals(true, sdk.capabilities(WH).supports(WarehouseCapability.OUTBOUND));
}
@Test
void writeWithoutIdempotencyStoreFails() {
InMemoryWarehouses repo = new InMemoryWarehouses()
.put(FakeWarehouseAdapter.account(WH, WarehouseProvider.CUSTOM));
WarehouseSdk noGuard = WarehouseSdk.builder()
.warehouseRepository(repo)
.clock(CLOCK)
.register(new FakeWarehouseAdapter())
.build();
assertThrows(IllegalStateException.class,
() -> noGuard.warehouses(WH, FakeWarehouseAdapter.connection())
.outbound().create(cmd("OB-5")));
}
@Test
void unknownWarehouseFails() {
assertThrows(IllegalStateException.class,
() -> sdk.warehouses("NOT-CONFIGURED", FakeWarehouseAdapter.connection()));
}
}