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

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;
}
}