249 lines
8.2 KiB
Markdown
249 lines
8.2 KiB
Markdown
# 多注册流程状态迁移设计
|
||
|
||
本文是 `docs/多注册流程架构边界.md` 的落地补充，专门解决“现有扁平状态怎么迁到多 flow 架构”这个最容易把旧逻辑拖垮的问题。
|
||
|
||
## 1. 先说结论
|
||
|
||
当前项目不能直接在 `DEFAULT_STATE` 上继续堆字段。要支持多个完全不同的注册流程，必须先把“运行态”“持久配置”“共享服务状态”“flow 私有状态”分层，再保留一层 OpenAI 旧步骤兼容视图。
|
||
|
||
这次迁移的目标不是一步把全部字段搬完，而是先建立新的状态主模型，让旧代码通过 adapter 继续运行。
|
||
|
||
## 2. 当前源码里的真实问题
|
||
|
||
### 2.1 `DEFAULT_STATE` 仍然是单流程扁平模型
|
||
|
||
`background.js` 里的 `DEFAULT_STATE` 目前把这些不同层次的状态混在一起：
|
||
|
||
- 流程进度：`currentStep`、`stepStatuses`
|
||
- 通用运行态：`automationWindowId`、`tabRegistry`、`logs`
|
||
- OpenAI OAuth / 平台回调：`oauthUrl`、`localhostUrl`、`sub2apiSessionId`、`codex2apiSessionId`
|
||
- OpenAI Plus：`plusCheckoutTabId`、`plusCheckoutUrl`、`plusBillingAddress`
|
||
- OpenAI 接码：`currentPhoneActivation`、`signupPhoneActivation`、`reusablePhoneActivation`
|
||
- OpenAI LuckMail：`currentLuckmailPurchase`
|
||
- 共享邮箱运行态：`registrationEmailState`
|
||
|
||
这会带来两个直接后果：
|
||
|
||
1. 新 flow 一接进来，就只能继续往全局 state 加字段。
|
||
2. 任何 reset / retry / stop 都容易误清理别的业务域状态。
|
||
|
||
### 2.2 旧步骤数字模型已经渗透到多个模块
|
||
|
||
当前不只是 `background.js` 依赖 `currentStep / stepStatuses`，下列模块也在按“Step 1~13”理解流程：
|
||
|
||
- `background/auto-run-controller.js`
|
||
- `background/logging-status.js`
|
||
- `background/account-run-history.js`
|
||
|
||
所以新状态模型不能只改 `background.js`，必须给自动运行、日志、账号记录保留兼容出口。
|
||
|
||
### 2.3 `registrationEmailState` 名字看起来通用，内部却仍带 OpenAI 身份假设
|
||
|
||
`background/registration-email-state.js` 已经把邮箱运行态单独抽出来了，这是好事；但它的 `preserveAccountIdentity` 现在默认保留的是“手机号身份”，也就是：
|
||
|
||
- `accountIdentifierType = phone`
|
||
- `signupPhoneNumber`
|
||
- `signupPhoneActivation`
|
||
- `signupPhoneCompletedActivation`
|
||
|
||
这对 OpenAI 的 `add-email` 分支是对的，但对未来可能出现的“用户名主身份”“邀请码主身份”“钱包地址主身份”并不通用。
|
||
|
||
## 3. 目标状态分层
|
||
|
||
建议先建立“概念上的标准状态模型”，物理存储可以分阶段迁移。
|
||
|
||
```js
|
||
chrome.storage.session.runtimeState = {
|
||
activeFlowId: 'openai',
|
||
activeRunId: 'run_20260512_xxx',
|
||
currentNodeId: 'submit-signup-email',
|
||
nodeStatuses: {
|
||
'open-chatgpt': 'completed',
|
||
'submit-signup-email': 'running',
|
||
},
|
||
|
||
shared: {
|
||
automationWindowId: 123,
|
||
tabRegistry: {},
|
||
sourceLastUrls: {},
|
||
logs: [],
|
||
autoRun: {},
|
||
accountArtifacts: {},
|
||
},
|
||
|
||
services: {
|
||
mail: {},
|
||
proxy: {},
|
||
accountPools: {},
|
||
},
|
||
|
||
flows: {
|
||
openai: {
|
||
auth: {},
|
||
platformBinding: {},
|
||
plus: {},
|
||
phoneVerification: {},
|
||
luckmail: {},
|
||
identity: {},
|
||
},
|
||
},
|
||
|
||
legacyStepCompat: {
|
||
currentStep: 2,
|
||
stepStatuses: { 1: 'completed', 2: 'running' },
|
||
},
|
||
};
|
||
|
||
chrome.storage.local.settings = {
|
||
schemaVersion: 2,
|
||
|
||
shared: {
|
||
autoRunDefaults: {},
|
||
logging: {},
|
||
},
|
||
|
||
services: {
|
||
mailProviders: {},
|
||
ipProxy: {},
|
||
hotmailPool: {},
|
||
mail2925Pool: {},
|
||
icloud: {},
|
||
customEmailPool: {},
|
||
},
|
||
|
||
flows: {
|
||
openai: {
|
||
signupMethod: 'email',
|
||
phoneVerificationEnabled: false,
|
||
plusModeEnabled: false,
|
||
plusPaymentMethod: 'paypal',
|
||
sub2api: {},
|
||
codex2api: {},
|
||
luckmail: {},
|
||
smsProviders: {},
|
||
},
|
||
},
|
||
};
|
||
```
|
||
|
||
## 4. 四层状态边界
|
||
|
||
### 4.1 共享运行态 `runtimeState.shared`
|
||
|
||
只放“运行任何 flow 都需要”的内容：
|
||
|
||
- `activeFlowId / activeRunId / currentNodeId / nodeStatuses`
|
||
- `automationWindowId`
|
||
- `tabRegistry`
|
||
- `sourceLastUrls`
|
||
- `logs`
|
||
- 自动运行轮次、暂停、计时器计划
|
||
- 账号产物总览，如最终身份、最终邮箱、最终手机号、完成时间
|
||
|
||
这里不要再放 OpenAI 特有概念，例如 `plusCheckoutTabId`、`currentPhoneActivation`。
|
||
|
||
### 4.2 共享服务状态 `runtimeState.services`
|
||
|
||
放“可被多个 flow 复用的服务运行态”，而不是具体网站流程状态：
|
||
|
||
- 邮箱 provider 当前会话
|
||
- 2925 / Hotmail / iCloud / Cloud Mail 等共享邮箱服务上下文
|
||
- IP 代理当前应用结果、探测结果、池游标
|
||
- 可复用的共享账号池游标
|
||
|
||
注意：`LuckMail` 目前不进这一层，它仍属于 OpenAI flow 私有能力。
|
||
|
||
### 4.3 flow 私有运行态 `runtimeState.flows[flowId]`
|
||
|
||
每个 flow 自己保管自己的业务运行态。当前 OpenAI 至少应拆成：
|
||
|
||
- `auth`：`oauthUrl`、`localhostUrl`
|
||
- `platformBinding`：`sub2api*`、`codex2api*`
|
||
- `plus`：`plusCheckoutTabId`、`plusCheckoutUrl`、`plusBillingAddress`
|
||
- `phoneVerification`：`currentPhoneActivation`、`signupPhoneActivation`、`reusablePhoneActivation`
|
||
- `luckmail`：`currentLuckmailPurchase`、`currentLuckmailMailCursor`
|
||
- `identity`：OpenAI 特有的登录方式冻结结果、`step8VerificationTargetEmail` 等
|
||
|
||
### 4.4 持久配置 `settings`
|
||
|
||
持久配置必须按“共享 / 服务 / flow 私有”拆开，不再把所有配置都平铺到同一个 namespace。
|
||
|
||
特别注意：
|
||
|
||
- `signupMethod` 先保留在 `flows.openai`，不要急着抽成全局通用枚举。
|
||
- `plusModeEnabled`、`plusPaymentMethod`、`gopay*`、`paypal*` 都属于 OpenAI flow 私有配置。
|
||
- `phoneVerificationEnabled` 当前也属于 OpenAI flow 私有配置。
|
||
|
||
## 5. 旧步骤兼容层怎么做
|
||
|
||
迁移阶段仍要保留 `currentStep / stepStatuses`，但它们不再是主数据，只是 `legacyStepCompat` 的派生视图。
|
||
|
||
建议规则：
|
||
|
||
1. 新的 canonical 状态只写 `activeFlowId / currentNodeId / nodeStatuses`
|
||
2. OpenAI flow 通过 node-to-step 映射生成 `legacyStepCompat`
|
||
3. `getState()` 对旧模块仍返回：
|
||
- `currentStep`
|
||
- `stepStatuses`
|
||
- OpenAI 旧字段镜像
|
||
4. `setStepStatus(step, status)` 内部先更新 node，再回写 legacy step 视图
|
||
|
||
这样可以保证：
|
||
|
||
- `background/auto-run-controller.js` 先不重写也能跑
|
||
- `background/logging-status.js` 先不重写也能继续渲染
|
||
- `background/account-run-history.js` 仍能按旧语义落盘
|
||
|
||
## 6. 账号记录与自动运行的兼容策略
|
||
|
||
### 6.1 自动运行
|
||
|
||
`background/auto-run-controller.js` 当前按数字步骤推断进度、失败点和恢复点。迁移阶段要增加一层统一 selector：
|
||
|
||
- `getActiveRunProgress(state)`
|
||
- `getLegacyStepCompat(state)`
|
||
- `inferResumeNode(state, flowId)`
|
||
|
||
第一阶段可以继续让 OpenAI flow 通过旧 step 恢复；第二个 flow 接入时再真正改成 node-based resume。
|
||
|
||
### 6.2 账号记录
|
||
|
||
`background/account-run-history.js` 不能只记“失败在第几步”，还要开始记录：
|
||
|
||
- `activeFlowId`
|
||
- `activeRunId`
|
||
- `currentNodeId`
|
||
- `nodeStatuses` 摘要
|
||
- `legacyFailedStep`（仅 OpenAI 兼容）
|
||
|
||
否则未来多 flow 下，单看 `step7_failed` 已经没有意义。
|
||
|
||
## 7. 命名约束
|
||
|
||
仓库里已经存在别的 `flow_id` 语义，用在 GPC / GoPay 远端任务里。为了避免冲突：
|
||
|
||
- 扩展内部运行态统一使用 `activeFlowId`
|
||
- 当前轮标识统一使用 `activeRunId`
|
||
- 节点标识统一使用 `currentNodeId`
|
||
- 不新增裸字段 `flowId`
|
||
|
||
`flow_id` 只保留给外部接口 payload 兼容使用。
|
||
|
||
## 8. 第一阶段迁移顺序
|
||
|
||
1. 新增状态 selector / patch helper，不改业务步骤行为。
|
||
2. 给 OpenAI flow 建立 `flowState.openai` 命名空间，同时保留旧字段镜像。
|
||
3. 把日志、自动运行、账号记录改为优先读 selector，不直接拼 `stepStatuses`。
|
||
4. 把新加字段一律放进 `shared / services / flows.openai`，禁止继续向 `DEFAULT_STATE` 顶层加 OpenAI 字段。
|
||
5. 第二个 flow 接入前，再清理旧 step 镜像的写路径。
|
||
|
||
## 9. 本文对应解决的缺口
|
||
|
||
本文主要补齐以下缺口：
|
||
|
||
- `DEFAULT_STATE` 扁平模型没有命名空间
|
||
- 旧步骤状态与新 node 状态如何并存
|
||
- 自动运行 / 日志 / 账号记录如何不被状态迁移打断
|
||
- `registrationEmailState` 当前仍隐含“手机号是唯一可保留主身份”的假设
|
||
|