diff --git a/项目完整链路说明.md b/项目完整链路说明.md index 59245dc..c7c8c33 100644 --- a/项目完整链路说明.md +++ b/项目完整链路说明.md @@ -566,6 +566,58 @@ 8. sidepanel 中 2925 账号池的新增表单也走与 Hotmail 相同的共享交互:默认收起,头部按钮切换“添加账号 / 取消添加”,操作行右侧提供“批量导入”,保存成功后自动收起并清空。 9. 当 2925 号池模式开启时,当前选中的号池邮箱会同步回写到同一个 `mail2925BaseEmail` 字段;因此用户切换号池账号后,即使再次关闭号池模式,也会直接沿用刚才选中的邮箱作为手动基邮箱,无需重新输入。 +### 7.4.1 2925 双模式维护约定 + +这是后续维护 `2925` 时最容易被重新打散的一段链路,建议按下面的职责边界理解: + +- UI 层: + - `sidepanel/sidepanel.html` + - 负责展示 `提供邮箱 / 接收邮箱` + - 负责展示独立的 `2925 号池` 配置行 + - 不负责决定“2925 是否参与别名邮箱生成” + - `sidepanel/sidepanel.js` + - 只负责把当前 `mail2925Mode`、号池开关、当前账号选择同步到 state / runtime message + - 只负责用共享规则决定当前文案、显隐和前端校验 + - 不应再次复制一套“provide / receive 对应什么行为”的业务判断 + +- 共享规则层: + - `managed-alias-utils.js` + - 负责 `mail2925Mode` 归一化 + - 负责判断 `2925` 当前是否属于“别名邮箱 provider” + - 负责保证 `2925` 只有在 `provide` 模式下才进入共享别名邮箱链路 + - 如果未来要新增第三种模式,应该先改这里,再改 sidepanel / background 接线 + +- 注册邮箱生成层: + - `background/generated-email-helpers.js` + - 只负责根据当前 provider / mode 选择“共享别名邮箱”还是“普通邮箱生成器” + - 不负责定义 `provide / receive` 的语义本身 + - `background/signup-flow-helpers.js` + - 只负责真正提交前的“复用已有邮箱 / 重新生成邮箱” + - 这里看到的 `isGeneratedAliasProvider(state)` 已经包含 `mail2925Mode` 语义,不应该再手写 `state.mail2925Mode === 'provide'` + +- 收信与验证码层: + - `background/verification-flow.js` + - 负责决定是否给 2925 内容脚本下发 `mail2925MatchTargetEmail` + - 当前约定:仅 `receive` 模式开启弱目标邮箱匹配 + - `content/mail-2925.js` + - 负责真正执行“弱目标邮箱匹配” + - 当前约定:只有邮件里显式出现了其他邮箱才跳过;若邮件里没有写邮箱,仍允许继续尝试 + - 这样做的目的,是在不破坏历史兼容性的前提下,降低 receive 模式误收验证码的概率 + +- 账号池与登录态层: + - `background/mail-2925-session.js` + - 不关心 `provide / receive` 哪个负责生成注册邮箱 + - 只关心当前是否允许自动登录、是否需要切号、是否命中上限、是否需要停止自动流程 + - 因此后续如果只改别名生成语义,不应把这层重新卷入 provider 判定 + +后续如果再改 `2925`,建议最少按下面顺序自检: + +1. `managed-alias-utils.js` 是否仍是 `provide / receive` 的唯一共享语义来源 +2. `sidepanel/sidepanel.js` 是否只做接线,没有复制业务规则 +3. `background/generated-email-helpers.js` / `background/signup-flow-helpers.js` 是否仍然只做调度,不重复写模式语义 +4. `background/verification-flow.js` 与 `content/mail-2925.js` 的“弱目标邮箱匹配”是否保持同步 +5. `项目文件结构说明.md` 与当前文件是否已同步更新 + ### 7.5 iCloud 组成: diff --git a/项目开发规范(AI协作).md b/项目开发规范(AI协作).md index 5b99d0e..8b7ef6a 100644 --- a/项目开发规范(AI协作).md +++ b/项目开发规范(AI协作).md @@ -93,10 +93,12 @@ 当前约定: - Gmail / 2925 的基邮箱解析、兼容性判断、别名生成、UI 文案优先收敛到 `managed-alias-utils.js` +- `2925` 是否参与“共享别名邮箱链路”必须由共享层统一判断;当前只有 `mail2925Mode = provide` 才允许把 `2925` 视为别名邮箱 provider,`receive` 不能在 sidepanel / step / provider 分支里各自偷写一套判断 - `background/generated-email-helpers.js` 只负责调度,不应再次复制 Gmail / 2925 规则 - `background/signup-flow-helpers.js` 只负责“复用已有邮箱还是重新生成”的流程决策 - `sidepanel/sidepanel.js` 只负责 UI 接线、校验触发和状态同步 - Hotmail / 2925 账号池这类跨 provider 的 sidepanel 表单显隐、头部按钮文案切换与共用操作行,应优先收敛到共享 UI helper(当前为 `sidepanel/account-pool-ui.js`),不要在各自 manager 中复制一套近似状态机 +- 如果 `2925` 的某个运行态模式会让“别名基邮箱”和“账号池 / 当前账号选择”出现不同显隐规则,必须优先拆行或拆成独立配置块,不能把账号池开关绑死在别名基邮箱那一行里 ### 3.3 新增配置项