social-app/docs/plans/2026-02-24-auth-profile-implementation.md

Auth Profile Enhancement Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 基于 Supabase 能力补齐注册/登录/按邮箱查用户/更新 profile 的一致化实现，并移除 profiles.display_name。

Architecture: 认证流程继续走 Supabase Auth（signup/login/refresh/logout），后端仅做薄封装与输入校验。profiles 通过 auth.users 触发器自动创建并绑定同一 id，profile 资料更新仍走业务接口。新增按邮箱查用户接口走 service_role 的 Admin API。

Tech Stack: FastAPI, Supabase Python SDK, SQLAlchemy, Alembic, PostgreSQL

---

Task 1: 调整 profiles 数据模型与迁移

Files:

• Modify: backend/src/models/profile.py
• Create: backend/alembic/versions/20260224_drop_profile_display_name_and_trigger_username.py

Step 1: Write the failing test

• 新增迁移验证脚本测试：断言 profiles 不含 display_name 且触发器使用 metadata.username。

Step 2: Run test to verify it fails

Run: PYTHONPATH=src uv run python -m pytest tests/integration -k profile_migration -q Expected: FAIL（旧结构仍有 display_name 或触发器逻辑不匹配）

Step 3: Write minimal implementation

• model 删除 display_name
• 迁移删除列并重建触发器函数：profiles.username = NEW.raw_user_meta_data->>'username'

Step 4: Run test to verify it passes

Run: PYTHONPATH=src uv run python -m pytest tests/integration -k profile_migration -q Expected: PASS

Task 2: 注册接口改为 username+email+password

Files:

• Modify: backend/src/v1/auth/schemas.py
• Modify: backend/src/v1/auth/service.py

Step 1: Write the failing test

• 测试 signup 缺 username 返回 422
• 测试 signup 将 data.username 传递给 Supabase gateway

Step 2: Run test to verify it fails

Run: PYTHONPATH=src uv run python -m pytest tests/unit -k auth_signup -q Expected: FAIL

Step 3: Write minimal implementation

• SignupRequest 添加必填 username
• SupabaseAuthGateway.signup payload 增加 data.username

Step 4: Run test to verify it passes

Run: PYTHONPATH=src uv run python -m pytest tests/unit -k auth_signup -q Expected: PASS

Task 3: 新增按邮箱查询 auth 用户接口

Files:

• Modify: backend/src/v1/auth/router.py
• Modify: backend/src/v1/auth/service.py
• Modify: backend/src/v1/auth/schemas.py

Step 1: Write the failing test

• 测试 GET /auth/users/by-email 命中返回用户最小字段
• 测试未命中返回 404

Step 2: Run test to verify it fails

Run: PYTHONPATH=src uv run python -m pytest tests/unit -k auth_by_email -q Expected: FAIL

Step 3: Write minimal implementation

• service 新增 get_user_by_email
• gateway 用 service_role client 调用 Supabase Admin 查询
• router 暴露 GET /auth/users/by-email

Step 4: Run test to verify it passes

Run: PYTHONPATH=src uv run python -m pytest tests/unit -k auth_by_email -q Expected: PASS

Task 4: profile 更新协议去除 display_name

Files:

• Modify: backend/src/v1/profile/schemas.py
• Modify: backend/src/v1/profile/service.py
• Modify: backend/src/v1/profile/router.py

Step 1: Write the failing test

• 测试 PATCH /profile/me 仅允许 username/avatar_url/bio

Step 2: Run test to verify it fails

Run: PYTHONPATH=src uv run python -m pytest tests/unit -k profile_update -q Expected: FAIL

Step 3: Write minimal implementation

• 移除 display_name 字段与映射
• 保留原有更新路径和事务边界

Step 4: Run test to verify it passes

Run: PYTHONPATH=src uv run python -m pytest tests/unit -k profile_update -q Expected: PASS

Task 5: 集成验证

Files:

• Modify: docs/runtime/runtime-runbook.md

Step 1: 运行关键验证

Run: docker compose --env-file .env -f infra/docker/docker-compose.yml --profile job run --rm init-job Expected: 迁移成功

Run: PYTHONPATH=src uv run python -m pytest tests -q Expected: 全部通过

Step 2: 手工 API 验证

• signup(username,email,password) 成功
• login(email,password) 成功
• by-email 查询命中
• patch profile 更新成功