迁移后端认证与拆分 Spacetime 客户端

docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md

@@ -0,0 +1,66 @@
+# 密码登录、修改与重置落地设计
+
+日期：`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 不承担注册能力。