feat(auth): switch signup to OTP verification flow

Replace legacy signup with start/verify/resend endpoints, add OTP-focused mail templates and auth rate limits, and align compose/env/runbook for local self-hosted Supabase OTP behavior.
2026-02-25 13:34:02 +08:00
parent 02e5e52e1f
commit 1cc8fa1abf
16 changed files with 707 additions and 112 deletions
@@ -0,0 +1,85 @@
+# Auth Signup OTP Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 将注册流程改为两阶段 OTP（start/verify/resend），并移除旧 `/auth/signup` 路由。
+
+**Architecture:** 后端继续作为 Supabase Auth 的薄封装层。`signup/start` 只创建待验证用户并触发验证码邮件；`signup/verify` 通过 `verifyOtp(type=signup)` 完成验证并返回 token；`signup/resend` 负责重发验证码。保留现有 token 响应模型，最小化客户端和网关改造。
+
+**Tech Stack:** FastAPI, Pydantic, supabase-py, pytest
+
+---
+
+### Task 1: 更新认证 Schema
+
+**Files:**
+- Modify: `backend/src/v1/auth/schemas.py`
+- Test: `backend/tests/unit/v1/auth/test_auth_models.py`
+
+**Step 1: Write the failing test**
+- 为 `SignupStartRequest`、`SignupVerifyRequest`、`SignupResendRequest` 增加字段校验测试。
+
+**Step 2: Run test to verify it fails**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/unit/v1/auth/test_auth_models.py -q`
+
+**Step 3: Write minimal implementation**
+- 新增 start/verify/resend 的请求与响应模型。
+
+**Step 4: Run test to verify it passes**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/unit/v1/auth/test_auth_models.py -q`
+
+### Task 2: 改造 Service/Gateway 为三阶段 OTP
+
+**Files:**
+- Modify: `backend/src/v1/auth/service.py`
+- Modify: `backend/src/v1/auth/gateway.py`
+- Test: `backend/tests/unit/v1/auth/test_auth_service.py`
+
+**Step 1: Write the failing test**
+- 为 `signup_start/signup_verify/signup_resend` 增加 service 转发与 gateway Supabase 调用行为测试。
+
+**Step 2: Run test to verify it fails**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/unit/v1/auth/test_auth_service.py -q`
+
+**Step 3: Write minimal implementation**
+- 删除旧 `signup` 入口，新增三个方法。
+- `signup_verify` 使用 `verify_otp` 并返回 `AuthTokenResponse`。
+- `signup_resend` 调用 `resend(type=signup)` 并返回通用消息。
+
+**Step 4: Run test to verify it passes**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/unit/v1/auth/test_auth_service.py -q`
+
+### Task 3: 替换 Router 路由并删除旧 signup
+
+**Files:**
+- Modify: `backend/src/v1/auth/router.py`
+- Test: `backend/tests/integration/test_auth_routes.py`
+- Test: `backend/tests/e2e/test_auth_flow.py`
+
+**Step 1: Write the failing test**
+- 集成测试改为 `/auth/signup/start`、`/auth/signup/verify`、`/auth/signup/resend`。
+- 删除对旧 `/auth/signup` 的断言。
+
+**Step 2: Run test to verify it fails**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/integration/test_auth_routes.py -q`
+
+**Step 3: Write minimal implementation**
+- Router 新增三条路由并移除旧 `/signup`。
+- 保持 RFC7807 错误映射行为。
+
+**Step 4: Run test to verify it passes**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/integration/test_auth_routes.py -q`
+
+### Task 4: 全量验证
+
+**Files:**
+- Test: `backend/tests/unit/v1/auth/test_auth_models.py`
+- Test: `backend/tests/unit/v1/auth/test_auth_service.py`
+- Test: `backend/tests/integration/test_auth_routes.py`
+- Test: `backend/tests/e2e/test_auth_flow.py`
+
+**Step 1: Run focused suite**
+- Run: `PYTHONPATH=backend/src uv run python -m pytest backend/tests/unit/v1/auth backend/tests/integration/test_auth_routes.py backend/tests/e2e/test_auth_flow.py -q`
+
+**Step 2: Report evidence**
+- 记录通过/失败数量与关键行为验证结果。