Genarrative/docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md

/api/auth/login-options 登录方式选项设计

日期：2026-04-21

1. 文档目的

这份文档用于冻结 Rust api-server 首版 GET /api/auth/login-options 的返回 contract、配置来源与当前阶段边界，确保前端在登录页读取“当前可用登录方式”时，不需要依赖硬编码开关。

2. 当前目标

当前阶段只解决一件事：

1. 由 Axum 根据服务端配置，返回当前环境启用的登录方式列表。
2. 密码登录入口由 Rust password_entry 固定承载，作为登录弹窗的保底入口。

本阶段明确不包含：

1. 短信或微信登录链路本身是否已经完整落地
2. 对前端返回更细粒度的 provider 配置
3. 第三方登录按钮文案、图标或 UI 布局规则

3. 接口 contract

3.1 请求

1. 方法：GET
2. 路径：/api/auth/login-options
3. 鉴权：不需要
4. 请求体：空

3.2 成功响应

{
  "availableLoginMethods": ["phone", "password", "wechat"]
}

字段说明：

1. availableLoginMethods 为字符串数组
2. 当前阶段只允许出现：
   • phone
   • password
   • wechat

3.3 返回顺序

返回顺序固定为：

1. 先 phone
2. 再 password
3. 再 wechat

这样可以保证前端按钮顺序稳定，不因配置解析顺序变化而漂移。

4. 配置来源

api-server 只读取以下布尔配置：

1. SMS_AUTH_ENABLED
2. WECHAT_AUTH_ENABLED

映射规则固定为：

1. SMS_AUTH_ENABLED=true 时返回 phone
2. Rust 密码登录主链可用时固定返回 password
3. WECHAT_AUTH_ENABLED=true 时返回 wechat
4. 短信与微信都关闭时仍返回 ["password"]

5. crate 边界

5.1 api-server

负责：

1. 读取 AppState.config
2. 组装 availableLoginMethods
3. 返回项目兼容的响应 envelope

5.2 module-auth

本接口当前阶段不依赖 module-auth。

5.3 前端

负责：

1. 根据 availableLoginMethods 决定是否展示手机号 / 微信入口
2. 不再假设某种登录方式一定存在
3. 若 /api/auth/login-options 联调失败或返回空数组，前端仍保留 password 入口，避免登录弹窗显示“当前登录入口暂不可用”后无法继续操作。

6. 测试要求

至少覆盖：

1. 默认配置下返回 ["password"]
2. 同时启用短信、密码与微信时返回 ["phone", "password", "wechat"]
3. 前端在 login-options 读取失败或返回空数组时，仍展示密码登录表单

7. 完成定义

满足以下条件时，本任务视为完成：

1. Rust 已提供 GET /api/auth/login-options
2. 响应字段命名与前端约定一致
3. 配置开关可稳定映射到返回数组
4. 文档、任务清单与测试已同步更新