规则1 · 客户只要回复，无论当前处于哪个阶段，都会立刻被"捞出来"重新分类——但不是发新的第一封邮件

这条是最容易被忽略、也最重要的一条。

不管客户当前是刚发完 first 还在等打开、是在 followup1/warm/high_intent 排队中、还是已经进了 cooling 在倒数第几轮的冷却期——只要他真的回复了一封邮件，系统检查收件箱时（checkInboxReplies）就会立刻按回复内容重新判定这个客户该去哪，把它从原本正在走的自动化路径里"捞出来"，不会等原来的流程走完。具体去哪，看回复内容属于哪一类（对应 B组）：

规则2 · 为什么 reengagement 邮件发出去后，客户状态是变回 contacted 而不是留在 cooling

cooling 这个状态代表的含义是"我们现在什么都不做，纯粹在倒数等待"。但 reengagement 邮件一旦真的发出去了，客户收件箱里就又躺着一封等待回复的邮件了——这和当初发完第一封邮件后的处境，本质上是同一回事：都是"发了一封东西，正等对方反应"。所以系统直接复用了 contacted 这个早就存在的状态来表示"正在等待"，而不是另外发明一个"cooling 期间发了 reengagement 后的特殊等待状态"。

这样做的好处是：判断"等了多久还没反应、该不该重新打入冷宫"这件事，可以直接复用原本就用来监控 contacted 客户的那套逻辑（也就是 C2 场景里说的"cycle 2+ 客户"检查），不用为 reengagement 这一种情况单独再写一套监控代码。

规则3 · 唯一能让客户"重新收到一封真正意义上的第一封邮件"的情况

只有一种情况：爬虫在一家已经是 cooling / not_interested / bounced 的公司，抓到了一个和档案里不一样的联系邮箱（详见 D组）。这时系统才会把这家公司当成一个全新的机会，重新走一遍从 first 开始的完整流程，并且把这个新联系人之前累积的所有跟进计时清零（靠 contact_reset_at 这个字段实现，具体见 D1）。除此之外——不管是客户自己回复、还是冷却期满自动发 reengagement——都不会触发"重发第一封邮件"这个动作，最多只是把状态改变或者发一封 reengagement/跟进邮件。

规则4 · 测试必须和真实环境判断逻辑完全一致，但绝不能碰到除测试客户以外的任何真实客户

两条同等重要的原则，2026-07-30 明确定下的，任何测试相关的代码改动都要同时满足这两条。

原则A：判断逻辑必须和正式环境一模一样。候选人筛选条件（是否打开过、是否过了天数、cold_restart 互斥、cycle<=1、第2轮+续冷却）测试客户和真实客户走的是同一段代码、同一条 SQL，不允许测试模式用一套简化过的逻辑——不然测出来的结果没有意义。

原则B：测试执行范围必须严格限定在你选中的这一个测试客户身上，绝不能波及任何其他真实客户。这条比听起来更容易被违反——因为 generateFollowupQueue() 这类函数在正式环境本来就要每天9点被调用一次处理所有真实客户,并且真的会读 Auto Followup 1/2 这些全局设置决定要不要自动发送;如果测试模式的"允许发送"也去读同一批全局设置，那为了测试而打开它，就会同时让"处理所有真实客户"的那次调用也真的开始自动发信——所以 Test Follow-up 这个开关必须是独立于真实开关的，只作用于测试客户，Auto Followup 1/2 和 Auto Send New Emails 整个测试期间都要保持关闭。

规则5 · Clients 标签页的 Contacted 分类，现在是互斥的，并且带一个子状态筛选下拉框 2026-08-04

这条直接影响你在下面每个场景里"去哪个 tab 验证结果"。

改之前，Contacted tab 是个"宽口径"分类：只要发过邮件，即使客户现在的真实状态是 cooling / not_interested / bounced，也会一并显示在 Contacted 里——结果就是同一个客户会在两个 tab 里同时出现（比如一个 bounced 客户，Bounced tab 有它，Contacted tab 也有它）。现在改成和 Active / Cooling / Not Interested / Bounced / Competitors 这几个 tab 完全一样的口径：Contacted tab 只显示 status='contacted' 的客户，一个客户永远只会出现在一个 tab 里。

同时在 Contacted tab 里，"All Industries" 筛选框右边新增了一个 "All Contacted Stages" 下拉框（只在 Contacted tab 打开时才显示），可以直接按卡片上那个状态标签筛选：Awaiting Reply / Cold Restart Pending / Cold Restart / Follow-up 1 Pending / Follow-up 1 / Follow-up 2 Pending / Follow-up 2 / Warm Pending / Warm / High Intent Pending / High Intent / Re-engagement Pending / Re-engaged——这些选项和 createClientRow() 里算出来的卡片状态标签是一一对应的，"Pending" 代表还在 Preview Send Queue 里等你审核，不带 Pending 的代表已经发出去、还没排下一个。

A1 · 完全没打开 逻辑本身没变，但现在会按 contact_reset_at 分段计算

Cold Restart（进队列）→ 发送 → Followup 2（自动发）→ 进入 Cooling。

1. 不要打开第一封邮件。点 Run Test Follow-up Now，不用等一小时。
2. 打开 Preview Send Queue → Follow-ups 里应该出现一条 cold_restart，主题是 Re: {第一封邮件的原主题}（2026-08-06 起，Cold Restart/Warm/High Intent/Followup1/Followup2/Reengagement 这6类统一改成这个格式，不再各自用独立文案——实测发现独立主题即使带了正确的回复邮件头，Gmail 也不会把它跟原邮件合并成同一个对话串，客户看不到之前的邮件内容，所以改成跟原主题挂钩的 "Re:" 格式，确保能在 Gmail 里正确合并显示），正文来自 Settings → Email Templates 里保存的 Cold Restart 模板（2026-07-30 起改为完全按模板生成，不再是 AI 现场写的内容——如果正文跟你在模板里编辑保存的不一样，就是 bug）。
3. 点 Send。确认它带着模板里的内容真的进了收件箱。
4. 仍然不要打开它。再点一次 Run Test Follow-up Now。

A2 · 打开一次（Warm → Followup 1 → Followup 2）

Warm（进队列，按模板生成）→ 发送 → Followup 1（进队列）→ 发送 → Followup 2（进队列）→ 进入 Cooling。

1. 真的打开第一封邮件一次（在私人邮箱里点开它，让 Brevo 的 open 事件真实触发）。
2. 确认 Brevo 后台/邮件的追踪像素被加载后，点 Run Test Follow-up Now。Follow-ups 里应该出现一条 warm，正文来自 Settings → Email Templates 里保存的 Warm 模板。
3. 从 Preview Send Queue 里发送它。
4. 再次 Run Test Follow-up Now——应该出现一条 followup1（正文用的是新版"help you get set up"这段中性措辞，不再预设对方到底看没看过邮件，因为这条现在只会接在 Warm 后面出现）。
5. 发送它，再 Run Test Follow-up Now 一次 → 出现 followup2。

A3 · 调高 Warm 阈值不会有实际效果——只要打开过就算 Warm 2026-08-25 起

验证"把 behavior_warm_opens 手动调高（比如调到3）之后，客户只打开了1次，会怎样"——这是个边界确认，不是常规路径，默认设置（阈值1）下走不到这里，A2 已经覆盖默认情况。

1. 把 Settings 里 behavior_warm_opens（"Warm trigger after (opens)"）临时改成 3。
2. 真的打开第一封邮件1次。
3. 等够 Warm send after (days) 设置的天数，Run Test Follow-up Now → Follow-ups 里正常出现一条 warm，不会因为阈值调到了3而被拦下、也不会误触发 cold_restart。
4. 把 behavior_warm_opens 改回默认值 1，测试完记得复位。

