FlowPilot/docs/local-customizations-maintenance.md

本地自定义功能维护说明

目的：记录本仓库相对上游 upstream/master 需要长期保留的定制能力、关键代码位置和后续同步上游时的检查点。

最近一次整理基线：upstream/master Ultra2.0（87fc333）已合入到本地同步分支 sync/upstream-ultra20-20260428，合并提交为 413057b。

快速结论

后续同步上游时，需要优先保留以下本地功能：

1. Plus checkout 日本账单资料匹配与本地化地址填写。
2. 自定义邮箱池/账号池表格管理能力。
3. Hotmail / 2925 账号池搜索筛选。
4. Plus 免费试用资格提前判断，以及跳过账号仍标记“已用”。
5. SUB2API 多分组创建账号。
6. OAuth 登录使用全新标签页。
7. 本地导出配置 /config.json 忽略规则。

推荐每次同步后执行：

git diff --check
npm test

本地定制提交栈

在 Ultra2.0 合并后，本地相对 upstream/master 仍保留的定制提交主要是：

3cf5f22 feat: upgrade custom email pool with manager UI and entry states
8d850be chore: 忽略本地导出配置
4d20160 fix(accounts): 统一流程完成后的账号标记
c52f505 fix(plus): 增强 checkout 免费试用校验
cc7671e feat(sub2api): 支持多分组创建账号
9f2c3eb feat(sidepanel): 添加账号池搜索筛选
b3790c1 fix(auth): OAuth 登录使用全新标签页

排查本地定制范围可用：

git diff --stat upstream/master..HEAD
git diff --name-only upstream/master..HEAD
git log --oneline --reverse --no-merges upstream/master..HEAD

1. Plus checkout 日本资料匹配

目标

Plus checkout 填账单资料时，支持日本地区：

• 国家/地区选项可匹配 JP、Japan、日本、日本国。
• 日本地址可走本地化接口路径 /jp-address。
• 能识别日文表单标签，例如 郵便番号、都道府県。
• 地区匹配支持 東京都 与 Tokyo 这类本地化/英文混合值。

关键文件

文件	作用
data/address-sources.js	国家别名和本地 fallback 地址种子，包含 JP。
background/steps/fill-plus-checkout.js	Plus checkout 后台步骤，COUNTRY_ENDPOINTS.JP 指向 /jp-address。
content/plus-checkout.js	checkout 页面内容脚本，负责国家、地区、地址字段定位和填写。
tests/address-sources.test.js	国家码与地址 seed 单测。
tests/plus-checkout-address-input.test.js	地址字段、国家、地区匹配单测。
tests/plus-checkout-billing-tab-resolution.test.js	billing tab 和地址 seed 传递单测。

关键代码点

• data/address-sources.js
  • COUNTRY_ALIASES.JP
  • LOCAL_ADDRESS_SEEDS.JP
• background/steps/fill-plus-checkout.js
  • COUNTRY_ENDPOINTS.JP
• content/plus-checkout.js
  • COUNTRY_OPTION_ALIASES.JP
  • matchesCountryOption(...)
  • matchesRegionOption(...)
  • 地址字段识别正则里对 都道府県、郵便番号 的支持。

维护注意

1. 上游如果重写 checkout 地址填写逻辑，不要只保留英文 country/state/zip 匹配，必须继续保留日文字段识别。
2. 上游如果调整地址接口配置，确认 JP 仍指向 /jp-address 或新的等效路径。
3. 合并后至少跑：

node --test \
  tests/address-sources.test.js \
  tests/plus-checkout-address-input.test.js \
  tests/plus-checkout-billing-tab-resolution.test.js

2. 自定义邮箱池 / 账号池表格

目标

支持导入一批自定义注册邮箱，并在侧边栏以表格/列表方式管理：

• 导入邮箱。
• 搜索邮箱。
• 按状态筛选。
• 批量标记已用/未用。
• 批量启用/停用。
• 批量删除。
• 自动运行时按轮次取邮箱。
• 成功、跳过或完成后标记当前邮箱为“已用”。

关键文件

文件	作用
background.js	状态结构、邮箱池规范化、取当前轮邮箱、标记已用。
background/message-router.js	步骤完成/Plus 完成时调用标记已用逻辑。
sidepanel/sidepanel.html	自定义邮箱池 UI 区域和脚本加载。
sidepanel/sidepanel.js	侧边栏状态收集、DOM 绑定、manager 初始化。
sidepanel/custom-email-pool-manager.js	自定义邮箱池表格/列表管理器。
sidepanel/sidepanel.css	表格、搜索、筛选和批量操作样式。
tests/background-custom-email-pool.test.js	后台邮箱池逻辑测试。
tests/sidepanel-custom-email-pool.test.js	侧边栏脚本加载/基础 UI 测试。

