多注册流程架构边界

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

1. 总体判断

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

目标形态：

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，而不是直接抽完整手机号验证编排：

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

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

5. 迁移顺序

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

6.1 KiB Raw Blame History Unescape Escape