A4 · 点击了链接（High Intent）

High Intent 邮件（进队列）→ 发送 → Followup 2（进队列）→ 进入 Cooling。点击优先级高于打开——不会退回到 warm 路径。

1. 真的点击第一封邮件里的链接。
2. Run Test Follow-up Now → 应该出现一条 high_intent，主题是 Re: {第一封邮件的原主题}（见 A1 场景里 2026-08-06 那条说明），正文来自 Settings → Email Templates 里保存的 High Intent 模板（2026-07-30 起改为完全按模板生成，不再是 AI 现场写的内容）。
3. 发送它，再跑一次 → 出现 followup2。

A5 · 自动回复（度假自动回复）

确认系统不会把度假自动回复误判成真实回复。

1. 把测试邮箱设成 out-of-office 自动回复，或者直接手动回一封标题像 "Automatic reply: Out of Office" 的邮件。
2. Run Test Follow-up Now（会触发 checkInboxReplies）。

B1 · 感兴趣

1. 回复第一封邮件："这个看起来不错，想再多了解一下，能约个电话吗？"
2. Run Test Follow-up Now。

B2 · 提问

1. 回复："这个多少钱，需要签合同吗？"
2. Run Test Follow-up Now。

B3 · 软拒绝 新行为

判断标准是"有没有明确邀请以后再联系"——有，走 B1（active）；没有，走这里（cooling）。见 B1 的补充说明。

1. 回复："我们暂时不招人，谢谢。"（注意：不是"过几个月再联系"这种带邀请性质的说法，那种现在走 B1）
2. Run Test Follow-up Now。

B4 · 硬拒绝，只有一个联系人 新行为

1. 确认测试客户名下目前只登记了一个联系邮箱。
2. 回复："请把我们移除，我们不感兴趣，不要再联系了。"
3. Run Test Follow-up Now。

B5 · 硬拒绝，但还有其他联系人有效 新行为，也是这次改动真正的设计初衷

一个人拒绝了，不代表这家公司所有人都拒绝了——不应该因此关掉整个公司。

1. 给测试客户加一个也能收到邮件的第二联系邮箱，比如 UPDATE clients SET contact_email = CONCAT(contact_email, ', your+alt@address.com') WHERE id=<id>，并给这个邮箱补一条 email_log（type='first', status='sent'），让它看起来是一个真实、未被拦截的联系人。
2. 用主邮箱回复和 B4 一样的硬拒绝措辞。
3. Run Test Follow-up Now。

UPDATE clients SET contact_email = SUBSTRING_INDEX(contact_email, ',', 1) WHERE id = <test_client_id>;

C1 · 再触达按期触发

1. 用上面任意场景（A1 或 B3 最快）把客户先弄进 cooling。
2. 直接把等待期拨到今天：UPDATE clients SET reengagement_date = CURDATE() WHERE id=<id>。
3. Run Test Follow-up Now → 打开 Preview Send Queue，Follow-ups 里应该出现一条 reengagement，正文来自 Settings → Email Templates 里保存的 Reengagement 模板。
4. 点 Send。

C2 · 冷却期随轮次递增

只有第1轮会走完整的邮件序列，第2轮起每轮只发一封 reengagement 邮件。2026-07-30 起 90/180/365 这三个数字不再是写死的，Settings → Autopilot → Re-engagement 面板里新增了 Cycle 2 / Cycle 3 / Cycle 4+ cooldown 三个输入框，测试期间同样可以改成 0。

1. 走 A1 完成第1轮，进入 cooling。
2. 用 C1 的办法把 reengagement_date 拨到今天，触发 reengagement 邮件；发送后客户变回 contacted，cycle 仍是2。
3. 不回复，等 Followup 2 天数那么久（测试期已改成0），确认又自动回到 cooling。
4. 重复第2-3步两次，检查 cycle 与冷却天数是否照上表递增。

这里的 contacted 是什么意思——容易看错的一点

上面第2步会看到 clients.status 变成了 contacted，cycle 却已经是2、3、4——第一眼很容易误会成"系统把它当成了一个刚认识的全新客户"。不是这样的：clients.status 这个字段总共就 new / contacted / active / cooling / not_interested / bounced / competitor 这几个取值，没有专门给"reengagement 发出后等回应"单独造一个新状态，而是直接复用了 contacted 这个值——它在这里的含义是"当前有一封 outreach 邮件发出去了、正等对方反应"，跟真正第一次认识这家公司时的 contacted 是同一个字段值、但不是同一件事，要看 cycle 字段才知道这其实是第几轮了。这样设计是为了能直接复用原本监控"contacted 客户等多久没反应该怎么办"的那套代码，不用为 reengagement 专门再写一套。

如果在等待期间（第2轮或以后）客户突然回复了呢

不管客户是在第1轮还没打开、还是已经进了第2、3、4轮的 cooling/等待期，只要真的回复了，checkInboxReplies 一检查到就会立刻按回复内容重新分类，把它从"按部就班等冷却期满"这套自动化节奏里拉出来——感兴趣/提问 → 直接变 active；软拒绝 → 刷新回 cooling，冷却计时器从这一刻重算；硬拒绝 → 如果这是最后一个还没被拒绝的联系人，变 not_interested。但注意：这几种结果都只是"改状态"，都不会让客户重新收到一封全新的"第一封邮件"。系统里唯一会让客户真正收到一封全新 first 邮件的情况，只有 D组说的那种——爬虫在这家公司发现了一个和档案里不一样的联系人，那才是真正"重新开始"，跟这里说的"回复被重新分类"是两件完全不同的事，别搞混。

D1 · 爬虫在已归档公司发现新联系人 2026-08-06 真实环境触发过一次，顺带修了两个缝隙

这套逻辑只会从真实爬虫内部触发（Seek/Indeed/TradeMe/SJS/Himalayas 解析到一条真实招聘帖时）——没有任何 UI 操作能直接激活它，没法像上面的场景一样手动驱动。

1. 之前完全无迹可寻——触发之后 cycle/reengagement_date 静默改变，时间线上找不到任何原因，只看到状态莫名其妙变了。现在 isCompanyArchived() 会写一条 client_activities 记录（"🆕 New contact found: {邮箱} — starting fresh outreach"），时间线弹窗会把这条记录和其他历史事件混在一起按真实时间排好序显示出来；旧联系人的历史邮件记录完全保留，不会因为这次重置而消失。
2. 硬拒绝误判风险——如果重置发生后，新联系人的第一封邮件还没来得及发出去，这时候旧联系人恰好发来一封硬拒绝，之前的代码会因为"新联系人没有任何已发送、未被拒绝的邮件记录"而误判成"没有其他有效联系人了"，直接把公司标成 not_interested——即使这个新联系人根本还没被联系过。现在硬拒绝判断新增了"是否存在从未发过信的已知联系人"这层保护，具体测试步骤见 B5 那条"未联系过的联系人保护"分支。

继续追查这次真实触发的过程中，同一条链路上又挖出三个更深的问题，一并修复（2026-08-07）：

