From 888d345db33bb05eb052c4bab419023250d88307 Mon Sep 17 00:00:00 2001 From: QLHazyCoder <2825305047@qq.com> Date: Sun, 26 Apr 2026 20:19:13 +0800 Subject: [PATCH] docs: align iCloud resilience PR documentation --- background.js | 12 ++++++------ 项目完整链路说明.md | 12 ++++++++++++ 项目开发规范（AI协作）.md | 7 +++++++ 项目文件结构说明.md | 1 + 4 files changed, 26 insertions(+), 6 deletions(-) diff --git a/background.js b/background.js index d37e583..96ce33c 100644 --- a/background.js +++ b/background.js @@ -4678,12 +4678,12 @@ async function fetchIcloudHideMyEmail(options = {}) { try { let generated = null; try { - generated = await icloudRequest('POST', `${activeServiceUrl}/v1/hme/generate`, { - timeoutMs: ICLOUD_REQUEST_TIMEOUT_MS, - maxAttempts: ICLOUD_WRITE_MAX_ATTEMPTS, - retryLabel: '生成 Hide My Email 地址', - logRetries: true, - }); + generated = await icloudRequest('POST', `${activeServiceUrl}/v1/hme/generate`, { + timeoutMs: ICLOUD_REQUEST_TIMEOUT_MS, + maxAttempts: ICLOUD_WRITE_MAX_ATTEMPTS, + retryLabel: '生成 Hide My Email 地址', + logRetries: true, + }); } catch (err) { if (!isIcloudRetryableError(err)) { throw err; diff --git a/项目完整链路说明.md b/项目完整链路说明.md index 27120f0..65ce224 100644 --- a/项目完整链路说明.md +++ b/项目完整链路说明.md @@ -170,6 +170,7 @@ - Cloudflare / Temp Email 设置 - 接码开关，以及 HeroSMS 的 API Key 与默认国家设置 - iCloud 相关偏好：Host、获取策略、成功后自动删除、目标邮箱类型与转发收码邮箱 provider +- iCloud Hide My Email 别名缓存：`icloudAliasCache` / `icloudAliasCacheAt`，用于在 iCloud 会话或网络上下文短暂波动时回退展示最近可用列表 - LuckMail API 配置 - 自动运行默认配置 - 账号运行历史 `accountRunHistory`（以邮箱为主键，保存该邮箱最近一次状态：成功/失败/停止） @@ -745,11 +746,22 @@ Plus 模式可见步骤： - `icloudTargetMailboxType = icloud-inbox` 时，Step 4 / Step 8 直接打开 iCloud Mail 收件箱轮询验证码。 - `icloudTargetMailboxType = forward-mailbox` 时，注册邮箱仍由 iCloud Hide My Email 生成，但 Step 4 / Step 8 改为打开 `icloudForwardMailProvider` 指定的转发目标邮箱收码；当前支持 `qq / 163 / 163-vip / 126 / gmail`。 +Hide My Email 获取与管理链路： + +1. 后台优先通过 `setup.icloud.com*/setup/ws/1/validate` 解析 `premiummailsettings.url`，并记录最近可用服务节点。 +2. 如果后台请求受 401 / 403 / 409 / 421 / 429 / 5xx、CORS、超时或地址空间限制影响，会优先尝试在已打开或自动创建的 `www.icloud.com*/mail/` 页面主上下文中重放请求。 +3. `maildomainws` 请求会补充 `clientBuildNumber / clientMasteringNumber / clientId / dsid` 查询参数，写请求使用 `text/plain;charset=UTF-8`，以兼容 iCloud 网页端接口。 +4. 别名列表加载成功后会缓存到 `icloudAliasCache`；遇到短暂上下文波动时，列表展示会按“最近缓存 -> 历史缓存 -> 本地已用/保留记录”回退。 +5. 生成新别名后若 `reserve` 返回鉴权或网络异常，会先回查列表确认候选别名是否已经创建；必要时刷新服务节点重试一次，最后才进入可复用别名回退或暂停等待用户处理。 +6. 自动运行获取 iCloud 别名时，检测到会话或网络上下文异常后会停止重复消耗获取重试次数，转入等待邮箱状态，避免连续请求放大 iCloud 风控或上下文抖动。 + 维护约定： - iCloud 转发目标邮箱 provider 的 label、URL、source、inject 配置统一由 `mail-provider-utils.js` 输出。 - `background.js` 只根据 `icloudTargetMailboxType` 选择 iCloud Mail 收件箱或共享转发邮箱配置，不再在主文件内硬编码各 provider 地址。 - `sidepanel/sidepanel.js` 只负责展示、保存和回显目标邮箱类型 / 转发邮箱 provider，不重复定义 provider 业务清单。 +- iCloud 登录态提示必须区分“真实未登录”和“已登录但请求上下文波动”；不能把所有 401 / 403 / 421 都直接提示为未登录。 +- iCloud 别名缓存只用于短暂失败回退，不应改变最终的已用 / 保留状态来源；状态仍以 `manualAliasUsage`、`preservedAliases` 与最新线上列表合并后的结果为准。 ## 8. 自动运行完整链路 diff --git a/项目开发规范（AI协作）.md b/项目开发规范（AI协作）.md index 65f006c..4a09168 100644 --- a/项目开发规范（AI协作）.md +++ b/项目开发规范（AI协作）.md @@ -142,6 +142,13 @@ - 贡献模式的侧栏按钮、状态展示和轮询调度应优先收敛到独立 manager，例如 `sidepanel/contribution-mode.js` - 如果服务端当前返回“无需手动提交 callback”，扩展端必须把它当兼容成功态处理，不能简单按 HTTP 非 200 直接视为失败 +### 3.4.1 iCloud Hide My Email 维护补充 + +- iCloud Hide My Email 的会话校验、页面上下文回退、别名缓存回退和 `maildomainws` 兼容参数属于同一条链路；修改其中任一环时，必须同步检查列表加载、别名生成、保留、删除、自动运行等待邮箱和 sidepanel 登录提示。 +- iCloud 登录态判断不能只看单个 HTTP 状态码。`401 / 403 / 421 / 429 / 5xx` 可能来自后台请求上下文、CORS 或服务节点波动，必须结合错误文案、页面上下文回退结果和用户提示文案判断。 +- iCloud 别名缓存只能作为短暂失败回退，不允许替代线上列表成为最终状态来源；已用和保留状态仍然以 `manualAliasUsage`、`preservedAliases` 与最新线上列表合并后的结果为准。 +- 如果新增 iCloud 相关回退路径，必须补覆盖登录提示、缓存回退、自动运行停止重试和 reserve 异常恢复的测试，并同步更新 [项目完整链路说明.md](c:/Users/projectf/Downloads/codex注册扩展/项目完整链路说明.md)。 + ## 4. 测试规范 ### 4.1 原则 diff --git a/项目文件结构说明.md b/项目文件结构说明.md index 6122bdf..a22a481 100644 --- a/项目文件结构说明.md +++ b/项目文件结构说明.md @@ -174,6 +174,7 @@ - `tests/background-custom-email-pool.test.js`：测试后台对自定义邮箱池生成方式，以及自定义邮箱服务号池的归一化、标签文案和按轮次取邮箱逻辑。 - `tests/background-generated-email-module.test.js`：测试生成邮箱辅助模块已接入且导出工厂，并覆盖 2925 receive 模式回退普通邮箱生成、自定义邮箱池按轮次取值、2925 provide 模式账号池预热，以及 iCloud `always_new` 传参。 - `tests/background-icloud.test.js`：测试 iCloud 相关后台纯函数与别名收尾逻辑。 +- `tests/background-icloud-login-help.test.js`：测试 iCloud 登录判定、页面上下文回退、别名缓存回退和保留异常恢复的关键源码约束。 - `tests/background-icloud-mail-provider.test.js`：测试 iCloud 邮箱 provider 配置解析，并覆盖转发收码模式复用共享 provider 配置。 - `tests/background-logging-status-module.test.js`：测试日志 / 状态模块已接入且导出工厂。 - `tests/background-luckmail.test.js`：测试 LuckMail 相关后台逻辑，如购买、复用、标记已用与重置。