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.InboundCapable; import common.ecommerce.warehouse.capability.InventoryCapable; import common.ecommerce.warehouse.capability.OutboundCapable; import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; import common.ecommerce.warehouse.capability.WarehouseChannelRecommendCapable; 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.InventorySyncStrategy; 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.ChannelRecommendQuery; import common.ecommerce.warehouse.model.InventoryAgeQuery; import common.ecommerce.warehouse.model.InventoryAgeRecord; 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.WarehouseFacility; import common.ecommerce.warehouse.model.InventorySnapshot; import common.ecommerce.warehouse.model.ChannelRecommendResult; import common.ecommerce.warehouse.model.CancelResult; import common.ecommerce.warehouse.model.OutboundCommand; import common.ecommerce.warehouse.model.ProductInfo; import common.ecommerce.warehouse.model.ProductQuery; 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.XincangChannelRecommendDtos; import common.ecommerce.xincang.dto.XincangForecastCreateDtos; import common.ecommerce.xincang.dto.XincangForecastDetailDtos; import common.ecommerce.xincang.dto.XincangForecastImproveDtos; import common.ecommerce.xincang.dto.XincangLogisticsDtos; import common.ecommerce.xincang.dto.XincangOrderCreateDtos; import common.ecommerce.xincang.dto.XincangOrderDetailDtos; import common.ecommerce.xincang.dto.XincangProductListDtos; import common.ecommerce.xincang.dto.XincangProductSaveDtos; import common.ecommerce.xincang.dto.XincangStockAgeListDtos; import common.ecommerce.xincang.dto.XincangStockListDtos; import common.ecommerce.xincang.dto.XincangTransferCreateDtos; import common.ecommerce.xincang.dto.XincangTransferDetailDtos; import common.ecommerce.xincang.dto.XincangWarehouseDtos; 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.time.Instant; import java.util.ArrayList; 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, WarehouseChannelRecommendCapable, InventoryCapable, InboundCapable, WarehouseDirectoryCapable { 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; } /** 默认连生产环境;联调请在账户上配置 {@code endpointBaseUrl} 覆盖。 */ @Override public String defaultEndpointBaseUrl() { return common.ecommerce.xincang.XincangConstants.PRODUCTION_BASE_URL; } @Override public EnumSet capabilities() { return EnumSet.of(WarehouseCapability.PRODUCT, WarehouseCapability.OUTBOUND, WarehouseCapability.TRANSFER, WarehouseCapability.SPLIT, WarehouseCapability.CHANNEL_RECOMMEND, WarehouseCapability.INVENTORY_QUERY, WarehouseCapability.INBOUND, WarehouseCapability.DIRECTORY); } /** * 取一个可用 token(缓存命中则不登录)。 * *

供健康检查与联调探针使用;业务方法接入时也应经此取 token, * 不要在适配器外自行缓存。

* * @throws common.ecommerce.shared.error.AuthException 登录被拒或令牌结构不符合文档 */ public AccessToken login(WarehouseContext ctx) { return tokenManager.getOrRefresh(tokenKey(ctx.secret()), ctx.secret()); } // ------------------------------------------------------------------ 商品 /** * 创建或更新商品。 * *

信仓没有 upsert 接口,按「先查临时产品、有则更新、无则新增」实现:

