# `auth_identity` 表设计

日期：`2026-04-21`

## 1. 文档目的

这份文档用于完成 `M2` 的第二条任务：`设计 auth_identity`。

目标是把“账号主实体”和“外部登录身份”彻底拆清楚，让后续编码时不会再出现：

1. 微信身份字段继续堆进 `user_account`
2. 手机号既是账号字段又没有对应身份行
3. 微信待绑定壳账号并入正式手机号账号时，不知道到底迁哪些记录

## 2. 当前基线

当前 Node 后端已经有一张 `auth_identities` 表，但范围还不完整：

1. 当前只真实存了 `wechat` 身份
2. 手机号登录仍主要依赖 `users.phone_number`
3. `/api/auth/me` 的 `wechatBound` 依赖查询 `auth_identities`
4. 微信登录后的“已有正式账号 / 首次待绑定账号 / 绑定后归并”三种分支，都已经在 `authService.ts` 中真实发生

当前 Node `auth_identities` 字段基线：

1. `id`
2. `user_id`
3. `provider`
4. `provider_uid`
5. `provider_unionid`
6. `display_name`
7. `avatar_url`
8. `is_verified`
9. `meta_json`
10. `created_at`
11. `updated_at`

这说明：

1. `auth_identity` 在现有系统里已经不是新概念，而是微信登录链路的既有事实。
2. Rust 重写时不能再把它降级成“可有可无的附属表”。
3. 但它也还没有扩展到手机号身份层，因此本轮需要把“手机号是否入表、如何入表”钉死。

## 3. 与 `user_account` 的边界

`auth_identity` 与 `user_account` 的固定边界如下。

### 3.1 `user_account` 负责

1. 账号主键与主状态
2. `password_hash`
3. `token_version`
4. `display_name`
5. `primary_phone_e164`
6. `login_provider`

### 3.2 `auth_identity` 负责

1. 一个账号绑定了哪些外部身份
2. 每个 provider 的唯一主体键
3. provider 级验证状态
4. provider 资料快照
5. provider 绑定时间与最近一次使用时间
6. 身份迁移时的归属变更

### 3.3 不允许的漂移

1. 不把 `password_hash` 放进 `auth_identity`
2. 不把 refresh token hash 放进 `auth_identity`
3. 不让 `auth_identity` 取代 `user_account` 成为账号主表
4. 不再只给微信建 identity 行，而让手机号继续做“无 identity 的特殊分支”

## 4. provider 范围

当前阶段 `auth_identity.provider` 固定只支持：

1. `phone`
2. `wechat`

说明：

1. `password` 当前仍留在 `user_account.password_hash`，不进入 `auth_identity`。
2. 后续若补 OIDC 或更多社交登录，再在新任务里追加 provider，不在本轮预支。

## 5. 字段设计

| 字段名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `identity_id` | `String` | 是 | 主键，建议沿用 `authi_*` 前缀。 |
| `user_id` | `String` | 是 | 归属账号 ID，外键指向 `user_account.user_id`。 |
| `provider` | `String` | 是 | 枚举固定为 `phone`、`wechat`。 |
| `provider_uid` | `String` | 是 | provider 主主体键；`phone` 时固定等于 `phone_e164`，`wechat` 时固定存 provider 返回的稳定 UID。 |
| `provider_unionid` | `Option<String>` | 否 | 仅 `wechat` 使用；有值时作为更高优先级唯一键。 |
| `phone_e164` | `Option<String>` | 否 | 仅 `phone` provider 使用，统一存 `E.164`。 |
| `display_name` | `Option<String>` | 否 | provider 侧显示名快照；`wechat` 可用昵称，`phone` 可为空。 |
| `avatar_url` | `Option<String>` | 否 | provider 侧头像；当前主要给 `wechat` 用。 |
| `is_verified` | `bool` | 是 | 当前 identity 是否已完成可信校验。 |
| `is_primary` | `bool` | 是 | 当前 identity 是否是该 provider 在本账号下的主身份。 |
| `meta_json` | `Option<String>` | 否 | provider 扩展元信息 JSON 字符串。 |
| `bound_at` | `String` | 是 | 首次绑定到该账号的 UTC RFC3339 时间。 |
| `last_login_at` | `Option<String>` | 否 | 最近一次由该 identity 驱动完成交互式登录成功的时间。 |
| `created_at` | `String` | 是 | UTC RFC3339 创建时间。 |
| `updated_at` | `String` | 是 | UTC RFC3339 最近更新时间。 |

补充说明：

1. 当前阶段统一继续使用 UTC RFC3339 字符串时间，先与现有 Node 表与调试习惯对齐。
2. `meta_json` 当前建议直接存 JSON 字符串，避免后续第一版 schema 先引入过宽的嵌套类型。
3. `is_primary` 当前虽然大多是冗余字段，但必须先保留，为后续多 identity/同 provider 扩展留稳定位置。

