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.
1870 lines
93 KiB
1870 lines
93 KiB
package common.ecommerce.hengjian.adapter; |
|
|
|
import com.fasterxml.jackson.databind.JsonNode; |
|
import common.ecommerce.hengjian.dto.HengjianAddressClassificationDtos; |
|
import common.ecommerce.hengjian.dto.HengjianCancelOrderDtos; |
|
import common.ecommerce.hengjian.dto.HengjianCarrierGroupDtos; |
|
import common.ecommerce.hengjian.dto.HengjianBoxLabelDtos; |
|
import common.ecommerce.hengjian.dto.HengjianCreateOrderDtos; |
|
import common.ecommerce.hengjian.dto.HengjianDestructionDtos; |
|
import common.ecommerce.hengjian.dto.HengjianFeeEstimateDtos; |
|
import common.ecommerce.hengjian.dto.HengjianInventoryDtos; |
|
import common.ecommerce.hengjian.dto.HengjianInboundCreateDtos; |
|
import common.ecommerce.hengjian.dto.HengjianInboundQueryDtos; |
|
import common.ecommerce.hengjian.dto.HengjianInventoryMovementDtos; |
|
import common.ecommerce.hengjian.dto.HengjianReturnDetailDtos; |
|
import common.ecommerce.hengjian.dto.HengjianReturnHandleDtos; |
|
import common.ecommerce.hengjian.dto.HengjianReturnListDtos; |
|
import common.ecommerce.hengjian.dto.HengjianReturnPlanCreateDtos; |
|
import common.ecommerce.hengjian.dto.HengjianTransferDtos; |
|
import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; |
|
import common.ecommerce.hengjian.dto.HengjianOrderDetailDtos; |
|
import common.ecommerce.hengjian.dto.HengjianOrderAttachmentDtos; |
|
import common.ecommerce.hengjian.dto.HengjianOrderListDtos; |
|
import common.ecommerce.hengjian.dto.HengjianProductQueryDtos; |
|
import common.ecommerce.hengjian.dto.HengjianProductSaveDtos; |
|
import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos; |
|
import common.ecommerce.hengjian.dto.HengjianTailDeliveryFeeDtos; |
|
import common.ecommerce.hengjian.dto.HengjianTrackingChangeDtos; |
|
import common.ecommerce.hengjian.dto.HengjianTrackingChangeQueryDtos; |
|
import common.ecommerce.hengjian.dto.HengjianWarehouseDtos; |
|
import common.ecommerce.hengjian.HengjianConstants; |
|
import common.ecommerce.hengjian.http.HengjianEnvelope; |
|
import common.ecommerce.hengjian.http.HengjianRateLimiter; |
|
import common.ecommerce.hengjian.http.HengjianRequestFactory; |
|
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.capability.AddressClassificationCapable; |
|
import common.ecommerce.warehouse.capability.DestructionCapable; |
|
import common.ecommerce.warehouse.capability.InboundCapable; |
|
import common.ecommerce.warehouse.capability.InventoryCapable; |
|
import common.ecommerce.warehouse.capability.TransferCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseReturnCapable; |
|
import common.ecommerce.warehouse.capability.LogisticsProductCapable; |
|
import common.ecommerce.warehouse.capability.OutboundCapable; |
|
import common.ecommerce.warehouse.capability.TrackingChangeCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseDirectoryCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseFeeCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseFeeEstimateCapable; |
|
import common.ecommerce.warehouse.capability.WarehouseProductCapable; |
|
import common.ecommerce.warehouse.enums.AddressType; |
|
import common.ecommerce.warehouse.enums.CancelEligibility; |
|
import common.ecommerce.warehouse.enums.InventorySyncStrategy; |
|
import common.ecommerce.warehouse.enums.ReturnStatus; |
|
import common.ecommerce.warehouse.enums.LabelMode; |
|
import common.ecommerce.warehouse.enums.TrackingChangeHandleType; |
|
import common.ecommerce.warehouse.enums.WarehouseCapability; |
|
import common.ecommerce.warehouse.enums.SortDirection; |
|
import common.ecommerce.warehouse.enums.WarehouseFeeType; |
|
import common.ecommerce.warehouse.enums.WarehouseProvider; |
|
import common.ecommerce.warehouse.error.OutboundCancelBlockedException; |
|
import common.ecommerce.warehouse.error.WarehouseException; |
|
import common.ecommerce.warehouse.model.BillingDocument; |
|
import common.ecommerce.warehouse.model.CancelCommand; |
|
import common.ecommerce.warehouse.model.BoxLabelCommand; |
|
import common.ecommerce.warehouse.model.DestructionCommand; |
|
import common.ecommerce.warehouse.model.DestructionOrder; |
|
import common.ecommerce.warehouse.model.CancelResult; |
|
import common.ecommerce.warehouse.model.FeeEstimateQuery; |
|
import common.ecommerce.warehouse.model.FeeEstimateResult; |
|
import common.ecommerce.warehouse.model.FeeQuery; |
|
import common.ecommerce.warehouse.model.InboundCommand; |
|
import common.ecommerce.warehouse.model.InboundOrder; |
|
import common.ecommerce.warehouse.model.InboundQuery; |
|
import common.ecommerce.warehouse.model.InboundReceipt; |
|
import common.ecommerce.warehouse.model.InventoryMovement; |
|
import common.ecommerce.warehouse.model.LabelPrintTask; |
|
import common.ecommerce.warehouse.model.InventoryMovementQuery; |
|
import common.ecommerce.warehouse.model.InventoryQuery; |
|
import common.ecommerce.warehouse.model.InventorySnapshot; |
|
import common.ecommerce.warehouse.model.TransferCommand; |
|
import common.ecommerce.warehouse.model.TransferOrder; |
|
import common.ecommerce.warehouse.model.ReturnCommand; |
|
import common.ecommerce.warehouse.model.ReturnHandle; |
|
import common.ecommerce.warehouse.model.ReturnProcessCommand; |
|
import common.ecommerce.warehouse.model.ReturnQuery; |
|
import common.ecommerce.warehouse.model.TransferQuery; |
|
import common.ecommerce.warehouse.model.WarehouseAttachment; |
|
import common.ecommerce.warehouse.model.WarehouseReturn; |
|
import common.ecommerce.warehouse.model.LogisticsProduct; |
|
import common.ecommerce.warehouse.model.OutboundCommand; |
|
import common.ecommerce.warehouse.model.OutboundOrder; |
|
import common.ecommerce.warehouse.model.OutboundQuery; |
|
import common.ecommerce.warehouse.capability.WarehouseProduct; |
|
import common.ecommerce.warehouse.model.ProductInfo; |
|
import common.ecommerce.warehouse.model.ProductQuery; |
|
import common.ecommerce.warehouse.model.OutboundReceipt; |
|
import common.ecommerce.warehouse.model.OutboundRef; |
|
import common.ecommerce.warehouse.model.PackageResult; |
|
import common.ecommerce.warehouse.model.TrackingChangeCommand; |
|
import common.ecommerce.warehouse.model.TrackingChangeOrder; |
|
import common.ecommerce.warehouse.model.WarehouseFacility; |
|
import common.ecommerce.warehouse.sdk.WarehouseContext; |
|
|
|
import java.time.ZoneOffset; |
|
import java.util.ArrayList; |
|
import java.util.EnumSet; |
|
import java.util.Iterator; |
|
import java.util.LinkedHashMap; |
|
import java.util.List; |
|
import java.util.Map; |
|
|
|
/** |
|
* 恒健适配器。 |
|
* |
|
* <p><b>已接入</b>:仓库目录、承运商 / 物流产品、按仓的物流渠道(只读), |
|
* 以及商品创建 / 编辑({@code /v1/product/save},保存语义)。</p> |
|
* |
|
* <p>出库 / 库存 / 入库 / 退货等接口<b>尚未接入</b>,能力位不声明: |
|
* 门面调用会显式抛 {@code WarehouseUnsupportedCapabilityException},不返回空集合。</p> |
|
* |
|
* <p>适配器只持有协议与基础设施,不持有端点与凭据——两者随每次调用经 |
|
* {@code WarehouseConnection} 传入。</p> |
|
*/ |
|
public final class HengjianAdapter implements WarehouseDirectoryCapable, LogisticsProductCapable, |
|
WarehouseProductCapable, OutboundCapable, TrackingChangeCapable, WarehouseFeeCapable, |
|
WarehouseFeeEstimateCapable, AddressClassificationCapable, InventoryCapable, |
|
InboundCapable, TransferCapable, WarehouseReturnCapable, DestructionCapable { |
|
|
|
private static final String OP_WAREHOUSE_LIST = "warehouse.directory.warehouses"; |
|
private static final String OP_CARRIERS = "warehouse.directory.carriers"; |
|
private static final String OP_LOGISTICS_PRODUCTS = "warehouse.logistics.products"; |
|
private static final String OP_PRODUCT_SAVE = "warehouse.product.create"; |
|
private static final String OP_PRODUCT_QUERY = "warehouse.product.query"; |
|
private static final String OP_ORDER_CREATE = "warehouse.outbound.create"; |
|
private static final String OP_ORDER_GET = "warehouse.outbound.get"; |
|
private static final String OP_ORDER_QUERY = "warehouse.outbound.query"; |
|
private static final String OP_ORDER_CANCEL = "warehouse.outbound.cancel"; |
|
private static final String OP_ORDER_ATTACHMENT = "warehouse.outbound.attachment"; |
|
private static final String OP_TRACKING_CHANGE_CREATE = "warehouse.tracking.change.create"; |
|
private static final String OP_TRACKING_CHANGE_GET = "warehouse.tracking.change.get"; |
|
private static final String OP_FEE_STORAGE = "warehouse.fee.storage"; |
|
private static final String OP_FEE_TAIL_DELIVERY = "warehouse.fee.tailDelivery"; |
|
private static final String OP_FEE_OPERATION = "warehouse.fee.operation"; |
|
private static final String OP_FEE_ESTIMATE = "warehouse.fee.estimate"; |
|
private static final String OP_ADDRESS_CLASSIFY = "warehouse.address.classify"; |
|
private static final String OP_INVENTORY_QUERY = "warehouse.inventory.query"; |
|
private static final String OP_INVENTORY_MOVEMENTS = "warehouse.inventory.movements"; |
|
private static final String OP_INBOUND_CREATE = "warehouse.inbound.create"; |
|
private static final String OP_INBOUND_GET = "warehouse.inbound.get"; |
|
private static final String OP_INBOUND_QUERY = "warehouse.inbound.query"; |
|
private static final String OP_INBOUND_BOX_LABEL = "warehouse.inbound.boxLabel"; |
|
private static final String OP_TRANSFER_CREATE = "warehouse.transfer.create"; |
|
private static final String OP_TRANSFER_QUERY = "warehouse.transfer.query"; |
|
private static final String OP_TRANSFER_CANCEL = "warehouse.transfer.cancel"; |
|
private static final String OP_RETURN_CREATE = "warehouse.return.create"; |
|
private static final String OP_DESTRUCTION_CREATE = "warehouse.destruction.create"; |
|
private static final String OP_DESTRUCTION_GET = "warehouse.destruction.get"; |
|
private static final String OP_RETURN_GET = "warehouse.return.get"; |
|
private static final String OP_RETURN_QUERY = "warehouse.return.query"; |
|
/** 退货列表的时间窗格式(恒健文档:{@code yyyy-MM-dd HH:mm:ss},UTC)。 */ |
|
private static final java.time.format.DateTimeFormatter HENGJIAN_TIME = |
|
java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss"); |
|
/** 恒健 {@code queryType}:来源单号。 */ |
|
private static final String QUERY_TYPE_SOURCE_NO = "2"; |
|
/** 恒健 {@code queryType}:退货 tracking。 */ |
|
private static final String QUERY_TYPE_TRACKING = "4"; |
|
private static final String OP_RETURN_HANDLES = "warehouse.return.handles"; |
|
private static final String OP_RETURN_PROCESS = "warehouse.return.process"; |
|
/** 退货列表默认页大小(文档没写,按同站惯例 100)。 */ |
|
private static final int PAGE_SIZE_DEFAULT = 100; |
|
/** 退货处理单列表默认页大小(文档写默认 20)。 */ |
|
private static final int HANDLE_PAGE_SIZE_DEFAULT = 20; |
|
/** 保存语义没有 create / update 之分,仓方也不回是哪种。 */ |
|
private static final String SAVED = "SAVED"; |
|
|
|
private final HttpTransport transport; |
|
private final JacksonJsonCodec json; |
|
private final HengjianRequestFactory requestFactory; |
|
private final HengjianRateLimiter rateLimiter; |
|
|
|
public HengjianAdapter(HttpTransport transport, JacksonJsonCodec json) { |
|
this.transport = transport; |
|
this.json = json; |
|
this.requestFactory = new HengjianRequestFactory(json); |
|
this.rateLimiter = new HengjianRateLimiter(); |
|
} |
|
|
|
@Override |
|
public String adapterId() { |
|
return HengjianConstants.ADAPTER_ID; |
|
} |
|
|
|
@Override |
|
public WarehouseProvider provider() { |
|
return WarehouseProvider.HENGJIAN; |
|
} |
|
|
|
/** 默认连生产环境;联调请在账户上配置 {@code endpointBaseUrl} 覆盖。 */ |
|
@Override |
|
public String defaultEndpointBaseUrl() { |
|
return common.ecommerce.hengjian.HengjianConstants.PRODUCTION_BASE_URL; |
|
} |
|
|
|
@Override |
|
public EnumSet<WarehouseCapability> capabilities() { |
|
return EnumSet.of( |
|
WarehouseCapability.PRODUCT, |
|
WarehouseCapability.OUTBOUND, |
|
WarehouseCapability.PLATFORM_LABEL_DELIVERY, |
|
WarehouseCapability.TRACKING_CHANGE, |
|
WarehouseCapability.INVENTORY_QUERY, |
|
WarehouseCapability.INBOUND, |
|
WarehouseCapability.BOX_LABEL, |
|
WarehouseCapability.TRANSFER, |
|
WarehouseCapability.RETURN, |
|
WarehouseCapability.DESTRUCTION, |
|
WarehouseCapability.FEE_SETTLEMENT, |
|
WarehouseCapability.FEE_ESTIMATE, |
|
WarehouseCapability.ADDRESS_CLASSIFICATION, |
|
WarehouseCapability.DIRECTORY, |
|
WarehouseCapability.LOGISTICS_PRODUCT); |
|
} |
|
|
|
// ------------------------------------------------------------------ 销毁 |
|
|
|
/** |
|
* 创建销毁计划({@code POST /v2/destroyPlanOrder/create})。 |
|
* |
|
* <p><b>⚠ 路径未真机确认</b>,见 {@link HengjianConstants#PATH_DESTRUCTION_CREATE}。</p> |
|
* |
|
* <p>响应<b>无 data</b>:只有 {@code code / message},不回仓单号也不回状态。 |
|
* 所以 {@code providerDestructionId} 与 {@code status} 都留 null——不拿来源单号冒充仓单号, |
|
* 也不把「已提交」当「已执行」。</p> |
|
*/ |
|
@Override |
|
public DestructionOrder create(WarehouseContext ctx, DestructionCommand cmd) { |
|
String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( |
|
cmd.warehouseId(), ctx.providerWarehouseId()); |
|
HengjianDestructionDtos.CreateRequest body = |
|
HengjianDestructionMapper.toRequest(cmd, warehouseCode); |
|
execute(ctx, HengjianConstants.PATH_DESTRUCTION_CREATE, body, OP_DESTRUCTION_CREATE); |
|
return HengjianDestructionMapper.toCreated(cmd, warehouseCode); |
|
} |
|
|
|
/** |
|
* 查销毁计划({@code POST /v2/destroyPlanOrder/find})。 |
|
* |
|
* <p><b>⚠ 路径未真机确认</b>,见 {@link HengjianConstants#PATH_DESTRUCTION_FIND}。</p> |
|
* |
|
* <p>请求体是<b>裸数组</b>;响应 {@code data} 也是数组,查不到的单号不返回 |
|
* (不是返回空对象)。这里只查一个单号,返回匹配的那条,没有则 null。</p> |
|
*/ |
|
@Override |
|
public DestructionOrder getDestruction(WarehouseContext ctx, String destructionNo) { |
|
List<String> body = HengjianDestructionMapper.toFindRequest(destructionNo); |
|
String raw = execute(ctx, HengjianConstants.PATH_DESTRUCTION_FIND, body, |
|
OP_DESTRUCTION_GET); |
|
List<HengjianDestructionDtos.DestroyPlan> plans = |
|
json.listAt(raw, "data", HengjianDestructionDtos.DestroyPlan.class); |
|
return HengjianDestructionMapper.find(plans, destructionNo); |
|
} |
|
|
|
// ------------------------------------------------------------------ 退货 |
|
|
|
/** |
|
* 创建退货计划({@code POST /v1/saleReturn/thirdParty/saveReturnPlan})。 |
|
* |
|
* <p>承接门面的幂等守卫(键 {@code warehouseCode + returnRequestNo + create})。</p> |
|
* |
|
* <p><b>请求是双层包裹</b>(业务字段在 {@code params} 下),与其它接口不同。</p> |
|
* |
|
* <p>响应只回头级信息,<b>不回明细行</b>——需要明细要再查详情。</p> |
|
*/ |
|
@Override |
|
public WarehouseReturn create(WarehouseContext ctx, ReturnCommand cmd) { |
|
String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( |
|
cmd.warehouseId(), ctx.providerWarehouseId()); |
|
HengjianReturnPlanCreateDtos.SaveRequest body = |
|
HengjianReturnMapper.toRequest(cmd, warehouseCode); |
|
String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_CREATE, body, OP_RETURN_CREATE); |
|
HengjianReturnPlanCreateDtos.SaveResponse resp = |
|
json.fromJson(raw, HengjianReturnPlanCreateDtos.SaveResponse.class); |
|
if (resp == null || resp.data == null || trimToNull(resp.data.returnPlanNo) == null) { |
|
// 拿不到仓侧计划单号不能当成功:后续查询 / 处理方式都要它 |
|
throw WarehouseException.builder() |
|
.message("hengjian return plan returned no returnPlanNo: " + safeRelay(raw)) |
|
.operation(OP_RETURN_CREATE) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
return HengjianReturnMapper.toCreated(cmd, resp.data); |
|
} |
|
|
|
/** |
|
* 查退货计划详情({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo})。 |
|
* |
|
* <p>请求是<b>双层包裹</b>({@code {"params":{"orderNo"}}})。单号既可是计划单号, |
|
* 也可是来源单号——详情响应同时回 {@code returnPlanNo} 与 {@code sourceOrderNo}。</p> |
|
* |
|
* <p>查不到({@code data} 为空)返回 null。</p> |
|
*/ |
|
@Override |
|
public WarehouseReturn getReturn(WarehouseContext ctx, String returnRequestNo) { |
|
String orderNo = trimToNull(returnRequestNo); |
|
if (orderNo == null) { |
|
throw new IllegalArgumentException("hengjian return detail requires an order number"); |
|
} |
|
HengjianReturnDetailDtos.DetailRequest body = |
|
HengjianReturnQueryMapper.toDetailRequest(orderNo); |
|
String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_DETAIL, body, OP_RETURN_GET); |
|
JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || data.isNull() || data.isMissingNode()) { |
|
return null; |
|
} |
|
HengjianReturnDetailDtos.PlanDetail detail = |
|
json.fromJson(data.toString(), HengjianReturnDetailDtos.PlanDetail.class); |
|
return HengjianReturnQueryMapper.toReturn(detail); |
|
} |
|
|
|
/** |
|
* 分页查退货计划({@code POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage})。 |
|
* |
|
* <p>支持的维度见 {@link ReturnQuery};<b>不支持的维度直接拒绝</b>, |
|
* 静默忽略会让调用方以为筛过。</p> |
|
* |
|
* <p>恒健的三处限制:</p> |
|
* <ul> |
|
* <li>状态是<b>单值</b>({@code returnPlanStatus} 不是数组),给多个即拒绝;</li> |
|
* <li>没有 SKU 过滤;</li> |
|
* <li>「单号」与「自由查询条件」共用一组 {@code queryType/queryValue}, |
|
* 所以不能同时给 {@code orderNo} 和 {@code trackingNo}。</li> |
|
* </ul> |
|
*/ |
|
@Override |
|
public Page<WarehouseReturn> queryReturns(WarehouseContext ctx, ReturnQuery query) { |
|
ReturnQuery q = query == null ? ReturnQuery.builder().build() : query; |
|
|
|
if (q.providerSku() != null) { |
|
throw validation(ctx, OP_RETURN_QUERY, |
|
"hengjian return list has no sku filter"); |
|
} |
|
if (q.statuses().size() > 1 || q.rawStatuses().size() > 1) { |
|
throw validation(ctx, OP_RETURN_QUERY, |
|
"hengjian return list supports a single status; got statuses=" + q.statuses() |
|
+ " rawStatuses=" + q.rawStatuses()); |
|
} |
|
if (q.orderNo() != null && q.trackingNo() != null) { |
|
throw validation(ctx, OP_RETURN_QUERY, |
|
"hengjian return list shares one queryType/queryValue pair;" |
|
+ " give orderNo or trackingNo, not both"); |
|
} |
|
|
|
ReturnStatus single = q.statuses().isEmpty() ? null : q.statuses().get(0); |
|
// 原值优先:调用方明确给了仓方码就用它,别让统一枚举再折一次 |
|
String rawStatus = q.rawStatuses().isEmpty() ? null : q.rawStatuses().get(0); |
|
if (rawStatus != null && single != null) { |
|
throw validation(ctx, OP_RETURN_QUERY, |
|
"statuses and rawStatuses are mutually exclusive"); |
|
} |
|
|
|
String startTime = null; |
|
String endTime = null; |
|
if (q.hasCreatedRange()) { |
|
startTime = HENGJIAN_TIME.format(q.createdAfter().atOffset(java.time.ZoneOffset.UTC)); |
|
endTime = HENGJIAN_TIME.format(q.createdBefore().atOffset(java.time.ZoneOffset.UTC)); |
|
} else if (q.createdAfter() != null || q.createdBefore() != null) { |
|
throw validation(ctx, OP_RETURN_QUERY, |
|
"hengjian return time window needs both createdAfter and createdBefore"); |
|
} |
|
|
|
// 单号 / tracking 与自由查询条件共用一组 queryType/queryValue |
|
String queryType = q.queryTypeValue(); |
|
String queryValue = q.queryValue(); |
|
if (q.orderNo() != null) { |
|
queryType = QUERY_TYPE_SOURCE_NO; |
|
queryValue = q.orderNo(); |
|
} else if (q.trackingNo() != null) { |
|
queryType = QUERY_TYPE_TRACKING; |
|
queryValue = q.trackingNo(); |
|
} else if ((queryType == null) != (queryValue == null)) { |
|
throw validation(ctx, OP_RETURN_QUERY, |
|
"hengjian return queryTypeValue and queryValue must be given together"); |
|
} |
|
|
|
int page = HengjianReturnQueryMapper.pageOf(q.cursor()); |
|
int size = q.pageSize() > 0 |
|
? HengjianReturnQueryMapper.rowsOf(q.pageSize()) |
|
: HengjianReturnQueryMapper.rowsOf(PAGE_SIZE_DEFAULT); |
|
List<String> warehouseCodes = q.warehouseCode() == null |
|
? null : java.util.Collections.singletonList(q.warehouseCode()); |
|
HengjianReturnListDtos.ListRequest body = HengjianReturnQueryMapper.toListRequest( |
|
q.statuses(), single, startTime, endTime, q.queryDataType(), |
|
queryType, queryValue, warehouseCodes, page, size); |
|
if (rawStatus != null) { |
|
// 原值直接落进报文:statusCodeOf 只认统一枚举,表达不了 20 / 35 的区分 |
|
body.params.returnPlanStatus = rawStatus; |
|
} |
|
String raw = execute(ctx, HengjianConstants.PATH_RETURN_PLAN_PAGE, body, OP_RETURN_QUERY); |
|
HengjianReturnListDtos.ListResponse resp = |
|
json.fromJson(raw, HengjianReturnListDtos.ListResponse.class); |
|
return HengjianReturnQueryMapper.toPage(resp == null ? null : resp.data, q.cursor(), size); |
|
} |
|
|
|
/** |
|
* 查退货处理单列表({@code POST /v1/saleReturn/getReturnPlanHandlePage})。 |
|
* |
|
* <p><b>请求是平铺的</b>(无 {@code params} 包裹),与 thirdParty 那两个不同。</p> |
|
* |
|
* <p>恒健没有对应的统一模型:这里返回仓方的处理单行,供宿主填写处理方式与回收照片。</p> |
|
*/ |
|
@Override |
|
public Page<ReturnHandle> queryHandles(WarehouseContext ctx, ReturnQuery query) { |
|
if (query == null) { |
|
query = ReturnQuery.builder().build(); |
|
} |
|
// 统一入口只带游标 / 仓库 / 单号;其余维度恒健这里没有对应口径,给了就拒绝 |
|
if (query.hasCreatedRange() || query.trackingNo() != null |
|
|| query.providerSku() != null || !query.statuses().isEmpty() |
|
|| query.orderNoType() != null) { |
|
throw validation(ctx, OP_RETURN_HANDLES, |
|
"hengjian return handle list takes returnPlanNo / tracking / warehouse / " |
|
+ "handlingStatus only; use queryHandlesAdvanced for those"); |
|
} |
|
List<String> planNos = query.orderNo() == null |
|
? null : java.util.Collections.singletonList(query.orderNo()); |
|
List<String> warehouseCodes = query.warehouseCode() == null |
|
? null : java.util.Collections.singletonList(query.warehouseCode()); |
|
return queryHandlesAdvanced(ctx, planNos, null, warehouseCodes, |
|
null, null, null, query.cursor()); |
|
} |
|
|
|
/** |
|
* 多条件分页查退货处理单({@code POST /v1/saleReturn/getReturnPlanHandlePage})。 |
|
* |
|
* <p><b>请求是平铺的</b>(无 {@code params} 包裹),与 thirdParty 那两个不同。</p> |
|
*/ |
|
public Page<ReturnHandle> queryHandlesAdvanced( |
|
WarehouseContext ctx, List<String> returnPlanNos, List<String> trackingNos, |
|
List<String> warehouseCodes, List<Integer> handlingStatuses, |
|
String createdStart, String createdEnd, String cursor) { |
|
int page = HengjianReturnQueryMapper.pageOf(cursor); |
|
int size = HengjianReturnQueryMapper.handleRowsOf(HANDLE_PAGE_SIZE_DEFAULT); |
|
HengjianReturnHandleDtos.HandleListRequest body = |
|
HengjianReturnQueryMapper.toHandleListRequest(returnPlanNos, trackingNos, |
|
warehouseCodes, handlingStatuses, createdStart, createdEnd, page, size); |
|
String raw = execute(ctx, HengjianConstants.PATH_RETURN_HANDLE_PAGE, body, |
|
OP_RETURN_HANDLES); |
|
HengjianReturnHandleDtos.HandleListResponse resp = |
|
json.fromJson(raw, HengjianReturnHandleDtos.HandleListResponse.class); |
|
return HengjianReturnQueryMapper.toHandlePage(resp == null ? null : resp.data, cursor, size); |
|
} |
|
|
|
/** |
|
* 填写退货处理方式({@code POST /v1/saleReturn/handlingMethod})。 |
|
* |
|
* <p><b>请求平铺</b>,用 {@code returnPlanNo + returnNo + erpSku + tracking} 四项定位, |
|
* <b>不用行 id</b>——与运去哪的条目处理接口不同。</p> |
|
* |
|
* <p>两级处理方式:{@code handlingMethod}(1 继续拍照 / 2 处理方式)是开关, |
|
* {@code primaryHandlingMethod}(101~206)是具体动作。core 的 |
|
* {@code ReturnProcessDisposition} 只有部分能映射(销毁 / 上架良品 / 换标上架 / 卖家自提), |
|
* 拍照类与重新包装必须显式给原值。</p> |
|
*/ |
|
@Override |
|
public void process(WarehouseContext ctx, ReturnProcessCommand cmd) { |
|
HengjianReturnHandleDtos.HandlingMethodRequest body = |
|
HengjianReturnQueryMapper.toHandlingMethodRequest(cmd); |
|
execute(ctx, HengjianConstants.PATH_RETURN_HANDLING_METHOD, body, OP_RETURN_PROCESS); |
|
} |
|
|
|
// ------------------------------------------------------------------ 调拨 |
|
|
|
/** |
|
* 创建调拨计划({@code POST /v1/transferPlan/create})。 |
|
* |
|
* <p>真机确认必填:调出 / 调入仓、期望出库 / 入库时间。 |
|
* 响应 {@code data} 是<b>字符串单号</b>(不是对象)。</p> |
|
* |
|
* <p>外部仓库用仓代码 {@code Other} 表达——恒健的约定,适配器不猜。</p> |
|
*/ |
|
@Override |
|
public TransferOrder create(WarehouseContext ctx, TransferCommand cmd) { |
|
HengjianTransferDtos.CreateRequest body = HengjianTransferMapper.toRequest(cmd); |
|
String raw = execute(ctx, HengjianConstants.PATH_TRANSFER_CREATE, body, OP_TRANSFER_CREATE); |
|
String planNo = json.stringAt(raw, "data"); |
|
if (trimToNull(planNo) == null) { |
|
// 拿不到单号不能当成功:后续查询 / 取消都要它 |
|
throw WarehouseException.builder() |
|
.message("hengjian transfer returned no data (plan no): " + safeRelay(raw)) |
|
.operation(OP_TRANSFER_CREATE) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
return HengjianTransferMapper.toCreated(cmd, planNo.trim()); |
|
} |
|
|
|
/** |
|
* 多条件分页查调拨计划({@code GET /v1/transferPlan/findByPage})。 |
|
* |
|
* <p>恒健的过滤参数都是<b>单值</b>(不是数组),所以统一模型里给了多个单号时 |
|
* 只下发第一个——这与其它接口「拒绝多值」的做法不同,因为这里的语义是 |
|
* 「按这个单号查」,多给没有意义。文档已注明。</p> |
|
*/ |
|
@Override |
|
public Page<TransferOrder> queryTransfers(WarehouseContext ctx, TransferQuery query) { |
|
Map<String, Object> params = HengjianTransferMapper.toPageParams(query, query.cursor()); |
|
rateLimiter.acquire(HengjianConstants.PATH_TRANSFER_PAGE, HengjianConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), |
|
HengjianConstants.PATH_TRANSFER_PAGE, params, ctx.secret(), ctx, OP_TRANSFER_QUERY); |
|
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_TRANSFER_QUERY, |
|
ctx.warehouseCode(), ctx.requestId()).body(); |
|
HengjianTransferDtos.PageResponse resp = |
|
json.fromJson(raw, HengjianTransferDtos.PageResponse.class); |
|
return HengjianTransferMapper.toPage(resp == null ? null : resp.data, query.cursor()); |
|
} |
|
|
|
/** |
|
* 取消调拨计划({@code GET /v1/transferPlan/cancel})。 |
|
* |
|
* <p>这是统一模型里 {@link TransferCapable#deleteTransfer} 的落点:恒健叫「取消」, |
|
* 语义等价于「撤销这张调拨单」。<b>取消要收费</b>是运去哪的概念,恒健没有。</p> |
|
* |
|
* <p>参数在 <b>query</b>(不是 body);真机确认 {@code sourceNo} 必填。</p> |
|
*/ |
|
@Override |
|
public void deleteTransfer(WarehouseContext ctx, String providerTransferNo) { |
|
String sourceNo = trimToNull(providerTransferNo); |
|
if (sourceNo == null) { |
|
throw new IllegalArgumentException("hengjian transfer cancel requires sourceNo"); |
|
} |
|
Map<String, Object> params = new LinkedHashMap<String, Object>(); |
|
params.put("sourceNo", sourceNo); |
|
rateLimiter.acquire(HengjianConstants.PATH_TRANSFER_CANCEL, HengjianConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), |
|
HengjianConstants.PATH_TRANSFER_CANCEL, params, ctx.secret(), ctx, OP_TRANSFER_CANCEL); |
|
try { |
|
HengjianEnvelope.of(transport.execute(req), json, OP_TRANSFER_CANCEL, |
|
ctx.warehouseCode(), ctx.requestId()); |
|
} catch (PlatformBusinessException e) { |
|
// 取消失败只有 message(如「未查询到对应调拨计划数据」); |
|
// 不能细分成状态错还是参数错,原样抛出业务异常 |
|
throw e; |
|
} |
|
} |
|
|
|
// ------------------------------------------------------------------ 入库 |
|
|
|
/** |
|
* 创建入库计划({@code POST /v1/inbound/createInboundPlan})。 |
|
* |
|
* <p>承接门面的幂等守卫(键 {@code warehouseCode + inboundRequestNo + create})。</p> |
|
* |
|
* <p><b>响应不回仓单号</b>:只有 {@code code / message}。所以 |
|
* {@code providerInboundId} 为 null——后续查详情 / 取消只能用来源单号。 |
|
* 这里不把来源单号冒充仓单号填进去。</p> |
|
* |
|
* <p>{@code status=0} 是草稿,草稿状态下再调本接口是<b>更新</b>而非新建。 |
|
* 由调用方经 {@code InboundCommand.documentStatus()} 决定,适配器不猜。</p> |
|
*/ |
|
@Override |
|
public InboundReceipt create(WarehouseContext ctx, InboundCommand cmd) { |
|
String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( |
|
cmd.warehouseId(), ctx.providerWarehouseId()); |
|
HengjianInboundCreateDtos.CreateRequest body = |
|
HengjianInboundMapper.toRequest(cmd, warehouseCode); |
|
execute(ctx, HengjianConstants.PATH_INBOUND_CREATE, body, OP_INBOUND_CREATE); |
|
// 仓方不回单号:保持 null,不拿来源单号顶替 |
|
return InboundReceipt.of(cmd.inboundRequestNo(), null); |
|
} |
|
|
|
/** |
|
* 查入库计划详情({@code POST /v1/inbound/getInboundPlanInfo})。 |
|
* |
|
* <p>恒健只按<b>单号</b>查,且这个单号可以是仓方计划单号,也可以是来源单号 |
|
* (详情响应同时回 {@code inboundPlanOrderNo} 与 {@code sourceNo})。</p> |
|
* |
|
* <p>查不到({@code data} 为空)返回 null——与其它仓一致。</p> |
|
*/ |
|
@Override |
|
public InboundOrder get(WarehouseContext ctx, String inboundRef) { |
|
String orderNo = trimToNull(inboundRef); |
|
if (orderNo == null) { |
|
throw new IllegalArgumentException("hengjian inbound get requires an order number"); |
|
} |
|
HengjianInboundQueryDtos.FindOneRequest body = |
|
HengjianInboundQueryMapper.toFindOneRequest(orderNo); |
|
String raw = execute(ctx, HengjianConstants.PATH_INBOUND_GET, body, OP_INBOUND_GET); |
|
JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || data.isNull() || data.isMissingNode()) { |
|
return null; |
|
} |
|
HengjianInboundQueryDtos.InboundPlan plan = |
|
json.fromJson(data.toString(), HengjianInboundQueryDtos.InboundPlan.class); |
|
return HengjianInboundQueryMapper.toOrder(plan, fallbackWarehouse(ctx)); |
|
} |
|
|
|
/** |
|
* 生成入库箱标({@code POST /v2/inbound/boxLabelGenerate})。 |
|
* |
|
* <p>响应<b>没有任务号也没有文件</b>:只有 {@code code / message}。 |
|
* 文件要从入库计划详情的 {@code packingLabelUrl} 取,所以返回的 |
|
* {@link LabelPrintTask#taskNo()} 为 null——<b>不代表调用失败</b>。</p> |
|
* |
|
* <p>恒健要求 {@code isIndexNo} / {@code isOriginCountry} 必填,统一模型里是 |
|
* null-able;没给时本地拒绝而不是猜一个值(猜错会多印或漏印一行)。</p> |
|
* |
|
* <p>尺寸 / 每页数量的联动约束由 {@link BoxLabelCommand} 构造期校验; |
|
* 恒健没有 {@code sizeType} / {@code downloadMode} 口径,改用 {@code paperType}。</p> |
|
*/ |
|
@Override |
|
public LabelPrintTask printBoxLabel(WarehouseContext ctx, BoxLabelCommand cmd) { |
|
String fallback = trimToNull(ctx.providerWarehouseId()); |
|
if (fallback == null) { |
|
fallback = trimToNull(cmd.inboundRequestNo()); |
|
} |
|
HengjianBoxLabelDtos.BoxLabelRequest body = |
|
HengjianBoxLabelMapper.toRequest(cmd, fallback); |
|
execute(ctx, HengjianConstants.PATH_INBOUND_BOX_LABEL, body, OP_INBOUND_BOX_LABEL); |
|
return HengjianBoxLabelMapper.toTask(cmd, fallback); |
|
} |
|
|
|
/** |
|
* 按游标分页查入库单。 |
|
* |
|
* <p>统一模型这个入口只有一个游标,恒健的列表接口支持多条件;这里把游标当页码, |
|
* 其余条件为空——需要按状态 / 时间窗筛时用 |
|
* {@link #queryInbounds(WarehouseContext, InboundQuery)}。</p> |
|
*/ |
|
@Override |
|
public Page<InboundOrder> query(WarehouseContext ctx, String cursor) { |
|
return queryInbounds(ctx, InboundQuery.builder().cursor(cursor).build()); |
|
} |
|
|
|
/** |
|
* 多条件分页查入库计划({@code POST /v1/inbound/getInboundPlanPage})。 |
|
* |
|
* <p>恒健列表支持的维度:仓 / 计划单号 / 来源单号 / 状态码 / 库存类型 / |
|
* 七种时间区间(创建 / 更新 / 完成 / 期望到货 / 预计发货 / 预计入库 / 首次接收)/ |
|
* Amazon shipmentId。</p> |
|
* |
|
* <p>统一模型只表达其中三种时间窗(创建 / 更新 / 完成)。其余四种恒健独有, |
|
* 模型里没有——需要时再经 {@code InboundQuery} 扩字段,不在这里硬塞。</p> |
|
* |
|
* <p><b>未支持的维度直接拒绝</b>:见 {@link #queryInbounds} 里的校验。</p> |
|
*/ |
|
@Override |
|
public Page<InboundOrder> queryInbounds(WarehouseContext ctx, InboundQuery query) { |
|
HengjianInboundQueryDtos.PageRequest body = |
|
HengjianInboundQueryMapper.toPageRequest(query, ctx.providerWarehouseId()); |
|
String raw = execute(ctx, HengjianConstants.PATH_INBOUND_PAGE, body, OP_INBOUND_QUERY); |
|
HengjianInboundQueryDtos.PageResponse resp = |
|
json.fromJson(raw, HengjianInboundQueryDtos.PageResponse.class); |
|
return HengjianInboundQueryMapper.toPage(resp == null ? null : resp.data, |
|
fallbackWarehouse(ctx), query.cursor()); |
|
} |
|
|
|
// ------------------------------------------------------------------ 库存 |
|
|
|
/** |
|
* 库存同步策略。 |
|
* |
|
* <p>恒健的两个库存接口都<b>不支持按更新时间增量</b>:按 SKU 的全量返回、 |
|
* 按仓的分页返回,都没有 {@code updatedAfter} 入参。所以策略是 |
|
* {@link InventorySyncStrategy#FULL_PULL_DIFF}——宿主全量拉后自己做差异比对。</p> |
|
* |
|
* <p>流水接口({@code movements})能按日期查,但那是<b>变动明细</b>, |
|
* 不是余额,不能拿来重建当前库存。</p> |
|
*/ |
|
@Override |
|
public InventorySyncStrategy syncStrategy() { |
|
return InventorySyncStrategy.FULL_PULL_DIFF; |
|
} |
|
|
|
/** |
|
* 查库存。 |
|
* |
|
* <p>恒健有两个接口,统一模型只有一个方法,按「给了什么」分流:</p> |
|
* <ul> |
|
* <li><b>给了 SKU</b> → {@code POST /v1/inventory/getInventory}(不分页,一次返回全部匹配行);</li> |
|
* <li><b>只给仓</b> → {@code GET /v2/inventory/get_inventory_by_page}(分页)。</li> |
|
* </ul> |
|
* |
|
* <p>两者都给的场景(按仓 + SKU 过滤)恒健没有对应接口,<b>本地拒绝</b>—— |
|
* 静默丢掉一个条件会让调用方以为过滤生效了。</p> |
|
* |
|
* <p>{@code updatedAfter} 恒健不支持,传了就拒绝(同上理由)。</p> |
|
*/ |
|
@Override |
|
public Page<InventorySnapshot> query(WarehouseContext ctx, InventoryQuery query) { |
|
if (query.updatedAfter() != null) { |
|
throw validation(ctx, OP_INVENTORY_QUERY, |
|
"hengjian inventory has no updatedAfter filter; full-pull and diff instead"); |
|
} |
|
boolean bySku = !query.providerSkus().isEmpty(); |
|
boolean byWarehouse = !query.warehouseCodes().isEmpty(); |
|
if (bySku && byWarehouse) { |
|
throw validation(ctx, OP_INVENTORY_QUERY, |
|
"hengjian has two separate inventory APIs: one filters by sku, " |
|
+ "the other by warehouseCodes; combining both is not supported"); |
|
} |
|
if (query.inventoryType() != null || query.includeZeroStock() != null) { |
|
throw validation(ctx, OP_INVENTORY_QUERY, |
|
"hengjian inventory has no inventoryType / includeZeroStock filter"); |
|
} |
|
if (!bySku && !byWarehouse) { |
|
// 什么都不给会退化成「整仓全量」;这必须是调用方显式意愿,不能由缺省触发 |
|
throw validation(ctx, OP_INVENTORY_QUERY, |
|
"hengjian inventory query requires providerSkus or warehouseCodes"); |
|
} |
|
return bySku ? queryBySku(ctx, query) : queryByPage(ctx, query); |
|
} |
|
|
|
/** 按 SKU 查(不分页)。 */ |
|
private Page<InventorySnapshot> queryBySku(WarehouseContext ctx, InventoryQuery query) { |
|
HengjianInventoryDtos.QueryBySkuRequest body = HengjianInventoryMapper.toBySkuRequest(query); |
|
String raw = execute(ctx, HengjianConstants.PATH_INVENTORY_BY_SKU, body, OP_INVENTORY_QUERY); |
|
List<HengjianInventoryDtos.InventoryRow> rows = |
|
json.listAt(raw, "data", HengjianInventoryDtos.InventoryRow.class); |
|
return Page.last(HengjianInventoryMapper.toSnapshots(rows, fallbackWarehouse(ctx))); |
|
} |
|
|
|
/** 按仓分页查。 */ |
|
private Page<InventorySnapshot> queryByPage(WarehouseContext ctx, InventoryQuery query) { |
|
Map<String, List<String>> params = |
|
HengjianInventoryMapper.toPageParams(query, ctx.providerWarehouseId()); |
|
rateLimiter.acquire(HengjianConstants.PATH_INVENTORY_PAGE, HengjianConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.getMulti(ctx.endpointBaseUrl(), |
|
HengjianConstants.PATH_INVENTORY_PAGE, params, ctx.secret(), ctx, OP_INVENTORY_QUERY); |
|
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_INVENTORY_QUERY, |
|
ctx.warehouseCode(), ctx.requestId()).body(); |
|
int rows = HengjianInventoryMapper.rowsOf(query.pageSize()); |
|
return HengjianInventoryMapper.toPage(json.nodeAt(raw, "data"), |
|
fallbackWarehouse(ctx), rows, json); |
|
} |
|
|
|
/** |
|
* 库存变动流水({@code POST /v1/inventory/task/query})。 |
|
* |
|
* <p>真机确认:SKU 与日期区间都必填,区间 ≤ 30 个自然日,rows 1~100。</p> |
|
*/ |
|
@Override |
|
public Page<InventoryMovement> queryMovements(WarehouseContext ctx, InventoryMovementQuery query) { |
|
HengjianInventoryMovementDtos.QueryRequest body = |
|
HengjianInventoryMapper.toMovementRequest(query); |
|
String raw = execute(ctx, HengjianConstants.PATH_INVENTORY_MOVEMENTS, body, OP_INVENTORY_MOVEMENTS); |
|
HengjianInventoryMovementDtos.QueryResponse resp = |
|
json.fromJson(raw, HengjianInventoryMovementDtos.QueryResponse.class); |
|
int rows = HengjianInventoryMapper.movementRowsOf(query.pageSize()); |
|
return HengjianInventoryMapper.toMovementPage( |
|
resp == null ? null : resp.data, fallbackWarehouse(ctx), rows, query.cursor()); |
|
} |
|
|
|
/** 仓编码兜底:优先仓方编码,其次 OMS 仓编码。 */ |
|
private static String fallbackWarehouse(WarehouseContext ctx) { |
|
String provider = trimToNull(ctx.providerWarehouseId()); |
|
return provider == null ? ctx.warehouseCode() : provider; |
|
} |
|
|
|
// ------------------------------------------------------------------ 试算与地址属性 |
|
|
|
/** |
|
* 运费测算({@code POST /v2/api/shipping/calculate})。 |
|
* |
|
* <p>统一模型是 cm / g,恒健也接受 {@code cm} / {@code g},<b>不换算</b>; |
|
* 但它的包裹尺寸字段是 INTEGER,所以厘米值四舍五入取整(截断会让报价偏低)。</p> |
|
* |
|
* <p>恒健不按仓维度返回报价,结果只有一个实例, |
|
* {@code shipOrgWarehouseCode} 用账户仓填充。</p> |
|
*/ |
|
@Override |
|
public List<FeeEstimateResult> estimate(WarehouseContext ctx, FeeEstimateQuery query) { |
|
HengjianFeeEstimateDtos.CalculateRequest body = HengjianEstimateMapper.toRequest(query, |
|
trimToNull(ctx.providerWarehouseId())); |
|
String raw = execute(ctx, HengjianConstants.PATH_FEE_ESTIMATE, body, OP_FEE_ESTIMATE); |
|
HengjianFeeEstimateDtos.CalculateResponse resp = |
|
json.fromJson(raw, HengjianFeeEstimateDtos.CalculateResponse.class); |
|
String warehouseCode = trimToNull(ctx.providerWarehouseId()) == null |
|
? ctx.warehouseCode() : ctx.providerWarehouseId(); |
|
List<FeeEstimateResult> out = new ArrayList<FeeEstimateResult>(1); |
|
out.add(HengjianEstimateMapper.toResult(resp == null ? null : resp.data, warehouseCode)); |
|
return out; |
|
} |
|
|
|
/** |
|
* 地址属性识别({@code POST /v2/api/shipping/addressClassification})。 |
|
* |
|
* <p>真机确认五项必填({@code street1 / zip / city / state / country}), |
|
* 缺任何一项仓方都回参数校验异常,所以本地先挡。</p> |
|
*/ |
|
@Override |
|
public AddressType classifyAddress(WarehouseContext ctx, String street1, String street2, |
|
String city, String state, String postal, String country) { |
|
String s1 = requireAddressPart(street1, "street1"); |
|
String c = requireAddressPart(city, "city"); |
|
String st = requireAddressPart(state, "state"); |
|
String zip = requireAddressPart(postal, "postal"); |
|
String cy = requireAddressPart(country, "country"); |
|
|
|
HengjianAddressClassificationDtos.ClassifyRequest body = |
|
HengjianEstimateMapper.toClassifyRequest(s1, street2, c, st, zip, cy); |
|
String raw = execute(ctx, HengjianConstants.PATH_ADDRESS_CLASSIFICATION, body, |
|
OP_ADDRESS_CLASSIFY); |
|
HengjianAddressClassificationDtos.ClassifyResponse resp = |
|
json.fromJson(raw, HengjianAddressClassificationDtos.ClassifyResponse.class); |
|
return HengjianEstimateMapper.addressTypeOf(resp == null ? null : resp.data); |
|
} |
|
|
|
private static String requireAddressPart(String value, String field) { |
|
String v = trimToNull(value); |
|
if (v == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian address classification requires " + field); |
|
} |
|
return v; |
|
} |
|
|
|
// ------------------------------------------------------------------ 计费明细 |
|
|
|
/** |
|
* 拉取计费明细(仓储费 / 尾程费 / 作业费)。 |
|
* |
|
* <p>恒健把三类费用拆成<b>三个独立接口</b>,行字段各不相同,统一模型只有一个 |
|
* {@code settlements()}。因此<b>必须由调用方用 {@link FeeQuery#costType()} 指定查哪一类</b>:</p> |
|
* |
|
* <table border="1"> |
|
* <tr><th>costType</th><th>接口</th></tr> |
|
* <tr><td>{@code STORAGE}</td><td>{@code getChargingStorageSettlement}</td></tr> |
|
* <tr><td>{@code LAST_MILE}</td><td>{@code getChargingTailDeliverySettlement}</td></tr> |
|
* <tr><td>{@code OPERATION}</td><td>{@code getChargingOperationSettlement}</td></tr> |
|
* </table> |
|
* |
|
* <p>不指定就<b>拒绝</b>而不是「三个都查再合并」:三类费用的行结构不同、金额口径也不同, |
|
* 合并会让调用方以为拿到了一份完整账单,实际少了另外两类。</p> |
|
* |
|
* <p>{@code VALUE_ADDED}(增值服务费)恒健没有对应接口,显式拒绝。</p> |
|
* |
|
* <h3>分页</h3> |
|
* <p>三个接口都是分页的,统一方法返回 {@code List}、不带游标,所以分页由调用方驱动: |
|
* 用 {@link FeeQuery#toBuilder()}{@code .pageCursor("2")} 翻页。 |
|
* <b>判末页的约定</b>:返回条数小于本次请求的 {@code pageSize} 即末页 |
|
* (少于请求量说明后面没有了)。</p> |
|
*/ |
|
@Override |
|
public List<BillingDocument> settlements(WarehouseContext ctx, FeeQuery query) { |
|
WarehouseFeeType type = query.costType(); |
|
if (type == null) { |
|
throw validation(ctx, OP_FEE_STORAGE, |
|
"hengjian exposes three separate billing APIs; set FeeQuery.costType " |
|
+ "(STORAGE / LAST_MILE / OPERATION) to pick one"); |
|
} |
|
switch (type) { |
|
case STORAGE: |
|
return fetchStorageFees(ctx, query); |
|
case LAST_MILE: |
|
return fetchTailDeliveryFees(ctx, query); |
|
case OPERATION: |
|
return fetchOperationFees(ctx, query); |
|
default: |
|
// VALUE_ADDED:恒健没有增值服务费的独立接口 |
|
throw validation(ctx, OP_FEE_STORAGE, |
|
"hengjian has no billing API for fee type " + type); |
|
} |
|
} |
|
|
|
private List<BillingDocument> fetchStorageFees(WarehouseContext ctx, FeeQuery query) { |
|
HengjianStorageFeeDtos.ListRequest body = new HengjianStorageFeeDtos.ListRequest(); |
|
body.page = HengjianFeeMapper.pageOf(query.pageCursor()); |
|
body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); |
|
body.orgWarehouseCodes = new ArrayList<String>(); |
|
body.relOrderNos = new ArrayList<String>(); |
|
body.sourceNos = new ArrayList<String>(); |
|
body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), |
|
body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_FEE_STORAGE, body, OP_FEE_STORAGE); |
|
HengjianStorageFeeDtos.ListResponse resp = |
|
json.fromJson(raw, HengjianStorageFeeDtos.ListResponse.class); |
|
if (resp == null || resp.data == null) { |
|
return new ArrayList<BillingDocument>(); |
|
} |
|
final String warehouseCode = ctx.warehouseCode(); |
|
return HengjianFeeMapper.mapAll(resp.data.content, |
|
new HengjianFeeMapper.RowMapper<HengjianStorageFeeDtos.StorageFeeRow>() { |
|
@Override |
|
public BillingDocument map(HengjianStorageFeeDtos.StorageFeeRow row) { |
|
return HengjianFeeMapper.toDocument(row, warehouseCode); |
|
} |
|
}); |
|
} |
|
|
|
private List<BillingDocument> fetchTailDeliveryFees(WarehouseContext ctx, FeeQuery query) { |
|
HengjianTailDeliveryFeeDtos.ListRequest body = new HengjianTailDeliveryFeeDtos.ListRequest(); |
|
body.page = HengjianFeeMapper.pageOf(query.pageCursor()); |
|
body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); |
|
body.orgWarehouseCodes = new ArrayList<String>(); |
|
body.relOrderNos = new ArrayList<String>(); |
|
body.sourceNos = new ArrayList<String>(); |
|
body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), |
|
body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_FEE_TAIL_DELIVERY, body, |
|
OP_FEE_TAIL_DELIVERY); |
|
HengjianTailDeliveryFeeDtos.ListResponse resp = |
|
json.fromJson(raw, HengjianTailDeliveryFeeDtos.ListResponse.class); |
|
if (resp == null || resp.data == null) { |
|
return new ArrayList<BillingDocument>(); |
|
} |
|
final String warehouseCode = ctx.warehouseCode(); |
|
return HengjianFeeMapper.mapAll(resp.data.content, |
|
new HengjianFeeMapper.RowMapper<HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow>() { |
|
@Override |
|
public BillingDocument map(HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow row) { |
|
return HengjianFeeMapper.toDocument(row, warehouseCode); |
|
} |
|
}); |
|
} |
|
|
|
private List<BillingDocument> fetchOperationFees(WarehouseContext ctx, FeeQuery query) { |
|
HengjianOperationFeeDtos.ListRequest body = new HengjianOperationFeeDtos.ListRequest(); |
|
body.page = HengjianFeeMapper.pageOf(query.pageCursor()); |
|
body.size = HengjianFeeMapper.pageSizeOf(query.pageSize()); |
|
body.orgWarehouseCodes = new ArrayList<String>(); |
|
body.relOrderNos = new ArrayList<String>(); |
|
body.sourceNos = new ArrayList<String>(); |
|
body.btChargeAt = HengjianFeeMapper.applyFilters(query, ctx.providerWarehouseId(), |
|
body.orgWarehouseCodes, body.relOrderNos, body.sourceNos); |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_FEE_OPERATION, body, OP_FEE_OPERATION); |
|
HengjianOperationFeeDtos.ListResponse resp = |
|
json.fromJson(raw, HengjianOperationFeeDtos.ListResponse.class); |
|
if (resp == null || resp.data == null) { |
|
return new ArrayList<BillingDocument>(); |
|
} |
|
final String warehouseCode = ctx.warehouseCode(); |
|
return HengjianFeeMapper.mapAll(resp.data.content, |
|
new HengjianFeeMapper.RowMapper<HengjianOperationFeeDtos.OperationFeeRow>() { |
|
@Override |
|
public BillingDocument map(HengjianOperationFeeDtos.OperationFeeRow row) { |
|
return HengjianFeeMapper.toDocument(row, warehouseCode); |
|
} |
|
}); |
|
} |
|
|
|
// ------------------------------------------------------------------ 物流异动单 |
|
|
|
/** |
|
* 创建物流异动单({@code POST /v1/trackingChange/create})。 |
|
* |
|
* <p>承接门面的幂等守卫(键 {@code warehouseCode + changeRequestNo + create}); |
|
* 这里只负责拼报文与解析。</p> |
|
* |
|
* <p><b>真机确认的必填项</b>(文档标错 / 漏标):{@code trackingNo}、{@code orderNo}、 |
|
* {@code remark}、{@code handleType};换址(2)还要新收件人三项。 |
|
* 仓方还会校验「来源单号与 trackingNo 属于同一张单」——这一条本地挡不住, |
|
* 只能在真机联调时保证调用方给的是一对真实存在的单号 + 运单号。</p> |
|
* |
|
* <p>响应只回 {@code trackingChangeOrderNo},<b>没有状态</b>——创建成功只代表申请已提交, |
|
* 承运商是否受理要看 subsequent 查询。</p> |
|
*/ |
|
@Override |
|
public TrackingChangeOrder createChange(WarehouseContext ctx, TrackingChangeCommand cmd) { |
|
HengjianTrackingChangeDtos.CreateRequest body = toCreateRequest(cmd); |
|
String raw = execute(ctx, HengjianConstants.PATH_TRACKING_CHANGE_CREATE, body, |
|
OP_TRACKING_CHANGE_CREATE); |
|
HengjianTrackingChangeDtos.CreateResponse resp = |
|
json.fromJson(raw, HengjianTrackingChangeDtos.CreateResponse.class); |
|
if (resp == null || resp.data == null || trimToNull(resp.data.trackingChangeOrderNo) == null) { |
|
throw WarehouseException.builder() |
|
.message("hengjian tracking change returned no trackingChangeOrderNo: " |
|
+ safeRelay(raw)) |
|
.operation(OP_TRACKING_CHANGE_CREATE) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
return TrackingChangeOrder.builder() |
|
.changeRequestNo(cmd.changeRequestNo()) |
|
.providerChangeOrderNo(resp.data.trackingChangeOrderNo.trim()) |
|
.sourceProvider(provider()) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.trackingNumber(cmd.trackingNumber()) |
|
.orderNo(trimToNull(cmd.orderNo())) |
|
.handleType(cmd.handleType()) |
|
// 创建接口不回状态:保持 null,不拿请求侧的值冒充仓方状态 |
|
.build(); |
|
} |
|
|
|
/** |
|
* 查询物流异动单({@code POST /v1/trackingChange/findOrder})。 |
|
* |
|
* <p><b>路径与文档不同</b>:文档写 {@code /v1/saleOrder/findOrder},真机 404; |
|
* 正确路径在 {@link HengjianConstants#PATH_TRACKING_CHANGE_FIND}。</p> |
|
*/ |
|
@Override |
|
public TrackingChangeOrder getChange(WarehouseContext ctx, String providerChangeOrderNo) { |
|
String changeNo = trimToNull(providerChangeOrderNo); |
|
if (changeNo == null) { |
|
throw new IllegalArgumentException("providerChangeOrderNo must not be blank"); |
|
} |
|
HengjianTrackingChangeQueryDtos.FindOrderRequest body = |
|
new HengjianTrackingChangeQueryDtos.FindOrderRequest(); |
|
body.trackingChangeOrderNo = changeNo; |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_TRACKING_CHANGE_FIND, body, |
|
OP_TRACKING_CHANGE_GET); |
|
JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || data.isNull() || data.isMissingNode()) { |
|
return null; |
|
} |
|
HengjianTrackingChangeQueryDtos.TrackingChangeDetail detail = |
|
json.fromJson(data.toString(), HengjianTrackingChangeQueryDtos.TrackingChangeDetail.class); |
|
return HengjianTrackingChangeMapper.toOrder(detail, ctx.warehouseCode(), provider()); |
|
} |
|
|
|
/** 统一命令 → 恒健请求;必填项在本地校验。 */ |
|
static HengjianTrackingChangeDtos.CreateRequest toCreateRequest(TrackingChangeCommand cmd) { |
|
String trackingNo = requireText(cmd.trackingNumber(), "trackingNumber", cmd.changeRequestNo()); |
|
String orderNo = requireText(cmd.orderNo(), "orderNo", cmd.changeRequestNo()); |
|
String remark = requireText(cmd.remark(), "remark", cmd.changeRequestNo()); |
|
int handleType = handleTypeOf(cmd.handleType()); |
|
|
|
HengjianTrackingChangeDtos.CreateRequest body = new HengjianTrackingChangeDtos.CreateRequest(); |
|
body.trackingNo = trackingNo; |
|
body.orderNo = orderNo; |
|
body.remark = remark; |
|
body.handleType = handleType; |
|
if (cmd.handleType() == TrackingChangeHandleType.ADDRESS_CHANGE) { |
|
// 换址三项真机必填,缺任一项仓方都会拒;本地先说清楚缺哪个 |
|
body.newRecipientName = requireText(cmd.newRecipientName(), "newRecipientName", |
|
cmd.changeRequestNo()); |
|
body.newRecipientPhone = requireText(cmd.newRecipientPhone(), "newRecipientPhone", |
|
cmd.changeRequestNo()); |
|
body.newRecipientAddress = requireText(cmd.newRecipientAddress(), "newRecipientAddress", |
|
cmd.changeRequestNo()); |
|
} |
|
return body; |
|
} |
|
|
|
/** 核心枚举 → 恒健 handleType:1 召回 / 2 换址 / 3 在途异常。 */ |
|
static int handleTypeOf(TrackingChangeHandleType type) { |
|
if (type == null) { |
|
throw new IllegalArgumentException("handleType must not be null"); |
|
} |
|
switch (type) { |
|
case RECALL: |
|
return 1; |
|
case ADDRESS_CHANGE: |
|
return 2; |
|
case IN_TRANSIT_EXCEPTION: |
|
return 3; |
|
default: |
|
throw new IllegalArgumentException("unsupported handleType: " + type); |
|
} |
|
} |
|
|
|
private static String requireText(String value, String field, String changeRequestNo) { |
|
String v = trimToNull(value); |
|
if (v == null) { |
|
throw new IllegalArgumentException("hengjian tracking change " + changeRequestNo |
|
+ " requires " + field + " (恒健必填)"); |
|
} |
|
return v; |
|
} |
|
|
|
// ------------------------------------------------------------------ 出库 |
|
|
|
/** |
|
* 创建销售发货单({@code POST /v1/saleOrder/create})。 |
|
* |
|
* <p>承接 {@code WarehouseOutbounds.create} 的幂等守卫:同一 |
|
* {@code outboundRequestNo} 重复下发由门面拦住,这里只负责拼报文与解析。</p> |
|
* |
|
* <p>响应只回 {@code data.orderId}(<b>仓内部数字 id</b>,不是字符串单号)。 |
|
* 恒健的取消接口同时要 {@code orderId} 与 {@code orderNo},所以这个 id |
|
* 必须随 {@link OutboundReceipt#providerOrderId()} 落库;缺了它后续取消做不了, |
|
* 因此拿不到就报错,<b>不静默当成创建成功</b>。</p> |
|
*/ |
|
@Override |
|
public OutboundReceipt create(WarehouseContext ctx, OutboundCommand cmd) { |
|
requirePlatformLabelSupported(cmd); |
|
String warehouseCode = HengjianOutboundMapper.resolveWarehouseCode( |
|
cmd.warehouseId(), ctx.providerWarehouseId()); |
|
HengjianCreateOrderDtos.CreateOrderRequest body = |
|
HengjianOutboundMapper.toRequest(cmd, warehouseCode, ctx.clock()); |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_ORDER_CREATE, body, OP_ORDER_CREATE); |
|
HengjianCreateOrderDtos.CreateOrderResponse resp = |
|
json.fromJson(raw, HengjianCreateOrderDtos.CreateOrderResponse.class); |
|
if (resp == null || resp.data == null || resp.data.orderId == null) { |
|
throw WarehouseException.builder() |
|
.message("hengjian create order returned no data.orderId: " + safeRelay(raw)) |
|
.operation(OP_ORDER_CREATE) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false) |
|
.rawResponse(safeRelay(raw)) |
|
.build(); |
|
} |
|
return OutboundReceipt.of(cmd.outboundRequestNo(), String.valueOf(resp.data.orderId), |
|
resp.message); |
|
} |
|
|
|
/** |
|
* 查订单详情({@code POST /v1/saleOrder/findOne})。 |
|
* |
|
* <p>恒健只按<b>来源单号</b>查。统一引用里的 {@code outboundRequestNo} 就是来源单号; |
|
* {@code providerOrderId} 是仓内部数字 id,<b>这个接口查不了</b>,所以拿来当兜底 |
|
* (调用方只给了 id 时照样发出去,仓方会查不到,由仓方报错而不是我们静默返回 null)。</p> |
|
* |
|
* <p>查不到({@code data} 为空)返回 null——与其它仓一致,调用方据此判断「没有这单」。</p> |
|
*/ |
|
@Override |
|
public OutboundOrder get(WarehouseContext ctx, OutboundRef ref) { |
|
String orderNo = orderNoOf(ref); |
|
HengjianOrderDetailDtos.FindOneRequest body = new HengjianOrderDetailDtos.FindOneRequest(); |
|
body.orderNo = orderNo; |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_ORDER_FIND_ONE, body, OP_ORDER_GET); |
|
JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || data.isNull() || data.isMissingNode()) { |
|
return null; |
|
} |
|
HengjianOrderDetailDtos.OrderDetail detail = |
|
json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class); |
|
return HengjianOrderMapper.toOrder(detail, ctx.providerWarehouseId()); |
|
} |
|
|
|
/** |
|
* 查订单列表({@code GET /v1/saleOrder/findByPage})。 |
|
* |
|
* <p>恒健要求「<b>时间、订单号、订单 id</b> 三者必填其一」,所以:</p> |
|
* <ul> |
|
* <li>给了 {@code outboundRequestNo} → 按 {@code orderNos} 查;</li> |
|
* <li>给了时间窗 → 按 {@code beginDateTime / endDateTime} 查(UTC 日期);</li> |
|
* <li>都没有 → <b>本地拒绝</b>,不发一个必然被仓方拒的请求。</li> |
|
* </ul> |
|
* |
|
* <p>时间跨度上限 30 天,超过也在本地拒绝。</p> |
|
* |
|
* <p>{@code orderRef}(平台单号)恒健没有对应查询参数,<b>不参与查询</b>; |
|
* {@code statuses} 恒健列表也没有状态过滤参数,传了就拒绝——静默忽略会让调用方 |
|
* 以为过滤生效了。</p> |
|
*/ |
|
@Override |
|
public Page<OutboundOrder> query(WarehouseContext ctx, OutboundQuery query) { |
|
if (!query.statuses().isEmpty()) { |
|
throw validation(ctx, OP_ORDER_QUERY, |
|
"hengjian order list has no status filter; refusing to silently ignore " |
|
+ query.statuses()); |
|
} |
|
// orderRef 是平台单号;恒健列表只有 orderNos(来源单号)与 orderIds, |
|
// 静默忽略会让调用方以为按平台单号过滤生效了 |
|
if (trimToNull(query.orderRef()) != null) { |
|
throw validation(ctx, OP_ORDER_QUERY, |
|
"hengjian order list cannot filter by platform order number (orderRef=" |
|
+ query.orderRef() + "); use outboundRequestNo or poNo instead"); |
|
} |
|
Map<String, Object> params = new LinkedHashMap<String, Object>(); |
|
// rows 上限是文档明写的「默认最高 100」,超过即拒绝(不静默截断) |
|
int pageSize = requireRows(ctx, query.pageSize()); |
|
params.put("rows", pageSize); |
|
// 排序:调用方指定优先,未指定才用默认值。文档里 sidx 可写死 id、sort 有 asc/desc 两值 |
|
params.put("sidx", sortFieldOf(query.sortField())); |
|
params.put("sort", sortDirectionOf(query.sortDirection())); |
|
params.put("page", pageNumberOf(query.cursor())); |
|
|
|
// 可选过滤:仓方支持就透传,不支持的维度已在上方拒绝 |
|
putIfPresent(params, "channel", query.channel()); |
|
putIfPresent(params, "channelAccount", query.channelAccount()); |
|
putIfPresent(params, "poNo", query.poNo()); |
|
if (!query.providerOrderIds().isEmpty()) { |
|
params.put("orderIds", joinIds(query.providerOrderIds())); |
|
} |
|
if (query.hasUpdatedRange()) { |
|
// 更新时间窗按 UTC 时间戳下发,格式 yyyy-MM-dd HH:mm:ss |
|
params.put("updateBeginDate", formatDateTime(query.updatedAfter())); |
|
params.put("updateEndDate", formatDateTime(query.updatedBefore())); |
|
} |
|
|
|
// 文档:时间、订单号、订单 id 三者必填其一。 |
|
// 「时间」取创建时间窗(beginDateTime/endDateTime);更新时间窗与 PO 单号是可选附加条件, |
|
// 不能单独当主键——只给它们时仍按缺少主键拒绝。 |
|
String orderNo = trimToNull(query.outboundRequestNo()); |
|
if (orderNo != null) { |
|
params.put("orderNos", orderNo); |
|
} else if (query.after() != null && query.before() != null) { |
|
addDateRange(ctx, params, query); |
|
} else if (!query.providerOrderIds().isEmpty()) { |
|
// orderIds 已在上方放入 params,本身就是合法主键 |
|
} else { |
|
throw validation(ctx, OP_ORDER_QUERY, |
|
"hengjian order list requires outboundRequestNo, providerOrderIds " |
|
+ "or both after/before (time, order number or order id - at least one)"); |
|
} |
|
|
|
rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), |
|
HengjianConstants.PATH_ORDER_FIND_BY_PAGE, params, ctx.secret(), ctx, OP_ORDER_QUERY); |
|
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_ORDER_QUERY, |
|
ctx.warehouseCode(), ctx.requestId()).body(); |
|
|
|
HengjianOrderListDtos.ListResponse resp = |
|
json.fromJson(raw, HengjianOrderListDtos.ListResponse.class); |
|
if (resp == null || resp.data == null) { |
|
throw validation(ctx, OP_ORDER_QUERY, "hengjian order list returned no data"); |
|
} |
|
List<OutboundOrder> orders = new ArrayList<OutboundOrder>(); |
|
if (resp.data.content != null) { |
|
for (HengjianOrderListDtos.OrderRow row : resp.data.content) { |
|
if (row == null) { |
|
continue; |
|
} |
|
orders.add(HengjianOrderMapper.toOrder(row, ctx.providerWarehouseId())); |
|
} |
|
} |
|
// 是否最后一页以仓方的 last 为准;缺省时用「本页是否满页」推断, |
|
// 不能只看 content 是否为空——空页在两种判断下含义不同 |
|
boolean last = resp.data.last != null |
|
? resp.data.last |
|
: (resp.data.numberOfElements != null && resp.data.numberOfElements < pageSize); |
|
return last ? Page.last(orders) : Page.of(orders, String.valueOf(pageNumberOf(query.cursor()) + 1)); |
|
} |
|
|
|
/** |
|
* 给已下发的订单补传附件({@code POST /v1/saleOrder/createAttachment})。 |
|
* |
|
* <p><b>请求平铺</b>(无 {@code params} 包裹)。响应无 data,只有 {@code code / message}, |
|
* 所以本方法无返回值。</p> |
|
* |
|
* <p>恒健要求每行 {@code name} / {@code type} 必填、{@code url} 与 {@code file} 二选一; |
|
* 缺了本地拒绝,不把半成品发出去。</p> |
|
*/ |
|
@Override |
|
public void uploadAttachments(WarehouseContext ctx, OutboundRef ref, |
|
List<WarehouseAttachment> attachments) { |
|
String orderNo = trimToNull(ref.outboundRequestNo()); |
|
if (orderNo == null) { |
|
orderNo = trimToNull(ref.providerOrderId()); |
|
} |
|
if (orderNo == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian attachment upload requires outboundRequestNo or providerOrderId"); |
|
} |
|
if (attachments == null || attachments.isEmpty()) { |
|
throw new IllegalArgumentException("hengjian attachment upload requires attachments"); |
|
} |
|
|
|
HengjianOrderAttachmentDtos.CreateAttachmentRequest body = |
|
new HengjianOrderAttachmentDtos.CreateAttachmentRequest(); |
|
body.orderNo = orderNo; |
|
body.attachInfoItemRequestList = toAttachItems(attachments, orderNo); |
|
execute(ctx, HengjianConstants.PATH_ORDER_ATTACHMENT, body, OP_ORDER_ATTACHMENT); |
|
} |
|
|
|
/** 统一附件 → 恒健附件行;逐行校验。 */ |
|
private static List<HengjianOrderAttachmentDtos.AttachInfoItem> toAttachItems( |
|
List<WarehouseAttachment> attachments, String orderNo) { |
|
List<HengjianOrderAttachmentDtos.AttachInfoItem> out = |
|
new ArrayList<HengjianOrderAttachmentDtos.AttachInfoItem>(attachments.size()); |
|
for (WarehouseAttachment attachment : attachments) { |
|
if (attachment == null) { |
|
continue; |
|
} |
|
String name = trimToNull(attachment.name()); |
|
if (name == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian attachment for order " + orderNo + " requires name"); |
|
} |
|
String type = trimToNull(attachment.type()); |
|
if (type == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian attachment for order " + orderNo + " requires type (0-6)"); |
|
} |
|
String url = trimToNull(attachment.url()); |
|
String content = trimToNull(attachment.contentBase64()); |
|
if (url == null && content == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian attachment " + name + " needs url or contentBase64"); |
|
} |
|
HengjianOrderAttachmentDtos.AttachInfoItem item = |
|
new HengjianOrderAttachmentDtos.AttachInfoItem(); |
|
item.name = name; |
|
item.type = parseAttachType(type, name); |
|
// file 优先于 url(仓方语义:给了 file 就忽略 url) |
|
item.file = content == null ? null : HengjianOutboundMapper.stripDataUri(content); |
|
item.url = content == null ? url : null; |
|
item.remark = trimToNull(attachment.remark()); |
|
out.add(item); |
|
} |
|
if (out.isEmpty()) { |
|
throw new IllegalArgumentException( |
|
"hengjian attachment upload for order " + orderNo + " has no usable attachment"); |
|
} |
|
return out; |
|
} |
|
|
|
/** |
|
* 附件类型:统一模型是<b>仓方原值字符串</b>,恒健这个接口要 INTEGER。 |
|
* |
|
* <p>认不出的值拒绝,不猜——发错类型会让仓方把面单当「其他」存。</p> |
|
*/ |
|
private static Integer parseAttachType(String raw, String name) { |
|
try { |
|
int value = Integer.parseInt(raw.trim()); |
|
if (value < 0 || value > 6) { |
|
throw new IllegalArgumentException( |
|
"hengjian attachment type for " + name + " must be 0-6, got " + value); |
|
} |
|
return value; |
|
} catch (NumberFormatException e) { |
|
// 部分仓用词表(Shippinglabel / BOL 等);恒健这里只收数字 |
|
throw new IllegalArgumentException( |
|
"hengjian attachment type for " + name |
|
+ " must be an integer 0-6, got " + raw); |
|
} |
|
} |
|
|
|
/** |
|
* 取消资格预判:查详情按状态推断。 |
|
* |
|
* <p>恒健没有独立的取消预判接口。已发货 / 已取消 / 已退款 / 已删除不再接受取消, |
|
* 判为 {@link CancelEligibility#BLOCKED};其余交给取消时仓方判定。</p> |
|
* |
|
* <p>查不到单时返回 BLOCKED,不猜 FREE——猜错会下发出一个注定被拒的取消。</p> |
|
*/ |
|
@Override |
|
public CancelEligibility checkCancel(WarehouseContext ctx, OutboundRef ref) { |
|
OutboundOrder order = get(ctx, ref); |
|
if (order == null) { |
|
return CancelEligibility.BLOCKED; |
|
} |
|
switch (order.status()) { |
|
case SHIPPED: |
|
case CANCELLED: |
|
case REFUNDED: |
|
case DELETED: |
|
case UNKNOWN: |
|
// UNKNOWN 也判 BLOCKED:恒健的状态词表将来可能加值, |
|
// 认不出时不该凭猜下发取消 |
|
return CancelEligibility.BLOCKED; |
|
default: |
|
return CancelEligibility.FREE; |
|
} |
|
} |
|
|
|
/** |
|
* 取消订单({@code POST /v1/saleOrder/cancel})。 |
|
* |
|
* <p>恒健要求 {@code orderId} 与 {@code orderNo} <b>两个都传</b>,而统一模型的 |
|
* {@link CancelCommand} 允许只给其中一个。约定:</p> |
|
* <ul> |
|
* <li>{@code outboundRequestNo} → 恒健 {@code orderNo};</li> |
|
* <li>{@code providerOrderId} → 恒健 {@code orderId}(仓内部数字 id)。</li> |
|
* </ul> |
|
* <p>缺哪个就用已知的那个去<b>列表接口</b>补一次——这是拿到 {@code orderId} 的正规途径 |
|
* (详情接口不回它)。补不到(仓里没有这张单)直接报参数错误, |
|
* <b>不发</b>必然被仓方拒的取消请求。</p> |
|
* |
|
* <p>恒健没有取消费概念,{@link CancelCommand#acceptCharge()} 在这里不生效。 |
|
* 仓方拒绝取消时抛 {@link OutboundCancelBlockedException},与参数错误区分开。</p> |
|
*/ |
|
@Override |
|
public CancelResult cancel(WarehouseContext ctx, CancelCommand cmd) { |
|
String orderNo = trimToNull(cmd.outboundRequestNo()); |
|
Long orderId = parseOrderId(cmd.providerOrderId()); |
|
if (orderNo == null && orderId == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian needs outboundRequestNo or providerOrderId to cancel an order"); |
|
} |
|
if (orderNo == null || orderId == null) { |
|
HengjianOrderListDtos.OrderRow row = findRow(ctx, orderNo, orderId); |
|
if (row == null) { |
|
throw validation(ctx, OP_ORDER_CANCEL, |
|
"hengjian order not found, cannot resolve " + (orderNo == null ? "orderNo" : "orderId") |
|
+ " for " + (orderNo != null ? orderNo : String.valueOf(orderId))); |
|
} |
|
if (orderNo == null) { |
|
orderNo = trimToNull(row.orderNo); |
|
} |
|
if (orderId == null && row.orderId != null) { |
|
orderId = row.orderId; |
|
} |
|
} |
|
if (orderNo == null || orderId == null) { |
|
throw validation(ctx, OP_ORDER_CANCEL, |
|
"hengjian cancel requires both orderId and orderNo; " |
|
+ "could not resolve " + (orderNo == null ? "orderNo" : "orderId")); |
|
} |
|
|
|
HengjianCancelOrderDtos.CancelOrderRequest body = new HengjianCancelOrderDtos.CancelOrderRequest(); |
|
body.orderId = orderId; |
|
body.orderNo = orderNo; |
|
|
|
String raw; |
|
try { |
|
raw = execute(ctx, HengjianConstants.PATH_ORDER_CANCEL, body, OP_ORDER_CANCEL); |
|
} catch (PlatformBusinessException e) { |
|
// 取消失败只有 message,无法细分原因;取消场景统一按「不可取消」表达 |
|
throw new OutboundCancelBlockedException(WarehouseException.builder() |
|
.message("hengjian refused cancellation: " + e.getMessage()) |
|
.operation(OP_ORDER_CANCEL) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.platformCode(e.platformCode()) |
|
.rawResponse(e.rawResponse()) |
|
.retryable(false)); |
|
} |
|
return CancelResult.builder() |
|
.outboundRequestNo(orderNo) |
|
.providerOrderId(String.valueOf(orderId)) |
|
.eligibility(CancelEligibility.FREE) |
|
.cancelled(true) |
|
.rawStatus(json.stringAt(raw, "message")) |
|
.build(); |
|
} |
|
|
|
/** |
|
* 按单号或订单 id 查一行,用于补全取消需要的另一个键。 |
|
* |
|
* <p>只认<b>精确匹配</b>:列表接口的 {@code orderNos} / {@code orderIds} 过滤是否精确 |
|
* 文档没说,取回来再逐条比对,避免拿近似结果去取消别的单。</p> |
|
*/ |
|
private HengjianOrderListDtos.OrderRow findRow(WarehouseContext ctx, String orderNo, Long orderId) { |
|
Map<String, Object> params = new LinkedHashMap<String, Object>(); |
|
params.put("rows", 1); |
|
params.put("sidx", HengjianConstants.ORDER_LIST_DEFAULT_SIDX); |
|
params.put("sort", HengjianConstants.ORDER_LIST_DEFAULT_SORT); |
|
params.put("page", 1); |
|
if (orderNo != null) { |
|
params.put("orderNos", orderNo); |
|
} else { |
|
params.put("orderIds", String.valueOf(orderId)); |
|
} |
|
rateLimiter.acquire(HengjianConstants.PATH_ORDER_FIND_BY_PAGE, HengjianConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.get(ctx.endpointBaseUrl(), |
|
HengjianConstants.PATH_ORDER_FIND_BY_PAGE, params, ctx.secret(), ctx, OP_ORDER_CANCEL); |
|
String raw = HengjianEnvelope.of(transport.execute(req), json, OP_ORDER_CANCEL, |
|
ctx.warehouseCode(), ctx.requestId()).body(); |
|
|
|
HengjianOrderListDtos.ListResponse resp = |
|
json.fromJson(raw, HengjianOrderListDtos.ListResponse.class); |
|
if (resp == null || resp.data == null || resp.data.content == null) { |
|
return null; |
|
} |
|
for (HengjianOrderListDtos.OrderRow row : resp.data.content) { |
|
if (row == null) { |
|
continue; |
|
} |
|
boolean matches = orderNo != null |
|
? orderNo.equals(trimToNull(row.orderNo)) |
|
: orderId != null && orderId.equals(row.orderId); |
|
if (matches) { |
|
return row; |
|
} |
|
} |
|
return null; |
|
} |
|
|
|
/** 仓内部订单 id;非数字返回 null(后续按单号补)。 */ |
|
private static Long parseOrderId(String providerOrderId) { |
|
String v = trimToNull(providerOrderId); |
|
if (v == null) { |
|
return null; |
|
} |
|
try { |
|
return Long.valueOf(v); |
|
} catch (NumberFormatException e) { |
|
return null; |
|
} |
|
} |
|
|
|
/** |
|
* 包裹列表:从详情的 {@code shipmentPackages} 提取。 |
|
* |
|
* <p>恒健没有独立的包裹接口,发货信息就在详情报文里。按 {@code trackingNo} 去重 |
|
* (同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹 |
|
* ({@code packageFlag=0})优先。</p> |
|
*/ |
|
@Override |
|
public List<PackageResult> packages(WarehouseContext ctx, OutboundRef ref) { |
|
String orderNo = orderNoOf(ref); |
|
HengjianOrderDetailDtos.FindOneRequest body = new HengjianOrderDetailDtos.FindOneRequest(); |
|
body.orderNo = orderNo; |
|
String raw = execute(ctx, HengjianConstants.PATH_ORDER_FIND_ONE, body, |
|
"warehouse.outbound.packages"); |
|
JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || data.isNull() || data.isMissingNode()) { |
|
return new ArrayList<PackageResult>(); |
|
} |
|
HengjianOrderDetailDtos.OrderDetail detail = |
|
json.fromJson(data.toString(), HengjianOrderDetailDtos.OrderDetail.class); |
|
return toPackages(detail, orderNo); |
|
} |
|
|
|
/** 实际包裹优先、按 trackingNo 去重;没有 trackingNo 时用 SKU 作键。 */ |
|
private static List<PackageResult> toPackages(HengjianOrderDetailDtos.OrderDetail detail, String orderNo) { |
|
List<PackageResult> out = new ArrayList<PackageResult>(); |
|
if (detail.shipmentPackages == null || detail.shipmentPackages.isEmpty()) { |
|
return out; |
|
} |
|
java.util.Set<String> seen = new java.util.LinkedHashSet<String>(); |
|
// 两遍:先实际包裹,再面单信息行 |
|
for (int pass = 0; pass < 2; pass++) { |
|
for (HengjianOrderDetailDtos.OrderDetail.ShipmentPackage p : detail.shipmentPackages) { |
|
if (p == null) { |
|
continue; |
|
} |
|
boolean actual = p.packageFlag == null || p.packageFlag == 0; |
|
if (actual != (pass == 0)) { |
|
continue; |
|
} |
|
String tracking = trimToNull(p.trackingNo); |
|
String key = tracking != null ? tracking : "SKU-" + trimToNull(p.erpSku); |
|
if (!seen.add(key)) { |
|
continue; |
|
} |
|
PackageResult.Builder builder = PackageResult.builder() |
|
.packageId(key) |
|
.outboundRequestNo(orderNo) |
|
.trackingNumber(tracking) |
|
.carrier(trimToNull(p.carrier)) |
|
.erpSku(trimToNull(p.erpSku)) |
|
.shippedQuantity(p.shipedQuantity) |
|
.shippedAt(HengjianOrderMapper.parseTime(p.shipmentDate)); |
|
if (p.cost != null && p.cost > 0) { |
|
builder.cost(HengjianOrderMapper.moneyOf(p.cost, detail.currency)); |
|
} |
|
out.add(builder.build()); |
|
} |
|
} |
|
return out; |
|
} |
|
|
|
/** 统一引用 → 来源单号;两者都空时拒绝。 */ |
|
private static String orderNoOf(OutboundRef ref) { |
|
String orderNo = trimToNull(ref.outboundRequestNo()); |
|
return orderNo != null ? orderNo : trimToNull(ref.providerOrderId()); |
|
} |
|
|
|
/** |
|
* 时间窗转恒健的日期参数。 |
|
* |
|
* <p>恒健收的是 UTC <b>日期</b>({@code yyyy-MM-dd}),不是时间戳;跨度不超过 |
|
* {@link HengjianConstants#ORDER_LIST_MAX_DAYS} 天。用「起止都含当天」的口径, |
|
* 所以计算跨度时把 end 当天算进去。</p> |
|
*/ |
|
private void addDateRange(WarehouseContext ctx, Map<String, Object> params, OutboundQuery query) { |
|
java.time.LocalDate begin = query.after().atZone(ZoneOffset.UTC).toLocalDate(); |
|
java.time.LocalDate end = query.before().atZone(ZoneOffset.UTC).toLocalDate(); |
|
long days = java.time.temporal.ChronoUnit.DAYS.between(begin, end); |
|
if (days > HengjianConstants.ORDER_LIST_MAX_DAYS) { |
|
throw validation(ctx, OP_ORDER_QUERY, |
|
"hengjian order list window must not exceed " |
|
+ HengjianConstants.ORDER_LIST_MAX_DAYS + " days, got " + days); |
|
} |
|
params.put("beginDateTime", begin.toString()); |
|
params.put("endDateTime", end.toString()); |
|
} |
|
|
|
/** |
|
* 单页行数。 |
|
* |
|
* <p>上限 100 是<b>文档明写</b>的(「一页的行数,默认最高 100」)。超过时 |
|
* <b>显式拒绝</b>而不是静默截断:调用方按自己传的 pageSize 判末页, |
|
* 被悄悄改小会误判「还有下一页」。</p> |
|
*/ |
|
private int requireRows(WarehouseContext ctx, int pageSize) { |
|
if (pageSize <= 0) { |
|
return HengjianConstants.ORDER_LIST_MAX_ROWS; |
|
} |
|
if (pageSize > HengjianConstants.ORDER_LIST_MAX_ROWS) { |
|
throw validation(ctx, OP_ORDER_QUERY, |
|
"hengjian order list rows must not exceed " |
|
+ HengjianConstants.ORDER_LIST_MAX_ROWS + ", got " + pageSize); |
|
} |
|
return pageSize; |
|
} |
|
|
|
|
|
/** 逗号拼接(恒健多条单号用逗号分隔)。 */ |
|
private static String joinIds(List<String> ids) { |
|
StringBuilder sb = new StringBuilder(); |
|
for (String id : ids) { |
|
if (sb.length() > 0) { |
|
sb.append(','); |
|
} |
|
sb.append(id); |
|
} |
|
return sb.toString(); |
|
} |
|
|
|
/** UTC 时间 → {@code yyyy-MM-dd HH:mm:ss}(恒健更新时间参数口径)。 */ |
|
private static String formatDateTime(java.time.Instant instant) { |
|
return instant == null ? null |
|
: java.time.LocalDateTime.ofInstant(instant, ZoneOffset.UTC) |
|
.format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss")); |
|
} |
|
|
|
/** null / 空白不放进参数表。 */ |
|
private static void putIfPresent(Map<String, Object> params, String key, String value) { |
|
String v = trimToNull(value); |
|
if (v != null) { |
|
params.put(key, v); |
|
} |
|
} |
|
|
|
/** 排序字段:调用方指定优先,否则用文档的默认 {@code id}。 */ |
|
private static String sortFieldOf(String requested) { |
|
String v = trimToNull(requested); |
|
return v == null ? HengjianConstants.ORDER_LIST_DEFAULT_SIDX : v; |
|
} |
|
|
|
/** 排序方向:{@code asc} / {@code desc};未指定用默认 {@code desc}。 */ |
|
private static String sortDirectionOf(SortDirection direction) { |
|
if (direction == null) { |
|
return HengjianConstants.ORDER_LIST_DEFAULT_SORT; |
|
} |
|
return direction == SortDirection.ASC ? "asc" : "desc"; |
|
} |
|
|
|
/** 游标是字符串化的页码;空游标表示第 1 页(恒健是 1 基入参)。 */ |
|
private static int pageNumberOf(String cursor) { |
|
String v = trimToNull(cursor); |
|
if (v == null) { |
|
return 1; |
|
} |
|
try { |
|
int page = Integer.parseInt(v); |
|
return page < 1 ? 1 : page; |
|
} catch (NumberFormatException e) { |
|
throw new IllegalArgumentException("hengjian order list cursor must be a page number, got " + v); |
|
} |
|
} |
|
|
|
private common.ecommerce.shared.error.ValidationException validation(WarehouseContext ctx, |
|
String operation, String message) { |
|
return new common.ecommerce.shared.error.ValidationException(WarehouseException.builder() |
|
.message(message) |
|
.operation(operation) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(false)); |
|
} |
|
|
|
private static String trimToNull(String v) { |
|
if (v == null) { |
|
return null; |
|
} |
|
String t = v.trim(); |
|
return t.isEmpty() ? null : t; |
|
} |
|
|
|
/** |
|
* 平台面单必须真的带文件。 |
|
* |
|
* <p>恒健的面单就是 {@code attachInfoItems} 里的一条附件;声明了 |
|
* {@code PLATFORM_LABEL_DELIVERY} 却不给文件,仓没有面单可打,等于静默失败。</p> |
|
*/ |
|
private static void requirePlatformLabelSupported(OutboundCommand cmd) { |
|
if (cmd.labelMode() == LabelMode.PLATFORM_LABEL |
|
&& (cmd.labelContentBase64() == null || cmd.labelContentBase64().trim().isEmpty())) { |
|
throw new IllegalArgumentException( |
|
"labelContentBase64 is required when labelMode=PLATFORM_LABEL for " |
|
+ cmd.outboundRequestNo()); |
|
} |
|
} |
|
|
|
/** 原始响应可能含 PII,异常里只留短片段。 */ private static String safeRelay(String raw) { |
|
if (raw == null) { |
|
return null; |
|
} |
|
return raw.length() <= 300 ? raw : raw.substring(0, 300) + "..."; |
|
} |
|
|
|
// ------------------------------------------------------------------ 商品 |
|
|
|
/** |
|
* 创建 / 编辑商品({@code POST /v1/product/save})。 |
|
* |
|
* <p>接口是<b>保存语义</b>:同一 SKU 再调即更新,所以不区分 create 与 update, |
|
* 也不像信仓那样先查一次再决定调哪个接口。</p> |
|
* |
|
* <p>响应只有 {@code code / message},<b>没有 data</b>,因此结果里的 |
|
* {@code status} 固定为 {@code SAVED}、{@code rawStatus} 取仓方的 message—— |
|
* 仓方并不告诉我们这次是新建还是更新,不能替它编。</p> |
|
* |
|
* @throws IllegalArgumentException 恒健要求但统一模型未给的非空字段缺失(本地拒绝) |
|
*/ |
|
@Override |
|
public ProductResult createOrUpdate(WarehouseContext ctx, WarehouseProduct product) { |
|
HengjianProductSaveDtos.SaveProductRequest body = HengjianProductMapper.toRequest(product); |
|
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_SAVE, body, OP_PRODUCT_SAVE); |
|
return ProductResult.of(body.sku, SAVED, json.stringAt(raw, "message")); |
|
} |
|
|
|
/** |
|
* 分页查商品({@code POST /v2/product/queryPage})。<b>只读</b>,不走幂等。 |
|
* |
|
* <p>请求的 {@code pageSize} / {@code pageNum} 文档标 STRING; |
|
* 文档的字段说明把两者写反了,按<b>响应</b>里的含义实现 |
|
* (pageSize = 每页条数,pageNum = 页码)。</p> |
|
* |
|
* <p>响应 {@code data} 是分页对象(不是数组);{@code total} 用来判断是否还有下一页。</p> |
|
*/ |
|
@Override |
|
public Page<ProductInfo> query(WarehouseContext ctx, ProductQuery query) { |
|
HengjianProductQueryDtos.QueryRequest body = HengjianProductQueryMapper.toRequest(query); |
|
String raw = execute(ctx, HengjianConstants.PATH_PRODUCT_QUERY_PAGE, body, OP_PRODUCT_QUERY); |
|
HengjianProductQueryDtos.QueryResponse resp = |
|
json.fromJson(raw, HengjianProductQueryDtos.QueryResponse.class); |
|
return HengjianProductQueryMapper.toPage(resp == null ? null : resp.data, |
|
query.cursor(), HengjianProductQueryMapper.pageSizeOf(query.pageSize())); |
|
} |
|
|
|
// ------------------------------------------------------------------ 仓库目录 |
|
|
|
/** |
|
* 当前组织下的全部仓库({@code POST /v2/warehouse/getWarehouse},无参数)。 |
|
* |
|
* <p>返回的 {@code warehouseCode} 可直接用于下单、库存查询等接口。</p> |
|
*/ |
|
@Override |
|
public List<WarehouseFacility> warehouses(WarehouseContext ctx) { |
|
String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_LIST, null, OP_WAREHOUSE_LIST); |
|
List<HengjianWarehouseDtos.WarehouseRow> rows = |
|
json.listAt(raw, "data", HengjianWarehouseDtos.WarehouseRow.class); |
|
return HengjianDirectoryMapper.toWarehouses(rows); |
|
} |
|
|
|
/** |
|
* 承运商 / 物流方式代码({@code POST /v2/carrierGroup/getCarrierGroup},无参数)。 |
|
* |
|
* <p>返回物流产品代码(如 {@code UPS2DAM_HL}),可直接作为下单的 {@code carrierCode}。 |
|
* 按出现顺序去重。</p> |
|
*/ |
|
@Override |
|
public List<String> carriers(WarehouseContext ctx) { |
|
return codesOf(fetchAllServices(ctx)); |
|
} |
|
|
|
/** |
|
* 物流产品清单({@code POST /v2/carrierGroup/getCarrierGroup})。 |
|
* |
|
* <p>恒健这个接口<b>没有仓维度</b>,拿到的是组织级清单;{@code warehouseCode} |
|
* 仅用于写进结果字段,便于调用方区分来源。需要「某仓支持哪些渠道」用 |
|
* {@link #productsOfWarehouse}。</p> |
|
*/ |
|
@Override |
|
public List<LogisticsProduct> products(WarehouseContext ctx, String warehouseCode) { |
|
return HengjianDirectoryMapper.toProducts(fetchAllServices(ctx), resolveWarehouseCode(ctx, warehouseCode)); |
|
} |
|
|
|
/** |
|
* 查询「某仓支持哪些物流渠道」({@code POST |
|
* /v2/carrierGroup/getWarehouseCarrierGroupServices})。 |
|
* |
|
* <p>返回形状与 {@link #products} 不同:{@code data} 是以仓代码为键的对象, |
|
* 不是数组;只取请求的那个仓,混进别的仓的渠道会让「仓不支持该渠道」 |
|
* 变成仓方报错。</p> |
|
*/ |
|
public List<LogisticsProduct> productsOfWarehouse(WarehouseContext ctx, String warehouseCode) { |
|
String code = resolveWarehouseCode(ctx, warehouseCode); |
|
if (code == null) { |
|
throw new IllegalArgumentException( |
|
"hengjian warehouse carrier services need a warehouseCode; none given and account has none"); |
|
} |
|
List<String> codes = new ArrayList<String>(); |
|
codes.add(code); |
|
Map<String, Object> body = new LinkedHashMap<String, Object>(); |
|
body.put("warehouseCodes", codes); |
|
|
|
String raw = execute(ctx, HengjianConstants.PATH_WAREHOUSE_CARRIER_GROUP, body, |
|
OP_LOGISTICS_PRODUCTS); |
|
return HengjianDirectoryMapper.toProducts(servicesOfWarehouse(raw, code), code); |
|
} |
|
|
|
// ------------------------------------------------------------------ 内部 |
|
|
|
private List<HengjianCarrierGroupDtos.CarrierServiceRow> fetchAllServices(WarehouseContext ctx) { |
|
String raw = execute(ctx, HengjianConstants.PATH_CARRIER_GROUP, null, OP_CARRIERS); |
|
return json.listAt(raw, "data", HengjianCarrierGroupDtos.CarrierServiceRow.class); |
|
} |
|
|
|
/** {@code data} 是 {@code 仓代码 → 服务数组} 的对象;只取指定仓。 */ |
|
private List<HengjianCarrierGroupDtos.CarrierServiceRow> servicesOfWarehouse(String raw, String warehouseCode) { |
|
List<HengjianCarrierGroupDtos.CarrierServiceRow> rows = |
|
new ArrayList<HengjianCarrierGroupDtos.CarrierServiceRow>(); |
|
JsonNode data = json.nodeAt(raw, "data"); |
|
if (data == null || !data.isObject()) { |
|
return rows; |
|
} |
|
JsonNode node = data.get(warehouseCode); |
|
if (node == null || !node.isArray()) { |
|
return rows; |
|
} |
|
Iterator<JsonNode> it = node.elements(); |
|
while (it.hasNext()) { |
|
rows.add(json.mapper().convertValue(it.next(), |
|
HengjianCarrierGroupDtos.CarrierServiceRow.class)); |
|
} |
|
return rows; |
|
} |
|
|
|
/** 显式仓代码优先,否则用账户配置的;都没有返回 null,由调用方决定是否拒绝。 */ |
|
private static String resolveWarehouseCode(WarehouseContext ctx, String warehouseCode) { |
|
if (warehouseCode != null && !warehouseCode.trim().isEmpty()) { |
|
return warehouseCode.trim(); |
|
} |
|
String configured = ctx.providerWarehouseId(); |
|
return configured == null || configured.trim().isEmpty() ? null : configured.trim(); |
|
} |
|
|
|
private static List<String> codesOf(List<HengjianCarrierGroupDtos.CarrierServiceRow> rows) { |
|
List<String> out = new ArrayList<String>(); |
|
if (rows == null) { |
|
return out; |
|
} |
|
for (HengjianCarrierGroupDtos.CarrierServiceRow row : rows) { |
|
if (row == null || row.code == null || row.code.trim().isEmpty()) { |
|
continue; |
|
} |
|
String code = row.code.trim(); |
|
if (!out.contains(code)) { |
|
out.add(code); |
|
} |
|
} |
|
return out; |
|
} |
|
|
|
/** |
|
* 发请求并校验信封。 |
|
* |
|
* @param body null 表示无参数接口,发送空 JSON 对象 |
|
*/ |
|
private String execute(WarehouseContext ctx, String path, Object body, String operation) { |
|
rateLimiter.acquire(path, HengjianConstants.PERMITS_PER_SECOND); |
|
HttpRequest req = requestFactory.post(ctx.endpointBaseUrl(), path, body, ctx.secret(), ctx, operation); |
|
HttpResponse resp = transport.execute(req); |
|
String raw = HengjianEnvelope.of(resp, json, operation, ctx.warehouseCode(), ctx.requestId()).body(); |
|
if (raw == null || raw.trim().isEmpty()) { |
|
throw WarehouseException.builder() |
|
.message("hengjian " + operation + " returned an empty body") |
|
.operation(operation) |
|
.warehouseCode(ctx.warehouseCode()) |
|
.provider(provider().name()) |
|
.requestId(ctx.requestId()) |
|
.retryable(true) |
|
.build(); |
|
} |
|
return raw; |
|
} |
|
}
|
|
|