test: document IP proxy integration and harden sidepanel restore

项目完整链路说明.md

@@ -145,6 +145,7 @@
 - localhost 回调地址
 - 自动运行轮次信息
 - 当前自动运行 session 标识 `autoRunSessionId`
+- IP 代理运行态：`ipProxyApiPool / ipProxyAccountPool / ipProxyCurrent / ipProxyApplied*`，用于记录当前代理池、当前代理节点、PAC 接管结果、出口检测结果和诊断信息
 - 标签注册表
 - 最近打开的来源地址
 - LuckMail 当前运行时选择
@@ -160,6 +161,7 @@
 
 - CPA / SUB2API 配置
 - Codex2API 配置
+- IP 代理持久配置：`ipProxyEnabled`、服务商、模式、API 地址、服务商配置快照、账号列表、固定 Host / Port / Protocol / Username / Password、地区参数、session 与自动切换阈值
 - Plus 模式开关 `plusModeEnabled`
 - PayPal 登录配置 `paypalEmail / paypalPassword`
 - 邮箱 provider 配置
@@ -195,6 +197,8 @@
 - `ICLOUD_LOGIN_REQUIRED`
 - `ICLOUD_ALIASES_CHANGED`
 
+IP 代理模块在同步、切换、Change、出口探测和自动运行成功阈值切换后，会通过 `DATA_UPDATED` 广播 `ipProxyApplied*` 与当前代理池字段，sidepanel 只根据广播更新状态卡，不在 UI 层重新推断后台代理结果。
+
 ### 4.4 贡献模式链路
 
 贡献模式的目标不是新增一个 provider，而是在 sidepanel 内开启一套“贡献账号”专用 UI，并把公开贡献服务并进原有 10 步主链：
@@ -764,6 +768,42 @@ Hide My Email 获取与管理链路：
 - iCloud 登录态提示必须区分“真实未登录”和“已登录但请求上下文波动”；不能把所有 401 / 403 / 421 都直接提示为未登录。
 - iCloud 别名缓存只用于短暂失败回退，不应改变最终的已用 / 保留状态来源；状态仍以 `manualAliasUsage`、`preservedAliases` 与最新线上列表合并后的结果为准。
 
+### 7.7 IP Proxy
+
+组成：
+
+- [background/ip-proxy-core.js](c:/Users/projectf/Downloads/codex注册扩展/background/ip-proxy-core.js)
+- [background/ip-proxy-provider-711proxy.js](c:/Users/projectf/Downloads/codex注册扩展/background/ip-proxy-provider-711proxy.js)
+- [sidepanel/ip-proxy-panel.js](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/ip-proxy-panel.js)
+- [sidepanel/ip-proxy-provider-711proxy.js](c:/Users/projectf/Downloads/codex注册扩展/sidepanel/ip-proxy-provider-711proxy.js)
+- [docs/ip-proxy-module.md](c:/Users/projectf/Downloads/codex注册扩展/docs/ip-proxy-module.md)
+
+职责边界：
+
+- `background/ip-proxy-core.js` 负责代理条目解析、运行态代理池、PAC 应用与清除、`webRequest.onAuthRequired` 代理鉴权回填、出口探测和失败时的目标站点 fail-close 规则。
+- `background/ip-proxy-provider-711proxy.js` 只承接 711Proxy 的账号串参数规则，负责把 `region / session / sessTime` 叠加到最终用户名。
+- `background/message-router.js` 只暴露 `REFRESH_IP_PROXY_POOL / SWITCH_IP_PROXY / CHANGE_IP_PROXY_EXIT / PROBE_IP_PROXY_EXIT` 消息，不在路由层复制代理解析逻辑。
+- `sidepanel/ip-proxy-panel.js` 负责 UI 状态渲染、表单快照、按钮动作和 711 参数输入联动；`sidepanel/sidepanel.js` 只保留配置保存、事件绑定和广播接线。
+
+基础链路：
+
+1. 用户在 sidepanel 打开 `IP代理`，选择服务和账号模式。
+2. 首版只开放 `711proxy + account` 主路径；API 模式和账号列表入口保留但默认禁用。
+3. 用户填写固定账号的 Host / Port / Protocol / Username / Password，可选填写地区、session 和时长。
+4. 点击 `同步` 后，sidepanel 发送 `REFRESH_IP_PROXY_POOL`，后台解析当前账号为代理池并调用 `chrome.proxy.settings.set` 写入 PAC。
+5. 如果代理需要账号密码，后台通过 `webRequest.onAuthRequired` 对代理 407 challenge 回填用户名和密码。
+6. PAC 成功应用后，后台关闭 fail-close 规则；如果配置缺失、应用失败或出口探测失败，则开启只覆盖 OpenAI / ChatGPT 目标域的阻断规则，避免误以为已经走代理。
+7. `检测出口` 会优先用页面上下文探测公网 IP，再用后台请求兜底，并把出口 IP、地区、探测来源和诊断摘要写回运行态。
+8. `下一条` 根据当前代理池 index 切换节点；`Change` 在 711 session 场景下强制重绑代理链路，用于刷新出口。
+9. 自动运行成功轮数命中 `ipProxyPoolTargetCount` 时，后台会尝试自动切到下一条代理；只有代理候选数量大于 1 时才执行切换。
+
+维护约定：
+
+- 代理解析、PAC、鉴权和出口检测必须留在后台模块，不应继续堆进 `background.js`。
+- UI 层不能凭输入值直接判断“代理已接管”，只能展示后台返回的 `ipProxyApplied*` 状态。
+- 新增代理服务商时，应优先新增 provider 规则模块，并让共享解析/运行态继续走 `background/ip-proxy-core.js`。
+- 修改代理字段、权限或链路时，需要同步更新 [docs/ip-proxy-module.md](c:/Users/projectf/Downloads/codex注册扩展/docs/ip-proxy-module.md)、当前完整链路说明和结构说明。
+
 ## 8. 自动运行完整链路
 
 文件：
@@ -794,7 +834,8 @@ Hide My Email 获取与管理链路：
    - 手动停止与自动停止会写入“停止”状态（若后续同邮箱成功/失败，会被覆盖为最新状态）
 8. 如果配置了线程间隔，则挂计时计划；计时计划会带上当前 `autoRunSessionId`
 9. 旧 timer / 旧 alarm / 旧恢复入口只有在 session 仍有效时才允许恢复执行；Stop 会立即使当前 session 失效，防止“停止后旧倒计时又把流程重新拉起”
-10. 所有轮次结束后输出汇总，并清空当前 session 标识
+10. 如果启用 IP 代理，后台会在每轮成功后按 `ipProxyPoolTargetCount` 检查是否需要切换出口；候选代理不足时只记录日志并跳过切换
+11. 所有轮次结束后输出汇总，并清空当前 session 标识
 
 ## 9. 新增功能时最容易漏掉的地方