# 本地自定义功能维护说明

> 目的：记录本仓库相对上游 `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` 忽略规则。

推荐每次同步后执行：

```bash
git diff --check
npm test
```

## 本地定制提交栈

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

```text
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 登录使用全新标签页
```

排查本地定制范围可用：

```bash
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. 合并后至少跑：

```bash
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` 之前加载：

```html
<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` 和上游新增脚本。

### 验证

```bash
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`

### 维护注意

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

## 后续同步上游的建议流程

```bash
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. 合并后执行完整测试：

```bash
npm test
```

## 快速检查命令

检查日本地址能力：

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

检查自定义邮箱池能力：

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

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

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

检查 SUB2API 多分组：

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