package common.ecommerce.hengjian.adapter; import common.ecommerce.hengjian.HengjianConstants; import common.ecommerce.hengjian.dto.HengjianOperationFeeDtos; import common.ecommerce.hengjian.dto.HengjianStorageFeeDtos; import common.ecommerce.hengjian.dto.HengjianTailDeliveryFeeDtos; import common.ecommerce.shared.support.Money; import common.ecommerce.warehouse.enums.WarehouseFeeType; import common.ecommerce.warehouse.enums.WarehouseProvider; import common.ecommerce.warehouse.model.BillingDocument; import common.ecommerce.warehouse.model.FeeQuery; import java.math.BigDecimal; import java.time.LocalDate; import java.time.ZoneOffset; import java.util.ArrayList; import java.util.List; /** * 恒健计费明细映射(仓储费 / 尾程费 / 作业费)。 * *

三个接口的请求结构一致、行字段完全不同,所以请求构造共用一份, * 行映射各写一个方法。

* *

口径

* */ public final class HengjianFeeMapper { /** 币种缺失时的默认值(恒健默认 USD)。 */ private static final String DEFAULT_CURRENCY = "USD"; private HengjianFeeMapper() { } // ================================================================ 请求 /** * 把统一查询条件填进三个计费接口共用的过滤字段。 * *

必须有过滤条件:全空等于拉全量账单,这里直接拒绝, * 不发这种请求。

* *

字段对应关系:

* * * * * * * * *
{@link FeeQuery}恒健说明
{@code billingTransNo}{@code relOrderNos}计费单号(账单侧的业务单号)
{@code saleOrderNo} / {@code externalOrderNo}{@code sourceNos}来源单号(我们下发的出库单号);两个字段都当来源单号,去重后下发
{@code settledAfter/Before} 或 {@code snapshotDateRange}{@code btChargeAt}{@code yyyy-MM-dd ~ yyyy-MM-dd}
* * @param defaultWarehouseCode 调用方没在 {@code orgWarehouseCodes} 里指定仓时用的兜底仓 * @return {@code btChargeAt};没有日期条件时为 null * @throws IllegalArgumentException 一条过滤条件都没有 */ public static String applyFilters(FeeQuery query, String defaultWarehouseCode, List orgWarehouseCodes, List relOrderNos, List sourceNos) { boolean filtered = false; String billingNo = trimToNull(query.billingTransNo()); if (billingNo != null) { relOrderNos.add(billingNo); filtered = true; } // 两个字段语义都是「业务侧的单号」,都映射到来源单号;重复时只发一个 String orderNo = trimToNull(firstNonBlank(query.externalOrderNo(), query.saleOrderNo())); if (orderNo != null) { sourceNos.add(orderNo); filtered = true; } String dateRange = null; if (query.hasSettledRange()) { dateRange = formatDateRange(query.settledAfter(), query.settledBefore()); filtered = true; } else if (query.hasDateRange()) { dateRange = formatDateRange(query.snapshotStartDate(), query.snapshotEndDate()); filtered = true; } // 恒健三个计费接口都没有 SKU 维度,也没有「单号类型」参数: // 静默忽略会让调用方以为过滤生效了,对账金额对不上 if (trimToNull(query.providerSku()) != null) { throw new IllegalArgumentException( "hengjian billing detail has no SKU filter, got providerSku=" + query.providerSku()); } if (query.noType() != null) { throw new IllegalArgumentException( "hengjian billing detail has no order-number-type parameter, got noType=" + query.noType()); } if (!filtered) { throw new IllegalArgumentException( "hengjian billing detail query requires at least one filter " + "(billingTransNo / saleOrderNo / externalOrderNo / date range); " + "refusing to pull the whole bill"); } // 仓过滤:调用方显式给了就用调用方的(账单接口本就是复数仓), // 没给才退回账户仓,避免跨仓混账 if (!query.warehouseCodes().isEmpty()) { orgWarehouseCodes.addAll(query.warehouseCodes()); } else { String warehouse = trimToNull(defaultWarehouseCode); if (warehouse != null) { orgWarehouseCodes.add(warehouse); } } return dateRange; } /** 日期区间 → {@code "yyyy-MM-dd ~ yyyy-MM-dd"}(UTC 日期)。 */ static String formatDateRange(java.time.Instant after, java.time.Instant before) { LocalDate start = after.atZone(ZoneOffset.UTC).toLocalDate(); LocalDate end = before.atZone(ZoneOffset.UTC).toLocalDate(); return start + HengjianConstants.FEE_DATE_RANGE_SEPARATOR + end; } /** 日期区间(仅日期版本)。 */ static String formatDateRange(LocalDate start, LocalDate end) { return start + HengjianConstants.FEE_DATE_RANGE_SEPARATOR + end; } /** 页码:游标是字符串化的页码,空游标表示第 1 页(恒健入参 1 基)。 */ static int pageOf(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 billing page cursor must be a page number, got " + v); } } /** * 每页条数:0 用默认值;超过上限显式报错。 * *

上一版是静默截断到 200——调用方传 9999 实际只发 200 却毫不知情, * 再按自己的 pageSize 判「本页是否满」就会误判末页,漏账。现在超限直接拒绝。

*/ static int pageSizeOf(int requested) { if (requested <= 0) { return HengjianConstants.FEE_PAGE_SIZE_DEFAULT; } if (requested > HengjianConstants.FEE_PAGE_SIZE_MAX) { throw new IllegalArgumentException( "hengjian billing page size must not exceed " + HengjianConstants.FEE_PAGE_SIZE_MAX + " (仓方上限待真机确认), got " + requested); } return requested; } // ================================================================ 仓储费 /** 仓储费行 → 统一费用单据。 */ public static BillingDocument toDocument(HengjianStorageFeeDtos.StorageFeeRow row, String warehouseCode) { Money amount = moneyOf(row.cost, row.currency); if (amount == null) { // 金额缺失的行无法入账:返回 null,由 mapAll 跳过,不用 0 兜底 return null; } return BillingDocument.builder() .warehouseCode(firstNonBlank(row.orgWarehouseCode, warehouseCode)) .sourceProvider(WarehouseProvider.HENGJIAN) .documentNo(trimToNull(row.billNo)) .serialNumber(trimToNull(row.transactionNo)) .feeName(trimToNull(row.settlementName)) .feeType(WarehouseFeeType.STORAGE) // 账单明细是已发生账目,不是预估 .estimated(false) .settledAt(HengjianOrderMapper.parseTime( firstNonBlank(row.settlementAt, null))) .amount(amount) .providerSku(trimToNull(row.sku)) .saleOrderNo(trimToNull(row.sourceNo)) .build(); } // ================================================================ 尾程费 /** 尾程费行 → 统一费用单据。 */ public static BillingDocument toDocument(HengjianTailDeliveryFeeDtos.TailDeliveryFeeRow row, String warehouseCode) { Money amount = moneyOf(row.cost, row.currency); if (amount == null) { return null; } return BillingDocument.builder() .warehouseCode(firstNonBlank(row.orgWarehouseCode, warehouseCode)) .sourceProvider(WarehouseProvider.HENGJIAN) .documentNo(trimToNull(row.billNo)) .serialNumber(trimToNull(row.transactionNo)) .feeName(trimToNull(row.settlementName)) .feeType(WarehouseFeeType.LAST_MILE) .estimated(false) .settledAt(HengjianOrderMapper.parseTime( firstNonBlank(row.settlementAt, row.chargeAt))) .amount(amount) .providerSku(trimToNull(row.erpSku)) // 订单号口径:站内单号优先,其次是来源单号,最后平台单号 .saleOrderNo(firstNonBlank(row.deliveryOrderNo, firstNonBlank(row.sourceOrderNo, firstNonBlank(row.orderNo, row.platformOrderNo)))) .build(); } // ================================================================ 作业费 /** 作业费行 → 统一费用单据。 */ public static BillingDocument toDocument(HengjianOperationFeeDtos.OperationFeeRow row, String warehouseCode) { Money amount = moneyOf(row.cost, row.currency); if (amount == null) { return null; } return BillingDocument.builder() .warehouseCode(firstNonBlank(row.orgWarehouseCode, warehouseCode)) .sourceProvider(WarehouseProvider.HENGJIAN) .documentNo(trimToNull(row.billNo)) .serialNumber(trimToNull(row.transactionNo)) .feeName(trimToNull(row.settlementName)) .feeType(WarehouseFeeType.OPERATION) .estimated(false) .settledAt(HengjianOrderMapper.parseTime( firstNonBlank(row.settlementAt, row.chargeAt))) .amount(amount) .providerSku(trimToNull(row.relSku)) .saleOrderNo(firstNonBlank(row.relOrderNo, row.sourceNo)) .build(); } // ================================================================ 列表 static List mapAll(List rows, RowMapper mapper) { if (rows == null || rows.isEmpty()) { return new ArrayList(); } List out = new ArrayList(rows.size()); for (T row : rows) { if (row == null) { continue; } BillingDocument doc = mapper.map(row); // 金额缺失的行直接跳过:BillingDocument 要求 amount 非空, // 用 0 兜底会让对账金额偏小且查不出原因 if (doc != null && doc.amount() != null) { out.add(doc); } } return out; } /** 行 → 单据。 */ interface RowMapper { BillingDocument map(T row); } // ================================================================ 工具 /** * 金额。 * *

恒健三项计费接口的 {@code cost} 都是该行总费用;缺失时返回 * {@code null}(调用方会跳过该行),不用 0 兜底——0 会让对账金额偏小, * 而且看不出是哪一行缺了。

*/ static Money moneyOf(Double cost, String currency) { if (cost == null) { return null; } String code = trimToNull(currency); return Money.of(BigDecimal.valueOf(cost), code == null ? DEFAULT_CURRENCY : code); } static String firstNonBlank(String a, String b) { String x = trimToNull(a); return x != null ? x : trimToNull(b); } static String trimToNull(String v) { if (v == null) { return null; } String t = v.trim(); return t.isEmpty() ? null : t; } }