qzl
1cc8fa1abf
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.
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# 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**
|
||
- 记录通过/失败数量与关键行为验证结果。
|