# Auth + Profile（Supabase 优先）设计

**Date:** 2026-02-24
**Status:** Approved

## 目标

在最大化复用 Supabase Auth 能力前提下，完成以下能力：

1. 用户注册：`username + email + password`
2. 用户登录：`email + password`
3. 用户按 email 查询（Auth 维度）
4. 用户资料更新（Profile 维度）

## 范围与原则

- 保留并复用现有 `/auth/signup`、`/auth/login`、`/profile/me` 主体能力
- 仅补齐差距，不重复造轮子
- 登录标识仅使用 email，`username` 仅用于展示
- `profiles.username` 允许重复，不加唯一约束
- 当前为开发阶段，按“无历史数据”处理迁移

## 数据模型设计

`public.profiles` 字段调整：

- 保留：`id`, `username`, `avatar_url`, `bio`, `created_at`, `updated_at`, `deleted_at`
- 删除：`display_name`
- `id` 继续绑定 `auth.users.id`（FK + ON DELETE CASCADE）

## 认证与资料流转

### 注册

- 请求：`username + email + password`
- 后端调用 Supabase `auth.sign_up`，并将 `username` 写入 `raw_user_meta_data.username`
- 由数据库触发器在 `auth.users` 插入后自动创建 `public.profiles`
  - `profiles.id = auth.users.id`
  - `profiles.username = raw_user_meta_data.username`

### 登录

- 保持现有 `email + password` 登录，不改协议

### 按 email 查找用户

- 新增后端接口：`GET /auth/users/by-email?email=...`
- 通过 Supabase Admin 能力查询（后端 service_role）
- 返回最小必要字段（例如 `id/email/created_at/email_confirmed_at`）

### 资料更新

- `PATCH /profile/me` 继续使用
- 去除 `display_name` 更新项
- 允许更新：`username/avatar_url/bio`

## 安全与权限

- 按 email 查找接口必须后端受控，避免普通用户枚举
- 注册与更新时做输入校验（格式、长度）
- 认证继续依赖 Supabase 签发 token，后端负责业务鉴权

## 验收标准

1. 注册时提交 `username+email+password` 可成功创建 Auth 用户
2. 注册后自动创建 profile，且 `profiles.username` 等于注册时 `username`
3. 登录保持 `email+password` 可用
4. `PATCH /profile/me` 可更新 `username/avatar_url/bio`
5. `GET /auth/users/by-email` 返回正确用户或 404
6. `profiles` 表无 `display_name` 字段