发生了什么

充电网点开业前要先和用电方签一份用电合同。合同生效后,计费系统按月出电费账单:先按小时采集的用电数据形成日账单,月初再把上个月的日账单汇总成一张月账单。账单不是凭空算出来的,它挂在“合同快照”上——快照是合同系统为主合同保存的一份副本,记录这份合同当前处在待履行、履行中还是已结束。合同生效时的状态推进、首次账单任务的创建,都由系统里按时间点执行的任务记录完成,这类记录通常叫触发器。

正常流程是:首份合同生效当天,合同系统的状态变更触发器把快照从“待履行”改成“履行中”,同时链式创建一条首次电费触发器,起算月等于合同生效当月;之后每个月初的凌晨,调度按这张快照结算上个月的月账单。

这次,一个网点的首份合同在 2025 年 11 月 19 日生效,此后五个多月里,快照的更新时间没有任何变化,状态一直是“待履行”。同一时刻创建的首次电费触发器,起算月直接落到了 2026 年 2 月,跳过了 11 月、12 月和次年 1 月。于是这三个月没有进入月度调度:11 月和 12 月既没有日账单,也没有月账单。

后面两个月的账是补出来的:1 月中旬有人在非调度时段手动触发,才为 1 月生成了当月日账单和一张月账单;12 月的电费则由运营用人工补单的方式录了一张,账期挂在 1 月。到 2 月上旬该网点重新签约,新快照状态正常,重签流程顺带生成了 2 月账单,3 月起月账单才回到月初调度。11 月的账单到记录时仍未补。

本质

问题不是账单算错了,而是账单根本没有被创建。原因有两层,并且相互叠加。

第一层在首次签约分支:它先调用远程服务绑卡,再更新快照状态,最后把触发器标记为“已执行”。这次快照更新没有改到任何一行,但代码没有检查更新影响的行数,也没有抛异常,触发器照常把“已执行”写进自己的记录并提交。两条记录因此分叉:任务记录说做完了,快照还停在“待履行”。账单任务挂在快照上,看到快照没有进入“履行中”,就不会为这份合同排月账单,缺失从这一步开始。

第二层在链式创建:首次电费触发器的起算月被算成了生效月之后第三个月。等它第一次执行时,前面三个月已经不在它的范围内,系统也不会回头补算,所以缺失不会自愈。

任务记录显示已执行,不代表它负责的那条数据真的被改过。

至于快照更新为什么零行——是更新条件没有命中,还是异常在中途被吞掉,当时没有拿到那次执行的链路日志,尚未最终定位。修复方向是:更新后校验影响行数,零行就抛异常并回滚,让“已执行”与状态推进同成败;远程绑卡失败不再吞掉,并且要为远端动作准备幂等或补偿;起算月改为合同生效当月,首次触发时间取生效月次月 1 日;再补两类扫描,一类找“已签约多日仍是待履行”的快照,一类找起算月与生效月跨度超过一个月的触发器。数据侧需要补建缺失月份账单,并把旧快照状态校正为合同已结束。修复上线状态待确认。

错误代码

void contractStatusChange(ContractTrigger trigger) {
    if (trigger.isFirstSign()) {
        cardService.bindFirstCard(trigger);
        // 为什么错:更新条件不匹配时影响 0 行,不抛异常也不回滚
        snapshotRepository.updateStatus(trigger.getSnapshotId(), "PERFORMING");
        // 为什么错:起算月按生效月加 3 个月,中间月份被整段跳过
        YearMonth start = YearMonth.from(trigger.getLeaseStart()).plusMonths(3);
        billTriggerService.createFirstEleTrigger(trigger, start.atDay(1));
    }
    // 为什么错:不论上面是否真的生效,都标记已执行
    triggerRepository.markExecuted(trigger.getId());
}

修复代码示例

@Transactional
void contractStatusChange(ContractTrigger trigger) {
    if (trigger.isFirstSign()) {
        cardService.bindFirstCard(trigger);          // 绑卡失败直接抛出,不再吞掉
        int rows = snapshotRepository.updateStatus(
            trigger.getSnapshotId(), "PERFORMING");
        if (rows != 1) {                             // 零行说明快照没被改到
            throw new IllegalStateException(
                "快照状态未推进:" + trigger.getSnapshotId());
        }
        YearMonth start = YearMonth.from(trigger.getLeaseStart());
        billTriggerService.createFirstEleTrigger(trigger, start.atDay(1));
    }
    triggerRepository.markExecuted(trigger.getId()); // 与状态推进同一次提交
}

两段代码是脱敏教学示例,不是事故源码。修复的关键是让“标记已执行”与“快照状态推进”同成败,而不是在失败后继续往下走。绑卡是远程调用,事务回滚不会撤销已经发生的远端动作,因此远端一侧还要按稳定的业务编号做幂等或补偿,否则重试会在对方那里留下第二条记录。

下次遇到这些场景要警惕

  • 给状态机任务增加新步骤:先确认这一步和“标记已执行”是否在同一次提交里,再用不存在的快照编号、已结束的快照各执行一次,观察任务是否仍被标记成功。
  • 由生效日推导下一次执行时间:用月中生效、月末生效、跨年、闰月各建一份合同,核对起算月和首次触发时间,确认没有任何自然月被跳过。
  • 账单或报表“没出来”:先分清是没创建、创建了没展示,还是金额不对;沿任务记录、快照状态、账单三层各查一条记录,不要只看任务的执行状态。
  • 补监控:对“已签约超过若干天仍是待履行”和“起算月与生效月跨度大于一个月”各设一条告警,而不是只告警任务失败。