发生了什么

网点是业务里对外营业的门店,每个网点对应一份租赁合同,合同约定这个网点要承担的租金。系统按合同约定的结算周期生成租金账单,一张账单记录这一期应付多少租金、覆盖哪段时间,之后进入结算和付款。账单由定时任务生成:任务扫描合同,挑出该出账的合同,再逐份生成账单。

正常路径是合同签完、网点处于营业中,定时任务就会在每一期为它生成账单。这个网点的合同不是在线上签完后自动进入系统的,而是签署完成之后,由业务人员把合同内容补录进来。

这类合同在系统里的编号统一以固定前缀开头,用来标识它是线下补录。补录时合同记录的状态是已签署,网点也处于营业中,两个条件都满足。但这家网点从头到尾没有出现过租金账单,业务人员在核对网点账单时发现租金未生成,才把问题报出来。这个网点的合同起始时间在 2025 年 5 月,发现时账单仍然缺失。

本质

一句话:定时任务在判断“这份合同要不要出账”时,除了合同状态和网点状态,还用编号前缀判断合同来源;只要前缀表示线下补录就直接跳过,于是一份本该出账的合同从来没有进入账单生成逻辑。

按执行顺序拆开看:

  1. 定时任务先查出候选合同,再逐份过滤。前两道条件是合同状态为已签署、网点状态为营业中,这个网点都满足。
  2. 紧接着还有第三道判断:合同编号是否以线下补录的前缀开头。命中就跳过当前合同,后面的生成动作完全不会执行。
  3. 这道判断的本意是让线下补录的合同不走自动出账。但它把“合同从哪里录入”当成了“合同该不该出账”,两者并不等价:这个网点的合同确实要按期承担租金,只是录入渠道不同。
  4. 因为跳过是静默的,任务不报错,也不留下待处理记录,表面看一切正常。账单列表里长期没有这一期,业务只能靠人工对账发现。
  5. 给出的处置建议是走数据订正,直接补出缺失的租金账单,而不是重跑常规生成链路。常规链路仍会按前缀把这份合同跳过。补账前要确认从哪一期开始补、此前是否已经人工补过部分月份;该网点还有一份变更合同在审批中,审批通过后可能覆盖现在这份合同,补账范围要把变更算进去。
  6. 修复方向是:去掉按前缀整体跳过的写法,改成按“合同 + 账期”判断这一期是否已经生成,只为缺失的账期增量补生成;线下合同如果确实需要人工确认,就用显式标记生成待办,不再静默跳过。修复上线状态待确认。

下面用一段脱敏教学示例说明过滤位置,代码只用于解释错误与修复思路,不代表实际项目源码或已上线实现。

错误代码

// 租金账单生成任务:逐份合同判断当期是否出账
public void generateRentBills(LocalDate period) {
    for (RentContract c : rentContractMapper.listCandidate(period)) {
        if (c.getStatus() != ContractStatus.SIGNED) continue;
        if (c.getSiteStatus() != SiteStatus.IN_BUSINESS) continue;

        // 为什么错:把“线下补录”当成“不该出账”,
        // 已签署、营业中的合同在这里被静默跳过,永远不会生成账单
        if (c.getContractNo() != null
                && c.getContractNo().startsWith("OFFLINE_")) {
            continue;
        }
        rentBillService.createBill(c, period);
    }
}

修复代码示例

public void generateRentBills(LocalDate period) {
    for (RentContract c : rentContractMapper.listCandidate(period)) {
        if (c.getStatus() != ContractStatus.SIGNED) continue;
        if (c.getSiteStatus() != SiteStatus.IN_BUSINESS) continue;
        if (!c.covers(period)) continue;

        // 按“合同 + 账期”判重,重跑或补账都不会重复生成同一期
        if (rentBillService.exists(c.getId(), period)) continue;

        // 确实需要人工确认的线下合同,生成待办并留下原因,不再静默跳过
        if (c.isManualConfirmRequired() && !c.isConfirmedFor(period)) {
            manualBillTaskService.create(c, period);
            continue;
        }
        rentBillService.createBill(c, period);
    }
}

下次遇到这些场景要警惕

  • 给自动出账、自动结算类任务增加筛选条件时,先把所有跳过分支列出来,逐条问:这个条件描述的是数据来源,还是这笔业务是否该产生费用?如果只是来源,就不要用它决定要不要出账。
  • 构造一份“线下补录、合同已签署、网点营业中”的合同,跑一次任务,同时查合同列表和账单列表;两份列表的差集里每一条都要有明确原因,不能出现什么都没发生的合同。
  • 自动任务跳过数据时记录跳过原因,并按原因汇总数量;对“状态满足却因来源被跳过”的合同单独告警,避免只靠人工对账才发现。
  • 补录、迁移、导入这类非标准入口上线时,用它们造一套数据走完整链路(录入、审批、出账),确认这类合同在账单和结算上的行为与在线签署的合同一致。