重构duckduckgo邮箱获取

项目完整链路说明.md

@@ -150,9 +150,11 @@
 - 当前轮冻结后的注册方式 `resolvedSignupMethod`
 - 当前统一账号标识 `accountIdentifierType / accountIdentifier`
 - 当前邮箱 / 密码
+- 注册邮箱运行态 `registrationEmailState = { current, previous, source, updatedAt }`
 - 当前手机号注册运行态 `signupPhoneNumber / signupPhoneActivation / signupPhoneCompletedActivation`
 - 侧栏“注册手机号”输入框只同步运行态 `signupPhoneNumber / accountIdentifierType / accountIdentifier`，不属于持久配置，也不参与配置导入导出
 - 邮箱身份写入时会把 `accountIdentifierType / accountIdentifier` 改回邮箱，并清理旧的 `signupPhone*` 注册手机号运行态，避免后续 Step 4 / Step 8 被旧手机号污染而误走短信分支
+- 邮箱写入统一通过 `setEmailState*` 同步更新 `email` 与 `registrationEmailState`；如果当前邮箱因 Step 8 恢复被清空，但还需要保留上一份 Duck / add-email 对比基线，则只清空 `current`，保留 `previous`
 - 本轮联动自检重点：
   1. Step 2 一旦自动取到手机号，必须立刻广播并回填侧栏运行态手机号。
   2. sidepanel 重新加载后，必须从当前 state 恢复“注册手机号”文本框，而不是只恢复邮箱。
@@ -468,6 +470,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 1. 先确认当前认证页真实状态，而不是只看 `accountIdentifierType`。
 2. 当前是 `add-email`：
    - 调用 `resolveSignupEmailForFlow` 按需获取或生成本轮绑定邮箱；手机号注册不会在 Step 2 提前生成邮箱，只有真实进入 `add-email` 时才占用邮箱资源
+   - 如果邮箱生成器已经在生成阶段写回运行态，这里不会再重复覆盖 `registrationEmailState`，但会保留手机号身份
    - 内容脚本发送 `SUBMIT_ADD_EMAIL` 填写邮箱并提交
    - 页面进入邮箱验证码页后，用绑定邮箱作为 `step8VerificationTargetEmail`
 3. 当前是邮箱验证码页：
@@ -489,7 +492,7 @@ IP 代理模块在同步、切换、Change、出口探测和自动运行成功
 - 当登录验证码提交后进入 `phone-verification` 页时，内容脚本会显式把该页面识别为“手机验证码页”，避免与邮箱验证码页混淆。
 - 手机号注册身份本身不会让 Step 8 自动走短信；只有真实页面状态是 `phone_verification_page` 时才调用短信 helper。手机号注册登录后出现 `add-email` 时，Step 8 走“按需生成邮箱 -> 绑定邮箱 -> 邮箱验证码”链路。
 - 如果手机号注册账号在 Step 8 的 `add-email` / 邮箱验证码阶段失败并回退到 Step 7，Step 7 会优先使用当前轮保留的注册手机号身份重新登录，避免误用尚未绑定成功的邮箱登录。
-- `email_in_use` 会在 Step 8 当前步骤内清理当前邮箱并重新打开 `add-email` 获取新邮箱；`max_check_attempts` 不继续点击认证页 `重试`，只恢复当前 Step 8。
+- `email_in_use` 会在 Step 8 当前步骤内仅清空 `registrationEmailState.current / state.email`，保留 `registrationEmailState.previous` 作为上一轮比较基线，再重新打开 `add-email` 获取新邮箱；`max_check_attempts` 不继续点击认证页 `重试`，只恢复当前 Step 8。
 
 ### Step 9
 
@@ -599,11 +602,15 @@ Plus 模式可见步骤：
 2. 点击 `获取 / 生成` 时：
    - Gmail 生成 `name+tag@gmail.com`
    - 2925 仅在 provide 模式下生成 `name123456@2925.com`
-3. Step 2 / Step 3 进入注册流程前，会先判断当前 `state.email`
-   - 如果已经是与当前基邮箱兼容的完整邮箱，则直接复用
+3. 生成链路与手动保存邮箱都会统一维护 `registrationEmailState = { current, previous, source, updatedAt }`
+   - `current` 表示当前准备提交或刚生成的注册邮箱
+   - `previous` 表示最近一份仍可作为 Duck / Step 8 恢复对比基线的邮箱
+4. Step 2 / Step 3 进入注册流程前，不再只看单一的 `state.email`
+   - 如果当前完整邮箱仍与当前基邮箱兼容，则直接复用
    - 如果为空或不兼容，则按当前 provider / mode 重新生成
-4. 保存或执行 Step 3 时，如果手动填写的完整邮箱与当前 Gmail / 2925 provide 基邮箱不兼容，sidepanel 会直接拦截；`2925 receive` 不参与这条兼容性约束
-5. auto-run fresh attempt reset 时，会保留：
+5. sidepanel 手动点击“获取 / 生成”时，会把输入框当前可见邮箱一并传给后台，优先作为 Duck 新地址比较基线；如果 UI 当前为空，再回退到 `registrationEmailState.current / previous`
+6. 保存或执行 Step 3 时，如果手动填写的完整邮箱与当前 Gmail / 2925 provide 基邮箱不兼容，sidepanel 会直接拦截；`2925 receive` 不参与这条兼容性约束
+7. auto-run fresh attempt reset 时，会保留：
    - `gmailBaseEmail`
    - `mail2925BaseEmail`
 
@@ -645,11 +652,14 @@ Plus 模式可见步骤：
   - 别名邮箱生成
   - UI 文案输出
 
+- `background/registration-email-state.js`
+  统一维护当前注册邮箱、上一份比较基线邮箱、来源与更新时间，并提供 Duck 生成前解析比较基线、Step 8 清空当前邮箱但保留历史基线的共享工具。
+
 - `background/generated-email-helpers.js`
-  在原有 Duck / Cloudflare / iCloud / Cloudflare Temp Email 生成链路之外，新增 Gmail / 2925 的共享生成接入。
+  在原有 Duck / Cloudflare / iCloud / Cloudflare Temp Email 生成链路之外，新增 Gmail / 2925 的共享生成接入；Duck 生成前会按“侧栏当前可见邮箱 -> `registrationEmailState.current` -> `registrationEmailState.previous`”的顺序解析比较基线。
 
 - `background/signup-flow-helpers.js`
-  负责在真正提交注册邮箱前做“复用已有完整邮箱 / 重新生成”的最终决策。
+  负责在真正提交注册邮箱前做“复用已有完整邮箱 / 重新生成”的最终决策，并避免把生成阶段已经落库的邮箱再次重复写入运行态。
 
 ### 7.1 生成邮箱
 
@@ -666,6 +676,11 @@ Plus 模式可见步骤：
 - 自定义邮箱池
 - iCloud 隐私邮箱
 
+补充：
+
+- 所有生成器在返回邮箱后都会统一调用 `setEmailState(..., { source })` 回写运行态，保证 `email` 与 `registrationEmailState` 同步更新。
+- Duck 生成链路不会再直接拿“生成前瞬间读到的输入框值”当唯一基线，而是优先使用 sidepanel 当前可见邮箱，再回退到共享的注册邮箱运行态基线，避免生成前后地址对比失效。
+
 ### 7.1.1 Cloud Mail
 
 组成：