# 多注册流程架构边界

本文记录后续从“OpenAI 注册扩展”升级到“多注册流程扩展”时的模块边界。当前结论是：需要引入多 flow 架构，但不要把所有能力都提前抽成通用服务。

## 1. 总体判断

后续新增注册项目时，不应继续在现有 OpenAI 步骤里堆 `if site === ...`。不同网站的注册入口、验证码、资料页、风控页、回调页和成功判定都可能完全不同，应按独立 flow 处理。

目标形态：

```txt
core/
  flow-registry
  workflow-engine
  runtime-state
  tab-runtime
  logging
  account-artifacts
  email
  mail-code-polling
  network-proxy

flows/
  openai/
    workflow.js
    content-driver.js
    mail-rules.js
    network-profile.js
    phone-verification-flow.js
    phone-sms-providers/

  site-a/
    workflow.js
    content-driver.js
    mail-rules.js
    network-profile.js
```

第一阶段不需要立刻调整成上述目录，只需要按这个边界重构，避免新增项目继续污染 OpenAI 专用逻辑。

## 2. 必须通用化的部分

- `activeFlowId / runId / nodeId` 状态模型：替代只适合单流程的 `currentStep / stepStatuses`，同时避免与现有外部接口里的远端 `flow_id` 语义冲突。
- Workflow engine：负责节点执行、跳转、停止、恢复、重试和超时，不理解具体网站页面。
- Flow registry：负责注册 OpenAI、后续网站 A、网站 B 等独立流程。
- Tab runtime：标签页注册、自动化窗口锁定、脚本注入、消息超时、页面 ready 检查。
- Logging / status：结构化日志、节点状态、运行进度、停止和失败展示。
- Account artifact store：记录账号产物、身份、凭据、回调结果和失败信息。
- Email identity：邮箱生成、邮箱池、别名、转发收件目标等身份能力。
- Mail polling：邮件验证码、magic link、激活链接的轮询框架；具体过滤和提取规则由 flow 提供。
- IP proxy / network policy：代理应用、切换、出口检测、防泄漏；目标域名和探测 URL 由 flow 提供。
- Sidepanel dynamic renderer：按 flow capability 显示配置区、步骤列表和运行状态。
- Settings schema：通用配置与 flow 私有配置分层导入导出。
- Error taxonomy / recovery policy：通用层只处理执行框架错误，业务错误由 flow 自己分类。

## 3. 暂不通用化的部分

以下能力当前只属于 OpenAI flow，不进入 core：

- 手机接码：HeroSMS / 5sim / NexSMS、取号、复用、轮询、换号、释放、手机号注册和后置 add-phone。
- LuckMail：当前 `project_code = openai` 的购邮、复用、已用/保留/禁用管理。
- OpenAI / ChatGPT 页面 DOM 操作。
- OpenAI OAuth 授权、localhost callback、CPA / SUB2API / Codex2API 绑定。
- ChatGPT Plus、PayPal、GoPay、GPC 相关支付流程。
- OpenAI 的验证码邮件过滤规则、登录状态判断、add-phone fatal 判断。
- OpenAI 专属账号产物字段，如 Plus checkout、OAuth state、平台验证字段。

原因：当前除了 OpenAI，新项目暂不需要手机接码。过早把接码抽成通用服务会让新 flow 被迫理解手机号订单、短信平台、号码复用和页面 resend 细节，增加维护成本。

## 4. 手机接码边界

手机接码先保持为 OpenAI 专属能力。

当前这些模块在逻辑上归属 `flows/openai`，即使物理路径暂时还在旧目录：

- `background/phone-verification-flow.js`
- `phone-sms/providers/hero-sms.js`
- `phone-sms/providers/five-sim.js`
- `phone-sms/providers/registry.js`
- `content/phone-auth.js`
- `content/phone-country-utils.js`
- sidepanel 中的接码配置区
- 相关测试：`tests/phone-verification-flow.test.js`、`tests/five-sim-provider.test.js`、`tests/sidepanel-phone-verification-settings.test.js`

后续新增 flow 默认 `sms: false`，不显示接码配置，不加载接码步骤，也不要求 workflow engine 理解短信订单。

如果未来第二个真实 flow 也需要接码，再按事实抽象，优先抽 provider API，而不是直接抽完整手机号验证编排：

```js
flow.phoneVerification = {
  acquirePolicy,
  submitPhoneNumber,
  submitCode,
  classifyPhoneError,
  recoverAfterTimeout,
}
```

只有两个以上 flow 共享相同短信供应商生命周期时，才考虑把 `phone-sms/providers/*` 下沉到 `core/services/sms`。

## 5. 迁移顺序

1. 引入 `activeFlowId / runId / currentNodeId / nodeStatuses / flowContext`，先兼容 OpenAI 旧步骤。
2. 把邮箱、邮件轮询、代理、tab runtime、日志和账号记录逐步参数化，去掉 OpenAI 常量。
3. 建立 `flows/openai` 边界，把 OpenAI 步骤、content driver、OAuth、Plus 和接码逻辑收拢进去。
4. 用第二个真实注册项目验证 flow registry 和 workflow engine，而不是靠假想接口设计过度抽象。
5. 稳定后清理旧 `step` 数字兼容层。

## 6. 新 flow 接入原则

新增注册项目时，只允许新增该 flow 的 workflow、content driver、mail rules、network profile 和必要的私有配置。不要直接修改 OpenAI 步骤，也不要把 OpenAI 的手机号验证、OAuth、Plus 支付逻辑提升为通用能力。

通用层只负责“怎么运行一个 flow”，具体 flow 负责“这个网站怎么注册”。

## 7. 配套设计文档

本边界文档只回答“什么该进 core、什么暂时不要抽”。要真正开工，还需要同时遵守下面四份配套设计：

- `docs/多注册流程状态迁移设计.md`：解决 `DEFAULT_STATE` 扁平模型、旧 step 兼容、自动运行/日志/账号记录如何迁移。
- `docs/多注册流程来源与驱动注册设计.md`：解决 `signup-page`、source family、内容脚本注入和 localhost callback cleanup 的注册表设计。
- `docs/多注册流程邮件分层设计.md`：解决 provider driver 与 flow mail rules 的边界，以及 LuckMail 暂不通用化的问题。
- `docs/多注册流程侧边栏能力矩阵.md`：解决 sidepanel 展示层与业务约束层混在一起的问题。

后续新 flow 设计如果与这四份文档冲突，以“先修正文档边界，再动代码”为准，不允许直接在现有 OpenAI 逻辑上叠条件分支。