* * * @return {@code status} 为 {@code ADDED} / {@code UPDATED},{@code rawStatus} 为信仓产品状态码 * @throws PlatformBusinessException 信仓业务失败(SKU / 条码重复、参数不合法等) */ @Override public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) { AccessToken token = login(ctx); XincangProductSaveDtos.ProductRequest body = XincangProductMapper.toRequest(product, token.value()); boolean existsAsTemporary = findTemporaryProduct(ctx, token, body.productNo) != null; if (existsAsTemporary) { execute(ctx, XincangConstants.PATH_PRODUCT_UPDATE, body, token, OP_PRODUCT_UPDATE); return ProductResult.of(body.productNo, "UPDATED", STATE_TEMPORARY); } execute(ctx, XincangConstants.PATH_PRODUCT_ADD, body, token, OP_PRODUCT_ADD); return ProductResult.of(body.productNo, "ADDED", STATE_TEMPORARY); } /** * 查该 SKU 是否已是临时产品。 * *

{@code api.productlist} 的 {@code key} 是 SKU 过滤条件,但文档没说是否精确匹配, * 这里再按 {@code product_no} 精确比对一次。

*/ private XincangProductListDtos.ProductItem findTemporaryProduct(WarehouseContext ctx, AccessToken token, String sku) { Map params = new LinkedHashMap<>(); params.put("state", 0); params.put("page", 1); params.put("limit", PRODUCT_QUERY_LIMIT); params.put("key", sku); String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token, OP_PRODUCT_QUERY); List items = json.listAt(raw, "rst.data", XincangProductListDtos.ProductItem.class); for (XincangProductListDtos.ProductItem item : items) { if (sku.equals(item.productNo)) { return item; } } return null; } /** * 分页查商品({@code GET api.productlist})。只读,不走幂等。 * *

{@code token} / {@code state} / {@code page} / {@code limit} 四项仓方必填, * 适配器固定传 {@code state=1}(正式产品)——临时产品是建档中间态, * 混进业务列表会让人以为能下单。

* *

只支持按单个 SKU 过滤:信仓的 {@code key} 是单值。传多个时拒绝, * 静默只取第一个会让调用方以为其余也查了,而它们缺席看起来像「仓里没有」。

* *

响应同时给厘米/英寸两套尺寸、千克/磅两套重量,统一模型是 cm/g, * 映射时直接用厘米那套,不做二次换算。

*/ @Override public Page query(WarehouseContext ctx, ProductQuery query) { AccessToken token = login(ctx); Map params = XincangProductQueryMapper.toParams(query); String raw = executeGet(ctx, XincangConstants.PATH_PRODUCT_LIST, params, token, OP_PRODUCT_QUERY); XincangProductListDtos.ProductListResponse resp = json.fromJson(raw, XincangProductListDtos.ProductListResponse.class); return XincangProductQueryMapper.toPage(resp == null ? null : resp.rst, query.cursor(), XincangProductQueryMapper.limitOf(query.pageSize())); } // ------------------------------------------------------------------ 出库 /** * 下发出库单(一单多件)。 * *

