发生了什么
网点是线下经营的点位,每个点位都要签合同,合同里写明合作期限和起止时间,系统据此判断这个点位能经营到什么时候。合同签署完成后,系统并不让后台直接去读合同主表,而是为合同生成一份“合同快照”:把合同编号、起止时间、签约主体这些关键字段复制成一条独立记录。网点管理后台的合同列表读的就是这份快照。
多这一层快照,是因为后台要按点位一次列出名下全部合同,还要能看到每份合同签约当时的原始内容;如果直接读主表,合同后续变更会把历史内容一起改掉。
正常流程是:合同签署完成,签署结果回到系统,合同主表的状态改成已签,随后生成对应的快照,网点管理后台再按点位查快照,新合同就出现在列表里。
这一次,一个点位的新合同起租日期是 2026 年 4 月 21 日,签署也已完成,但后台的合同列表里没有这份合同。排查发现,这个点位的合同快照里本来就有重复记录;签约完成之后那次快照生成,没有走到为这份新合同写一条快照的那一步。后台只能看到旧合同,看不到新签的这一份,运营也就无法在页面上确认新合同的期限。
本质
快照生成不是签约成功后无条件执行的一步。写入之前,程序要先确认“这份合同是不是已经有快照”,已经有了就不再重复生成——这一步本身是必要的,否则一次签约的回调重发几次,列表里就会多出几份同样的合同。
问题就出在这个确认上。确认依据的是快照数据本身,而这个点位的快照表里存在重复行;重复数据让判断得出了“已经有快照”的错误答案,新合同缺的那一份被盖住了。生成步骤随即返回,没有写入任何记录。签约主流程本身是成功的,这一步跳过也不抛错,所以从签约结果上看不出异常。
页面读的是快照,不是合同主表。快照里没有这份合同,列表自然不会展示它。所以“后台看不到新合同”既不是签约没完成,也不是列表筛选或权限的问题,而是主表已经更新、派生数据少了一行,两个数据源之间对不上了。
处理上是按这份合同重新调用一次快照生成,把缺的快照补出来。修复方向是两件事一起做:生成之前按合同编号逐份比对,不再依赖可能被重复行撑大的汇总条件;同时清掉历史重复行,并给“点位 + 合同编号”补上唯一约束,否则脏数据还在,下一次生成仍会被带偏。生成步骤被跳过时,也应该留下带业务键的记录,而不是静默返回。
下面用最小示意复现这个判断:错误版用点位下的快照条数与合同条数对账,修复版改成逐份按合同编号确认。
错误代码
public class ContractSnapshotService {
/** 合同签署完成后调用,为页面生成一份合同快照 */
public void createAfterSign(Long nodeId, Contract contract) {
long snapshotCount = snapshotMapper.countByNode(nodeId);
long contractCount = contractMapper.countByNode(nodeId);
// 为什么错:用条数对账代替逐份比对,快照表里的重复行会把总数撑大,
// 缺口被掩盖,判断认为已经生成齐全,于是直接返回
if (snapshotCount >= contractCount) {
return;
}
snapshotMapper.insert(Snapshot.from(contract));
}
}
修复代码示例
public class ContractSnapshotService {
/** 合同签署完成后调用,为页面生成一份合同快照 */
public void createAfterSign(Long nodeId, Contract contract) {
// 按合同编号逐份确认,重复行不会再影响这份合同的判断
Snapshot existed = snapshotMapper.selectByContractNo(contract.getNo());
if (existed != null) {
// 跳过时留痕,避免“签约成功但没有快照”只能由业务侧发现
log.info("snapshot skip, node={}, contract={}", nodeId, contract.getNo());
return;
}
snapshotMapper.insert(Snapshot.from(contract));
}
}
两段代码是脱敏教学示例,用于解释错误与修复思路,不代表实际项目源码或已上线实现。逐份比对之外还要清理历史重复行并补唯一约束,否则同一份合同仍可能被并发写入两份快照。
下次遇到这些场景要警惕
- 给“签约完成后生成派生数据”加前置判断:用业务唯一键逐份确认,不要用条数、总量对账。验证时先造一条历史重复数据,再签一份新合同,看这份合同能否正常生成。
- 页面读快照、汇总表或索引表时排查“查不到”:先比对主表与派生表的键集合,找出缺失的那一份,再去怀疑权限、筛选和缓存;只对总数会让重复行把缺口掩盖掉。
- 派生表出现重复行:先确认是否缺少唯一约束、是否有去重清理,再改生成逻辑;只修逻辑不治数据,脏数据会再次把判断带偏。
- 生成步骤被跳过或降级:在跳过分支记录业务键并告警,观察是否出现“签约成功但页面没有快照”的情况;静默返回的代价是问题只能在业务侧被发现。