1. 发信后邮箱被覆盖，不是合并——"发出第一封邮件后回填客户记录"这段代码（真实自动发信循环、"Send All First Emails"批量路由、单条手动发送共用的 ensureClientForLead()、以及测试用的 Run First Email Now，一共4处）之前都是 contact_email = 新邮箱 直接覆盖整个字段，不是合并进已有的逗号分隔列表。新联系人的第一封邮件一旦真的发出去，isCompanyArchived() 之前辛苦合并进去的老联系人邮箱反而会被冲掉丢失——The Painting Company 这个测试客户真实中招过，老邮箱被冲得只剩新邮箱一个。已改成发信前先查一次数据库当前值，再合并写回，不再是无脑覆盖。
2. isCompanyArchived() 自我拉黑——真实自动发信循环、以及"Send All First Emails"批量发送路由，之前会在真正发信之前再调用一次 isCompanyArchived() 做"最后确认"。但这个函数第一次调用（爬虫抓取时）已经把新邮箱合并进 contact_email 了，第二次调用比较的是"已经合并过的邮箱"，永远会判定为"已知联系人"从而被永久跳过——新联系人的第一封邮件因此永远发不出去，这就是2026-08-06那次真实卡住的根本原因。已删除这个多余的第二次调用。
3. 联系人姓名没跟着换——邮箱合并只处理了 contact_email，从没更新过 contact_person，导致给新联系人发的邮件称呼还是老联系人的名字（比如实际收件人是"Dave"，邮件称呼却还是"John"）。现在合并邮箱的同时也会把姓名换成新联系人的（提取不到像样姓名就清空，落到"Hi there"，绝不会保留旧姓名去称呼一个不同的人）。

contacted / active 期间发现新联系人，现在怎么处理

2026-08-07 之前，只要公司当前是 contacted 或 active 状态（原联系人的序列还在进行中），爬虫爬到的任何新联系人都会被 isCompanyArchived() 当成"已归档"整条丢弃，连 b2b_leads 里的记录都不会留下——如果这条招聘帖后来下架、爬虫再也没爬到过同一条，这个新联系人就永久性地丢失了。现在改成：照常记录进 b2b_leads，但不会立即合并进 contact_email、不会打扰原联系人正在进行的序列。等这家公司真正因为"没回应"要从 contacted 转入 cooling 的那一刻（2026-08-24 起是 sendFollowupQueueItem 的 Followup2 完成分支、以及 autopilotRecycleReengagements（原名 autopilotFollowUp）的 cycle 2+ 收尾这两处，不再是原来同一个函数里的两段），系统会主动回头检查 b2b_leads 里有没有这种"记录了但还没合并"的新联系人——如果有，就直接走"发现新联系人"那套流程（合并邮箱+姓名、cycle 归1、清空 reengagement_date），而不是照常排一封给老联系人的 re-engagement 邮件。

E1 · 邮件在排队期间"过期"了

2026-08-07 现在有两条独立的防线：如果是客户直接回复导致的状态变化，回复处理的同时就会立刻把排队项标掉，不用等到点 Send 才发现；如果状态变化是通过别的方式发生的（没经过回复处理这条链路），才会退回"点 Send 时才被拦下来"这条本来就有的保险丝。这个场景把两种情况都测一遍。

变体1：客户真的回复了（现在会立刻清掉，不用等点 Send）

1. 先让某条 followup1（或任意类型）静静地躺在队列里（参考 A2 第2步）。
2. 用 B1（感兴趣）/B2（提问）/B3（软拒绝）/B4（硬拒绝）任意一种真实回复，让客户状态发生变化。
3. 回到 Preview Send Queue 刷新看一眼，不用点 Send。

变体2：状态变化不是通过回复触发的（还是走"点 Send 时才拦下"这条旧路径）

1. 同样先让一条排队项躺着。
2. 不经过回复，直接改数据库模拟退信：UPDATE email_log SET status='bounced' WHERE client_id=<id> ORDER BY sent_at DESC LIMIT 1。
3. 现在再去点这条仍显示"待发送"的队列项的 Send。

F1–F3 · not_interested / bounced 公司防止重新联系 F2/F3 本轮升级

验证的是这条规则：公司已经被标成 not_interested 或 bounced 之后，同一个联系人再出现不该被重新联系；换了个不同联系人则应该正常放行，当成一个全新机会，不该被上一个人的拒绝连累。

先说清楚这条规则实际是怎么落实的，因为容易理解错：真正做判断的只有一个地方——isCompanyArchived()，而且只在 crawler.js 里、爬虫准备把一条新线索插入 b2b_leads 表的那一刻调用一次。同一联系人 → 这条线索压根不会被插入 b2b_leads；换联系人 → 正常插入，同时把新邮箱合并进 clients.contact_email，判定为全新周期。F1（全自动主流程）和 F3（批量发送）都没有自己的拦截逻辑，只是分别去读"现在 b2b_leads 里有哪些能发的线索"——既然同一联系人的线索从一开始就没能力进这张表，F1/F3 自然也就看不到它、更谈不上要不要拦，不是"F1/F3 收到了、判断一下、悄悄跳过"。F2 是唯一的例外，见下方说明。

为什么 F2 不一样，需要自己单独查一次：F2 操作的是你直接指定的某一条已经存在的线索 id——这条线索完全可能是在公司被标成 not_interested 之前就已经躺在 b2b_leads 里了（那时候公司还没被拒绝，插入时压根没触发过 isCompanyArchived 的拦截），所以 F2 必须在真正发送前自己单独查一次公司当前的真实状态，弹窗确认，不能假设"能走到这一步就说明已经检查过了"——这跟 F1/F3 只处理"当下正常插入进来的新线索"是不同的场景。

怎么测：F1/F3 不需要单独构造"同一联系人"的测试用例（构造不出来，线索进不了表），直接复用 D1 的验证结论即可（本质是同一个判断函数）；F1/F3 只需要测"换联系人后能否正常放行发出"这一半。F2 单独测两半：把测试客户手动标成 not_interested，分别用同一个邮箱和一个新邮箱去发，确认弹窗文案里"同一个联系人" vs "换了联系人，之前是…"这两句话分别在对的场景下出现。

DELETE FROM b2b_leads WHERE company_name = (SELECT company_name FROM clients WHERE id = <test_client_id>) AND status != 'sent';

G1 · 点击事件归因与优先级 2026-08-24 改版

这是唯一真正需要靠真实 Brevo 才能测到位的场景——本地环境无法收到 webhook，交给真实环境验证。三个子场景都围绕同一件事：点击事件有没有被记到正确的邮件上，以及记对之后系统会不会真的据此改变分支。

子场景 A（核心）：Cold Restart 里的链接被点击 → 触发 High Intent

1. 让测试客户走到"Cold Restart 已发送、Followup 2 还没发"这个阶段。
2. 确认这封 Cold Restart 邮件里的链接是 https://www.jobvista.app 这种真链接（而不是裸文字 "jobvista.app"）——包括数据库 settings.cold_restart_template 里存的版本，不只是代码默认值。
3. 点击邮件里的链接。
4. 点 Run Test Follow-up Now（或等下一次每小时测试 cron）。

子场景 B（边界测试）：Warm 里的链接被点击 → 不应该触发 High Intent

1. 让测试客户走到 Warm 已发送阶段（打开次数达到 Warm 阈值后自然会走到这一步）。
2. 点击 Warm 邮件里的链接。
3. 点 Run Test Follow-up Now。

子场景 C：两封邮件同时在外，事件的行归属

1. 给同一个客户先后发出 first 和 cold_restart 两封邮件——email_log 里会有两条记录，各自带着不同的 brevo_message_id。
2. 用下面这个模拟工具，选中较早那封（first），事件类型选"退信"，点模拟——不用真的发到一个会退信的地址，也不用等 Brevo 真实回调。
3. 看模拟结果、或去数据库确认。

背景：为什么"点击"要分邮件类型讨论，"打开"不用