## 6. provider 专属约束

### 6.1 `phone` provider

固定规则：

1. `provider_uid = phone_e164`
2. `provider_unionid = null`
3. `phone_e164 != null`
4. `is_verified = true`
5. `is_primary = true`

当前阶段约束：

1. 一个账号最多只允许一条活跃 `phone` identity
2. 它必须与 `user_account.primary_phone_e164` 一致

### 6.2 `wechat` provider

固定规则：

1. `provider_uid` 必填
2. `provider_unionid` 可空，但若存在则优先作为稳定唯一键
3. `phone_e164 = null`
4. `display_name`、`avatar_url`、`meta_json` 可按登录回调刷新
5. `is_verified = true`

当前阶段约束：

1. 一个账号最多只允许一条活跃 `wechat` identity
2. 微信首次登录但未绑定手机号时，也必须先创建这条 identity 行

## 7. 唯一约束与索引

### 7.1 必须具备的唯一约束

1. `identity_id` 主键唯一
2. `(provider, provider_uid)` 全局唯一
3. `(provider, provider_unionid)` 在 `provider_unionid != null` 时全局唯一
4. `(provider, phone_e164)` 在 `provider = phone` 且 `phone_e164 != null` 时全局唯一

### 7.2 必须具备的查询索引

1. `(user_id, provider)`
   作用：支撑 `/api/auth/me`、账号中心与 provider 检查
2. `provider_uid`
   作用：支撑微信回调身份查找
3. `provider_unionid`
   作用：支撑微信跨应用稳定身份查找
4. `phone_e164`
   作用：支撑手机号登录、手机号换绑与手机号冲突检查

## 8. 与 `user_account` 的一致性规则

### 8.1 手机号 identity 与账号主手机号必须一致

只要 `user_account.primary_phone_e164` 非空，就必须满足：

1. 同一 `user_id` 下存在一条 `provider = phone` 的 identity
2. 该行 `phone_e164 = user_account.primary_phone_e164`
3. 该行 `provider_uid = user_account.primary_phone_e164`
4. 该行 `is_primary = true`
5. 该行 `is_verified = true`

### 8.2 `login_provider` 不等于 `identity.provider`

必须明确：

1. `user_account.login_provider` 表示账号主归属方式
2. `auth_identity.provider` 表示账号下挂了哪一种外部身份

因此一个手机号正式账号在绑定微信后，完全允许出现：

1. `user_account.login_provider = phone`
2. 同时存在 `provider = phone` 与 `provider = wechat` 两条 identity

### 8.3 待绑定微信账号允许没有手机号 identity

若：

1. `user_account.account_status = pending_bind_phone`
2. `user_account.primary_phone_e164 = null`

则允许：

1. 当前账号只有一条 `wechat` identity
2. 不存在 `phone` identity

## 9. 写入场景设计

### 9.1 `POST /api/auth/entry`

当前阶段不写 `auth_identity`。

原因：

1. 密码登录仍由 `user_account.password_hash` 承担
2. 本轮不引入 `password` provider identity
3. 密码登录只接受已绑定手机号的账号，不支持邮箱、用户名或百梦号作为登录身份
4. 密码登录不创建账号，新账号只由手机号验证码登录创建

### 9.2 `POST /api/auth/phone/login`

写入规则：

1. 若账号不存在，则先创建 `user_account`
2. 同时创建一条 `provider = phone` identity
3. 若账号已存在，则校验手机号一致并更新 `last_login_at`
4. `bound_at` 只在首次绑定时写入

### 9.3 `GET /api/auth/wechat/callback`

写入规则：

1. 先按 `provider_unionid` 查；没有再按 `provider_uid` 查
2. 若 identity 已存在，则更新资料快照并写 `last_login_at`
3. 若本次是按 `provider_unionid` 命中，但 `provider_uid` 已变化，则必须把新的 `provider_uid` 一并回写为最新主映射
4. 若 identity 不存在，则创建一条新的 `wechat` identity
5. 若是首次微信登录，还要同步创建 `pending_bind_phone` 的 `user_account`

### 9.4 `POST /api/auth/wechat/bind-phone`

分两种情况：

1. 手机号未被其他账号使用
   - 当前账号写入 `phone` identity
   - 当前 `user_account` 转 `active`
2. 手机号已绑定已有正式账号
   - 不新建第二条 `phone` identity
   - 把当前壳账号下的 `wechat` identity 迁移到目标正式账号
   - 当前壳账号标记为并入

### 9.5 `POST /api/auth/phone/change`

写入规则：

