social-app/docs/protocols/models/auth.md

Auth 协议（手机号 OTP）

本文档定义 /api/v1/auth 的手机号验证码认证协议。

Base URL: /api/v1/auth

---

手机号格式

• 统一使用 E.164：^\+[1-9]\d{7,14}$
• 前端必须提供国家/地区码选择，提交时拼接为完整 E.164（例如：+14155552671、+8613812345678）
• 后端只做安全归一化（去空白和常见分隔符），不推断或补全国家码

---

端点

方法	路径	说明
POST	/otp/send	发送短信验证码
POST	/phone-session	验证码登录/注册（同一路由）
POST	/sessions/refresh	刷新会话
DELETE	/sessions	退出登录

---

本地开发约定（Supabase Self-Hosting）

• 环境：本地网关地址为 http://localhost:8001，后端通过 SOCIAL_SUPABASE__PUBLIC_URL 访问。
• 认证：开发机启用 SMS 测试 OTP，不走真实短信供应商。
• 默认测试账号：SOCIAL_TEST__PHONE（提交时需使用 E.164，即在前面补 +）。
• 默认测试验证码：123456（由本地 auth 服务的 GOTRUE_SMS_TEST_OTP 提供）。

兼容性策略：

• 对外 API 合约不变（/otp/send、/phone-session、/sessions/* 保持一致）。
• 仅切换验证码来源（生产/云环境真实短信，本地环境测试 OTP）。
• 前后端不需要因本地/云差异修改接口调用方式。

---

1) POST /otp/send

发送验证码，不区分登录和注册场景。

Request

{
  "phone": "+14155552671"
}

Response

204 No Content

---

2) POST /phone-session

验证码校验成功后返回会话。

• 若手机号已存在：直接登录
• 若手机号不存在：自动创建账号后登录

Request

{
  "phone": "+14155552671",
  "token": "123456"
}

Response

{
  "access_token": "...",
  "refresh_token": "...",
  "expires_in": 3600,
  "token_type": "bearer",
  "user": {
    "id": "uuid",
    "phone": "+14155552671"
  }
}

---

3) POST /sessions/refresh

Request

{
  "refresh_token": "..."
}

Response

同 /phone-session 会话响应。

---

4) DELETE /sessions

Request

{
  "refresh_token": "..."
}

Response

204 No Content

---

已移除端点

• POST /verifications
• POST /verify
• POST /resend
• POST /sessions（旧密码/短信混合登录入口）