Browse Source

fix(hengjian): 计费的「未结算」哨兵日期 1997-01-01 转 null

重测计费接口时发现真问题:未结算的账单行把 settlementAt / bookAt
填成 1997-01-01 00:00:00 而不是 null。直接落库会让对账以为
1997 年结过一笔。

- HengjianFeeMapper 新增 settledAt():哨兵日期转 null;
  仓储费 / 尾程费 / 作业费三个接口统一走它
- 尾程费与作业费原先的 firstNonBlank(settlementAt, chargeAt) 回落
  一并去掉——chargeAt 是计费发生时间,不是结算时间,回落会让
  「未结算」看起来像「已结算」

顺带更正之前的结论:ES 抖动无法复现。同一参数连打 20 次全部成功,
rows 5/10/20/50/100 也都成功,说明当时是仓方一次性抖动,不是稳定
故障。重试逻辑保留(成本极低、只读无副作用),但文档改为如实记录。

新增结算哨兵测试。mvn test 全量通过。
master
lml 3 days ago
parent
commit
492743b34e
  1. 21
      docs-warehouse/hengjian/README.md
  2. 38
      warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java

21
docs-warehouse/hengjian/README.md

@ -1124,6 +1124,27 @@ mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
| 商品 `cost` | DOUBLE | 可为 **0.0**,是合法成本不是「没给」 | | 商品 `cost` | DOUBLE | 可为 **0.0**,是合法成本不是「没给」 |
| 商品 `isInsuranceRate` | 保价费率 | 是**费率**不是金额,不能塞进 `insuranceFee` | | 商品 `isInsuranceRate` | 保价费率 | 是**费率**不是金额,不能塞进 `insuranceFee` |
### 计费接口:重测结论(2026-11-17 晚间)
之前记录的 ES 故障<b>无法复现</b>。同一参数连打 20 次全部成功(0 失败),
换 `rows` = 5/10/20/50/100 也都成功。所以当时的 ES 异常是<b>仓方一次性抖动</b>,
不是稳定故障。
**但这轮重测发现了一个真问题**:
| 项 | 现象 |
|---|---|
| 未结算行的 `settlementAt` | 返回 **`1997-01-01 00:00:00`**(哨兵),**不是 null** |
| 未结算行的 `billNo` / `settlementName` | 空串 |
| 未结算行的 `currency` | 空串 |
| 未结算行的 `errorMessage` | 有内容,如「UAT 组织EFCA 仓库仓储费报价未匹配!」 |
直接落库会让对账以为「1997 年结过一笔」。适配器已加 `settledAt()`:
**哨兵日期转 null**,三个计费接口统一处理。
另外注意:仓储费的 `cost` 可以为 0 且 `currency` 为空——适配器用默认币种兜底
(`DEFAULT_CURRENCY`),不会丢行。
### 仓方自身故障(非我方问题) ### 仓方自身故障(非我方问题)
三个计费接口在测试环境<b>间歇性</b>回 `code=999999`: 三个计费接口在测试环境<b>间歇性</b>回 `code=999999`:

38
warehouse-sdk-hengjian/src/main/java/common/ecommerce/hengjian/adapter/HengjianFeeMapper.java

@ -168,6 +168,33 @@ public final class HengjianFeeMapper {
return 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;
}
// ================================================================ 仓储费 // ================================================================ 仓储费
/** 仓储费行 → 统一费用单据。 */ /** 仓储费行 → 统一费用单据。 */
@ -187,8 +214,7 @@ public final class HengjianFeeMapper {
.feeType(WarehouseFeeType.STORAGE) .feeType(WarehouseFeeType.STORAGE)
// 账单明细是已发生账目,不是预估 // 账单明细是已发生账目,不是预估
.estimated(false) .estimated(false)
.settledAt(HengjianOrderMapper.parseTime( .settledAt(settledAt(row.settlementAt))
firstNonBlank(row.settlementAt, null)))
.amount(amount) .amount(amount)
.providerSku(trimToNull(row.sku)) .providerSku(trimToNull(row.sku))
.saleOrderNo(trimToNull(row.sourceNo)) .saleOrderNo(trimToNull(row.sourceNo))
@ -212,8 +238,8 @@ public final class HengjianFeeMapper {
.feeName(trimToNull(row.settlementName)) .feeName(trimToNull(row.settlementName))
.feeType(WarehouseFeeType.LAST_MILE) .feeType(WarehouseFeeType.LAST_MILE)
.estimated(false) .estimated(false)
.settledAt(HengjianOrderMapper.parseTime( // 未结算行回 1997-01-01 哨兵;哨兵转 null,不回落到 chargeAt
firstNonBlank(row.settlementAt, row.chargeAt))) .settledAt(settledAt(row.settlementAt))
.amount(amount) .amount(amount)
.providerSku(trimToNull(row.erpSku)) .providerSku(trimToNull(row.erpSku))
// 订单号口径:站内单号优先,其次是来源单号,最后平台单号 // 订单号口径:站内单号优先,其次是来源单号,最后平台单号
@ -240,8 +266,8 @@ public final class HengjianFeeMapper {
.feeName(trimToNull(row.settlementName)) .feeName(trimToNull(row.settlementName))
.feeType(WarehouseFeeType.OPERATION) .feeType(WarehouseFeeType.OPERATION)
.estimated(false) .estimated(false)
.settledAt(HengjianOrderMapper.parseTime( // 未结算行回 1997-01-01 哨兵;哨兵转 null,不回落到 chargeAt
firstNonBlank(row.settlementAt, row.chargeAt))) .settledAt(settledAt(row.settlementAt))
.amount(amount) .amount(amount)
.providerSku(trimToNull(row.relSku)) .providerSku(trimToNull(row.relSku))
.saleOrderNo(firstNonBlank(row.relOrderNo, row.sourceNo)) .saleOrderNo(firstNonBlank(row.relOrderNo, row.sourceNo))

Loading…
Cancel
Save