1. 更新当前账号唯一一条 `phone` identity 的 `phone_e164`
2. 同步更新 `provider_uid`
3. 更新 `bound_at` 不变
4. 更新 `last_login_at` 不变
5. `updated_at = 当前时间`

说明：

1. 当前阶段手机号换绑不保留“旧手机号 identity 历史行”。
2. 历史审计交给 `auth_audit_log`，不让 identity 表承担日志表职责。

## 10. 迁移场景设计

### 10.1 从当前 Node `auth_identities` 迁移

`wechat` identity 直接一比一迁移：

| Node 列 | 新字段 |
| --- | --- |
| `id` | `identity_id` |
| `user_id` | `user_id` |
| `provider` | `provider` |
| `provider_uid` | `provider_uid` |
| `provider_unionid` | `provider_unionid` |
| `display_name` | `display_name` |
| `avatar_url` | `avatar_url` |
| `is_verified` | `is_verified` |
| `meta_json` | `meta_json` |
| `created_at` | `bound_at`、`created_at` |
| `updated_at` | `updated_at` |

`last_login_at` 初次迁移规则：

1. 先回填为 `updated_at`

### 10.2 从当前 Node `users.phone_number` 反向补 phone identity

凡是当前 `users.phone_number` 非空的账号，都要补一条 `phone` identity：

1. `provider = phone`
2. `provider_uid = phone_number`
3. `phone_e164 = phone_number`
4. `display_name = null`
5. `avatar_url = null`
6. `is_verified = phone_verified_at != null`
7. `is_primary = true`
8. `bound_at = phone_verified_at ?? created_at`
9. `last_login_at = updated_at`

### 10.3 初次迁移的兼容结论

迁移完成后，必须满足：

1. 每个带手机号的账号都有一条 `phone` identity
2. 每个微信已绑定账号都有一条 `wechat` identity
3. `/api/auth/me` 的 `wechatBound` 不再依赖旧 Node 仓储逻辑，而能直接从 `auth_identity` 派生

## 11. 读模型约束

`auth_identity` 至少要支撑以下读需求：

### 11.1 `/api/auth/me`

需要派生：

1. `wechatBound`
2. `bindingStatus`
3. `phoneNumberMasked`

其中：

1. `phoneNumberMasked` 最终以 `user_account.primary_phone_e164` 为准
2. `wechatBound` 以是否存在 `provider = wechat` identity 为准

### 11.2 `/api/auth/wechat/start` 与 `/api/auth/wechat/callback`

需要支撑：

1. 微信 callback 身份查找
2. 首次登录 identity 创建
3. 绑定后 identity 迁移

### 11.3 账号安全页

未来至少会依赖：

1. 当前账号绑定了哪些 provider
2. 是否完成手机号正式归属
3. 微信头像与昵称展示

## 12. reducer / service 落地约束

### 12.1 `module-auth` reducer 层

必须至少具备这些命令入口：

1. `create_phone_identity`
2. `upsert_phone_identity_after_phone_change`
3. `create_wechat_identity`
4. `touch_identity_last_login`
5. `refresh_wechat_identity_profile`
6. `move_identity_to_user`

### 12.2 Axum 应用层

固定负责：

1. 从微信 provider 拿到 `uid / unionid / 昵称 / 头像`
2. 决定微信 callback 应该命中已有 identity 还是创建新 identity
3. 在手机号绑定或换绑成功后，同步调用 `user_account` 与 `auth_identity` 相关 reducer

## 13. 不允许的设计漂移

后续实现时禁止出现以下情况：

1. 继续让手机号登录只写 `user_account.primary_phone_e164`，不写 `auth_identity`
2. 把微信 `unionid` 丢到 `meta_json` 里，而不是单独做唯一约束字段
3. 微信壳账号并入正式账号时直接删除 `wechat` identity 再重建，导致 `bound_at` 与历史 identity ID 丢失
4. 为图省事，把不同 provider 的唯一键都塞成一个模糊 `subject` 字段而不保留微信/手机号的显式结构

## 14. 本任务完成定义

当以下条件满足时，`设计 auth_identity` 视为完成：

1. provider 范围、字段与唯一约束已明确到可以直接编码。
2. 手机号 identity 与微信 identity 的写入规则都已固定。
3. 已和 `user_account` 明确好一致性关系。
4. 微信 identity 迁移与手机号换绑的更新策略已经明确。

## 15. 依据文件

1. `server-node/src/routes/authRoutes.ts`
2. `server-node/src/auth/authService.ts`
3. `server-node/src/repositories/authIdentityRepository.ts`
4. `server-node/src/repositories/userRepository.ts`
5. `server-node/src/db/migrations.ts`
6. `docs/prd/ACCOUNT_SYSTEM_AND_LOGIN_ENTRY_PRD_2026-04-09.md`
7. `docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md`
8. `docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md`