关键代码点

后台：

• background.js
  • customEmailPool
  • customEmailPoolEntries
  • normalizeCustomEmailPoolEntryObjects(...)
  • getCustomEmailPool(...)
  • getCustomEmailPoolEntries(...)
  • getCustomEmailPoolEmailForRun(...)
  • markCurrentCustomEmailPoolEntryUsed(...)
  • markCurrentRegistrationAccountUsed(...)
• background/message-router.js
  • step 完成和 Plus 完成路径里需要能调用 markCurrentRegistrationAccountUsed(...)。
  • fallback 兼容路径仍需保留 markCurrentCustomEmailPoolEntryUsed(...)。

侧边栏：

• sidepanel/sidepanel.html
  • row-custom-email-pool
  • input-custom-email-pool
  • input-custom-email-pool-import
  • input-custom-email-pool-search
  • select-custom-email-pool-filter
  • checkbox-custom-email-pool-select-all
  • btn-custom-email-pool-bulk-used
  • btn-custom-email-pool-bulk-unused
  • btn-custom-email-pool-bulk-enable
  • btn-custom-email-pool-bulk-disable
  • btn-custom-email-pool-bulk-delete
  • custom-email-pool-list
• sidepanel/custom-email-pool-manager.js
  • createCustomEmailPoolManager(...)
  • 内部维护 selectedEntryIds、搜索词和筛选状态。
• sidepanel/sidepanel.js
  • 读取并传入上述 DOM 节点。
  • 初始化 window.SidepanelCustomEmailPoolManager?.createCustomEmailPoolManager(...)。

同步上游时的高风险点

上游经常改侧边栏脚本加载顺序。合并时必须确认这些脚本都还在，并且在 sidepanel.js 之前加载：

<script src="custom-email-pool-manager.js"></script>
<script src="ip-proxy-provider-711proxy.js"></script>
<script src="ip-proxy-panel.js"></script>
<script src="sidepanel.js"></script>

如果上游新增脚本，例如 IP 代理面板，不要用“二选一”的方式解决冲突；应该同时保留本地 custom-email-pool-manager.js 和上游新增脚本。

验证

node --test \
  tests/background-custom-email-pool.test.js \
  tests/sidepanel-custom-email-pool.test.js \
  tests/background-registration-account-used.test.js

3. Hotmail / 2925 账号池搜索筛选

目标

账号池表格支持搜索和按状态筛选，便于维护大量账号。

关键文件

文件	作用
sidepanel/sidepanel.html	Hotmail / 2925 搜索框和筛选下拉框。
sidepanel/sidepanel.js	DOM 节点绑定并传入 manager。
sidepanel/hotmail-manager.js	Hotmail 搜索、筛选、渲染。
sidepanel/mail-2925-manager.js	2925 搜索、筛选、渲染。
sidepanel/sidepanel.css	搜索框/筛选框样式。

关键 DOM

• Hotmail：
  • input-hotmail-search
  • select-hotmail-filter
• 2925：
  • input-mail2925-search
  • select-mail2925-filter

维护注意

上游如果重构账号池 UI，确认 manager 里这些事件仍存在：

• dom.inputHotmailSearch?.addEventListener('input', ...)
• dom.selectHotmailFilter?.addEventListener('change', ...)
• dom.inputMail2925Search?.addEventListener('input', ...)
• dom.selectMail2925Filter?.addEventListener('change', ...)

4. Plus 免费试用资格提前判断和账号标记

目标

Plus checkout 页面加载后尽早判断是否有免费试用资格：

• 如果“今日应付金额”不是 0，直接跳过 PayPal 填写/提交。
• 被跳过的账号也要标记为“已用”，避免下次重复拿到。
• 提交前再检查一次金额，防止页面中途变化。

关键文件

文件	作用
background/steps/fill-plus-checkout.js	Plus 第 7 步提前检查金额并抛出非重试 sentinel。
content/plus-checkout.js	checkout 页面读取 checkoutAmountSummary。
background.js	isPlusCheckoutNonFreeTrialError(...) 和账号标记统一入口。
background/message-router.js	Plus 完成或跳过路径统一标记账号已用。
tests/plus-checkout-billing-tab-resolution.test.js	非免费试用跳过逻辑测试。
tests/background-registration-account-used.test.js	账号标记使用 fresh state 的测试。
tests/background-luckmail.test.js	LuckMail Plus 完成后标记测试。