generateFollowupQueue 判断"打开次数"（opens）时，看的只是 first 这一封邮件自己的 open_count——但要走到"两封邮件同时在外"这种可能记错行的状态，前提是打开阈值早就跨过去了，所以一次记错行的迟到打开，不会翻盘任何分支决策，不再需要单独测。判断"点击"则不同，2026-08-24 起明确定义为：点击 first 自己的链接，或点击 cold_restart 自己的链接，都会被判断逻辑读取并触发 High Intent；点击 warm/followup1/followup2/high_intent/reengagement 自己的链接则只会被记录、不会被判断逻辑读取。子场景 A/B 就是分别验证这两半是不是都对。

G2 · 回信记录本身缺失客户关联时的兜底匹配 2026-08-01 新增修复

验证即使某封发件记录先天没有关联到客户（历史遗留问题——早期 autopilotAutoSend 不会主动建客户档案，详见 H2 背景说明第③条），客户真的回信时依然能被正确识别、状态正常更新，不会因为这条记录本身有缺陷就把回信悄悄丢掉。

1. 走一遍标准准备工作：Set Test Client → Run First Email Now，确认收到邮件。
2. 手动跑一条 SQL，故意把这封邮件在数据库里的客户关联字段清空，模拟"当时建档没跟上"这个历史问题：

   UPDATE email_log SET client_id = NULL WHERE client_id = <test_client_id> AND type = 'first';

3. 正常回复这封邮件，比如跟 B1 一样写"这个看起来不错，想再多了解一下"。
4. 点 Run Test Follow-up Now。

Watchlist · 完整机制说明 2026-08-26 补充

这是背景说明，不是可执行的测试步骤——先搞清楚这个标记具体在哪几个环节起作用，再看下面 Watchlist1/2 具体怎么测。

manual_review 这个字段，b2b_leads 和 clients 两张表里都有，是"公司级别"的意图标记，不是只存在某一张表里：

Watchlist · 标记后自动开关必须失效

验证即使真实的自动发送开关是打开的，被标记 Watchlist 的这一个客户依然会被强制摁住，不会被自动发出去。

1. 准备工作跟平时一样，把 Settings → Autopilot 里所有"天数"类设置改成 0。
2. 在 B2B Leads 里选一条线索，把它的联系邮箱改成你自己的私人邮箱。
3. 点这条线索行前面的 Watchlist 复选框（🔖 图标），确认它被标记进了 Watchlist。
4. 不要用 Set Test Client + Run First Email Now——直接在这条线索上点手工的 Send Email 按钮发出去。Watchlist 要测的是"真实客户的真实自动化流程会不会被拦住"，用测试客户机制会直接绕开所有拦截判断，测不出东西。
5. 这一次可以临时把 Auto Cold Restart / Auto Warm / Auto High Intent 这几个真实开关打开（平时测试要求它们必须关闭，这是唯一的例外——因为整个测试范围就锁定在这一条打了 Watchlist 标记的线索上，不会影响到其他真实客户）。
6. 等系统状态从 New 变成 cold_restart 或者 followup1（取决于有没有打开过邮件，两者不会同时出现）。
7. 去 Preview Send Queue 确认这封邮件在等着，没有因为开关是打开的就自动发出去。
8. 手动点发送，在私人邮箱里打开/点击这封邮件，等 Brevo 把打开/点击事件推回来，系统状态升级成 warm/high_intent。
9. 再去 Preview Send Queue 确认，同样在等着，依然没有自动发出去。

Watchlist2 · 有排队邮件未处理时，复选框必须锁住无法取消 2026-08-26 新增

验证"取消 Watchlist 标记"这个动作，在这个客户名下还有没处理完的排队邮件时会被正确拦住——不然下一次自动任务一跑，这条从没被人审核过的排队邮件会立刻被自动发出去。

1. 沿用 Watchlist1 场景，让测试用的这条线索/客户带着 Watchlist 标记，走到"名下有一条 pending 排队邮件"这个状态（比如 Cold Restart 或 Warm 正躺在 Preview Send Queue 里等审核）。
2. 去 Opportunities 列表，尝试点掉这条线索前面的 Watchlist 复选框。
3. 确认复选框是灰色、点不动的状态，鼠标悬停能看到提示文字说明原因。
4. 把这条 pending 邮件处理掉（在线索详情页的编辑器里点 Send 真发出去，或者点 Skip 跳过）。
5. 回到 Opportunities 列表，确认复选框恢复成可以点击的状态。
6. 这次点掉复选框，确认能正常取消 Watchlist 标记。

Follow-up Draft 1 · 面板显示的类型必须跟真实引擎判断一致

验证面板顶部显示的"当前该轮到的类型"，跟时间线弹窗、真实引擎会生成的类型完全一致，不是另外一套自己猜的逻辑。

1. 走标准准备工作，让测试客户处于"发完 First Email、还没打开过"的状态。
2. 打开这个客户的 Clients 详情页，确认 Follow-up Draft 标签显示"Follow-up Draft (Cold Restart):"，Generate 按钮可以点。
3. 真实打开一次这封邮件，刷新详情页，确认标签变成"Follow-up Draft (Warm):"。
4. 点击邮件里的链接，刷新详情页，确认标签变成"Follow-up Draft (High Intent):"。
5. 对照时间线弹窗（Email Timeline）里"预测下一步"显示的类型，应该跟面板上显示的完全一致。

Follow-up Draft 2 · 手动发送不会跟自动流程重复，且能正确续接下一步

验证手动发送这一步真的会替代掉自动引擎本该做的事，不会两边都发一遍；也验证发送之后，自动引擎能正确从"这一步已经发过"续接到下一步，不会重跑或卡住。

1. 让测试客户走到某个引擎已经生成了 pending 排队邮件的状态（比如打开过邮件，Warm 已经在 Preview Send Queue 里等审核）。
2. 去这个客户的 Clients 详情页，Follow-up Draft 面板此时应该显示"Warm"，点 Generate 生成内容，点 Send 发出去。
3. 去 Preview Send Queue 确认：刚才那条 Warm 排队记录已经消失（变成 sent 状态），不是又多出来一条重复的。
4. 去 email_log 确认新记录的 type 是真实的 warm，不是笼统的编号。
5. 等够 Followup 1 after (days) 设置的天数，Run Test Follow-up Now，确认自动生成的是 followup1（不是重新生成一次 Warm，也不是卡住不知道下一步）。

H0 · 测试环境怎么搭（开始测试前）

1. 从生产库整体拷贝一份出来（比如 mysqldump 导出再导入一个新库名），新版 Stella 的 .env 连接这份独立副本，不要连生产库本体。
2. 新版 Stella 首次连上这份副本启动时，会自动把 contact_reset_at、rejection_type 这两个新列加上去（纯新增，不影响其他数据）。
3. 确认 OnlineStella 那边的部署完全没有改动——它应该继续正常连着生产库本体、正常跑它自己的自动化，你的日常业务不受这次测试影响。

H1 · 正式接管的时序 全部场景测试通过后再做

这一步不是改几个设置那么简单，是两个独立进程的交接，顺序错了会有真实风险，请按顺序做，不要图快跳步骤。

