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.
332 lines
14 KiB
332 lines
14 KiB
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; |
|
|
|
/** |
|
* 恒健计费明细映射(仓储费 / 尾程费 / 作业费)。 |
|
* |
|
* <p>三个接口的<b>请求结构一致</b>、<b>行字段完全不同</b>,所以请求构造共用一份, |
|
* 行映射各写一个方法。</p> |
|
* |
|
* <h2>口径</h2> |
|
* <ul> |
|
* <li><b>都是已发生的账单明细</b>,不是预估 → {@code estimated(false)}。 |
|
* 恒健的计费明细来自账单({@code billNo}),不存在「先给预估、后出实际」的两段式。</li> |
|
* <li><b>金额单位</b>:{@code cost} 是<b>该行总费用</b>,不是单价。</li> |
|
* <li><b>交易号</b>:{@code transactionNo} 是同一计费项多条记录的唯一区分, |
|
* 落 {@link BillingDocument#serialNumber()};{@code billNo} 落 |
|
* {@link BillingDocument#documentNo()}。</li> |
|
* <li><b>费用类型</b>由<i>接口</i>决定(仓储 / 尾程 / 作业),不靠猜费用名—— |
|
* 作业费的 {@code settlementName} 形如「退货入库->入库费->…」,靠字符串归类迟早错。</li> |
|
* </ul> |
|
*/ |
|
public final class HengjianFeeMapper { |
|
|
|
/** 币种缺失时的默认值(恒健默认 USD)。 */ |
|
private static final String DEFAULT_CURRENCY = "USD"; |
|
|
|
private HengjianFeeMapper() { |
|
} |
|
|
|
// ================================================================ 请求 |
|
|
|
/** |
|
* 把统一查询条件填进三个计费接口共用的过滤字段。 |
|
* |
|
* <p><b>必须有过滤条件</b>:全空等于拉全量账单,这里直接拒绝, |
|
* 不发这种请求。</p> |
|
* |
|
* <p>字段对应关系:</p> |
|
* <table border="1"> |
|
* <tr><th>{@link FeeQuery}</th><th>恒健</th><th>说明</th></tr> |
|
* <tr><td>{@code billingTransNo}</td><td>{@code relOrderNos}</td> |
|
* <td>计费单号(账单侧的业务单号)</td></tr> |
|
* <tr><td>{@code saleOrderNo} / {@code externalOrderNo}</td><td>{@code sourceNos}</td> |
|
* <td>来源单号(我们下发的出库单号);两个字段都当来源单号,去重后下发</td></tr> |
|
* <tr><td>{@code settledAfter/Before} 或 {@code snapshotDateRange}</td> |
|
* <td>{@code btChargeAt}</td><td>{@code yyyy-MM-dd ~ yyyy-MM-dd}</td></tr> |
|
* </table> |
|
* |
|
* @param defaultWarehouseCode 调用方没在 {@code orgWarehouseCodes} 里指定仓时用的兜底仓 |
|
* @return {@code btChargeAt};没有日期条件时为 null |
|
* @throws IllegalArgumentException 一条过滤条件都没有 |
|
*/ |
|
public static String applyFilters(FeeQuery query, String defaultWarehouseCode, |
|
List<String> orgWarehouseCodes, |
|
List<String> relOrderNos, |
|
List<String> 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 用默认值;超过上限<b>显式报错</b>。 |
|
* |
|
* <p>上一版是静默截断到 200——调用方传 9999 实际只发 200 却毫不知情, |
|
* 再按自己的 pageSize 判「本页是否满」就会误判末页,漏账。现在超限直接拒绝。</p> |
|
*/ |
|
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; |
|
} |
|
|
|
/** |
|
* 恒健的「未结算」哨兵日期。 |
|
* |
|
* <p><b>真机确认(2026-11-17)</b>:未结算的账单行会把 |
|
* {@code settlementAt} / {@code bookAt} 填成 {@code 1997-01-01 00:00:00}, |
|
* 不是 null。直接落库会让对账以为「1997 年结过一笔」。</p> |
|
*/ |
|
static final java.time.LocalDate NO_SETTLEMENT_DATE = java.time.LocalDate.of(1997, 1, 1); |
|
|
|
/** |
|
* 结算时间:哨兵日期转 null。 |
|
* |
|
* @param raw 仓方原始时间字符串 |
|
* @return 真实结算时间;未结算 / 空 / 无法解析时返回 null |
|
*/ |
|
static java.time.Instant settledAt(String raw) { |
|
java.time.Instant parsed = HengjianOrderMapper.parseTime(raw); |
|
if (parsed == null) { |
|
return null; |
|
} |
|
if (NO_SETTLEMENT_DATE.equals( |
|
parsed.atZone(java.time.ZoneOffset.UTC).toLocalDate())) { |
|
return null; |
|
} |
|
return parsed; |
|
} |
|
|
|
// ================================================================ 仓储费 |
|
|
|
/** 仓储费行 → 统一费用单据。 */ |
|
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(settledAt(row.settlementAt)) |
|
.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) |
|
// 未结算行回 1997-01-01 哨兵;哨兵转 null,不回落到 chargeAt |
|
.settledAt(settledAt(row.settlementAt)) |
|
.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) |
|
// 未结算行回 1997-01-01 哨兵;哨兵转 null,不回落到 chargeAt |
|
.settledAt(settledAt(row.settlementAt)) |
|
.amount(amount) |
|
.providerSku(trimToNull(row.relSku)) |
|
.saleOrderNo(firstNonBlank(row.relOrderNo, row.sourceNo)) |
|
.build(); |
|
} |
|
|
|
// ================================================================ 列表 |
|
|
|
static <T> List<BillingDocument> mapAll(List<T> rows, RowMapper<T> mapper) { |
|
if (rows == null || rows.isEmpty()) { |
|
return new ArrayList<BillingDocument>(); |
|
} |
|
List<BillingDocument> out = new ArrayList<BillingDocument>(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<T> { |
|
BillingDocument map(T row); |
|
} |
|
|
|
// ================================================================ 工具 |
|
|
|
/** |
|
* 金额。 |
|
* |
|
* <p>恒健三项计费接口的 {@code cost} 都是<b>该行总费用</b>;缺失时返回 |
|
* {@code null}(调用方会跳过该行),<b>不用 0 兜底</b>——0 会让对账金额偏小, |
|
* 而且看不出是哪一行缺了。</p> |
|
*/ |
|
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; |
|
} |
|
}
|
|
|