关键代码点

• background/steps/fill-plus-checkout.js
  • inspectCheckoutAmountSummary(...)
  • PLUS_CHECKOUT_NON_FREE_TRIAL::...
  • 调用 markCurrentRegistrationAccountUsed(...)
• content/plus-checkout.js
  • getCheckoutAmountSummary(...)
  • 返回 checkoutAmountSummary
• background.js
  • markCurrentRegistrationAccountUsed(...)
  • isPlusCheckoutNonFreeTrialError(...)

维护注意

1. 不要把免费资格判断放到地址/PayPal 填写之后。
2. 不要把 PLUS_CHECKOUT_NON_FREE_TRIAL:: 当作普通可重试错误。
3. 标记账号已用时要读取 fresh state，避免 step 局部传入的 state 过期。

5. SUB2API 多分组创建账号

目标

支持一次配置多个 SUB2API 分组，完成 OAuth 后为多个分组创建账号。

关键文件

文件	作用
content/sub2api-panel.js	多分组解析、查询和创建账号。
sidepanel/sidepanel.html	分组输入框提示支持多个分组。
background.js / background/message-router.js	payload 透传。
background/steps/platform-verify.js	Plus platform verify 兼容。
tests/sub2api-panel-proxy.test.js	SUB2API 代理与多分组测试。

关键代码点

• content/sub2api-panel.js
  • normalizeSub2ApiGroupNames(...)
  • getGroupsByNames(...)
  • sub2apiGroupIds
• sidepanel/sidepanel.html
  • input-sub2api-group
  • placeholder：默认 codex；多个用逗号或换行分隔

维护注意

上游如果只按单个 sub2apiGroupId 写回，需要保留本地 sub2apiGroupIds 数组逻辑。

6. OAuth 登录使用全新标签页

目标

OAuth 登录流程打开新标签页，避免复用旧页面导致状态污染。

关键文件

文件	作用
background/steps/oauth-login.js	OAuth 登录步骤入口。
background/tab-runtime.js	新标签打开和导航等待能力。

维护注意

上游如果改 OAuth tab 打开方式，确认仍保留“全新标签页”语义，不要退回到复用已有 tab。

7. 本地配置文件忽略

目标

避免本地导出的运行配置误提交。

关键文件

• .gitignore
  • /config.json

维护注意

如果后续出现新的本地导出文件，先确认是否应该忽略，不要直接提交。

后续同步上游的建议流程

git status --short --branch
git fetch --prune upstream
git switch -c sync/upstream-YYYYMMDD
git merge --no-ff upstream/master

冲突处理优先级：

1. 同时保留上游新增能力和本地定制能力。
2. background.js / background/message-router.js 里不要丢失：
   • markCurrentRegistrationAccountUsed
   • markCurrentCustomEmailPoolEntryUsed
   • 上游新增的 refreshIpProxyPool 等能力。
3. sidepanel/sidepanel.html 脚本冲突时不要二选一：
   • 保留 custom-email-pool-manager.js
   • 保留上游新增脚本。
4. content/plus-checkout.js 冲突时重点检查：
   • 日本国家/地区匹配。
   • checkout amount summary。
   • 地址字段定位正则。
5. 合并后执行完整测试：

npm test

快速检查命令

检查日本地址能力：

rg -n "JP:|日本|jp-address|matchesCountryOption|matchesRegionOption|郵便番号|都道府県" \
  data/address-sources.js \
  background/steps/fill-plus-checkout.js \
  content/plus-checkout.js \
  tests

检查自定义邮箱池能力：

rg -n "customEmailPool|custom-email-pool|markCurrentCustomEmailPoolEntryUsed|createCustomEmailPoolManager" \
  background.js \
  background/message-router.js \
  sidepanel \
  tests

检查 Plus 免费资格提前跳过：

rg -n "PLUS_CHECKOUT_NON_FREE_TRIAL|checkoutAmountSummary|inspectCheckoutAmountSummary|markCurrentRegistrationAccountUsed" \
  background \
  content \
  tests

检查 SUB2API 多分组：

rg -n "normalizeSub2ApiGroupNames|getGroupsByNames|sub2apiGroupIds|input-sub2api-group" \
  content/sub2api-panel.js \
  sidepanel/sidepanel.html \
  tests