From 1a8cbc143b6b47d541b559580a68094a290eb09f Mon Sep 17 00:00:00 2001
From: QLHazyCoder <2825305047@qq.com>
Date: Fri, 17 Apr 2026 14:37:05 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85md=E6=96=87=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                 | 23 ++++++++++++++++++++++
 项目完整链路说明.md       | 40 +++++++++++++++++++++++++++++++++++++++
 项目开发规范（AI协作）.md | 25 ++++++++++++++++++++++++
 项目文件结构说明.md       | 39 ++++++++++++++++++++++++++++++++++++++
 4 files changed, 127 insertions(+)

diff --git a/README.md b/README.md
index b8fad02..ce8c49c 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,29 @@
 ## 安装
 
 1. 打开 `chrome://extensions/`
+
+## 2026-04-17 更新补充：Gmail / 2925 别名邮箱
+
+本次版本对 `Gmail` 与 `2925` 的注册邮箱逻辑做了统一整理：
+
+- `Gmail` 与 `2925` 现在都走同一套“别名邮箱”逻辑。
+- 两者都不再使用“只填前缀再特殊拼接”的界面交互。
+- 两者都要求先填写“基邮箱”：
+  - `Gmail`：例如 `name@gmail.com`
+  - `2925`：例如 `name@2925.com`
+- 侧边栏里的“注册邮箱”输入框对这两种模式都已开放，可直接手动填写完整邮箱。
+- 侧边栏里的 `获取 / 生成` 按钮对这两种模式也可用，行为与 Duck / Cloudflare 一样，都是“可自动生成，也可手动覆盖”。
+
+具体行为：
+
+- `Gmail` 会基于完整基邮箱生成 `name+tag@gmail.com`
+- `2925` 会基于完整基邮箱生成 `name123456@2925.com`
+- 如果当前“注册邮箱”里已经是与当前基邮箱兼容的完整邮箱，流程会优先复用，不会强行重新生成
+
+注意：
+
+- `2925` 旧的“只填前缀”使用方式已经不再推荐，应该改为填写完整基邮箱
+- 如果你手动填写了与当前 `Gmail / 2925` 基邮箱不匹配的完整邮箱，侧边栏会在保存或执行 Step 3 时拦截
 2. 开启“开发者模式”
 3. 点击“加载已解压的扩展程序”
 4. 选择本项目目录
diff --git a/项目完整链路说明.md b/项目完整链路说明.md
index e2ab5b4..c4c57a8 100644
--- a/项目完整链路说明.md
+++ b/项目完整链路说明.md
@@ -310,6 +310,46 @@
 
 ## 7. 邮箱与 provider 链路
 
+### 7.1 2026-04-17 补充：Gmail / 2925 统一别名邮箱链路
+
+本轮将 Gmail 与 2925 的注册邮箱逻辑统一收敛为“共享别名邮箱链路”：
+
+- 两者都先填写“基邮箱”
+  - Gmail：`name@gmail.com`
+  - 2925：`name@2925.com`
+- 两者都允许两种入口：
+  - 点击侧边栏按钮自动生成完整注册邮箱
+  - 直接在“注册邮箱”输入框中手动填写完整邮箱
+
+当前行为约定：
+
+1. sidepanel 展示“别名基邮箱”输入框，并根据当前 provider 显示对应文案
+2. 点击 `获取 / 生成` 时：
+   - Gmail 生成 `name+tag@gmail.com`
+   - 2925 生成 `name123456@2925.com`
+3. Step 2 / Step 3 进入注册流程前，会先判断当前 `state.email`
+   - 如果已经是与当前基邮箱兼容的完整邮箱，则直接复用
+   - 如果为空或不兼容，则按当前 provider 重新生成
+4. 保存或执行 Step 3 时，如果手动填写的完整邮箱与当前 Gmail / 2925 基邮箱不兼容，sidepanel 会直接拦截
+5. auto-run fresh attempt reset 时，会保留：
+   - `gmailBaseEmail`
+   - `mail2925BaseEmail`
+
+### 7.2 共享模块分工
+
+- `managed-alias-utils.js`
+  统一承接 Gmail / 2925 的：
+  - 基邮箱解析
+  - 完整邮箱兼容性判断
+  - 别名邮箱生成
+  - UI 文案输出
+
+- `background/generated-email-helpers.js`
+  在原有 Duck / Cloudflare / iCloud / Cloudflare Temp Email 生成链路之外，新增 Gmail / 2925 的共享生成接入。
+
+- `background/signup-flow-helpers.js`
+  负责在真正提交注册邮箱前做“复用已有完整邮箱 / 重新生成”的最终决策。
+
 ### 7.1 生成邮箱
 
 文件：
diff --git a/项目开发规范（AI协作）.md b/项目开发规范（AI协作）.md
index 8b84497..dd172db 100644
--- a/项目开发规范（AI协作）.md
+++ b/项目开发规范（AI协作）.md
@@ -81,6 +81,21 @@
 5. 是否需要成功收尾逻辑
 6. 是否需要 README 与完整链路文档更新
 
