# 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**
- 记录通过/失败数量与关键行为验证结果。
