手机 App 登录注册与鉴权联调说明
文档版本：v1.0
更新日期：2026-04-02
适用对象：AOVIS / NEXA 手机 App 研发
目标：帮助 App 侧开始网络请求联调，明确现有登录注册体系、可验证接口、现阶段限制、以及推荐接入方式
1. 先说结论
当前独立站已经有统一账号体系，但还没有专门为手机 App 单独设计的一套登录注册 API。
现状是：
- 账号主库已经存在，使用站内 PostgreSQL 的
User体系 - 认证框架是
Auth.js / NextAuth - 当前登录方式是：
- Apple
- Email Magic Link
- 当前没有：
- 手机号注册
- 邮箱密码注册
- 独立的原生 App token exchange API
当前系统应理解为：
- Web 登录体系已经完成
- App 统一账号是明确目标
- 但 App 原生登录 API 仍需要补一层适配接口
2. 当前账号体系说明
2.1 统一账号主系统
当前独立站的统一账号数据源是：
- 数据表：
User - 会话：数据库 Session
- 认证入口：
/api/auth/*
这意味着：
- App 不应该自己再建设一套独立用户表
- App 和独立站应共用同一套用户 ID
- “注册”在当前体系里并不是一个单独表单动作，而是：
- 用户第一次完成第三方登录后，系统自动创建用户
2.2 当前“注册”的真实含义
目前没有单独的 register 接口。
当前注册逻辑是：
- 用户通过 Google / Apple / Email Magic Link 完成认证
- 如果站内不存在该用户，则自动创建
User - 后续继续使用该账号登录
“注册 API”在当前体系中的定义如下：
- 没有单独注册 API
- 首次登录即注册
3. 当前已经存在、可用于联调验证的接口
以下接口已经存在，可以帮助 App 研发了解当前认证系统状态。
3.1 查看当前启用的登录方式
GET /api/auth/providers
用途：
- 用来判断当前环境是否启用了
google、apple、email - App 侧可据此做联调环境确认
示例返回：
{
"google": {
"id": "google",
"name": "Google",
"type": "oauth",
"signinUrl": "https://aovis.app/api/auth/signin/google",
"callbackUrl": "https://aovis.app/api/auth/callback/google"
},
"apple": {
"id": "apple",
"name": "Apple",
"type": "oauth",
"signinUrl": "https://aovis.app/api/auth/signin/apple",
"callbackUrl": "https://aovis.app/api/auth/callback/apple"
},
"email": {
"id": "email",
"name": "Email",
"type": "email",
"signinUrl": "https://aovis.app/api/auth/signin/email",
"callbackUrl": "https://aovis.app/api/auth/callback/email"
}
}
说明：
- 真实返回内容以当前环境配置为准
- 如果某个 provider 未配置，就不会出现在返回中，或者不会处于可用状态
3.2 查看当前会话
GET /api/auth/session
用途：
- 判断当前请求是否已经处于登录状态
- 用来验证 cookie / session 是否生效
已登录示例：
{
"user": {
"name": "Example User",
"image": null,
"id": "clx123abc456"
},
"expires": "2026-04-20T10:00:00.000Z"
}
未登录示例：
null
3.3 Web 现有登录入口
这些是当前 Web 体系使用的认证路由：
POST /api/auth/signin/googlePOST /api/auth/signin/applePOST /api/auth/signin/emailGET /api/auth/callback/*POST /api/auth/signout
说明：
- 这些接口是 Auth.js 标准 Web 认证路由
- 适合浏览器跳转和 cookie 会话
- 不能直接等同于“原生 App 正式登录 API”
4. App 研发当前最需要的验证信息
开始网络请求联调前，应先确认以下信息：
4.1 环境基线
- Base URL：
https://aovis.app - 当前认证提供方检查接口：
GET /api/auth/providers - 当前会话检查接口：
GET /api/auth/session
4.2 现有登录方式
- Google 登录：已接入
- Apple 登录：已接入
- Email Magic Link：已接入
4.3 当前没有的能力
- 手机号验证码登录：没有
- 邮箱密码登录：没有
- 用户名密码注册：没有
- 专门面向原生 App 的登录换 token 接口：没有
5. 现阶段 App 应该怎么做环境检查
当前阶段如仅需“开始网络请求并确认认证环境是否可用”，可直接执行下面两步。
5.1 第一步：检查当前启用的登录方式
请求：
GET https://aovis.app/api/auth/providers
App 侧需要做的事情：
- 在 App 中写一个最简单的
GET请求 - 请求
https://aovis.app/api/auth/providers - 查看返回中是否包含：
googleappleemail
这一步的目的：
- 验证 base URL 是否可访问
- 验证认证路由是否存在
- 验证当前服务端启用了哪些登录方式
成功判断：
- HTTP 状态码为
200 - 响应体为 JSON
- JSON 中可见 provider 信息
说明：
- 这一步不是完成登录
- 这一步只是确认当前认证环境已正常暴露
5.2 第二步：检查当前 Session 接口
请求：
GET https://aovis.app/api/auth/session
App 侧需要做的事情：
- 在未登录状态下直接发起请求
- 查看返回结果是否为：
null
这一步的目的：
- 验证 Session 接口存在
- 验证未登录情况下的返回格式
- 为未来登录完成后的 Session 校验做对照
成功判断：
- HTTP 状态码为
200 - 未登录时响应体通常为
null
如果未来通过浏览器 / WebView 或后续 App 专用登录接口建立了登录态，再请求同一接口，才应该返回用户 Session 信息。
5.3 当前请求时是否需要 token / header
对于当前这两个环境检查接口：
GET /api/auth/providers
- 不需要 token
- 不需要登录
- 不需要额外鉴权 header
- 直接请求即可
GET /api/auth/session
- 可直接请求
- 未登录时返回
null - 如果没有浏览器 cookie 或后续 App token，对应就不会返回用户信息
结论：
- App 当前直接请求这两个接口，不需要额外预置任何 token
- 它们的用途就是“先看环境是否活着、当前认证能力是否已挂出来”
6. 当前是否需要单独搭测试环境
6.1 当前目标仅为开始网络请求和环境检查时
不一定需要现在就单独搭测试环境。
原因是这两个接口当前只承担：
- 探测 base URL 是否可用
- 探测认证路由是否存在
- 探测当前 provider 配置情况
- 探测 Session 接口是否能正常返回
此阶段可直接使用：
https://aovis.app/api/auth/providershttps://aovis.app/api/auth/session
6.2 下一步进入真正登录联调时
建议准备独立测试环境。
原因：
aovis.app是正式基线域名- Google / Apple 登录涉及真实回调域名
- Email Magic Link 可能涉及真实邮件投递
- 未来若补 App 专用登录接口，也更适合先在测试环境联调
所以当前建议是：
- 现在做环境检查：直接用
aovis.app - 开始真实登录联调：再准备单独测试环境
7. 对 App 侧的短期建议
为了尽快开始联调并验证统一账号方向，短期可分两层理解。
7.1 短期验证方案
短期可以用以下方式验证账号体系是否统一：
- App 侧先请求
GET /api/auth/providers - 确认当前环境中启用了哪些 provider
- 如需快速验证，可先通过浏览器 / WebView 打开：
/login/signin
- 登录完成后，再通过
GET /api/auth/session验证当前登录态
这适合做：
- 环境确认
- provider 可用性确认
- 会话存在性验证
但不适合作为长期正式方案。
7.2 不建议的做法
App 侧当前不应直接把 Web cookie 体系当作最终移动端设计。
不建议：
- 直接硬依赖浏览器 cookie 作为 App 最终登录方案
- 自己单独做一套账号注册
- 在移动端本地维护一套和站内
User不一致的用户体系
8. 推荐的正式接入方向
若目标是让 App 和独立站统一账号，推荐后续补一层 App 专用登录适配接口。
建议后端未来新增：
8.1 App OAuth 凭证交换接口
POST /api/app-auth/oauth/exchange
用途：
- App 原生完成 Google / Apple 登录
- 将原生拿到的
idToken/authorizationCode等凭证提交给站内后端 - 后端校验凭证后，查找或创建统一
User - 最后返回给 App 一个可用的统一登录态凭证
示例请求：
{
"provider": "google",
"idToken": "google-id-token",
"accessToken": "google-access-token"
}
或：
{
"provider": "apple",
"idToken": "apple-id-token",
"authorizationCode": "apple-auth-code"
}
推荐响应结构：
{
"ok": true,
"user": {
"id": "clx123abc456",
"name": "Example User"
},
"token": "app-session-token",
"expiresAt": "2026-04-20T10:00:00.000Z"
}
8.2 App 当前用户信息接口
GET /api/app-auth/me
用途：
- App 在拿到 token 后验证当前用户身份
- 获取当前统一账号信息
推荐返回：
{
"id": "clx123abc456",
"name": "Example User",
"image": null
}
8.3 App 登出接口
POST /api/app-auth/signout
用途：
- 让 App 与 Web 在统一账号体系里有清晰的会话失效机制
9. 当前建议 App 研发先做什么
当前开始联调时，建议按以下顺序推进：
- 先按当前真实情况接入环境检查
GET /api/auth/providersGET /api/auth/session
- 确认 App 产品上最终接受的登录方式
- Apple
- Email Magic Link
- 与后端确认是否要新增 App 专用的 OAuth exchange API
- 不要先做独立的邮箱密码注册体系
- 不要先做与站内账号脱离的本地用户系统
10. 联调口径
当前联调口径如下：
当前独立站已经有统一账号体系，但它主要是 Web 认证体系，使用 Auth.js / NextAuth。
当前已经支持 Google、Apple、Email Magic Link，首次登录即自动创建账号，没有单独注册接口。
App 若要与独立站统一账号，应复用当前站内User体系，后续通过后端补充一层面向 App 的 token exchange 接口，而不是重新建设一套账号系统。
11. 本阶段联调信息清单
- Base URL：
https://aovis.app - Provider 检查接口：
GET /api/auth/providers - Session 检查接口：
GET /api/auth/session - 当前登录方式：
- Apple
- Email Magic Link
- 当前注册逻辑：
- 首次登录自动创建用户
- 当前没有：
- 手机号注册
- 邮箱密码注册
- App 专用登录换 token API
- 推荐下一步：
- 后端新增
/api/app-auth/oauth/exchange - App 原生登录后走 token exchange，统一落到站内
User体系
- 后端新增
12. 对接文件参考
auth.ts(legacy codebase reference)app/api/auth/[...nextauth]/route.ts(legacy codebase reference)lib/auth-config.ts(legacy codebase reference)- docs/current-store-development-status.md
- docs/tange-sdk-integration-plan.md