1. 接管前，对生产库做一次快照备份（纯粹是保险，用不上最好）。
2. 先彻底停掉 OnlineStella 的进程（PM2 层面真正 stop，不是点某个页面上的开关）。这一步和下一步之间不要有任何真实自动化在跑——两边进程绝不能同时连着生产库，否则爬虫、收件箱监听、自动发送都可能撞车、重复处理。
3. 把新版 Stella 的 .env 数据库连接从"测试副本"改成指向生产库本体（不是 H0 拷的那份旧快照——OnlineStella 停之前一直在真实运行，数据比你测试用的那份新）。
4. 启动新版 Stella 连生产库。
5. 跑一次 DESCRIBE clients，确认 contact_reset_at、rejection_type 已经自动加上了。
6. 去 Settings → Autopilot 确认所有天数类设置、Cooldown 数值都是生产真实值（14 / 14 / 7 / 3 / 7 / 60 / 90 / 180 / 365，真实 Daily Send Limit），不是测试期间在副本里改过的0——这是最容易出事的一步：如果这几个设置在生产库上被误留成0，新实例一启动，会瞬间判定所有真实客户都逾期，可能对整个客户名单猛发一轮。
7. 确认 Auto Send New Emails / Auto Followup 1 / Auto Followup 2 / Auto Cold Restart / Auto Warm / Auto High Intent / Auto Reengagement / Auto Crawl Data 这几个真实开关此时都是关闭状态。
8. 观察日志几分钟（pm2 logs），确认没有报错、启动流程正常、（如果 Auto Crawl 后面会开）爬虫翻页记录正常。
9. 确认反向代理/端口指向的是新进程，不是残留的旧进程。
10. 一切正常后打开这几个真实开关。Auto Send New Emails 有真实的 Daily Send Limit 把关，可以按原计划直接开。Auto Cold Restart / Auto Warm / Auto High Intent / Auto Followup 1 / Auto Followup 2 / Auto Reengagement 这6个共用 Settings → Standard → Email Send Limit → Capacity & Queue 里的 Follow-up Daily Limit，推荐这样开：
    
    推荐做法——先把 Follow-up Daily Limit 调低（比如 20-30），6 个开关一起打开：这个量级下，就算某个类型有问题，当天真发出去的总量也很小，影响范围可控，同时能一次性完整看到 6 个类型各自的真实效果，不用像逐个开关那样等好几天（generateFollowupQueue 一天只跑一次，严格一个一个开、每个都等一整天的话，6 个类型可能要排到一周之后才能全部验证完）。跑完一轮之后，去 email_log / Preview Send Queue 抽查这次真发出去的邮件，6 个类型各挑几封，确认模板渲染、收件人、发送后的状态流转（比如 Follow-up 2 发完是不是正确进入了 cooling）都是对的。连续观察几天没问题，再把 Follow-up Daily Limit 调回 250。
    
    如果想更谨慎、一个一个隔离着排查：也可以先去 Send Capacity & Queue 看一眼 6 个类型各自真实的 Pending 量级，按积压量从小到大开，不是按代码里 High Intent→Warm→Cold Restart→Follow-up1→Follow-up2→Re-engagement 那个固定顺序开——那个顺序只是同一天多个类型同时开着、互相抢 Follow-up Daily Limit 额度时的分配规则（只在多个开关同时开着时才起作用，不会记住你先开的是哪个），不代表开关必须照这个顺序打开。先开积压最小的类型，确认没问题再开下一个，把积压最大的（大概率是 Cold Restart 或 Follow-up 1）留到最后，出问题时影响范围最小；缺点是全部开完可能要好几天。
11. 对 Auto Cold Restart / Auto Warm / Auto High Intent / Auto Reengagement 这4个新开关，打开后第一次有对应类型的邮件产生时，去 Preview Send Queue 确认它没有停在里面——应该是已经直接进了 email_log 变成已发送状态。但先排除两种正常情况再下结论：①这个客户是不是 watchlist（是的话，不管开关开没开，永远停在队列里等人工点 Send，这不代表开关没生效）；②当天的 Follow-up Daily Limit 额度是不是已经被更高优先级的类型用完了（用完的话，会正常留到下一次 generateFollowupQueue 运行，也不代表开关没生效）。排除这两种情况之后，如果还停在队列里，才说明开关没生效。
12. 盯着接管后第一次整点 cron、第一次9点每日 generateFollowupQueue 的日志，确认行为符合预期——尤其留意日志里 [FollowupQueue] Auto-sent N queued item(s) 和 N auto-eligible item(s) held back - daily follow-up cap reached 这两行，能直接看出当天有多少被发了、多少被上限挡住留到下一次。

举例：Follow-up Daily Limit 具体怎么算

假设 Follow-up Daily Limit 设的是 250，6 个 Auto 开关全部打开，今天队列里躺着这些"等发"的邮件：

9 点定时任务跑起来，实际发生的是：

1. 按优先级发，不是雨露均沾：先把 High Intent 的 3 个全发（剩 247 额度）→ 再把 Warm 的 5 个全发（剩 242 额度）→ 轮到 Cold Restart，400 个里刨掉 9 个 watchlist 还剩 391 个候选，只够发 242 个，剩下 149 个继续留在 Pending → 额度花光，Follow-up 1（196 个非 watchlist 候选）、Follow-up 2（9 个非 watchlist 候选）、Re-engagement（8 个）今天一封都不发，全部留到明天。
2. 发失败的不算钱：上面那 242 个尝试里，如果有 2 个客户刚好在这几分钟里自己回信了，系统会跳过这 2 个不发，也不会占用额度——会多试 2 个候选人补上，保证真正发出去的还是尽量接近该有的名额，不白白浪费。
3. 手动发的也占用额度：如果 9 点之前你自己在 Preview Send Queue 手动点发了 50 封，9 点定时任务算出来的额度就是 250-50=200，不是满额 250——目的是保护 Brevo 一天的总发送量，不是只管"自动"发的那部分。
4. 没发完的不会丢，明天接着排：Cold Restart 剩的 149 个、Follow-up 1 的 196 个，原样留在 Pending，不会消失也不会被重发。明天额度重置回 250，还是按同样的优先级顺序，先紧着上面几类，剩下的才轮到 Cold Restart 继续清。
5. watchlist 的 14 个（9+4+1），不管开关和额度，永远不会被这套逻辑自动发——这是 watchlist 本身的设计目的，需要你自己去 Preview Send Queue 手动点 Send，Preview Send Queue 因此不会因为开关打开就完全清空，watchlist 的部分会一直留着等你处理。
6. 测试客户不受影响：如果候选人是专门用来测试的"测试客户"，不管开关开没开、额度够不够，系统都不会自动发，永远要手动点 Send。

H2 · 正式接管后的历史数据 backfill 必须在 H1 完成之后才做

2026-08-01 排查线上数据时发现：由于两个独立的历史 bug，4 月下旬到现在这段时间，一部分本该发生的状态变化实际上从没写进 clients 表。这些 bug 本身已经在代码里修好了，但已经"漏掉"的这段历史，代码修复不会自动帮你补——需要在新版 Stella 正式接管生产库之后，单独跑一次性的数据补录。这里把来龙去脉、要做的两件事、以及每件事要注意的坑都写清楚，供接管后照着执行。

背景：为什么会漏，漏了什么

一共有三个独立的历史 bug，分别在这里发现、这里修复：

真正开始批量往真实客户发信的日期，是用 email_log 里 unsubscribed / opened / clicked / replied 这四类各自独立的最早一条记录互相印证出来的——四个信号的最早时间都集中在 2026-04-23 这一天附近，不是最初猜测的 3 月，也不是中途猜测的 6 月。下面两个任务都以这个日期为起点。

举个例子，把整件事串起来

三个虚构的客户，分别对应"任务1要处理的情况"、"任务2要处理的情况"、"什么都不用管、自己会好的情况"：

8月，新版 Stella 正式接管，跑 backfill：任务1连上 connect@ 邮箱，翻到 Lisa 5/8 那封回信，AI 判断是婉拒，调用 markClientReplied()——阳光建材的 clients.status 被正确改成 cooling（server.js soft_rejection 分支），冷却到期日从"今天"（backfill 执行的那天）往后推 60 天，不是从 5/8 号往后推，时间会比理想情况晚一些，这个没有完美解法。任务2重放 email_log 里绿源物流那条 unsubscribed 记录，clients.status 被正确同步成 not_interested，正式退出联系名单。东方物流不需要 backfill 做任何事，他的数据从头到尾都是对的。