信仓下单有两个接口:{@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 form = XincangOrderMapper.toForm(ctx, cmd, json); String raw = executeMultipart(ctx, XincangConstants.PATH_ORDER_ADD_MULTIPLE, form, "warehouse.outbound.create"); XincangOrderCreateDtos.OrderResult result = json.fromJson(raw, XincangOrderCreateDtos.OrderResponse.class).rst; if (result == null || blank(result.orderNo)) { throw WarehouseException.builder() .message("xincang create order returned no rst.order_no: " + 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(), result.orderNo, null); } /** * 查订单详情({@code GET api.get_order})。 * *

信仓按 {@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 params = new LinkedHashMap(); if (!blank(ref.providerOrderId())) { params.put("order_no", ref.providerOrderId()); } else if (!blank(ref.outboundRequestNo())) { params.put("ckh", ref.outboundRequestNo()); } String raw = executeGet(ctx, XincangConstants.PATH_ORDER_DETAIL, params, login(ctx), "warehouse.outbound.get"); XincangOrderDetailDtos.OrderDetail detail = json.fromJson(raw, XincangOrderDetailDtos.OrderDetailResponse.class).rst; if (detail == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.outbound.get", "xincang get_order returned no rst"); } return XincangOrderDetailMapper.toOrder(detail, ctx); } @Override public Page query(WarehouseContext ctx, OutboundQuery query) { throw XincangUnsupportedOutbound.queryUnsupported(ctx); } /** * 取消资格预判。 * *

信仓没有独立的取消预判接口,也没有收费取消:按订单详情状态推断。 * 文档「删除订单」的语义是——待审核→删除、待发货→已取消、拣货中/已拣货→已拦截; * 已发货、已取消、已删除、已拦截都不再接受删除,判为 {@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 params = new LinkedHashMap(); if (!blank(cmd.providerOrderId())) { params.put("order_no", cmd.providerOrderId()); } else if (!blank(cmd.outboundRequestNo())) { params.put("ckh", cmd.outboundRequestNo()); } try { executePostQuery(ctx, XincangConstants.PATH_ORDER_DELETE, params, "warehouse.outbound.cancel"); } catch (PlatformBusinessException e) { // 信仓失败只回 err 文本,无法细分原因;取消场景统一按「不可取消」表达 throw new OutboundCancelBlockedException(WarehouseException.builder() .message("xincang refused order deletion: " + 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) .build(); } /** * 取消资格映射。 * *

只有「尚未进入不可逆阶段」的状态可删;{@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 packages(WarehouseContext ctx, OutboundRef ref) { throw XincangUnsupportedOutbound.packagesUnsupported(ctx); } // ------------------------------------------------------------------ 调拨 / 转运 /** * 新增转运({@code POST fba.do_fba})。 * *

信仓的转运是从信仓发往平台仓,统一模型里用 {@code TransferType.OUTBOUND}。 * 字典字段(订单类型 / 转运类型 / 转运方式 / 标签需求)只接受信仓字典原值, * 由调用方传入,SDK 不做归一。

*/ @Override public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { String productsJson = json.toJson(XincangTransferMapper.products(cmd)); XincangTransferCreateDtos.TransferRequest body = XincangTransferMapper.toRequest(cmd, ctx, productsJson); String raw = execute(ctx, XincangConstants.PATH_TRANSFER_CREATE, body, login(ctx), "warehouse.transfer.create"); XincangTransferCreateDtos.TransferResult result = json.fromJson(raw, XincangTransferCreateDtos.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 params = new LinkedHashMap(); params.put("order_no", transferRequestNo); executePostQuery(ctx, XincangConstants.PATH_TRANSFER_APPROVE, params, "warehouse.transfer.approve"); } /** * 转运详情({@code GET fba.fba_detail})。 * * @param providerTransferNo 信仓转运单号 {@code order_no} */ @Override public TransferOrder getTransfer(WarehouseContext ctx, String providerTransferNo) { if (blank(providerTransferNo)) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get", "providerTransferNo must not be blank"); } Map params = new LinkedHashMap(); params.put("order_no", providerTransferNo); String raw = executeGet(ctx, XincangConstants.PATH_TRANSFER_DETAIL, params, login(ctx), "warehouse.transfer.get"); XincangTransferDetailDtos.TransferDetail detail = json.fromJson(raw, XincangTransferDetailDtos.TransferDetailResponse.class).rst; if (detail == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.transfer.get", "xincang fba_detail returned no rst"); } return XincangTransferDetailMapper.toOrder(detail); } /** * 删除转运({@code POST fba.delete_fba})。 * *

信仓只允许待审核状态删除,其余状态由仓方拒绝(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 params = new LinkedHashMap(); params.put("order_no", providerTransferNo); executePostQuery(ctx, XincangConstants.PATH_TRANSFER_DELETE, params, "warehouse.transfer.delete"); } // ------------------------------------------------------------------ 基础资料 /** * 客户名下所有仓库({@code GET api.get_customer_warehouses})。 * *

返回的 {@code warehouse_code} 可直接用于下单、库存查询等接口。

*/ @Override public List warehouses(WarehouseContext ctx) { String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_WAREHOUSES, new LinkedHashMap(), login(ctx), "warehouse.directory.warehouses"); XincangWarehouseDtos.WarehouseListResult rst = json.fromJson(raw, XincangWarehouseDtos.WarehouseListResponse.class).rst; if (rst == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.warehouses", "xincang get_customer_warehouses returned no rst"); } List out = new ArrayList(); if (rst.data != null) { for (XincangWarehouseDtos.WarehouseListResult.WarehouseRow row : rst.data) { if (row == null || XincangForecastMapper.blank(row.warehouseCode)) { continue; } out.add(WarehouseFacility.builder() .providerWarehouseId(XincangForecastMapper.blankToNull(row.id)) .warehouseCode(row.warehouseCode.trim()) .country(XincangForecastMapper.blankToNull(row.country)) .province(XincangForecastMapper.blankToNull(row.province)) .city(XincangForecastMapper.blankToNull(row.city)) .street(XincangForecastMapper.blankToNull(row.street)) .postcode(XincangForecastMapper.blankToNull(row.postcode)) .build()); } } return out; } /** * 客户可用的承运商({@code GET api.get_customer_logistics})。 * *

返回的 {@code logistics_type} 可直接作为下单的 {@code carrierCode}。

*/ @Override public List carriers(WarehouseContext ctx) { String raw = executeGet(ctx, XincangConstants.PATH_CUSTOMER_LOGISTICS, new LinkedHashMap(), login(ctx), "warehouse.directory.carriers"); XincangLogisticsDtos.LogisticsListResult rst = json.fromJson(raw, XincangLogisticsDtos.LogisticsListResponse.class).rst; if (rst == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.directory.carriers", "xincang get_customer_logistics returned no rst"); } List out = new ArrayList(); if (rst.data != null) { for (XincangLogisticsDtos.LogisticsListResult.LogisticsRow row : rst.data) { if (row != null && !XincangForecastMapper.blank(row.logisticsType)) { out.add(row.logisticsType.trim()); } } } return out; } // ------------------------------------------------------------------ 头程预报 /** * 创建入库单(信仓「新增预报」,{@code POST forecast.do_forecast})。 * *

信仓把入库拆成两步:这里只建空单,商品明细要再调 {@link #improve} 补; * 两条命令共用 {@link InboundCommand},所以这里只取单头字段。

*/ @Override public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { XincangForecastCreateDtos.ForecastCreateRequest body = XincangForecastMapper.toCreateRequest(cmd, ctx); String raw = execute(ctx, XincangConstants.PATH_FORECAST_CREATE, body, login(ctx), "warehouse.inbound.create"); XincangForecastCreateDtos.ForecastCreateResult result = json.fromJson(raw, XincangForecastCreateDtos.ForecastCreateResponse.class).rst; if (result == null || blank(result.orderNo)) { throw WarehouseException.builder() .message("xincang forecast returned no rst.order_no: " + safeRelay(raw)) .operation("warehouse.inbound.create") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false) .rawResponse(safeRelay(raw)) .build(); } return InboundReceipt.of(cmd.inboundRequestNo(), result.orderNo); } /** * 完善资料({@code POST forecast.do_improve_forecast})。 * *

商品明细是 JSON 字符串,新数据直接覆盖旧数据。

*/ @Override public void improve(WarehouseContext ctx, String inboundRef, InboundCommand cmd) { String productsJson = json.toJson(XincangForecastMapper.products(cmd)); XincangForecastImproveDtos.ForecastImproveRequest body = XincangForecastMapper.toImproveRequest(cmd, inboundRef, productsJson, ctx); execute(ctx, XincangConstants.PATH_FORECAST_IMPROVE, body, login(ctx), "warehouse.inbound.improve"); } /** * 预报提交({@code POST forecast.done_forecast})。 * *

文档同时要求 query 与 body 里都有 {@code forecast_no},这里两处都带。

*/ @Override public void submit(WarehouseContext ctx, String inboundRef) { if (blank(inboundRef)) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.submit", "forecast_no must not be blank"); } Map params = new LinkedHashMap(); params.put("forecast_no", inboundRef); Map body = new LinkedHashMap(); body.put("forecast_no", inboundRef); executePostQueryWithBody(ctx, XincangConstants.PATH_FORECAST_SUBMIT, params, body, "warehouse.inbound.submit"); } /** * 预报详情({@code GET forecast.forecast_detail})。 * * @param inboundRef 预报单号({@code forecast_no}) */ @Override public InboundOrder get(WarehouseContext ctx, String inboundRef) { if (blank(inboundRef)) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.get", "forecast_no must not be blank"); } Map params = new LinkedHashMap(); params.put("forecast_no", inboundRef); String raw = executeGet(ctx, XincangConstants.PATH_FORECAST_DETAIL, params, login(ctx), "warehouse.inbound.get"); XincangForecastDetailDtos.ForecastDetail detail = json.fromJson(raw, XincangForecastDetailDtos.ForecastDetailResponse.class).rst; if (detail == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.get", "xincang forecast_detail returned no rst"); } return XincangForecastMapper.toOrder(detail, ctx); } /** * 分页查入库单:信仓只有「按单号取详情」,没有列表接口。 * *

因此 {@code cursor} 按预报单号解释,返回 0 或 1 条;不传单号直接拒绝, * 避免被误当成增量同步入口。

*/ @Override public Page query(WarehouseContext ctx, String cursor) { if (blank(cursor)) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inbound.query", "xincang has no forecast list API; pass forecast_no as cursor"); } return XincangForecastMapper.singlePage(get(ctx, cursor)); } // ------------------------------------------------------------------ 库存 /** * 库存同步策略:信仓只能按页全量拉,没有按时间增量的参数。 * *

宿主按本值决定落库策略,不要按 {@code updatedAfter} 做增量。

*/ @Override public InventorySyncStrategy syncStrategy() { return InventorySyncStrategy.FULL_PULL_DIFF; } /** * 实时库存({@code GET api.stocklist})。 * *

信仓只支持单个 {@code warehouse_code};调用方传多个仓会显式拒绝, * 不静默只查第一个。{@code updatedAfter} 被忽略——该接口没有时间维度。

*/ @Override public Page query(WarehouseContext ctx, InventoryQuery query) { if (query.updatedAfter() != null) { throw new common.ecommerce.shared.error.ValidationException( WarehouseException.builder() .message("xincang inventory has no updatedAfter filter; full-pull and diff instead") .operation("warehouse.inventory.query") .warehouseCode(ctx.warehouseCode()) .provider(provider().name()) .requestId(ctx.requestId()) .retryable(false)); } Map params = XincangInventoryMapper.toStockParams(query, ctx.providerWarehouseId()); String raw = executeGet(ctx, XincangConstants.PATH_STOCK_LIST, params, login(ctx), "warehouse.inventory.query"); XincangStockListDtos.StockListResult rst = json.fromJson(raw, XincangStockListDtos.StockListResponse.class).rst; if (rst == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.query", "xincang stocklist returned no rst"); } int page = XincangInventoryMapper.pageNumber(query.cursor()); int size = XincangInventoryMapper.pageSize(query.pageSize()); return XincangInventoryMapper.toSnapshots(rst, ctx.providerWarehouseId(), Instant.now(ctx.clock()), page, size); } /** * 库龄列表({@code GET api.stockagelist})。 * *

按计费日期区间查;{@code bill_date} 是「起 - 止」单值字符串。

*/ @Override public Page queryAges(WarehouseContext ctx, InventoryAgeQuery query) { Map params = XincangInventoryMapper.toAgeParams(query, ctx.providerWarehouseId()); String raw = executeGet(ctx, XincangConstants.PATH_STOCK_AGE_LIST, params, login(ctx), "warehouse.inventory.ages"); XincangStockAgeListDtos.StockAgeListResult rst = json.fromJson(raw, XincangStockAgeListDtos.StockAgeListResponse.class).rst; if (rst == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.inventory.ages", "xincang stockagelist returned no rst"); } int page = XincangInventoryMapper.pageNumber(query.cursor()); int size = XincangInventoryMapper.pageSize(query.pageSize()); return XincangInventoryMapper.toAgeRecords(rst, ctx.providerWarehouseId(), page, size); } // ------------------------------------------------------------------ 最优渠道 /** * 最优渠道({@code api.calculate_order_v3})。 * *

按 SKU + 邮编让仓给出推荐仓 / 渠道与全部报价,两层结果都保留。

* *

协议待核对:文档写 GET + JSON body,OkHttp 不支持 GET 带 body, * 这里按 POST + JSON body 下发,见 {@code XincangConstants.PATH_CHANNEL_RECOMMEND}。

*/ @Override public ChannelRecommendResult recommend(WarehouseContext ctx, ChannelRecommendQuery query) { XincangChannelRecommendDtos.CalculateV3Request body = XincangChannelRecommendMapper.toRequest(query); String raw = execute(ctx, XincangConstants.PATH_CHANNEL_RECOMMEND, body, login(ctx), "warehouse.channel.recommend"); XincangChannelRecommendDtos.CalculateV3Result rst = json.fromJson(raw, XincangChannelRecommendDtos.CalculateV3Response.class).rst; if (rst == null) { throw XincangUnsupportedOutbound.businessError(ctx, "warehouse.channel.recommend", "xincang calculate_order_v3 returned no rst"); } return XincangChannelRecommendMapper.toResult(rst); } // ------------------------------------------------------------------ internals /** 写接口:JSON 请求体(含 token)+ query token。 */ private String execute(WarehouseContext ctx, String path, Object body, AccessToken token, String operation) { rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.postJsonWithToken(ctx.endpointBaseUrl(), path, json.toJson(body), token.value(), operation); HttpResponse resp = transport.execute(req); return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } /** 写接口:multipart 表单 + query token(信仓一单多件下单)。 */ private String executeMultipart(WarehouseContext ctx, String path, Map form, String operation) { rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); HttpRequest req = XincangMultipart.post(ctx.endpointBaseUrl(), path, form, login(ctx).value(), operation); HttpResponse resp = transport.execute(req); return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } /** POST:query 与 JSON body 各放一份参数(预报提交要求两处都有)。 */ private String executePostQueryWithBody(WarehouseContext ctx, String path, Map params, Map body, String operation) { rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); Map query = new LinkedHashMap(); if (params != null) { query.putAll(params); } String token = login(ctx).value(); query.put(XincangConstants.QUERY_TOKEN, token); HttpRequest req = requestFactory.postJsonWithToken(ctx.endpointBaseUrl(), path, json.toJson(body), token, operation); HttpRequest withQuery = req.toBuilder() .url(ctx.endpointBaseUrl() + path + "?" + XincangRequestFactory.queryString(query)) .build(); HttpResponse resp = transport.execute(withQuery); return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } /** POST 但无请求体:参数全在 query(转运审核)。 */ private String executePostQuery(WarehouseContext ctx, String path, Map params, String operation) { rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.postWithoutBodyWithToken(ctx.endpointBaseUrl(), path, params, login(ctx).value(), operation); HttpResponse resp = transport.execute(req); return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } /** 读接口:query token。 */ private String executeGet(WarehouseContext ctx, String path, Map params, AccessToken token, String operation) { rateLimiter.acquire(path, XincangConstants.PERMITS_PER_SECOND); HttpRequest req = requestFactory.getWithToken(ctx.endpointBaseUrl(), path, params, token.value(), operation); HttpResponse resp = transport.execute(req); return XincangEnvelope.of(resp, json, operation, ctx.requestId()).body(); } /** * 令牌缓存维度:信仓 token 按客户(appkey)发放,同一 appkey 下多仓共用一个 token。 * *

用 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) + "..."; } }