QLHazyCoder
125 lines
6.2 KiB
Markdown
125 lines
6.2 KiB
Markdown
# 多注册流程架构边界
|
||
|
||
本文记录后续从“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`
|
||
- `flows/openai/content/phone-auth.js`
|
||
- `flows/openai/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 逻辑上叠条件分支。
|