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.

512 lines
24 KiB

package common.ecommerce.yqn.adapter;
import common.ecommerce.http.HttpRequest;
import common.ecommerce.http.HttpResponse;
import common.ecommerce.http.HttpTransport;
import common.ecommerce.http.JacksonJsonCodec;
import common.ecommerce.shared.error.PlatformBusinessException;
import common.ecommerce.shared.support.Page;
import common.ecommerce.warehouse.WarehouseCapability;
import common.ecommerce.warehouse.WarehouseProvider;
import common.ecommerce.warehouse.capability.OutboundCapable;
import common.ecommerce.warehouse.model.BillingDocument;
import common.ecommerce.warehouse.model.FeeQuery;
import common.ecommerce.warehouse.capability.InboundCapable;
import common.ecommerce.warehouse.model.InboundCommand;
import common.ecommerce.warehouse.model.InboundOrder;
import common.ecommerce.warehouse.model.InboundReceipt;
import common.ecommerce.warehouse.model.InventoryQuery;
import common.ecommerce.warehouse.model.ReturnCommand;
import common.ecommerce.warehouse.model.ReturnProcessCommand;
import common.ecommerce.warehouse.model.TransferCommand;
import common.ecommerce.warehouse.model.WarehouseReturn;
import common.ecommerce.warehouse.model.TransferOrder;
import common.ecommerce.warehouse.model.InventorySnapshot;
import common.ecommerce.warehouse.model.InventorySyncStrategy;
import common.ecommerce.warehouse.capability.WarehouseProduct;
import common.ecommerce.warehouse.capability.InventoryCapable;
import common.ecommerce.warehouse.capability.TransferCapable;
import common.ecommerce.warehouse.capability.WarehouseReturnCapable;
import common.ecommerce.warehouse.capability.WarehouseFeeCapable;
import common.ecommerce.warehouse.capability.WarehouseProductCapable;
import common.ecommerce.warehouse.error.OutboundCancelBlockedException;
import common.ecommerce.warehouse.error.WarehouseException;
import common.ecommerce.warehouse.error.WarehouseUnsupportedCapabilityException;
import common.ecommerce.warehouse.model.CancelCommand;
import common.ecommerce.warehouse.model.CancelEligibility;
import common.ecommerce.warehouse.model.CancelResult;
import common.ecommerce.warehouse.model.LabelMode;
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.PackageResult;
import common.ecommerce.warehouse.sdk.WarehouseContext;
import common.ecommerce.yqn.YqnConstants;
import common.ecommerce.yqn.dto.YqnDtos;
import common.ecommerce.yqn.http.YqnEnvelope;
import common.ecommerce.yqn.http.YqnRateLimiter;
import common.ecommerce.yqn.http.YqnRequestFactory;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 运去哪适配器(P1 出库闭环)。
*
* <p>实现 {@code OutboundCapable}:创建 / 查询 / 取消 / 包裹。库存、入库、退货、销毁
* 等在 P2/P3 接入,未实现的能力位不声明,门面调用会显式拒绝。</p>
*
* <p>字段级契约待打样核对(Spec §8.6):本类只做「拼请求 + 解析响应」,
* 字段差异收敛在 {@link YqnDtos} 与 {@link YqnOutboundMapper}。</p>
*/
public final class YqnAdapter implements OutboundCapable, WarehouseProductCapable,
WarehouseFeeCapable, InventoryCapable, InboundCapable, TransferCapable,
WarehouseReturnCapable {
/** 运去哪请求里的时间格式;待核对。 */
private static final DateTimeFormatter REQUEST_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
private final HttpTransport transport;
private final JacksonJsonCodec json;
private final YqnRequestFactory requestFactory;
private final YqnRateLimiter rateLimiter;
public YqnAdapter(HttpTransport transport, JacksonJsonCodec json) {
this.transport = transport;
this.json = json;
this.requestFactory = new YqnRequestFactory(json);
this.rateLimiter = new YqnRateLimiter();
}
@Override
public String adapterId() {
return YqnConstants.ADAPTER_ID;
}
@Override
public WarehouseProvider provider() {
return WarehouseProvider.YQN;
}
@Override
public java.util.EnumSet<WarehouseCapability> capabilities() {
return java.util.EnumSet.of(
WarehouseCapability.PRODUCT,
WarehouseCapability.OUTBOUND,
WarehouseCapability.SPLIT,
WarehouseCapability.FEE_SETTLEMENT,
WarehouseCapability.INVENTORY_QUERY,
WarehouseCapability.INBOUND,
WarehouseCapability.TRANSFER,
WarehouseCapability.RETURN,
WarehouseCapability.RETURN_DISPOSITION);
}
// ------------------------------------------------------------------ 商品
/**
* 创建 / 编辑商品(API 115,{@code /v1/product/save})。
*
* <p>接口本身是保存语义(同 SKU 再调即更新),因此不区分 create 与 update。
* 响应只有 {@code code/message},没有 data,所以结果里只回填请求侧 SKU。</p>
*/
@Override
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) {
YqnDtos.SaveProductRequest body = YqnProductMapper.toRequest(product);
String raw = execute(ctx, YqnConstants.PATH_PRODUCT_SAVE, body, "warehouse.product.create");
return ProductResult.of(YqnProductMapper.skuOf(product), "SAVED",
json.stringAt(raw, "message"));
}
// ------------------------------------------------------------------ 出库
@Override
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) {
requirePlatformLabelSupported(ctx, cmd.labelMode());
YqnDtos.CreateOrderRequest body = YqnOutboundMapper.toRequest(cmd, warehouseId(ctx, cmd.warehouseId()));
String raw = execute(ctx, YqnConstants.PATH_ORDER_CREATE, body, "warehouse.outbound.create");
// API 123 只回 data.orderId(仓内部数字 id),不回字符串单号
String providerOrderId = json.stringAt(raw, "data.orderId");
if (providerOrderId == null || providerOrderId.trim().isEmpty()) {
// 仓未返回 id 时不能静默成功:幂等键记了成功但没法回查
throw WarehouseException.builder()
.message("yqn create returned no data.orderId: " + safeRelay(raw))
.operation("warehouse.outbound.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.rawResponse(safeRelay(raw))
.build();
}
return OutboundReceipt.of(cmd.outboundRequestNo(), providerOrderId, null);
}
@Override
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) {
// API 128 只按来源单号查;仓内部 id 查不了,调用方要给 outboundRequestNo
String orderNo = orderNoOf(ref);
YqnDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.get");
return detail == null ? null : YqnOutboundMapper.toOrder(detail, ctx.warehouseCode(), zoneOf(ctx));
}
/**
* 按条件查询。
*
* <p>运去哪的订单查询接口是「按单号取详情」,没有列表/时间窗接口,
* 因此这里按单号逐个取;没有单号时<b>拒绝</b>而不是返回全量,
* 避免误当成增量同步用。</p>
*/
@Override
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) {
String orderNo = firstNonBlank(query.providerOrderId(), query.orderRef());
if (orderNo == null) {
throw new common.ecommerce.shared.error.ValidationException(
WarehouseException.builder()
.message("yqn has no order list API; query requires providerOrderId or orderRef")
.operation("warehouse.outbound.query")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false));
}
YqnDtos.OrderDetail detail = findOne(ctx, orderNo, "warehouse.outbound.query");
return detail == null ? Page.<OutboundOrder>empty()
: Page.last(java.util.Collections.singletonList(
YqnOutboundMapper.toOrder(detail, ctx.warehouseCode(), zoneOf(ctx))));
}
/** 调 findOne 并解析 data;订单不存在时返回 null。 */
private YqnDtos.OrderDetail findOne(WarehouseContext ctx, String orderNo, String operation) {
YqnDtos.FindOneOrderRequest body = new YqnDtos.FindOneOrderRequest();
body.orderNo = orderNo;
String raw = execute(ctx, YqnConstants.PATH_ORDER_FIND_ONE, body, operation);
com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
return json.fromJson(data.toString(), YqnDtos.OrderDetail.class);
}
/** 统一引用 → 运去哪订单号(来源单号)。 */
private static String orderNoOf(OutboundRef ref) {
String orderNo = firstNonBlank(ref.outboundRequestNo(), ref.providerOrderId());
if (orderNo == null) {
throw new IllegalArgumentException("yqn needs outboundRequestNo to query an order");
}
return orderNo;
}
private static String firstNonBlank(String a, String b) {
if (a != null && !a.trim().isEmpty()) {
return a.trim();
}
return b == null || b.trim().isEmpty() ? null : b.trim();
}
@Override
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) {
// 运去哪没有独立的取消预判接口(Spec §8.6 第 5 项待核对):
// 先查单状态,已出库/已取消的一律 BLOCKED;其余交给 cancel 时仓判定。
OutboundOrder order = get(ctx, ref);
if (order == null) {
return CancelEligibility.BLOCKED;
}
switch (order.status()) {
case SHIPPED:
case CANCELLED:
return CancelEligibility.BLOCKED;
default:
return CancelEligibility.FREE;
}
}
/**
* 取消销售订单(API 122)。
*
* <p>运去哪没有收费取消的概念,也没有取消费预判:入参只有 {@code orderNo},
* 响应只有 {@code code/message}。因此 {@link CancelCommand#acceptCharge()} 在这里
* 不生效;仓判定为不可取消(已拣货 / 已出库)时返回非 200 业务码。</p>
*
* <p>「不可取消」按 {@link OutboundCancelBlockedException} 抛出,
* 而不是笼统的业务异常,方便调用方区分「状态不对」与「参数错」。</p>
*/
@Override
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) {
YqnDtos.CancelOrderRequest body = new YqnDtos.CancelOrderRequest();
body.orderNo = orderNoOf(cmd);
String raw;
try {
raw = execute(ctx, YqnConstants.PATH_ORDER_CANCEL, body, "warehouse.outbound.cancel");
} catch (PlatformBusinessException e) {
// API 122 的失败原因只有 message,无法细分;取消场景统一按「不可取消」表达
throw new OutboundCancelBlockedException(WarehouseException.builder()
.message("yqn refused cancellation: " + e.getMessage())
.operation("warehouse.outbound.cancel")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.platformCode(e.platformCode())
.rawResponse(e.rawResponse())
.retryable(false));
}
return CancelResult.builder()
.outboundRequestNo(cmd.outboundRequestNo())
.providerOrderId(cmd.providerOrderId())
.eligibility(CancelEligibility.FREE)
.cancelled(true)
.rawStatus(json.stringAt(raw, "message"))
.build();
}
/** 取消命令 → 运去哪订单号:优先来源单号,其次仓单号。 */
private static String orderNoOf(CancelCommand cmd) {
String orderNo = firstNonBlank(cmd.outboundRequestNo(), cmd.providerOrderId());
if (orderNo == null) {
throw new IllegalArgumentException("yqn needs outboundRequestNo to cancel an order");
}
return orderNo;
}
@Override
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) {
YqnDtos.OrderDetail detail = findOne(ctx, orderNoOf(ref), "warehouse.outbound.packages");
return detail == null ? java.util.Collections.<PackageResult>emptyList()
: YqnOutboundMapper.toPackages(detail);
}
// ------------------------------------------------------------------ 费用
/**
* 结算明细(API 133)。
*
* <p>预估与实际由 {@code settlementType} 区分(1 实际 / 2 预估),
* 映射到 {@link BillingDocument#estimated()}。仓一般发货后可查预估,
* 收货约一周后才出实际账单。</p>
*/
@Override
public List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query) {
YqnDtos.CostDetailRequest body = YqnFeeMapper.toRequest(query);
String raw = execute(ctx, YqnConstants.PATH_FEE_DETAIL, body, "warehouse.fee.settlements");
List<YqnDtos.CostDetail> rows = json.listAt(raw, "data", YqnDtos.CostDetail.class);
List<BillingDocument> out = new ArrayList<BillingDocument>(rows.size());
for (YqnDtos.CostDetail row : rows) {
out.add(YqnFeeMapper.toDocument(row, ctx.warehouseCode(), zoneOf(ctx)));
}
return out;
}
// ------------------------------------------------------------------ 库存
/**
* 运去哪只能全量分页拉,没有按时间增量。
*
* <p>宿主按 {@link #syncStrategy()} 决定落库策略:这里永远是
* {@link InventorySyncStrategy#FULL_PULL_DIFF},不要按 updatedAfter 做增量。</p>
*/
@Override
public InventorySyncStrategy syncStrategy() {
return InventorySyncStrategy.FULL_PULL_DIFF;
}
/**
* 批量查询库存(API 107)。
*
* <p>文档把参数写在「Body 参数」里,但方法是 GET;这里按重复 query 参数下发
* (见 {@link YqnRequestFactory#getMulti})。</p>
*/
@Override
public Page<InventorySnapshot> query(WarehouseContext ctx, InventoryQuery query) {
Map<String, List<String>> params = YqnInventoryMapper.toParams(query, ctx.providerWarehouseId());
rateLimiter.acquire(YqnConstants.PATH_INVENTORY_PAGE, YqnConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), YqnConstants.PATH_INVENTORY_PAGE,
params, ctx.secret(), ctx, "warehouse.inventory.query");
HttpResponse resp = transport.execute(req);
String raw = YqnEnvelope.of(resp, json, "warehouse.inventory.query",
ctx.warehouseCode(), ctx.requestId()).body();
YqnDtos.InventoryPage page = json.fromJson(raw, YqnDtos.InventoryPage.class);
return YqnInventoryMapper.toPage(page, ctx.providerWarehouseId(), zoneOf(ctx), query.cursor());
}
// ------------------------------------------------------------------ 入库
/**
* 创建入库计划单(API 97)。
*
* <p>响应只回 {@code data.inboundPlanOrderNo}(字符串计划单号),
* 正好可直接作为 {@code providerInboundId} 落库。</p>
*/
@Override
public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) {
String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId());
YqnDtos.CreateInboundPlanRequest body = YqnInboundMapper.toRequest(cmd, warehouseCode);
String raw = execute(ctx, YqnConstants.PATH_INBOUND_CREATE, body, "warehouse.inbound.create");
String planNo = json.stringAt(raw, "data.inboundPlanOrderNo");
return InboundReceipt.of(cmd.inboundRequestNo(), planNo);
}
/**
* 查入库计划详情(API 101)。
*
* <p>入参是入库单号或来源单号,两者都能传;我们下发的来源单号即
* {@code inboundRequestNo}。</p>
*/
@Override
public InboundOrder get(WarehouseContext ctx, String inboundRef) {
YqnDtos.GetInboundPlanRequest body = new YqnDtos.GetInboundPlanRequest();
body.orderNo = inboundRef;
String raw = execute(ctx, YqnConstants.PATH_INBOUND_GET, body, "warehouse.inbound.get");
com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
return null;
}
YqnDtos.InboundPlanInfo info = json.fromJson(data.toString(), YqnDtos.InboundPlanInfo.class);
return YqnInboundMapper.toOrder(info, ctx.warehouseCode(), zoneOf(ctx));
}
/**
* 运去哪没有入库单列表接口,与订单一样只能按单号取。
* {@code cursor} 在这里被当作入库单号使用;不给就拒绝,不返回全量。
*/
@Override
public Page<InboundOrder> query(WarehouseContext ctx, String inboundRef) {
if (inboundRef == null || inboundRef.trim().isEmpty()) {
throw new common.ecommerce.shared.error.ValidationException(
WarehouseException.builder()
.message("yqn has no inbound list API; query requires an inbound order no")
.operation("warehouse.inbound.query")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false));
}
InboundOrder order = get(ctx, inboundRef);
return order == null ? Page.<InboundOrder>empty()
: Page.last(java.util.Collections.singletonList(order));
}
// ------------------------------------------------------------------ 调拨
/**
* 创建调拨单(API 139)。
*
* <p>响应是一个完整对象,但只有 {@code transferOutboundPlanNo} /
* {@code transferOutboundPlanStatus} / {@code totalQuantity} 这几个字段有用。
* 类型不回传,从请求侧带过去。</p>
*/
@Override
public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) {
YqnDtos.CreateTransferPlanRequest body = YqnTransferMapper.toRequest(cmd);
String raw = execute(ctx, YqnConstants.PATH_TRANSFER_CREATE, body, "warehouse.transfer.create");
com.fasterxml.jackson.databind.JsonNode data = json.nodeAt(raw, "data");
if (data == null || data.isNull() || data.isMissingNode()) {
throw WarehouseException.builder()
.message("yqn create transfer returned no data: " + safeRelay(raw))
.operation("warehouse.transfer.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.rawResponse(safeRelay(raw))
.build();
}
YqnDtos.CreateTransferPlanResponse resp =
json.fromJson(data.toString(), YqnDtos.CreateTransferPlanResponse.class);
return YqnTransferMapper.toOrder(resp, cmd.type(), zoneOf(ctx));
}
// ------------------------------------------------------------------ 退货
/**
* 创建销售退货预约(API 81)。
*
* <p><b>响应只有 code/message,没有单号</b>:所以返回的
* {@code providerReturnId} 是 null。退货的仓侧单号只能靠后续查询或回调补。
* 这会影响「按仓单号做幂等 / 回查」的用法——按文档我们只能用来源单号。</p>
*/
@Override
public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) {
String warehouseCode = firstNonBlank(cmd.warehouseId(), ctx.providerWarehouseId());
YqnDtos.CreateSaleReturnRequest body = YqnReturnMapper.toRequest(cmd, warehouseCode);
execute(ctx, YqnConstants.PATH_RETURN_CREATE, body, "warehouse.return.create");
return YqnReturnMapper.toCreated(cmd, warehouseCode);
}
/**
* 按明细行设置检验后处理方式(API 77)。
*
* <p>运去哪没有退还货条目的「取消 / 撤回」,这里只做处理方式。</p>
*/
@Override
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) {
YqnDtos.SaleReturnProcessRequest body = YqnReturnMapper.toProcessRequest(cmd);
execute(ctx, YqnConstants.PATH_RETURN_PROCESS, body, "warehouse.return.process");
}
/** 退货查询未接入:文档只给了创建(81)与条目处理(77)。 */
@Override
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
@Override
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, String cursor) {
throw new WarehouseUnsupportedCapabilityException(WarehouseCapability.RETURN);
}
// ------------------------------------------------------------------ internals
/** 面单模式必须与仓能力匹配;不支持时拒绝,不静默降级。 */
private void requirePlatformLabelSupported(WarehouseContext ctx, LabelMode mode) {
if (mode == LabelMode.PLATFORM_LABEL && !supports(ctx.warehouseCode(),
WarehouseCapability.PLATFORM_LABEL_DELIVERY)) {
throw WarehouseException.builder()
.message("yqn account does not declare PLATFORM_LABEL_DELIVERY; "
+ "refusing to silently fall back to warehouse label")
.operation("warehouse.outbound.create")
.warehouseCode(ctx.warehouseCode())
.provider(provider().name())
.requestId(ctx.requestId())
.retryable(false)
.build();
}
}
/** 仓方仓编码:命令显式指定优先,否则用账户配置。 */
private static String warehouseId(WarehouseContext ctx, String fromCommand) {
if (fromCommand != null && !fromCommand.trim().isEmpty()) {
return fromCommand.trim();
}
return ctx.providerWarehouseId();
}
private static ZoneId zoneOf(WarehouseContext ctx) {
// 账户时区由 WarehouseAccount 提供;上下文没带时回退北京
return ZoneId.of("Asia/Shanghai");
}
/** 发请求并校验信封。 */
private String execute(WarehouseContext ctx, String path, Object body, String operation) {
rateLimiter.acquire(path, YqnConstants.PERMITS_PER_SECOND);
HttpRequest req = requestFactory.postJson(ctx.endpointBaseUrl(), path,
json.toJson(body), ctx.secret(), ctx, operation);
HttpResponse resp = transport.execute(req);
return YqnEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body();
}
/** 原始响应可能含 PII 与 token,异常里只留长度与首段。 */
private static String safeRelay(String raw) {
if (raw == null) {
return null;
}
return raw.length() <= 300 ? raw : raw.substring(0, 300) + "...";
}
}