156 lines
8.0 KiB
Markdown
156 lines
8.0 KiB
Markdown
# 用户公开注册与邮箱验证计划
|
||
|
||
**状态**：待实施
|
||
**创建日期**：2026-05-12
|
||
**核心目标**：给 Planet 增加公开注册流程 + 邮箱验证码 + 忘记密码，让客户无需管理员介入就能开通账号；同时把 SMTP 邮件作为可复用基础服务接入 `/settings`。
|
||
|
||
## 背景
|
||
|
||
当前认证只暴露 `/auth/login`、`/auth/refresh`、`/auth/logout`、`/auth/me`（`backend/app/api/v1/auth.py`），账号只能由 `super_admin` 在 `/users` 后台创建。User 模型 `backend/app/models/user.py` 没有 `email_verified` 字段，仓库也没有任何 SMTP/邮件发送基础设施。
|
||
|
||
客户旅程想从"打开浏览器→注册→验证→登录"开始走（见 [文档受众分层重构计划](/home/ray/dev/linkong/planet/docs/plans/docs-audience-split-plan.md)），就必须先把这条链路在代码里跑通。
|
||
|
||
注册策略（已确认）：
|
||
|
||
- 开放公开注册，任何人可在 `/register` 自助开通
|
||
- 默认角色 `viewer`
|
||
- 邮箱验证后立即可登录（无需管理员审批）
|
||
- 验证仅走 SMTP 邮件，6 位数字码，10 分钟 TTL
|
||
|
||
## 数据模型
|
||
|
||
`backend/app/models/user.py` 加两列：
|
||
|
||
```python
|
||
email_verified = Column(Boolean, default=False, nullable=False)
|
||
pending_email = Column(String(255), nullable=True) # 改邮箱时临时落地待验证地址
|
||
```
|
||
|
||
迁移路径：仓库目前没看到 alembic 目录，沿用 `backend/app/db/session.py` 的初始化风格在启动时跑 `ALTER TABLE users ADD COLUMN IF NOT EXISTS ...`。先确认是否存在 alembic，若有则正规迁移。
|
||
|
||
不另建 `verification_codes` 表 — OTP 走 **Redis**（系统已有 Redis，token blacklist 也走 Redis）：
|
||
|
||
```
|
||
key: otp:{purpose}:{email} purpose ∈ {register, verify_email, reset_password}
|
||
value: { code_hash: bcrypt, attempts: int, issued_at: ts }
|
||
TTL: 600 秒
|
||
```
|
||
|
||
`{purpose}:{email}` 同时配一个限流键 `otp_rate:{purpose}:{email}`，TTL 60 秒，用于"60 秒内禁止重发"。
|
||
|
||
## 服务拆分
|
||
|
||
按项目 `services/` 单职责风格拆两个：
|
||
|
||
**`backend/app/services/otp.py`**（通用 OTP 原语，未来 2FA / 手机号验证可直接复用）：
|
||
|
||
```python
|
||
async def issue_code(email: str, purpose: OtpPurpose) -> str # 生成 6 位、写 Redis、返回明码（调用方负责送达）
|
||
async def verify_code(email: str, purpose: OtpPurpose, code: str) -> bool # 校验并消耗
|
||
async def check_resend_allowed(email: str, purpose: OtpPurpose) -> None # 抛 RateLimited 异常
|
||
```
|
||
|
||
- 6 位数字，密码学随机
|
||
- Redis 存 `bcrypt(code)`，不存明码
|
||
- 校验失败计数 ≥ 5 直接失效该 key
|
||
- 重发触发即失效旧 code
|
||
|
||
**`backend/app/services/email.py`**（通用 SMTP 发送，告警/摘要等后续可复用）：
|
||
|
||
```python
|
||
async def send_email(to: str, subject: str, html: str, text: str | None = None) -> None
|
||
async def send_verification_email(to: str, code: str, purpose: OtpPurpose) -> None # 模板封装
|
||
```
|
||
|
||
- 用 `aiosmtplib` 异步发送
|
||
- 从 `system_settings` 的 `smtp` 命名空间读配置（host/port/username/password/from/use_tls）
|
||
- 未配置抛 `EmailNotConfiguredError`
|
||
- 模板用简单 HTML + 纯文本双段，按 `purpose` 切换文案
|
||
|
||
编排（"签码 → 发邮件"）在 `api/v1/auth.py` 端点里调两个服务，不在 service 内互相调用，保持单测可单独 mock。
|
||
|
||
## 后端端点
|
||
|
||
新增到 `backend/app/api/v1/auth.py`：
|
||
|
||
| 端点 | 入参 | 行为 |
|
||
| --- | --- | --- |
|
||
| `POST /auth/register` | `username, email, password` | 用户名/邮箱查重 → 写 User `is_active=True, email_verified=False, role="viewer"` → 调 `otp.issue_code(email, "register")` → 调 `email.send_verification_email` |
|
||
| `POST /auth/verify-email` | `email, code` | `otp.verify_code` → 置 `email_verified=True` → 直接返回 access/refresh token |
|
||
| `POST /auth/resend-code` | `email, purpose` | `check_resend_allowed` → `issue_code` → `send_verification_email` |
|
||
| `POST /auth/forgot-password` | `email` | 即便邮箱不存在也返回 200（防枚举）；存在则签 `reset_password` 码并发邮件 |
|
||
| `POST /auth/reset-password` | `email, code, new_password` | `verify_code(..., "reset_password")` → `user.set_password(new_password)` |
|
||
|
||
`/auth/login` 改造：邮箱未验证用户登录返回 `403 { code: "EMAIL_NOT_VERIFIED", email }`，前端拿到后跳验证页。
|
||
|
||
## SMTP 设置
|
||
|
||
复用 `backend/app/api/v1/settings.py` 现有 setting store，新增 `smtp` 命名空间：
|
||
|
||
- `smtp_host`、`smtp_port`、`smtp_username`、`smtp_password`、`smtp_from`、`smtp_from_name`、`smtp_use_tls`
|
||
- 密码走与 collector 凭证相同的加密路径（看 `backend/app/services/` 是否已有 `credentials_encryption` 之类工具，若有直接复用）
|
||
- `POST /settings/smtp/test` — 用当前未保存的入参试发一封到指定地址，不落库
|
||
|
||
未配置 SMTP 时 `/auth/register` 应返回明确错误 `503 { code: "EMAIL_PROVIDER_NOT_CONFIGURED" }`，提示管理员先去 `/settings` 配 SMTP 或用 `./planet.sh createuser` 兜底。
|
||
|
||
## 前端
|
||
|
||
**新页面**：
|
||
|
||
- `frontend/src/pages/Register/Register.tsx` — 两步表单：(1) 用户名/邮箱/密码 (2) 6 位验证码；60s 重发冷却；验证成功写 token，自动跳 `/admin`
|
||
- `frontend/src/pages/VerifyEmail/VerifyEmail.tsx` — 给登录拦截 `EMAIL_NOT_VERIFIED` 时落地的页，仅"输码 + 重发"
|
||
- `frontend/src/pages/ForgotPassword/ForgotPassword.tsx` — 两步：(1) 输邮箱 (2) 输码 + 新密码
|
||
|
||
**改动**：
|
||
|
||
- `frontend/src/pages/Login/Login.tsx` — 表单下加"注册账号"、"忘记密码"链接；接 `EMAIL_NOT_VERIFIED` 跳 `/verify-email`
|
||
- `frontend/src/pages/Settings/Settings.tsx` — 新增 SMTP 子 tab（host/port/username/password/from/TLS + 测试发送按钮），用工作区里新建的 `frontend/src/components/ConnectionTestInput/` 做连通测试输入
|
||
- 路由表（`frontend/src/App.tsx` 或 `frontend/src/router/*`）— 加 `/register`、`/forgot-password`、`/verify-email`
|
||
|
||
## 关键文件清单
|
||
|
||
后端：
|
||
|
||
- `backend/app/models/user.py` — 加字段
|
||
- `backend/app/schemas/user.py` — 新增 `UserRegister`、`VerifyCode`、`ResetPasswordRequest` schema
|
||
- `backend/app/api/v1/auth.py` — 新端点 + 登录校验
|
||
- `backend/app/services/otp.py` *(新)*
|
||
- `backend/app/services/email.py` *(新)*
|
||
- `backend/app/api/v1/settings.py` — SMTP 命名空间 + 测试发送
|
||
- `backend/app/core/config.py` — SMTP 默认值/特性开关
|
||
- `backend/app/db/session.py` — DDL 兜底（若无 alembic）
|
||
|
||
前端：
|
||
|
||
- `frontend/src/pages/Register/Register.tsx` *(新)*
|
||
- `frontend/src/pages/VerifyEmail/VerifyEmail.tsx` *(新)*
|
||
- `frontend/src/pages/ForgotPassword/ForgotPassword.tsx` *(新)*
|
||
- `frontend/src/pages/Login/Login.tsx`
|
||
- `frontend/src/pages/Settings/Settings.tsx`
|
||
- 路由文件
|
||
|
||
## 实施顺序
|
||
|
||
1. 后端：User 模型字段 + DDL 兜底
|
||
2. 后端：`services/otp.py`（先纯单测跑通）
|
||
3. 后端：`services/email.py`（用 MailHog 本地试发）
|
||
4. 后端：`/auth/register` + `/auth/verify-email` + `/auth/resend-code` + 登录拦截
|
||
5. 后端：`/auth/forgot-password` + `/auth/reset-password`
|
||
6. 后端：`/settings/smtp` 命名空间 + 测试发送
|
||
7. 前端：`Settings.tsx` 加 SMTP 子 tab
|
||
8. 前端：Register / VerifyEmail / ForgotPassword 页 + Login 入口
|
||
|
||
文档同步在 [文档受众分层重构计划](/home/ray/dev/linkong/planet/docs/plans/docs-audience-split-plan.md) 落地。
|
||
|
||
## 验证
|
||
|
||
- **后端单测**（仿 `backend/tests/test_settings_ai_provider.py`）：
|
||
- 注册端点用户名/邮箱查重
|
||
- OTP 过期、错码计数、重发限流
|
||
- 邮箱未验证用户登录返回 `EMAIL_NOT_VERIFIED`
|
||
- SMTP 未配置时注册端点返回 `EMAIL_PROVIDER_NOT_CONFIGURED`
|
||
- 忘记密码对不存在邮箱仍返回 200
|
||
- **后端集测**：本机起 MailHog 或 Mailtrap，把 SMTP 指到上面，跑 register → 收码 → verify → login 一遍
|
||
- **前端**：`source ~/.zshrc && bun run build`；启 dev server 走 `/register` → `/verify-email` → `/admin` 全流程，再试 `/forgot-password`
|
||
- **手测**：新邮箱注册 → 收码 → 输错 → 重发 → 输对 → 登录 → 改密码 → 用新密码再登；管理员在 `/settings` 改 SMTP → 测试发送
|