social-app/docs/plans/2026-02-25-auth-signup-otp-implementation.md

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

• 记录通过/失败数量与关键行为验证结果。