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 根据服务端配置，返回当前环境启用的登录方式列表。

本阶段明确不包含：

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

3. 接口 contract

3.1 请求

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

3.2 成功响应

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

字段说明：

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

3.3 返回顺序

返回顺序固定为：

1. 先 phone
2. 再 wechat

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

4. 配置来源

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

1. SMS_AUTH_ENABLED
2. WECHAT_AUTH_ENABLED

映射规则固定为：

1. SMS_AUTH_ENABLED=true 时返回 phone
2. WECHAT_AUTH_ENABLED=true 时返回 wechat
3. 两者都关闭时返回空数组

5. crate 边界

5.1 api-server

负责：

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

5.2 module-auth

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

5.3 前端

负责：

1. 根据 availableLoginMethods 决定是否展示手机号 / 微信入口
2. 不再假设某种登录方式一定存在

6. 测试要求

至少覆盖：

1. 默认配置下返回空数组
2. 同时启用短信与微信时返回 ["phone", "wechat"]

7. 完成定义

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

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