+### 3.2.1 共享别名邮箱逻辑补充
+
+当 Gmail / 2925 这类“既影响注册邮箱生成，又影响 sidepanel 表单行为”的 provider 发生变化时，必须优先检查是否应落入共享层，而不是继续把规则分散写在：
+
+- `background.js`
+- `sidepanel/sidepanel.js`
+- 某一个单独 provider 分支里
+
+当前约定：
+
+- Gmail / 2925 的基邮箱解析、兼容性判断、别名生成、UI 文案优先收敛到 `managed-alias-utils.js`
+- `background/generated-email-helpers.js` 只负责调度，不应再次复制 Gmail / 2925 规则
+- `background/signup-flow-helpers.js` 只负责“复用已有邮箱还是重新生成”的流程决策
+- `sidepanel/sidepanel.js` 只负责 UI 接线、校验触发和状态同步
+
 ### 3.3 新增配置项
 
 必须同步检查：
@@ -117,6 +132,15 @@
 bun test
 ```
 
+补充说明：
+
+- 实际执行命令以仓库当前 `package.json` 为准
+- 本仓库当前全量回归命令为：
+
+```bash
+npm test
+```
+
 ## 5. 文档更新规范
 
 ### 5.1 必须更新文档的场景
@@ -169,6 +193,7 @@ bun test
 4. 我有没有补或迁移测试？
 5. 我有没有更新三份根目录文档？
 6. 我新增或修改的文件是否有可见乱码？
+7. 如果改动影响 Gmail / 2925 别名邮箱逻辑，我有没有同步检查 `managed-alias-utils.js`、sidepanel 接线、background 调度、auto-run reset 和回归测试？
 
 ## 9. 完成标准
 
diff --git a/项目文件结构说明.md b/项目文件结构说明.md
index 2526d24..9ff2aa5 100644
--- a/项目文件结构说明.md
+++ b/项目文件结构说明.md
@@ -116,6 +116,45 @@
 
 ## `tests/`
 
+## 2026-04-17 增量补充
+
+### 新增共享模块
+
+- `managed-alias-utils.js`
+  共享 Gmail / 2925 的别名邮箱规则，负责：
+  - 解析基邮箱
+  - 校验“当前完整注册邮箱”是否仍与基邮箱兼容
+  - 生成 Gmail `+tag` 与 2925 随机后缀邮箱
+  - 输出 sidepanel 可复用的 UI 文案
+
+### 本轮受影响文件
+
+- `background/generated-email-helpers.js`
+  现在除了 Duck / Cloudflare / iCloud / Cloudflare Temp Email，也统一承接 Gmail / 2925 的别名邮箱生成入口。
+
+- `background/signup-flow-helpers.js`
+  在 Gmail / 2925 模式下，会优先复用已经存在且仍兼容的完整注册邮箱；只有不兼容或为空时才重新生成。
+
+- `background/auto-run-controller.js`
+  fresh-attempt reset 时，额外保留 `gmailBaseEmail` 与 `mail2925BaseEmail`，避免自动流程重置后丢失别名基邮箱配置。
+
+- `sidepanel/sidepanel.js`
+  现在把 Gmail / 2925 的“基邮箱输入”“完整注册邮箱输入”“自动生成按钮”“兼容性校验”统一接到共享别名逻辑上。
+
+- `sidepanel/sidepanel.html`
+  加载 `managed-alias-utils.js`，并把旧的“邮箱前缀”字段语义改为“别名基邮箱”。
+
+### 新增/补充测试
+
+- `tests/managed-alias-utils.test.js`
+  覆盖 Gmail / 2925 共享别名工具的解析、生成、兼容性判断。
+
+- `tests/background-signup-step2-branching.test.js`
+  补充“已有兼容别名邮箱时应直接复用，不应再次重生成”的行为验证。
+
+- `tests/auto-run-fresh-attempt-reset.test.js`
+  补充 `gmailBaseEmail` / `mail2925BaseEmail` 在自动流程 fresh reset 后仍被保留的回归验证。
+
 - `tests/activation-utils.test.js`閿涙碍绁寸拠鏇炲敶鐎圭鍓奸張顒佺负濞茶崵鐡ラ悾銉ょ瑢 Step 9 閸欘垱浠径宥夋晩鐠囶垰鍨介弬顓溾偓?
 - `tests/auto-run-fresh-attempt-reset.test.js`閿涙碍绁寸拠鏇″殰閸斻劏绻嶇悰灞芥躬閺傞绔存潪顔肩磻婵澧犳导姘跺櫢缂冾喗妫潻鎰攽閺冩湹绗傛稉瀣瀮閵?
 - `tests/auto-run-step6-restart.test.js`閿涙碍绁寸拠鏇″殰閸斻劏绻嶇悰灞芥躬濮濄儵顎?6 娑斿鎮楅柆鍥晩閺冩湹绱伴崶鐐插煂濮濄儵顎?6 闁插秴绱戦敍灞借嫙閸︺劌鎳℃稉?add-phone 閺冭泛浠犲銏ゅ櫢瀵偓閵?