docs: design auth user account table

backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md

@@ -140,7 +140,8 @@
 
 ### SpacetimeDB 身份表
 
-- [ ] 设计 `user_account`
+- [x] 设计 `user_account`
+  交付物：[../docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](../docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)
 - [ ] 设计 `auth_identity`
 - [ ] 设计 `refresh_session`
 - [ ] 设计 `auth_audit_log`

docs/technical/README.md

@@ -4,6 +4,7 @@
 
 ## 文档列表
 
+- [SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)：`M2` 第一张身份主表 `user_account` 的职责边界、字段、唯一约束、状态迁移、旧 `users` 映射与落地约束。
 - [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)：基于当前 Node 后端能力清单，设计用 `SpacetimeDB + Axum + 阿里云 OSS` 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。
 - [REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md](./REPO_NOISE_CLEANUP_BASELINE_2026-04-19.md)：落实工程清理审计第一阶段后的仓库噪音清理范围、忽略规则闭合点与后续约束。
 - [PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md](./PROMPT_DIRECTORY_MANAGEMENT_2026-04-19.md)：后端提示词收口到 `server-node/src/prompts/` 的目录方案、兼容策略与后续新增规则。

docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md

@@ -0,0 +1,378 @@
+# `user_account` 表设计
+
+日期：`2026-04-21`
+
+## 1. 文档目的
+
+这份文档用于完成 `M2` 的第一条任务：`设计 user_account`。
+
+目标不是只列一组字段名，而是把以下内容一次钉死到可编码级别：
+
+1. `user_account` 在新鉴权体系中的唯一职责
+2. 它与当前 Node `users` 表的一一映射关系
+3. 它与后续 `auth_identity`、`refresh_session` 的边界
+4. 它需要支撑的 `/api/auth/*` 兼容链路
+5. 它在 SpacetimeDB 中的字段、唯一约束、状态迁移与写入规则
+
+## 2. 现有基线
+
+当前 Node 鉴权主链已经依赖 `users` 主表完成以下能力：
+
+1. `POST /api/auth/entry`：用户名密码登录，不存在则自动创建账号
+2. `POST /api/auth/phone/login`：手机号验证码登录，不存在则自动创建账号
+3. `GET /api/auth/me`：读取当前账号基础信息
+4. `POST /api/auth/logout`：提升 `token_version`，让当前 access token 失效
+5. `POST /api/auth/logout-all`：提升 `token_version` 并吊销全部 refresh session
+6. `POST /api/auth/wechat/bind-phone`：待绑定微信账号激活，或把微信身份归并到已有手机号账号
+
+当前 Node `users` 表已有字段基线：
+
+1. `id`
+2. `username`
+3. `password_hash`
+4. `token_version`
+5. `display_name`
+6. `login_provider`
+7. `account_status`
+8. `phone_number`
+9. `phone_verified_at`
+10. `created_at`
+11. `updated_at`
+
+当前真实业务结论：
+
+1. 用户主实体已经存在，不能在 Rust 重写时把账号主表重新拆散成多个等价主表。
+2. `password_hash` 当前仍然是账号主链的一部分，不能因为正式前台主入口转向手机号/微信就直接删除。
+3. `token_version` 当前承担 access token 批量失效语义，必须保留。
+4. 微信待绑定账号壳当前通过 `account_status = pending_bind_phone` 表达，这个状态必须继续保留。
+
+## 3. 表职责边界
+
+`user_account` 只负责“账号主实体”本身，具体边界固定如下：
+
+### 3.1 它负责的内容
+
+1. 稳定账号 ID
+2. 账号显示名
+3. 主手机号归属
+4. 账号当前状态
+5. 主登录方式归属
+6. 密码登录所需的 `password_hash`
+7. access token 统一失效计数 `token_version`
+8. 账号级时间戳与合并痕迹
+
+### 3.2 它不负责的内容
+
+1. 微信 `openid / unionid / avatar` 这类 provider 明细
+2. refresh token hash 与设备会话
+3. 短信验证码发送与校验流水
+4. 风控封禁
+5. 审计日志
+
+### 3.3 与其他表的边界
+
+1. `auth_identity` 负责一个账号挂了哪些外部登录身份。
+2. `refresh_session` 负责一个账号有哪些活跃设备会话。
+3. `user_account` 只保留“主手机号”和“主登录方式”，不重复承担 provider 明细存储。
+
+## 4. 表访问级别
+
+`user_account` 固定为 `private table`。
+
+原因：
+
+1. 表内包含 `password_hash`
+2. 表内包含手机号主归属
+3. 表内包含账号状态和 token 失效控制字段
+4. 前端不应直接查询该表
+
+读取方式固定为：
+
+1. Axum 通过服务层查询账号信息
+2. SpacetimeDB 内部 reducer / view 通过 owner 身份读取
+3. `/api/auth/me` 等对外接口通过 view / Axum 聚合返回脱敏 DTO
+
+## 5. 字段设计
+
+建议字段如下。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `user_id` | `String` | 是 | 主键，继续沿用当前 `user_*` 前缀格式。 |
+| `username` | `String` | 是 | 当前密码登录用户名；手机号/微信创建的系统账号同样要写入唯一用户名。 |
+| `password_hash` | `String` | 是 | 密码登录校验字段；手机号/微信创建账号时继续写随机密码哈希，保持兼容。 |
+| `token_version` | `u32` | 是 | access token 统一失效计数，默认 `1`。 |
+| `display_name` | `String` | 是 | 账号展示名；密码账号默认用户名，手机号账号默认脱敏手机号，微信待绑定账号默认微信昵称或“微信旅人”。 |
+| `login_provider` | `String` | 是 | 当前账号的主登录归属，枚举固定为 `password`、`phone`、`wechat`。 |
+| `account_status` | `String` | 是 | 账号状态，枚举固定为 `active`、`pending_bind_phone`、`disabled`。 |
+| `primary_phone_e164` | `Option<String>` | 否 | 当前账号的主手机号，统一存 `E.164`。 |
+| `phone_verified_at` | `Option<String>` | 否 | 主手机号最近一次完成校验的 UTC RFC3339 时间。 |
+| `last_login_at` | `Option<String>` | 否 | 最近一次完成交互式登录成功的时间，不在 refresh 时更新。 |
+| `merged_to_user_id` | `Option<String>` | 否 | 待绑定微信壳账号并入已有手机号账号时写入目标账号 ID。 |
+| `merged_at` | `Option<String>` | 否 | 写入并入发生时间。 |
+| `status_reason_code` | `Option<String>` | 否 | 非 `active` 状态的原因码，例如 `manual_disabled`、`merged_into_existing_account`。 |
+| `created_at` | `String` | 是 | UTC RFC3339 创建时间。 |
+| `updated_at` | `String` | 是 | UTC RFC3339 最近更新时间。 |
+
+补充约束：
+
+1. 当前阶段时间字段统一继续使用 UTC RFC3339 字符串，优先对齐现有 Node 数据与调试方式。
+2. `username` 在账号创建后默认不可修改，本轮不设计用户名改名链路。
+3. `password_hash` 当前视为账号主字段，而不是 `auth_identity` 子字段。
+
+## 6. 唯一约束与索引
+
+### 6.1 必须具备的唯一约束
+
+1. `user_id` 主键唯一
+2. `username` 全局唯一
+3. `primary_phone_e164` 在非空时全局唯一
+
+### 6.2 必须具备的查询索引
+
+1. `username`
+   作用：支撑 `POST /api/auth/entry`
+2. `primary_phone_e164`
+   作用：支撑 `POST /api/auth/phone/login`、`POST /api/auth/phone/change`
+3. `account_status + updated_at`
+   作用：后续管理端、审计排查与禁用账号扫描
+4. `merged_to_user_id`
+   作用：微信待绑定壳账号归并后排查与数据修复
+
+### 6.3 当前阶段不放进 `user_account` 的查询需求
+
+1. 微信身份查找
+2. refresh token hash 查找
+3. 会话列表查找
+
+这些查询固定由后续 `auth_identity` 与 `refresh_session` 承担。
+
+## 7. 状态机设计
+
+`account_status` 当前阶段只允许以下三种值：
+
+### 7.1 `active`
+
+表示：
+
+1. 账号已完成正式激活
+2. 可以进入游戏
+3. 可以创建与读取正式存档
+4. 可以使用 `/api/auth/me`、`/api/auth/sessions` 等正式能力
+
+### 7.2 `pending_bind_phone`
+
+表示：
+
+1. 账号由微信首次登录创建
+2. 已经拿到微信身份，但还没有正式手机号归属
+3. 不允许进入游戏主链
+4. 只允许继续完成绑定手机号或退出
+
+### 7.3 `disabled`
+
+表示：
+
+1. 账号已被人工禁用
+2. 或账号已作为临时壳账号并入其他正式账号
+3. 所有 access token 与 refresh session 后续都应视为不可继续使用
+
+附加约束：
+
+1. 若 `account_status = disabled` 且 `merged_to_user_id` 非空，则该记录视为“并入后保留痕迹”，不能再恢复为活跃账号。
+2. 不新增 `merged` 枚举，统一使用 `disabled + status_reason_code = merged_into_existing_account` 表达。
+
+## 8. 字段写入规则
+
+### 8.1 `POST /api/auth/entry`
+
+写入规则：
+
+1. 先按 `username` 查询
+2. 若不存在，则创建一条 `active` 账号
+3. `login_provider = password`
+4. `display_name = username`
+5. `primary_phone_e164 = null`
+6. `phone_verified_at = null`
+7. `last_login_at = 当前时间`
+
+### 8.2 `POST /api/auth/phone/login`
+
+写入规则：
+
+1. 先按 `primary_phone_e164` 查询
+2. 若不存在，则创建一条 `active` 账号
+3. `login_provider = phone`
+4. `display_name = 脱敏手机号`
+5. `primary_phone_e164 = 验证成功的 E.164 手机号`
+6. `phone_verified_at = 当前时间`
+7. `last_login_at = 当前时间`
+
+### 8.3 `GET /api/auth/wechat/callback`
+
+写入规则：
+
+1. 若该微信身份未绑定任何账号，则创建一条 `pending_bind_phone` 账号壳
+2. `login_provider = wechat`
+3. `display_name = 微信昵称或“微信旅人”`
+4. `primary_phone_e164 = null`
+5. `phone_verified_at = null`
+6. `last_login_at = 当前时间`
+
+### 8.4 `POST /api/auth/wechat/bind-phone`
+
+分两种情况：
+
+1. 手机号未被使用
+   结果：更新当前 `pending_bind_phone` 账号为 `active`
+2. 手机号已绑定正式账号
+   结果：当前壳账号不再物理删除，而是：
+   - `account_status = disabled`
+   - `status_reason_code = merged_into_existing_account`
+   - `merged_to_user_id = 目标正式账号`
+   - `merged_at = 当前时间`
+
+同时：
+
+1. 微信身份迁移到目标正式账号
+2. 当前壳账号不再允许继续登录
+
+### 8.5 `POST /api/auth/phone/change`
+
+写入规则：
+
+1. 校验当前账号必须是 `active`
+2. 新手机号不能和旧手机号相同
+3. 新手机号必须在 `user_account` 中唯一
+4. 写入新的 `primary_phone_e164`
+5. 写入新的 `phone_verified_at`
+6. 若当前账号展示名本质上仍是旧手机号派生值，则同步更新 `display_name`
+
+### 8.6 `POST /api/auth/logout` 与 `POST /api/auth/logout-all`
+
+写入规则：
+
+1. `token_version = token_version + 1`
+2. `updated_at = 当前时间`
+
+说明：
+
+1. 继续保留当前 Node 语义，让 access token 可统一失效。
+2. 指定设备吊销只改 `refresh_session`，不修改 `user_account.token_version`。
+
+## 9. 读模型约束
+
+`user_account` 本身不直接面向前端暴露，但必须能稳定支撑以下读需求：
+
+### 9.1 `/api/auth/me`
+
+直接提供的字段：
+
+1. `user_id`
+2. `display_name`
+3. `login_provider`
+4. `account_status`
+5. `primary_phone_e164`
+
+经 Axum 或 view 转换后的字段：
+
+1. `phoneNumberMasked`
+2. `bindingStatus`
+3. `loginMethod`
+
+### 9.2 `/api/auth/login-options`
+
+不直接读取 `user_account`，但需要与 `user_account` 的状态语义兼容：
+
+1. 未登录无账号上下文时，只返回可用登录方式
+2. 已登录但 `pending_bind_phone` 时，前端要据 `account_status` 限制继续进入游戏
+
+### 9.3 `/api/auth/sessions`
+
+只依赖 `user_id` 作为 join 键，不在 `user_account` 上重复放会话信息。
+
+## 10. 与当前 Node `users` 表的映射关系
+
+| Node `users` 列 | 新 `user_account` 字段 | 迁移规则 |
+| --- | --- | --- |
+| `id` | `user_id` | 原样迁移，继续保留 `user_*` 前缀。 |
+| `username` | `username` | 原样迁移。 |
+| `password_hash` | `password_hash` | 原样迁移。 |
+| `token_version` | `token_version` | 原样迁移。 |
+| `display_name` | `display_name` | 原样迁移。 |
+| `login_provider` | `login_provider` | 原样迁移。 |
+| `account_status` | `account_status` | 原样迁移。 |
+| `phone_number` | `primary_phone_e164` | 原样迁移，但命名改为明确表示“主手机号”。 |
+| `phone_verified_at` | `phone_verified_at` | 原样迁移。 |
+| `created_at` | `created_at` | 原样迁移。 |
+| `updated_at` | `updated_at` | 原样迁移。 |
+
+新增字段回填规则：
+
+1. `last_login_at`
+   初次迁移时先回填为 `updated_at`
+2. `merged_to_user_id`
+   初次迁移统一为 `null`
+3. `merged_at`
+   初次迁移统一为 `null`
+4. `status_reason_code`
+   初次迁移统一为 `null`
+
+## 11. reducer / service 落地约束
+
+为避免后续实现漂移，`user_account` 相关能力固定拆成以下职责：
+
+### 11.1 `module-auth` reducer 层
+
+必须至少具备这些命令入口：
+
+1. `create_password_user_account`
+2. `create_phone_user_account`
+3. `create_pending_wechat_user_account`
+4. `activate_pending_wechat_user_account`
+5. `update_user_account_phone`
+6. `bump_user_account_token_version`
+7. `mark_user_account_merged`
+8. `disable_user_account`
+9. `touch_user_account_last_login`
+
+### 11.2 Axum 应用层
+
+固定负责：
+
+1. 密码校验
+2. 短信验证码校验
+3. 微信 code 换身份
+4. 决定调用哪条 reducer
+5. 再读取后续 view / join 结果返回旧接口 contract
+
+## 12. 不允许的设计漂移
+
+后续实现时禁止出现以下情况：
+
+1. 因为要做 `auth_identity`，就把 `password_hash` 从 `user_account` 里提前移走。
+2. 因为要做 `refresh_session`，就把 `token_version` 也移到会话表中。
+3. 因为微信待绑定账号壳当前无正式游戏数据，就继续走“物理删除账号”策略。
+4. 把手机号明细既放 `auth_identity` 又放多份等价主字段，导致唯一约束漂移。
+5. 为了图省事把 `pending_bind_phone` 和 `disabled` 混成一个状态。
+
+## 13. 本任务完成定义
+
+当以下条件满足时，`设计 user_account` 视为完成：
+
+1. `user_account` 的职责边界已经和 `auth_identity`、`refresh_session` 明确切开。
+2. 字段、唯一约束、状态枚举、写入规则已具体到可以直接编码。
+3. 已明确与当前 Node `users` 表的迁移关系。
+4. 后续 `auth_identity` 与 `refresh_session` 的设计可以直接以这份文档为前置约束继续展开。
+
+## 14. 依据文件
+
+1. `server-node/src/routes/authRoutes.ts`
+2. `server-node/src/auth/authService.ts`
+3. `server-node/src/repositories/userRepository.ts`
+4. `server-node/src/repositories/authIdentityRepository.ts`
+5. `server-node/src/repositories/userSessionRepository.ts`
+6. `server-node/src/db/migrations.ts`
+7. `docs/prd/ACCOUNT_SYSTEM_AND_LOGIN_ENTRY_PRD_2026-04-09.md`
+8. `backend-rewrite-tasklist/M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md`
+9. `docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md`

docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md

@@ -306,6 +306,10 @@ server-rs/
 2. 密码哈希、短信验证码校验、微信 code 换 token 的动作在 Axum 完成。
 3. Axum 再调用 reducer 写入最终结果。
 
+`user_account` 的详细字段、状态迁移与旧 `users` 映射规则，见：
+
+- [SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)
+
 ### B. 运行时主状态表
 
 - `runtime_snapshot`

server-rs/packages/module-auth/README.md

@@ -13,7 +13,7 @@
 
 ## 2. 当前阶段说明
 
-当前提交仅完成目录占位，不提前进入接口、表结构与 token 细节实现。
+当前阶段已先冻结第一张账号主表 `user_account` 的设计，其余身份表、会话表与 token 细节仍按顺序继续展开。
 
 后续与本 package 直接相关的任务包括：
 
@@ -22,6 +22,10 @@
 3. 设计 `sms_auth_event`、`wechat_auth_state`
 4. 落地 JWT claims、refresh cookie 与旧接口兼容
 
+当前已冻结文档：
+
+1. [../../../docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](../../../docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)
+
 ## 3. 边界约束
 
 1. `module-auth` 负责鉴权领域规则与模块级编排，不直接把供应商 SDK 逻辑写进主工程。