代码上线，autopilot 定时任务开始正常跑之后：阳光建材——因为任务1已经把她的状态改成了 cooling，generateFollowupQueue() 挑候选人时有一条硬性条件 c.status = 'contacted'，cooling 不满足这条，她会被直接排除，不会因为"打开过邮件"而又收到一封 warm 跟进邮件，跟她已经婉拒这件事不矛盾。东方物流——他的状态自始至终一直是 contacted，"打开过邮件、还没发过 warm"这个条件本来就一直是对的，generateFollowupQueue() 下一次运行时会直接命中他，正确生成一条 warm 跟进邮件——不需要为"5月的那次开信"单独写脚本去补，系统检查的是"现在符不符合条件"，不是"5月当时有没有实时触发过"。

任务1 · 回复情绪分类 backfill（连 connect@ 邮箱，2026-04-23 至今）

1. 写一个一次性脚本（不是常驻接口，跑完即可删除），复用 checkInboxReplies() 里逐封处理邮件的完整逻辑，唯一的改动是把"只查最近7天"（since = 7天前）这个时间参数换成一个固定的起点 since = 2026-04-23——效果是从 2026-04-23 一直查到脚本实际运行的那一天（不是只查 4 月 23 日当天），把这中间几个月积压的邮件一次性全部拉下来处理。
2. 邮件必须按 sent_at / 收件时间正序（从最早到最新）逐封处理——如果同一个客户在这几个月里回复过不止一次（比如先感兴趣、后来又拒绝），按正序处理完，最终状态才会正确停在最新的那一条上。
3. 识别到自动回复（度假自动回复等）时，必须调用现成的 detectAutoReply() 判断，不要囫囵当成真实客户情绪去分类——这一步直接复用现成函数，不要自己重写一遍类似逻辑，避免细节判断不一致。
4. 每一封真实回复，必须直接调用 markClientReplied() 这个函数本身（而不是照着它的逻辑重新写一遍）——这样能自动继承它已经写好的几层保护：按 contact_reset_at 限定范围的 hard_rejection 公司归档逻辑（不会误伤"联系人已经换过一轮"的公司）、按 message-id 写入 client_activities 的去重（保证跟以后正常的 7 天轮询不会重复处理同一封信）、清空 question_received_at 等细节。
5. 排除你会额外提供的"这段时间里已经人工手动处理过"的客户名单，这些不需要 AI 重新分类一遍。
6. 控制 Groq 调用节奏，配合已经上线的"按模型分开追踪 token 用量 + gpt-oss 额度不够自动借用 qwen"这套机制（callGroq / pickFreshProtagonist 附近的额度检查逻辑），不要因为一次性处理几个月的积压邮件，把当天 gpt-oss-120b 的额度一次性打满，影响到同一天其他实时功能（邮件分类、社媒生成等）。

为什么必须调用这个函数本身、不能自己重写——三条保护各举一个例子：

① contact_reset_at 保护，防止用旧联系人的拒绝信错杀新联系人——青山制造，3月的联系人 Tom 回信"不需要，别再联系了"（硬拒绝）；6月爬虫在青山制造又抓到了新的联系人 Amy，系统给这家公司重新开了一轮（重置时间记在 contact_reset_at 里）。补录脚本翻到 3 月 Tom 那封拒绝信时，不能因为这封信就把"青山制造"整个公司标成不再联系——现在联系的是 Amy，Amy 什么都没拒绝过，不该被 Tom 三个月前的话连累。markClientReplied() 会先判断这封回信是在 contact_reset_at 之前还是之后，是之前的旧回信就不会用来误杀新联系人；自己重写逻辑很容易漏掉这一步。

② message-id 去重保护，防止同一封信被处理两次——补录脚本这次是一次性把几个月的旧邮件翻一遍处理掉，处理完之后系统还会照常继续巡检收件箱。如果漏了"记一个已处理标记"这一步，以后系统正常巡检万一又扫到同一封旧邮件，会误以为是新回信，把改状态、发通知那套逻辑再跑一遍——同一封信被处理两次，客户动态记录里会出现重复的两条。markClientReplied() 会用邮件自带的 message-id 记一条"处理过了"的标记，以后再扫到同一封信会自动跳过；自己重写脚本容易忘记打这个标记。

③ 清空 question_received_at，防止留下一个过时的"还在等回答"状态——客户之前问过一个问题（比如"价格怎么算"），系统记了一个"在等回答"的时间戳。后来客户又发来一封信把事情说清楚了（比如直接说不需要了），这个"等回答"的时间戳应该被清掉，不然界面会一直显示"客户还在等你回复问题"，其实是个过时的假状态。markClientReplied() 处理新回信时会顺手清掉这类过时标记；自己单独写状态更新代码，很容易只改了状态字段，忘了这些连带的细节字段也要跟着清。

这三条都是"自己重写容易漏、用现成函数就自动不会漏"的坑，所以宁可让补录脚本调用这个函数本身，也不要照着逻辑抄一遍。

任务1 执行过程中顺带发现并修复的2个真实问题 2026-10

这两个不是另开的任务，而是在逐封核对那11封"自动匹配没认出来"的历史邮件时，顺带发现 checkInboxReplies()/analyseReplySentiment()/extractReplyBody() 本身也有缺口，当场一起修掉、一起跑进了 backfill：

任务2 · Not Interested / Bounced 状态重新同步

这个任务跟任务1完全独立，互不依赖，可以按任意顺序做，甚至可以合并到同一次脚本里一起跑。背景是"② Webhook 写库没等完成"这个 bug——email_log 里 unsubscribed / bounced 这两类记录本身没有缺失（已经用真实生产数据核实过，4-7 月每个工作日都有连续记录），缺的只是这些正确记录当时没有同步写进 clients.status。

1. 查询 email_log 里所有 status IN ('unsubscribed','bounced') 的记录，按 sent_at 正序取出——不限定具体某个月份，因为这个 bug 本质是"偶发的写入丢失"，理论上随时可能发生，不是固定在某一个月的窗口内，限定月份反而可能漏掉窗口外的个案。
2. 按时间正序逐条重放：status = 'bounced' → clients.status = 'bounced'；status = 'unsubscribed' → clients.status = 'not_interested'。同一个客户如果历史上有多条记录，正序处理完，状态会正确停在最新的那一条。
3. 按你的决定，这次 backfill 不使用"active / not_interested / bounced 状态不可被覆盖"这条保护（autopilotAutoSend 判断新客户时用得上，但这里刻意不用）——原因是当前只有 2 家 active 客户，风险很小，直接覆盖即可，不用为了极小概率的场景增加复杂度。
4. 每条重放的同时，补一条 client_activities 记录，body 前面加一个类似 [Backfilled] 的标记前缀，方便以后区分这条是当时实时产生的，还是这次补录的。

任务3 · brevo_message_id 格式修正（尖括号）2026-08-24 发现

跟上面两个任务的性质不太一样——不是"事件当时没被处理"，而是"事件处理时认错了对象"。根因：Brevo 发信 API 返回、以及它自己后台展示的 Message ID，格式都带尖括号（比如 <202608240648.18253653303@smtp-relay.mailin.fr>），但 sendViaBrevo() 存进 email_log.brevo_message_id 时一直原样存的带尖括号的值；而 webhook 收到 Brevo 推送的打开/点击/退信事件时，会先把它带的 message-id 去掉尖括号再拿去数据库里查。两边格式对不上，WHERE brevo_message_id = ? 从来没有真正匹配成功过，每次都会静默退回到"这个邮箱最近发出的那一封"这个兜底方案。

