package common.ecommerce.xincang.adapter; import common.ecommerce.http.HttpRequest; import common.ecommerce.http.HttpResponse; import common.ecommerce.http.HttpTransport; import common.ecommerce.http.JacksonJsonCodec; import common.ecommerce.http.TokenManager; import common.ecommerce.shared.error.PlatformBusinessException; import common.ecommerce.shared.spi.AccessToken; import common.ecommerce.shared.spi.ChannelSecret; import common.ecommerce.shared.spi.LockProvider; import common.ecommerce.shared.spi.TokenStore; import common.ecommerce.shared.support.Page; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.TransferCapable; import common.ecommerce.warehouse.capability.WarehouseProduct; import common.ecommerce.warehouse.capability.WarehouseProductCapable; import common.ecommerce.warehouse.enums.CancelEligibility; import common.ecommerce.warehouse.enums.OutboundStatus; import common.ecommerce.warehouse.enums.WarehouseCapability; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.error.OutboundCancelBlockedException; import common.ecommerce.warehouse.error.WarehouseException; import common.ecommerce.warehouse.model.CancelCommand; 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.PackageResult; import common.ecommerce.warehouse.model.TransferCommand; import common.ecommerce.warehouse.model.TransferOrder; import common.ecommerce.warehouse.sdk.WarehouseContext; import common.ecommerce.xincang.XincangConstants; import common.ecommerce.xincang.auth.XincangTokenClient; import common.ecommerce.xincang.dto.XincangDtos; import common.ecommerce.xincang.http.XincangEnvelope; import common.ecommerce.xincang.http.XincangMultipart; import common.ecommerce.xincang.http.XincangRateLimiter; import common.ecommerce.xincang.http.XincangRequestFactory; import java.time.Clock; import java.util.EnumSet; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; /** * 信仓适配器。 * *
文档确认的鉴权方式:{@code GET /api.login?appkey=&secret=} 换取客户级 token, * 有效期 2 小时、无 refresh 接口;业务请求把 token 放在 query 参数 {@code token} 里 * (新增 / 更新产品的请求体 schema 里也要求一份,见 {@link XincangRequestFactory})。
* *已实现能力:商品建档 / 更新({@code PRODUCT})、出库下单({@code OUTBOUND})、 * 转运创建 / 审核({@code TRANSFER})。出库的查询 / 取消 / 包裹字段未接入, * 调用会显式抛不支持异常,不返回空集合。
* *适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 * {@code WarehouseConnection} 传入。
*/ public final class XincangAdapter implements WarehouseProductCapable, OutboundCapable, TransferCapable { private static final String OP_PRODUCT_QUERY = "warehouse.product.query"; private static final String OP_PRODUCT_ADD = "warehouse.product.add"; private static final String OP_PRODUCT_UPDATE = "warehouse.product.update"; /** 查重时只取一页;按 SKU 过滤后通常 0~1 条。 */ private static final int PRODUCT_QUERY_LIMIT = 100; /** 信仓产品状态:0 临时产品。 */ private static final String STATE_TEMPORARY = XincangConstants.PRODUCT_STATE_TEMPORARY; private final HttpTransport transport; private final JacksonJsonCodec json; private final XincangTokenClient tokenClient; private final TokenManager tokenManager; private final XincangRequestFactory requestFactory; private final XincangRateLimiter rateLimiter; public XincangAdapter(HttpTransport transport, JacksonJsonCodec json, TokenStore tokenStore, LockProvider lockProvider, Clock clock) { this.transport = transport; this.json = json; this.tokenClient = new XincangTokenClient(transport, json, clock); // 信仓 token 2h、无 refresh 接口:到期前 10 分钟重新登录换取; // TokenManager 负责锁内防击穿与缓存读写,缓存键按 appkey(客户级)。 this.tokenManager = new TokenManager(tokenStore, lockProvider, clock, XincangConstants.TOKEN_EARLY_REFRESH_SECONDS) { @Override protected AccessToken refresh(ChannelSecret secret, AccessToken previous) { return tokenClient.fetch(secret.endpointBaseUrl(), secret.appKey(), secret.appSecret()); } }; this.requestFactory = new XincangRequestFactory(json); this.rateLimiter = new XincangRateLimiter(); } @Override public String adapterId() { return XincangConstants.ADAPTER_ID; } @Override public WarehouseProvider provider() { return WarehouseProvider.XINCANG; } @Override public EnumSet供健康检查与联调探针使用;业务方法接入时也应经此取 token, * 不要在适配器外自行缓存。
* * @throws common.ecommerce.shared.error.AuthException 登录被拒或令牌结构不符合文档 */ public AccessToken login(WarehouseContext ctx) { return tokenManager.getOrRefresh(tokenKey(ctx.secret()), ctx.secret()); } // ------------------------------------------------------------------ 商品 /** * 创建或更新商品。 * *信仓没有 upsert 接口,按「先查临时产品、有则更新、无则新增」实现:
*{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配, * 这里再按 {@code product_no} 精确比对一次。
*/ private XincangDtos.ProductListItem findTemporaryProduct(WarehouseContext ctx, AccessToken token, String sku) { Map信仓下单有两个接口:{@code api.add_order}(一票一件)与 * {@code api.add_order_multiple}(一单多件)。统一模型允许一单多行, * 所以这里固定走多件接口;单行订单也走它。
* *该接口是 {@code multipart/form-data},{@code products} 字段本身是一段 JSON; * 返回的 {@code rst.order_no} 是信仓系统单号({@code DS-...}), * {@code rst.order_id} 是内部 id,优先取单号。
* *查询 / 取消 / 包裹等接口本轮未接入,调用会显式抛不支持异常。
*/ @Override public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { Map信仓按 {@code order_no}(系统单号)或 {@code ckh}(参考号)二选一查询。 * 引用里的 {@code providerOrderId} 优先当作 {@code order_no}, * {@code outboundRequestNo} 当作 {@code ckh}——两者都传时以 provider 侧为准, * 因为只有仓单号能唯一定位。
* *查不到时信仓返回 {@code errno != 0},这里作为业务异常抛出,不返回 null—— * 「查不到」与「查到了但没有数据」对调用方的意义不同。
*/ @Override public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { Map信仓没有独立的取消预判接口,也没有收费取消:按订单详情状态推断。 * 文档「删除订单」的语义是——待审核→删除、待发货→已取消、拣货中/已拣货→已拦截; * 已发货、已取消、已删除、已拦截都不再接受删除,判为 {@link CancelEligibility#BLOCKED}。
* *查询失败时直接抛出,不猜成 FREE——猜错会下发出一个注定被拒的删除请求。
*/ @Override public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { OutboundOrder order = get(ctx, ref); return cancelEligibilityOf(order.status()); } /** * 删除订单({@code POST api.delete_order})。 * *信仓的「删除」按订单状态分流:待审核→删除、待发货→已取消、 * 拣货中/已拣货→已拦截,因此统一模型里映射为 {@link CancelResult}。 * 仓拒绝时按 {@link OutboundCancelBlockedException} 抛出,方便与参数错误区分。
*/ @Override public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { Map只有「尚未进入不可逆阶段」的状态可删;{@link OutboundStatus#UNKNOWN} * 也判为 BLOCKED,避免拿不准就下写请求。
*/ static CancelEligibility cancelEligibilityOf(OutboundStatus status) { if (status == null) { return CancelEligibility.BLOCKED; } switch (status) { case SHIPPED: case CANCELLED: case INTERCEPTED: case DELETED: case UNKNOWN: return CancelEligibility.BLOCKED; default: return CancelEligibility.FREE; } } @Override public List信仓的转运是从信仓发往平台仓,统一模型里用 {@code TransferType.OUTBOUND}。 * 字典字段(订单类型 / 转运类型 / 转运方式 / 标签需求)只接受信仓字典原值, * 由调用方传入,SDK 不做归一。
*/ @Override public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { String productsJson = json.toJson(XincangTransferMapper.products(cmd)); XincangDtos.TransferRequest body = XincangTransferMapper.toRequest(cmd, ctx, productsJson); String raw = execute(ctx, XincangConstants.PATH_TRANSFER_CREATE, body, login(ctx), "warehouse.transfer.create"); XincangDtos.TransferResult result = json.fromJson(raw, XincangDtos.TransferResponse.class).rst; if (result == null || blank(result.orderNo)) { throw WarehouseException.builder() .message("xincang transfer returned no rst.order_no: " + safeRelay(raw)) .operation("warehouse.transfer.create") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return XincangTransferMapper.toCreated(cmd, result.orderNo); } /** * 转运审核({@code POST fba.do_approve?token=&order_no=})。 * *注意是 POST 但无请求体,参数全在 query。
* * @param transferRequestNo 信仓转运单号,即 {@link #create} 返回的 {@code providerTransferNo} */ @Override public void approve(WarehouseContext ctx, String transferRequestNo) { Map信仓只允许待审核状态删除,其余状态由仓方拒绝(errno != 0), * 这里原样抛出业务异常,不擅自退化成「取消」。
*/ @Override public void deleteTransfer(WarehouseContext ctx, String providerTransferNo) { if (blank(providerTransferNo)) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.delete", "providerTransferNo must not be blank"); } Map用 appkey 而不是 {@code warehouseCode},避免同客户多仓重复登录。
*/ static String tokenKey(ChannelSecret secret) { return XincangConstants.ADAPTER_ID + ":" + secret.appKey(); } private static boolean blank(String v) { return v == null || v.trim().isEmpty(); } /** 原始响应可能含收件人信息,异常里只留首段。 */ private static String safeRelay(String raw) { if (raw == null) { return null; } return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; } }