fix: v2.3.1 Cloudflare OAuth scope 点号格式 + 授权失败可读提示 + 配置自检

- 根因:Cloudflare OAuth 的 scope 是点号分隔(account.read),冒号写法不被接受,
  授权端点直接返回 error=invalid_scope。默认 scope 改为
  account.read zone.read email_routing.write workers_scripts.write
- scope 可在设置页自定义(settings.cf_oauth_scopes),需与 App 登记值逐字一致
- 新增 GET /api/oauth/cloudflare/preflight + 设置页「检测授权配置」按钮:
  只读探测授权端点(不跟随跳转),区分 登录同意页 / 弹回回调 / Cloudflare /oauth/error,
  并把 invalid_scope、invalid_request 翻译成可执行的处置建议
- 回调端点处理 error 参数:不再拿空 code 去兑换 token,改为跳回账号页并弹窗说明原因
  (此前会落到 SPA 404 空壳页)
- 账号页读取 ?oauth_error= 弹窗展示 Cloudflare 的原始描述
- docs/02 补 Cloudflare OAuth App 配置清单(Redirect URL / Client URI 域名校验 /
  Promote to public / 点号 scope);83 个测试全通过

docs/02_CLOUDFLARE_OAUTH.md

@@ -47,3 +47,37 @@ Console
 —— 系统不提供任何模拟/降级通道,不会出现"看起来接入成功"的假账号与假资源。
 `GET /api/settings` 会返回 `cf_oauth.source`(settings / env / none)与 `redirect_uri`(需在
 Cloudflare Dashboard 登记的回调地址),`GET /api/oauth/mode` 返回 `source` 供账号页判断。
+
+## Cloudflare OAuth App 配置清单(docs 依据:Cloudflare "Create OAuth Client" API)
+
+在 <https://dash.cloudflare.com/profile/oauth-apps> 新建应用后,**必须**完成下面几项,否则授权端点
+会直接拒绝(此时 Console 收不到 code,只有 `error=invalid_scope` / `invalid_request`):
+
+| 字段 | 填什么 | 不对时的报错 |
+| --- | --- | --- |
+| Redirect URL(s) | `https://wmailhub.adx9.com/api/oauth/cloudflare/callback`(本地联调另加 `http://127.0.0.1:18787/api/oauth/cloudflare/callback`) | `invalid_request`: redirect_uri does not match |
+| **Client URI** | Console 站点首页,如 `https://wmailhub.adx9.com` | `promotion to public requires a verified client_uri host` |
+| 域名校验 | 按 Cloudflare 提示在 client_uri 域下加 TXT 记录(形如 `cloudflare_oauth_client_publisher=...`) | 同上,一直卡在 not verified |
+| Promote to public | 应用可见性从 private 提升为 public | 私有 App 不可被他人授权 |
+| Scopes | 与 Console「设置 → Cloudflare 接入」里的 scope 字段**逐字一致** | `invalid_scope`: Client is not allowed to request scope '...' |
+
+### scope 必须是点号分隔
+
+Cloudflare OAuth 的 scope 命名是 `account.read` 这种**点号**形式;冒号形式(`account:read`)不被接受,
+授权端点会判为 `invalid_scope`。默认请求的四个:
+
+```text
+account.read  zone.read  email_routing.write  workers_scripts.write
+```
+
+Console 允许在设置里改这个字段,以便与 App 中登记的值保持一致(`settings.cf_oauth_scopes`)。
+
+## 授权配置自检(不用开浏览器)
+
+`GET /api/oauth/cloudflare/preflight` 用当前配置请求一次 Cloudflare 授权端点但**不跟随跳转**,据跳转目标判定:
+
+- 跳到登录/同意页 → `ok: true`,配置可用;
+- 弹回我们的回调地址,或跳 `dash.cloudflare.com/oauth/error` → `ok: false` 并带回 `error` /
+  `error_description` 与一条处置建议。
+
+设置页「Cloudflare 接入」tab 的「检测授权配置」按钮就是调它。纯只读探测,不会产生任何授权。