先绑邮箱还是先导名单？操作顺序导致邮件往来无法同步的排查

在 Auto Email Sender 中，有一项让用户赞不绝口的“贴心特性”： 不管你之前是在手机 Outlook 还是电脑网页版给导师发过邮件，只要在软件里绑定好你的 IMAP 邮箱账号，它就会在后台静默同步，把每一位导师的历史通信记录、回信进展精准还原出来。

某天，一位换了新 MacBook 的同学在微信群里求助：

“奇怪，我的账号没变，导进来的导师名单也没变。为什么在旧电脑上能看到上周跟张教授的往来邮件，新电脑上张教授的动态全是一片空白？我点‘立即同步’好几次了，根本刷不出来！”

我让他截了个屏，一步步排查他在新电脑上的初始化路径。

问到最后，一个极其隐蔽但充满荒诞色彩的细节浮出了水面：

• 在旧电脑上： 他是先从导师名录库导入了 200 位导师，然后去设置页面绑定了自己的 163 邮箱；
• 在新电脑上： 他先跑去设置页面绑定了 163 邮箱（系统自动跑完了初始化同步），然后才去点击“导入导师 Excel 名单”。

完全一模一样的两组数据，仅仅因为新设备初始化的点击顺序颠倒了一下，过去半年的往来记录就彻底灰飞烟灭了！

水位线没有错，错在它是“单眼皮”

为什么会这样？我们来拆解一下同步引擎在底层的行为：

【新电脑上的悲剧时间线】
1. 用户绑定邮箱 ──> 系统触发 IMAP 首次握手全量扫描
2. 引擎拉取最近两个月的邮件 ──> 此时本地导师表空空如也！
3. 引擎心想：“这邮箱里没一封信是发给导师的”（废话，名单还没导呢！）
4. 引擎打卡下班 ──> 顺手把本地水位线 (High Watermark) 更新到最新一封邮件 UID
5. 用户终于导入 200 位导师 ──> 导师入库
6. 增量同步再次触发 ──> 引擎：“当前 UID < 水位线，没有新邮件”，直接跳过！
7. 结果：历史邮件永久沉睡在水位线之前，再无天日！

通俗比喻：先翻相册还是先拿寻人启事

为什么操作顺序颠倒会导致记录人间蒸发？ 想象你手里有一本厚厚的几千张聚会合影相册（邮箱里的历史邮件）：

• 先导名单再绑邮箱：你手里先攥着张教授的照片（导入名单），然后把相册从头翻到尾，顺利找到了张教授所有的合影并贴上标签；
• 先绑邮箱再导名单：你两手空空，先把相册从头到尾翻了一遍，在最后一页夹上书签：“我已经把相册全看完了，以后只看新拍的照片”。紧接着朋友才把张教授的照片递给你，你却指着书签说：“规矩是一经翻完概不回头，除非拍了新照片，否则我不看了”。

水位线只代表“相册翻过了”，可当时你根本不知道该在相册里找谁！

看懂了吗？增量同步的水位线逻辑本身极其严谨：“凡是 UID 小于上次记录的，都算已经看过了，不再重复拉取。”

但问题在于，同步引擎是只长了一只眼睛的“单眼皮”——它只盯着远端数据源（邮箱里有没有新信），却完全忽视了本地的消费规则（我们究竟在关心哪些人）！

在步骤 2 中，系统确实“看过”了那些历史邮件，但当时本地根本没有上下文；当真正的业务实体（导师邮箱）迟到进场时，门已经被水位线死死焊死了。

核心洞察：匹配是双向事件

“通信记录”不是单向从云端拉下来的独立实体，而是远端邮件字节流与本地业务关注集发生碰撞后的交集！ 远端哪怕没动一个标点符号，只要本地的“关注名单”变了，旧数据的意义就已经彻底颠覆。

治标不治本的粗暴冲动

发现问题后，很多人第一反应是：“这还不简单？只要用户一导入导师名单，把邮箱的水位线清零，全量重跑一遍不就得了！”

千万别！这是一个典型的“用新灾难掩盖旧灾难”的方案：

• 一个老邮箱可能存了近十万封跨越五六年的工作与生活邮件；
• 用户今天导 5 个导师清一次水位，明天通过爬虫抓取 10 个导师又清一次；
• 每一次变动都拉着整个邮箱全量回滚遍历，IMAP 服务器当场就会把账号封禁，软件也会在持续的高 I/O 中陷入假死。

永远不要为了局部更新去重置全局基线

邮箱的水位线是整个系统防重复、防过载的防洪堤。为了几个新导师去炸毁防洪堤，属于最偷懒也是最危险的架构自杀。

把“导师变动”升级为一级触发事件

治本的方法，是把同步系统的视界打开：让系统不仅对“远端收到新邮件”做出反应，更要对“本地导师集合变动”做出精准响应！

我们梳理了所有可能让“新邮箱进入视野”的业务入口：

• 从 Excel / CSV 批量导入导师；
• 智能抓取页面单条或批量保存导师；
• 手动新增/编辑导师的联系邮箱；
• 从回收站或归档列表里恢复导师。

只要满足**“一个新的有效邮箱被激活加入观察名单”**这一事实，就会向本地任务队列注入一个轻量级的补扫意图：

[ 导师变动事件 ] ──> 提取增量邮箱集合 ──> 派发定向补扫任务 (历史窗口：近 2 年)

为什么修改姓名不触发补扫？

只有当“邮箱地址”或“有效状态（是否归档）”发生改变时，才属于对通信交集的有效扰动。如果用户只是改了改导师的职称或办公室电话，触发逻辑直接静默，绝不消耗任何网络资源。

批量与单点的两副面孔

在真正执行定向补扫时，还需要面临一个现实挑战：

• 场景 A： 用户随手在界面上新录入了一位导师；
• 场景 B： 用户一口气导入了 3,000 位计算机系的老师名单。

这两种场景如果用同一套逻辑跑，必然会出事故。

针对这两种规模，我们设计了两条截然不同的战术路线：

【单点新增（少量）】
直接拿该导师的邮箱，向 IMAP 发起精准检索：
- SEARCH FROM "prof@univ.edu"
- SEARCH TO "prof@univ.edu"
秒级完成，体验极其丝滑！
 
【批量导入（巨量）】
绝不发 3000 次查询！而是翻转逻辑：
- 先向服务器取最近 2 年真实存在的所有发信 UID 列表；
- 批量拉回收件人 Header，在本地内存做 Set.intersection 高性能交集；
- 仅把真正命中发过信的几十个导师提取出来，定向补充收件箱回信。

同时，我们把单条任务与导师的“邮箱版本号”绑定：如果在排队等待补扫期间，用户手滑又把导师邮箱改成了另一个，旧版本的补扫结果会被自动废弃，杜绝脏数据串味。

总结

这个曾经让无数新设备用户抓狂的“玄学 bug”，给我们上了一堂生动的系统设计课：

1. 摆脱单向数据流的思维定式： 在很多关联业务中，数据是在两端同时演进的。只监听服务端的增量，往往会在客户端实体变化时踩进盲区；
2. 操作顺序不应该影响终态一致性： 一个成熟健壮的软件，无论用户是“先 A 后 B”还是“先 B 后 A”，最终呈现给用户的数据视图必须是严格等价的；
3. 把业务变动抽象为事件流： 别把补扫逻辑散落在各个 Controller 的按钮回调里。将其收敛为“关注集变动”这一核心领域事件，系统才能真正具备自愈和自我补全的能力。