QLHazycoder
260 lines
6.4 KiB
Markdown
260 lines
6.4 KiB
Markdown
# 多注册流程侧边栏能力矩阵
|
||
|
||
> 历史说明：本文记录的是多 flow 侧边栏能力矩阵的早期设计背景。2026-05-19 起，账号贡献运行态已从历史 `contributionMode` 升级为 `accountContributionEnabled` + `contributionAdapterId`；后续开发请以 `多Flow资源入口与贡献体系升级开发方案.md` 和当前代码为准，不要继续新增或恢复 `contributionMode` 运行时逻辑。
|
||
|
||
本文解决的是一个很容易被低估的问题：sidepanel 现在不只是“渲染 UI”，它还承担了大量业务约束。如果未来要支持多个 flow，不能只做动态渲染，还必须把“哪些能力允许显示、允许切换、允许启动”做成统一能力矩阵。
|
||
|
||
## 1. 当前源码里的真实问题
|
||
|
||
当前手机号注册能力至少同时受这几组条件约束：
|
||
|
||
- `phoneVerificationEnabled`
|
||
- `plusModeEnabled`
|
||
- `contributionMode`
|
||
- `panelMode === 'cpa'` 时还会触发额外提醒
|
||
|
||
而这些约束现在分散在多个地方：
|
||
|
||
- `background.js`：`canUsePhoneSignup`
|
||
- `background/message-router.js`：同类判断
|
||
- `sidepanel/sidepanel.js`：`canSelectPhoneSignupMethod`
|
||
- `sidepanel/sidepanel.js`：`shouldWarnCpaPhoneSignup`
|
||
|
||
这说明 sidepanel 当前既在做展示，也在做策略判定，而且判定逻辑有重复。
|
||
|
||
## 2. 设计目标
|
||
|
||
后续 sidepanel 至少要拆成三层能力判断：
|
||
|
||
1. `flowCapabilities`
|
||
2. `panelCapabilities`
|
||
3. `runtimeLocks`
|
||
|
||
最终所有显示 / 禁用 / 启动校验都只读这三层组合结果。
|
||
|
||
## 3. 三层能力定义
|
||
|
||
### 3.1 `flowCapabilities`
|
||
|
||
表示“当前 flow 业务上支持什么”。
|
||
|
||
示例：
|
||
|
||
```js
|
||
flowCapabilities.openai = {
|
||
supportsEmailSignup: true,
|
||
supportsPhoneSignup: true,
|
||
supportsPhoneVerificationSettings: true,
|
||
supportsPlusMode: true,
|
||
supportsContributionMode: true,
|
||
supportsPlatformBinding: ['cpa', 'sub2api', 'codex2api'],
|
||
supportsLuckmail: true,
|
||
supportsOauthTimeoutBudget: true,
|
||
stepDefinitionMode: 'openai-dynamic',
|
||
};
|
||
|
||
flowCapabilities.siteA = {
|
||
supportsEmailSignup: true,
|
||
supportsPhoneSignup: false,
|
||
supportsPhoneVerificationSettings: false,
|
||
supportsPlusMode: false,
|
||
supportsContributionMode: false,
|
||
supportsPlatformBinding: ['siteA-panel'],
|
||
supportsLuckmail: false,
|
||
supportsOauthTimeoutBudget: false,
|
||
stepDefinitionMode: 'siteA',
|
||
};
|
||
```
|
||
|
||
原则：
|
||
|
||
- 没有真实需求，不要默认给新 flow 打开手机号、Plus、LuckMail
|
||
- 新 flow 默认从最小能力集合开始
|
||
|
||
### 3.2 `panelCapabilities`
|
||
|
||
表示“当前面板来源允许什么交互”。
|
||
|
||
示例：
|
||
|
||
```js
|
||
panelCapabilities = {
|
||
cpa: {
|
||
supportsPhoneSignup: true,
|
||
requiresPhoneSignupWarning: true,
|
||
},
|
||
sub2api: {
|
||
supportsPhoneSignup: true,
|
||
requiresPhoneSignupWarning: false,
|
||
},
|
||
codex2api: {
|
||
supportsPhoneSignup: true,
|
||
requiresPhoneSignupWarning: false,
|
||
},
|
||
};
|
||
```
|
||
|
||
注意：`contributionMode` 不是新的 `panelMode`，它是独立运行态锁。
|
||
|
||
### 3.3 `runtimeLocks`
|
||
|
||
表示“当前这一次运行或当前 UI 状态是否允许操作”。
|
||
|
||
示例：
|
||
|
||
```js
|
||
runtimeLocks = {
|
||
autoRunLocked: false,
|
||
contributionMode: false,
|
||
plusModeEnabled: false,
|
||
phoneVerificationEnabled: true,
|
||
settingsMenuLocked: false,
|
||
};
|
||
```
|
||
|
||
它决定的是：
|
||
|
||
- 现在能不能切换注册方式
|
||
- 能不能改 flow
|
||
- 能不能导入导出配置
|
||
- 能不能打开某些配置区
|
||
|
||
## 4. 统一选择器
|
||
|
||
建议提供一个中心 selector：
|
||
|
||
```js
|
||
resolveSidepanelCapabilities({
|
||
activeFlowId,
|
||
panelMode,
|
||
state,
|
||
});
|
||
```
|
||
|
||
输出：
|
||
|
||
```js
|
||
{
|
||
effectiveSignupMethods: ['email', 'phone'],
|
||
canShowPhoneSettings: true,
|
||
canSelectPhoneSignup: true,
|
||
shouldWarnCpaPhoneSignup: true,
|
||
canShowPlusSettings: true,
|
||
canShowLuckmail: true,
|
||
canExportSettings: true,
|
||
canSwitchFlow: false,
|
||
stepDefinitionOptions: {},
|
||
}
|
||
```
|
||
|
||
以后 sidepanel 与 background 都只消费这份结果，不再各写一套判断。
|
||
|
||
## 5. OpenAI 当前矩阵
|
||
|
||
### 5.1 仅看 flow 能力
|
||
|
||
OpenAI 当前业务上支持：
|
||
|
||
- 邮箱注册
|
||
- 手机号注册
|
||
- OAuth 登录
|
||
- 平台回调绑定
|
||
- Plus
|
||
- LuckMail
|
||
- 接码配置
|
||
|
||
### 5.2 加上 runtime lock 后的真实结果
|
||
|
||
OpenAI 的手机号注册只有在以下条件同时成立时才可选：
|
||
|
||
- `flowCapabilities.openai.supportsPhoneSignup === true`
|
||
- `phoneVerificationEnabled === true`
|
||
- `plusModeEnabled === false`
|
||
- `contributionMode === false`
|
||
|
||
也就是说，手机号注册不是一个“单纯 UI 开关”，而是能力矩阵结果。
|
||
|
||
### 5.3 加上 panel 约束后的额外行为
|
||
|
||
当满足手机号注册可用，且当前 `panelMode === 'cpa'` 时：
|
||
|
||
- 不阻止
|
||
- 但要提示风险
|
||
|
||
这类“允许但要提醒”的逻辑也必须归到能力矩阵里，而不是散落在点击事件中。
|
||
|
||
## 6. 步骤列表也属于能力矩阵的一部分
|
||
|
||
当前步骤定义主要受：
|
||
|
||
- `plusModeEnabled`
|
||
- `signupMethod`
|
||
|
||
影响，并通过 `data/step-definitions.js` 动态切换。
|
||
|
||
多 flow 后必须升级成：
|
||
|
||
```js
|
||
getStepDefinitions({
|
||
activeFlowId,
|
||
signupVariant,
|
||
panelMode,
|
||
plusModeEnabled,
|
||
contributionMode,
|
||
});
|
||
```
|
||
|
||
也就是说，步骤列表不再是全局 `10 步 / 13 步` 二选一，而是 flow-aware 的定义。
|
||
|
||
## 7. Sidepanel 分层职责
|
||
|
||
### 7.1 展示层
|
||
|
||
只负责：
|
||
|
||
- show / hide
|
||
- enabled / disabled
|
||
- 文案与提示
|
||
|
||
### 7.2 能力判定层
|
||
|
||
只负责：
|
||
|
||
- `resolveSidepanelCapabilities()`
|
||
- `validateAutoRunStart()`
|
||
- `validateModeSwitch()`
|
||
|
||
### 7.3 后台复核层
|
||
|
||
后台在收到启动、切换注册方式、切换 flow 等消息时，仍要复核一遍同一套能力判断，避免 sidepanel 以外的入口绕过约束。
|
||
|
||
## 8. 新 flow 的默认能力策略
|
||
|
||
后续新增 flow 时，默认按以下最小集合开始：
|
||
|
||
- 仅邮箱注册
|
||
- 无手机号注册
|
||
- 无 Plus
|
||
- 无 LuckMail
|
||
- 无贡献模式
|
||
- 无 OpenAI 平台回调面板
|
||
|
||
只有真实需求出现时，再逐项打开 capability。
|
||
|
||
## 9. 迁移顺序
|
||
|
||
1. 提炼 `flowCapabilitiesRegistry`
|
||
2. 提炼 `panelCapabilitiesRegistry`
|
||
3. 新增 `resolveSidepanelCapabilities()` 与 `validateAutoRunStart()`
|
||
4. 让 `sidepanel.js`、`background.js`、`message-router.js` 共用同一套 selector
|
||
5. 再把步骤定义切换也改成 flow-aware
|
||
|
||
## 10. 本文对应解决的缺口
|
||
|
||
本文主要补齐以下缺口：
|
||
|
||
- sidepanel 不只是渲染层，还承接业务约束
|
||
- 手机号注册能力由多个开关共同决定，当前逻辑分散且重复
|
||
- `contributionMode` 与 `panelMode` 容易混淆
|
||
- 多 flow 之后，步骤列表也必须纳入能力矩阵，而不是继续全局写死
|