Genarrative/docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md

密码登录、修改与重置落地设计

日期：2026-04-24

1. 目标边界

本次迭代开放账号密码登录、登录后修改密码、手机号验证码重置密码，但不开放密码注册。

1. 新用户只能通过手机号验证码完成注册与首次登录。
2. 已有用户可以在登录后设置或修改密码。
3. 忘记密码时，只能通过已绑定手机号验证码重置密码。
4. 密码登录只校验已存在且已设置密码的账号，不自动创建新账号。

2. 接口设计

2.1 密码登录

沿用现有 POST /api/auth/entry：

1. 请求字段：username、password。
2. 用户不存在时返回 401，不创建账号。
3. 用户存在但未设置密码时返回 401。
4. 校验成功后签发 access token，并写入 refresh cookie。

2.2 修改密码

新增 POST /api/auth/password/change：

1. 需要 Bearer 登录态。
2. 请求字段：currentPassword、newPassword。
3. 若账号未设置过密码，允许 currentPassword 为空并设置首个密码。
4. 若账号已有密码，必须校验 currentPassword 后才能写入 newPassword。
5. 修改成功后递增用户 token_version，使旧 access token 失效；前端沿用当前 refresh 会话刷新登录态。

2.3 重置密码

新增 POST /api/auth/password/reset：

1. 不需要 Bearer 登录态。
2. 请求字段：phone、code、newPassword。
3. 使用 reset_password 短信场景校验验证码。
4. 手机号不存在时返回 404，避免用密码重置隐式注册账号。
5. 重置成功后签发新的 access token，并写入 refresh cookie，便于用户直接进入登录态。

2.4 发送重置验证码

复用 POST /api/auth/phone/send-code，scene 增加 reset_password。

3. 前端交互

登录弹窗拆成两个页签：

1. 登录：提供密码登录、手机号验证码登录、忘记密码入口。
2. 注册：只提供手机号验证码注册/登录，不提供账号密码注册。
3. 忘记密码：从登录页进入独立重置面板，不在当前表单下方展开。
4. 账号设置面板提供密码修改入口；未设置密码的账号显示为设置密码。

4. 数据约束

进程内认证快照中的 password_hash 改为可空语义：

1. 手机号新建账号默认没有用户可用密码。
2. 微信待绑定账号默认没有用户可用密码。
3. 只有用户显式修改或重置密码后，才允许密码登录。

后续迁移到 SpacetimeDB 表时，保持同一语义：密码哈希字段允许为空，密码登录 reducer 不承担注册能力。