大多数情况下这个兜底方案蒙对了结果（一个客户同一时间通常只有一封邮件在外，"最近发出的那封"碰巧就是对的），所以这个 bug 一直没被发现，直到 2026-08-24 测试"两封邮件同时在外"这类场景才真正暴露：两次打开事件都被记到了后发出的那封（Cold Restart）头上，先发出的 First Email 反而显示"从没打开过"。server.js 存库那一步已经改成存之前先去掉尖括号（不影响回复串联逻辑，那段代码本来就同时兼容带、不带尖括号两种输入），但这个改动只对代码上线之后新发的邮件生效，已经存在数据库里的旧记录格式不会自动被修正，需要单独跑一次。

1. 确认这次改动过的 server.js 已经部署、新进程已经在跑（跟本节步骤4一致）。
2. 跑一次性 SQL，把已有的 brevo_message_id 值批量去掉首尾尖括号：

   UPDATE email_log
   SET brevo_message_id = REPLACE(REPLACE(brevo_message_id, '<', ''), '>', '')
   WHERE brevo_message_id LIKE '<%>';

任务4 · 多联系人公司的 to_email 全链路追踪重构 2026-10 发现并修复

亲自去真实的 Preview Send Queue 里逐条看的时候发现的，不是靠查数据库发现的：Auckland Transport 出现了两条重复的 High Intent 排队邮件，同时好几家多联系人公司的称呼明显不对（"Hi Dr"、"Hi me"，或者称呼和实际收件邮箱对不上）。

根因：pickFollowupEmail(clientId, contactEmail) 解析的是"这家客户整体上该用哪个地址"（按互动强度：回复过 > 点击过 > 打开过，同等情况下按最近一次发信时间 tie-break），完全没有"这条跟进邮件具体是关于哪一封原始邮件"这个概念。Auckland Transport 真实有两个独立联系人（Rennie、Lynn），各自收到过自己的"第一封邮件"、各自点过自己那封的链接——但两个人都被这套逻辑解析成了同一个地址，其中一个人的互动记录被静默吞掉，完全没有任何报错或提示。

修复：给 followup_queue 加了 to_email 列，从候选查询到最终发送的整条链路都改成按这条跟进邮件具体对应哪一封原始邮件来追踪，不再是笼统的"这家公司的地址"：

• generateFollowupQueue() 的候选查询，关联上 lead_id 拿到这条原始邮件对应的具体联系人数据；去重条件从"按 client_id"改成"按 (client_id, to_email)"，两个联系人不会再互相顶替
• INSERT followup_queue 时把 to_email 一起存下来，不再是发送那一刻才现算
• sendFollowupQueueItem() 找"上一封邮件"来拼 Subject/In-Reply-To 这些续接邮件串的信息时，按存下来的 to_email 精确限定，不再是不分青红皂白地挑这家公司最早的那一封
• Preview Send Queue 接口、redirectStalePendingToHighIntent()（点击链接后把排队邮件临时改成 High Intent 那条逻辑）、手动"重新生成"接口，全部同步改成优先用存下来的 to_email，只有旧数据没有这个字段时才退回旧的 pickFollowupEmail() 兜底

任务5 · 邮件称呼（问候语）解析全面重构 2026-10 发现并修复，范围最大的一次

起因同样是亲自翻 Preview Send Queue 发现的，不是靠自动化测试发现的：陆续看到 Wellington City Mission"Hi Applications"、Sanitarium"Hi Talent"、Hierarchy Group"Hi Abby"、AFFCO"Hi Lucas"（收件地址明明是 brett.innes@）这类明显不对或者可疑的称呼。这是这一轮篇幅最长、反复最多的一次修复，这里只记最终结论和路上几个真正关键的发现，不复述每一轮排查细节。

· 排查路上走过的弯路（有意义的弯路，不是浪费时间）

1. 第一反应——扩充黑名单：一开始思路是"遇到一个垃圾词就加一个"（talent/acquisition/applications/human/resources/careers/cv/distribution/fabrication/managing/people/senior/supervisor 等等），这套办法能堵住已经发现的具体案例，但本质是在打地鼠，发现一个修一个，不成体系。
2. 公司名误当人名——"Hawkeswood Mining, Careers"：发现光靠黑名单堵不住"contact_person 字段里直接写进了公司名本身"这类情况（比如这条真实数据，"Hawkeswood"被当成人名提取出来，因为它确实首字母大写、不在任何黑名单里）。加了一道结构性检查：候选词如果等于这家公司自己名字的首词，直接判定不是人名——比继续堵词更一次性。
3. 升级成"行业标准的共享邮箱检测"：查证了邮件验证行业本身怎么处理这类问题（ZeroBounce 等工具的"role-based email detection"），确认"维护一份已知角色前缀词表、逐段比对邮箱前缀"是业内标准做法，不是自己瞎想的；原来只看"邮箱前缀有没有分隔符"的简单判断换成了这套更可靠的词表比对，顺带堵住了 no-reply@、customer-service@ 这类带连字符但其实是共享邮箱的地址。

· 真正的转折点：contact_person 这个数据源本身不可信

用真实数据核实 AFFCO / Fresh Meats NZ / Papamoa Dental 这三条"称呼明显不对"的记录时发现：不是关联错了联系人，是同一条 lead 记录内部，姓名字段和邮箱字段从一开始就没对上——专门加了一个诊断字段去核实"这条 lead 自己的邮箱是不是真的等于实际收件地址"，三条全部显示"是"（lead_email_matches_to_email: true），但姓名完全是另一个人（比如 lead #55583，contact_person="Lucas Bird"，contact_email="brett.innes@affco.co.nz"，这两个字段压根不是同一个人）。这说明问题出在最早的抓取/建档环节，不是查询关联的问题——就算关联链路完全正确，contact_person 这段抓取来的文本本身也可能是错的，靠"多核实一层关联"堵不住这类问题。

从收件地址解析名字本身，路上也找到并修了几个真实漏洞（全部是拿真实数据测出来的，不是凭空想的边界情况）：

为什么 warm / high_intent / cold_restart / re-engagement 不需要单独 backfill

这几类不是存起来的历史记录，而是 generateFollowupQueue() 每次运行时，根据 email_log 当前的 open_count / status，加上"距离首封邮件过了几天"现场算出来的，不依赖"当时是否被实时处理过"。只要满足两个条件：底层的 email_log.open_count / status 数据本身是对的（已确认——这块走的是 Brevo 的 opened/click webhook 事件，一直在正常记录，不受收件箱配错这个问题影响；但"正常记录"指的是事件本身没有被漏记，不代表一定记在了正确的那一封邮件上——如果某个客户当时恰好有两封邮件同时在外，可能撞上上面任务3那个 message-id 格式问题，记错了行，具体局限见任务3的说明），以及代码上线后 autopilot 的每小时 / 每日定时任务正常跑起来——那么任何当前真实符合 warm / high_intent / cold_restart 条件的客户，下一次定时任务运行时就会被自动、正确地捕捉到，不需要额外写脚本去补历史。re-engagement 同理，是靠 cooling.reengagement_date 到期后自动触发的，只要 cooling 状态被任务1正确同步了，re-engagement 会自然跟上，不需要单独处理。

H3 · 清理垃圾公司名 2026-08-28 发现

根因：crawler.js 抓 TradeMe 职位时，如果页面上专门放公司名的 CSS 选择器（.jb-listing__company-name 等）没抓到内容，会退而求其次，用一段正则从页面 meta 描述文字里"猜"一个公司名出来（crawler.js 里 jobData.meta_desc 那段兜底逻辑）。这段正则不设长度上限，遇到叙述性的长段描述文字，可能把一整句、甚至好几句话都当成"公司名"截下来，直接存进了 clients.company_name——不只是显示问题，这些"公司"会被当成正常线索走完整套自动化流程，已确认至少一条已经被真实发过一封跟进邮件。

