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.

199 lines
7.6 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.testkit;
import common.ecommerce.shared.spi.ChannelSecret;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.OutboundCancelChargeRequiredException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelEligibility;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.OutboundCommand;
import common.ecommerce.warehouse.model.OutboundOrder;
import common.ecommerce.warehouse.model.OutboundQuery;
import common.ecommerce.warehouse.model.OutboundReceipt;
import common.ecommerce.warehouse.model.OutboundRef;
import common.ecommerce.warehouse.model.OutboundStatus;
import common.ecommerce.warehouse.model.PackageResult;
import common.ecommerce.warehouse.sdk.WarehouseAdapter;
import common.ecommerce.warehouse.sdk.WarehouseConnection;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.warehouse.spi.WarehouseAccount;
import java.util.ArrayList;
import java.util.Collections;
import java.util.EnumSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 假仓适配器:只实现出库能力,用于验证门面抽象、幂等与能力检查。
*
* <pre>
* FakeWarehouseAdapter adapter = new FakeWarehouseAdapter();
* </pre>
*/
public final class FakeWarehouseAdapter implements OutboundCapable {
private final Map<String, OutboundOrder> orders = new LinkedHashMap<String, OutboundOrder>();
private final List<String> createCalls = new ArrayList<String>();
private int sequence;
/** 取消费用;非 null 时 checkCancel 返回 CHARGED。 */
private String cancelFee;
/** 置 true 时 checkCancel 返回 BLOCKED。 */
private boolean cancelBlocked;
/** 置 true 时 create 抛可重试异常,用于验证幂等 FAILED_RETRYABLE 路径。 */
private boolean failNextCreate;
public static WarehouseAccount account(String warehouseCode, WarehouseProvider provider) {
return WarehouseAccount.builder()
.warehouseCode(warehouseCode)
.provider(provider.name())
.providerWarehouseId("WH-" + warehouseCode)
.credentialRef("kms://test/fake-warehouse")
.timeZone("America/Los_Angeles")
.build();
}
public static WarehouseConnection connection() {
return WarehouseConnection.of("https://fake.warehouse.example.com",
ChannelSecret.builder().appSecret("fake-token").build());
}
public FakeWarehouseAdapter chargeCancel(String fee) {
this.cancelFee = fee;
return this;
}
public FakeWarehouseAdapter blockCancel() {
this.cancelBlocked = true;
return this;
}
public FakeWarehouseAdapter failNextCreate() {
this.failNextCreate = true;
return this;
}
@Override
public String adapterId() {
return "fake-warehouse";
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.CUSTOM;
}
@Override
public EnumSet<WarehouseCapability> capabilities() {
return EnumSet.of(WarehouseCapability.OUTBOUND);
}
@Override
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
if (!capabilities().contains(WarehouseCapability.OUTBOUND)) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.OUTBOUND);
}
if (failNextCreate) {
failNextCreate = false;
throw common.ecommerce.warehouse.error.WarehouseException.builder()
.message("fake transient failure")
.operation("warehouse.outbound.create")
.warehouseCode(ctx.warehouseCode())
.retryable(true)
.build();
}
createCalls.add(cmd.outboundRequestNo());
String providerOrderId = "WH" + (++sequence);
orders.put(cmd.outboundRequestNo(), OutboundOrder.builder()
.warehouseCode(ctx.warehouseCode())
.outboundRequestNo(cmd.outboundRequestNo())
.providerOrderId(providerOrderId)
.orderRef(cmd.orderRef())
.labelMode(cmd.labelMode())
.status(OutboundStatus.SUBMITTED)
.rawStatus("SUBMITTED")
.requestedAt(java.time.Instant.now(ctx.clock()))
.sourceProvider(provider())
.build());
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderId, "SUBMITTED");
}
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
if (ref.outboundRequestNo() != null) {
return orders.get(ref.outboundRequestNo());
}
for (OutboundOrder o : orders.values()) {
if (ref.providerOrderId().equals(o.providerOrderId())) {
return o;
}
}
return null;
}
@Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
return Page.last(new ArrayList<OutboundOrder>(orders.values()));
}
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
if (cancelBlocked) {
return CancelEligibility.BLOCKED;
}
return cancelFee == null ? CancelEligibility.FREE : CancelEligibility.CHARGED;
}
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
CancelEligibility eligibility = checkCancel(ctx, OutboundRef.ofRequestNo(cmd.outboundRequestNo()));
if (eligibility == CancelEligibility.BLOCKED) {
throw new OutboundCancelBlockedException(common.ecommerce.warehouse.error.WarehouseException.builder()
.message("outbound already shipped")
.operation("warehouse.outbound.cancel")
.warehouseCode(ctx.warehouseCode()));
}
if (eligibility == CancelEligibility.CHARGED && !cmd.acceptCharge()) {
throw new OutboundCancelChargeRequiredException(
common.ecommerce.warehouse.error.WarehouseException.builder()
.message("cancel is charged, acceptCharge required")
.operation("warehouse.outbound.cancel")
.warehouseCode(ctx.warehouseCode()),
cancelFee, "USD");
}
return CancelResult.builder()
.outboundRequestNo(cmd.outboundRequestNo())
.eligibility(eligibility)
.cancelled(true)
.rawStatus("CANCELLED")
.build();
}
@Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
return Collections.singletonList(PackageResult.builder()
.packageId("PKG-1")
.outboundRequestNo(ref.outboundRequestNo() == null ? "unknown" : ref.outboundRequestNo())
.trackingNumber("TRACK-1")
.carrier("FAKE")
.labelRef("LABEL-1")
.build());
}
/** 实际调用 create 的次数;验证幂等只调一次。 */
public int createCallCount() {
return createCalls.size();
}
public List<String> createCalls() {
return Collections.unmodifiableList(createCalls);
}
}