测试库里当时已确认的两条真实例子：id 33529（"Based in Twizel or Oamaru [换行] About the role [换行] Thi..."，status=new，从未联系过）、id 19789（"About the Role I am a 32-year-old woman who leads..."，status=contacted，已经真发过一封跟进邮件）。代码层面的修复见下方"顺便：crawler.js 怎么改比较保险"，这里只处理已经进了库的历史脏数据。

第一步：识别，只读不改

两条真垃圾数据都包含 "about the role" 这个词组（大小写不一），这是 TradeMe 职位描述页常见的标题用语，正常公司名几乎不可能出现这个短语；33529 那条另外还能看出里面混进了真实的换行符（\n），公司名同样不该出现换行。用这两个信号一起筛，比单纯看长度精确得多：

SELECT id, company_name, status, source, created_at
FROM clients
WHERE source = 'TradeMe'
  AND (LOWER(company_name) LIKE '%about the role%' OR company_name LIKE '%\n%')
ORDER BY created_at DESC;

这依然只是初筛，不是最终判定，跑完必须人工过一遍结果——如果这次搜出来的除了已确认的33529、19789之外没有别的，就只处理这两条即可，不需要额外操作。

第二步：按有没有真实发过邮件分两种处理

不建议无差别一律 DELETE：如果这条垃圾"客户"已经有过真实的 email_log/followup_queue/client_activities 记录（比如已经真发过一封邮件），删掉客户本身会让这些记录变成指向不存在客户的孤儿数据，也会抹掉"确实发过一封邮件"这个本该保留的事实。已确认的这两条正好一边一个例子：

1. 33529（从未联系过）——直接删除，加了保险条件，万一它其实有历史记录就不会被误删：

   DELETE FROM clients
   WHERE id = 33529
     AND id NOT IN (SELECT DISTINCT client_id FROM email_log WHERE client_id IS NOT NULL)
     AND id NOT IN (SELECT DISTINCT client_id FROM followup_queue WHERE client_id IS NOT NULL)
     AND id NOT IN (SELECT DISTINCT client_id FROM client_activities WHERE client_id IS NOT NULL);

2. 19789（已经真发过邮件）——保留客户行，只是让它彻底停止参与任何自动化，先撤掉还在排队没发的，再把状态改成 not_interested（generateFollowupQueue 之类的候选人查询都要求 status = 'contacted'，改完以后再也不会选中它），email_log/client_activities 的历史记录原样保留：

   UPDATE followup_queue SET status = 'skipped' WHERE status = 'pending' AND client_id = 19789;
   UPDATE clients SET status = 'not_interested' WHERE id = 19789;

如果第一步的搜索结果里还有别的记录，人工确认是真垃圾之后，把上面两条 SQL 里的具体 id 换成对应的 id、按"有没有真实记录"套用同样的两种处理方式即可。

crawler.js 的代码已经修好了 2026-08-28

最早想的方案是"猜不到就老实存 'Unknown (via TradeMe)'"，但这个想法有个漏洞：跟进邮件模板渲染那段代码（renderFollowupTemplate）本来就有 companyName || 'your company' 这种兜底，但这个兜底只在 companyName 真的是空值时才生效——'Unknown (via TradeMe)' 是个非空字符串，兜底不会触发，模板会把这串占位文字原样塞进邮件正文，比刚才发现的问题更离谱。改用了更干净的方案：公司名抓不到就直接不生成这条线索，跟其他来源（Seek/Indeed 等，本来就有 .filter(j => j.job_title && j.company_name)）保持一致，不再单独给 TradeMe 硬凑一个公司名。没有真实公司名的线索本来就没法正常发信，与其到处打补丁处理"公司名是占位符"这种边界情况，不如从源头不让它进 b2b_leads/clients 表：

if (jobData.job_title && jobData.company_name) {
    const tmContactInfo = extractContactInfo(jobData.descText || '');
    trademeJobs.push({
        job_title: jobData.job_title,
        job_url: jobUrl,
        company_name: jobData.company_name,
        contact_person: jobData.contact_person || tmContactInfo.contactName || '',
        contact_email: tmContactInfo.email || '',
        contact_phone: tmContactInfo.phone || '',
        location: jobData.location || ''
    });
}

这条改动只影响以后新抓的数据，不会自动清理已经在库里的历史脏数据，历史部分还是要靠上面第一、二步手动跑一次。

H1-H3 全部任务确认完成、正式开关打开之后，要删掉的临时内容 2026-10

以下都是为了这一轮接管测试临时加进 server.js 的诊断/补录用接口，不是长期要保留的功能，确认不再需要之后应该整批清掉，不要带进长期生产代码：

任务3（brevo_message_id 格式修正）和 H3 本身的脏数据清理，用的是直接在 phpMyAdmin 里手动跑的一次性 SQL，没有加临时接口，不需要额外清理代码；cleanup_garbled_contact_person.js（contact_person 乱码清理）是独立的维护脚本，不是 server.js 里的路由，留在项目目录里不影响什么，不需要跟上面这些接口一起删。

背景：为什么会有乱码

upsertClient() 里合并联系人信息的逻辑，之前是"只要抓到新的联系人名字就往后追加"，不会替换掉旧的。同一家公司只要被 Seek/Indeed/TradeMe/SJS 反复抓到（招聘信息本来就会重复出现），contact_person 就会不断变长，变成一长串逗号拼接的碎片——生产库里查到最长的一条超过 4500 字符。同一天还修了 extractContactInfo() 里人名抓取的正则本身（触发词大小写不敏感、人名部分强制要求真大写，避免把 "at"、"on" 这类词也当成人名的一部分抓进去，详见代码里的注释）。

修复之后：upsertClient() 改成"只保留最新一次抓到的名字，直接替换旧值"，不再无限追加——contact_person 唯一的用途是邮件称呼（isLikelyName() 本来就会在名字不像真名时兜底显示 "there"），保留一个可能猜错的名字没问题，但让它无限累积成一段乱码不行。但这个修复只能防止以后再变乱，已经存在的乱码数据不会自动被清掉，所以需要跑一次一次性清理。

脚本做什么 — cleanup_garbled_contact_person.js（项目根目录）

连接数据库的方式和 server.js 完全一样（自动识别 DB_SOCKET_PATH：生产环境走 socket，本地走 host/port），所以不管在本地还是生产服务器上跑，只要用的是当前环境自己的 .env，就能连到对应的库，不需要额外配置。

逻辑很简单：找出 clients.contact_person 长度超过 60 字符的所有记录（真实的"名 姓"基本不可能超过这个长度），默认只打印报告、不改数据；加上 --apply 参数才会真正把这些记录的 contact_person 清空。清空之后不用管——下次这家公司被爬虫重新抓到，新的替换逻辑会自动填回一条干净的名字；一直没被重新抓到就一直空着，邮件称呼会兜底显示 "there"，不影响发送。

怎么在生产服务器上跑

1. 把 cleanup_garbled_contact_person.js 上传到生产服务器的项目目录（跟 server.js 同一个目录），用你平时更新 server.js 的同一套方式（cPanel File Manager / FTP 等）。
2. 进 cPanel → Terminal，cd 到项目目录。
3. 先跑 dry-run，只看报告，不改任何数据：

   node cleanup_garbled_contact_person.js

4. 看一遍打印出来的清单（公司名 + 乱码内容预览），确认这些确实是垃圾数据，不是巧合的合法长文本。
5. 确认没问题后，加上 --apply 再跑一次，这次才会真正清空：

   node cleanup_garbled_contact_person.js --apply