Genarrative/docs/technical/SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md

wechat_auth_state 表设计

日期：2026-04-21

1. 文档目的

这份文档用于完成 M2 的第七条任务：设计 wechat_auth_state。

目标是把当前只存在于 Node 进程内存中的微信 OAuth state 临时仓，升级为一张可跨实例、可过期、可单次消费的 SpacetimeDB private table，并固定：

1. 微信登录 state 的职责边界
2. wechat/start 与 wechat/callback 的写入/消费顺序
3. 活跃态、已消费态、已过期态的判定规则
4. 它与 auth_identity、refresh_session、auth_audit_log 的边界

2. 当前基线

当前 Node 后端并没有数据库表，而是使用进程内临时 Map 维护微信登录状态：

1. server-node/src/services/wechatAuthStateStore.ts
2. server-node/src/auth/authService.ts
3. server-node/src/routes/authRoutes.ts

当前 Node WechatAuthStateStore 字段基线只有三项：

1. state
2. redirectPath
3. createdAt

当前 Node 已落地行为基线：

1. GET /api/auth/wechat/start 创建一个随机 state，并把 redirectPath 放进内存仓
2. WechatAuthService.buildAuthorizationUrl(...) 使用该 state 生成微信授权 URL
3. GET /api/auth/wechat/callback 进入时先 consume(state)，命中则立刻从内存仓删除
4. 若 state 未命中，则回退到默认 redirectPath 并带 auth_error
5. 即使后续微信 code 兑换、账号创建或绑定失败，当前 state 也不会恢复成可再次使用

当前实现的主要问题：

1. 状态仅存在于单进程内存，无法支撑 Axum 多实例部署
2. 进程重启后所有未完成的微信登录都会失效
3. 当前没有显式过期时间与清理策略
4. 当前 startWechatLogin(...) 会先创建 state，再校验授权场景；若是“普通手机浏览器非微信内打开”，会产生无法使用的脏状态

3. 表职责边界

3.1 wechat_auth_state 负责

1. 保存一次微信登录发起时生成的随机 state
2. 保存与这次 state 绑定的 redirect_path
3. 保存本次授权场景 scene
4. 保存 state 的过期时间与消费时间
5. 作为 wechat/callback 单次消费判定的唯一事实来源

3.2 它不负责

1. 保存微信 code、access_token、refresh_token
2. 保存微信用户资料或 provider 身份绑定结果
3. 保存长期登录会话
4. 承担账号安全审计展示

3.3 与其他表的边界

1. wechat_auth_state 只负责“这次 OAuth 跳转是否合法、是否还能被消费”
2. auth_identity 负责“微信 provider 身份最终绑定到哪个账号”
3. refresh_session 负责“微信登录成功后生成的长期浏览器登录态”
4. auth_audit_log 负责“微信登录成功、绑定手机号等长期可追溯安全事件”

4. 访问级别

wechat_auth_state 固定为 private table。

原因：

1. state 本身就是一次性安全令牌，不应该暴露给前端以外的查询面
2. redirect_path、request_user_agent 都属于登录上下文数据
3. 这张表只服务于 Axum 鉴权应用层，不应被前端直接查询或订阅

5. 字段设计

字段名	类型	必填	说明
wechat_state_id	String	是	主键，建议沿用 wxstate_* 前缀。
state_token	String	是	发往微信 OAuth 的随机 state 原文，固定唯一。
redirect_path	String	是	已归一化后的相对跳转路径，始终为站内路径。
scene	String	是	授权场景，枚举固定为 desktop、wechat_in_app。
request_user_agent	Option<String>	否	发起授权时的 UA 原文快照；缺失时为 null。
expires_at	String	是	当前 state 的失效时间，UTC RFC3339。
consumed_at	Option<String>	否	首次被成功消费的时间；未消费时为 null。
created_at	String	是	创建时间。
updated_at	String	是	最近一次状态变更时间；创建时等于 created_at，消费时更新。

补充约束：

1. state_token 继续兼容当前 Node 语义，默认由 18 字节随机数生成 36 位十六进制字符串。
2. redirect_path 必须先经过当前 normalizeRedirectPath(...) 规则归一化后再落表，不保存原始外部 URL。
3. request_user_agent 仅用于短期问题排查与场景回放，建议在 Axum 侧截断到 1024 字节以内。
4. 当前阶段不保存 request_ip，避免把短期 OAuth 状态表扩成额外的风控上下文表；若后续需要 IP 维度审计，应由 auth_audit_log 或独立风控表承担。

6. 场景与状态语义设计

6.1 scene

当前阶段固定只支持：

1. desktop
2. wechat_in_app

解释：

1. desktop 对应桌面浏览器发起的微信登录
2. wechat_in_app 对应微信内浏览器发起的微信登录

补充约束：

1. 普通手机浏览器且非微信内打开，不进入 wechat_auth_state 创建流程，直接按当前产品规则返回错误。
2. scene 必须在 wechat/start 创建表记录前先解析完成，避免写入无效状态。

6.2 活跃态

一条 wechat_auth_state 同时满足以下条件，才视为活跃可用：

1. consumed_at = null
2. expires_at > now

6.3 已消费态

满足以下条件时，视为已消费：

1. consumed_at != null

说明：

1. 已消费态不区分后续微信回调业务成功还是失败。
2. 只要进入 callback 并通过单次消费校验，这条 state 就不能再次复用。

6.4 已过期态

满足以下条件时，视为已过期：

1. consumed_at = null
2. expires_at <= now

说明：

1. 过期态不要求立即更新行状态。
2. 读取活跃态时自然排除。

7. 时效与清理策略

7.1 state 有效期

当前阶段固定设计为短时有效态：

1. 默认 TTL：15 分钟
2. 实际值由 Axum 配置提供，建议新增 wechat_auth.state_ttl_minutes

设计原因：

1. 需要覆盖桌面端扫码与微信内授权的正常完成窗口
2. 不能无限期保留可回放的 OAuth state

7.2 清理保留期

当前阶段建议保留短期排障窗口后再清理：

1. 已消费记录：consumed_at 之后保留 24 小时
2. 已过期未消费记录：expires_at 之后保留 24 小时

说明：

1. 不在消费成功时立即删行，避免短期内无法排查重复回调、授权失败等问题
2. 这张表不是审计表，不允许无限期堆积

8. 写入与消费规则

8.1 GET /api/auth/wechat/start

固定流程：

1. 先归一化 redirectPath；空值或非法值回退到默认 redirectPath
2. 先根据 userAgent 解析 scene
3. 若场景是“普通手机浏览器且非微信内打开”，直接返回错误，不写表
4. 生成随机 state_token
5. 计算 expires_at = now + ttl
6. 写入一条新的 wechat_auth_state
7. 使用 state_token + scene + callbackUrl 生成最终授权 URL

关键约束：

1. 每次点击微信登录都创建新记录，不复用旧记录。
2. 不按 redirect_path 去重，允许同一用户在多个标签页并行发起微信登录。
3. 只有场景校验通过后才允许写表，避免制造无意义脏数据。

8.2 GET /api/auth/wechat/callback

固定流程：

1. 读取请求里的 state
2. 若 state 为空，直接使用默认 redirectPath 重定向并带 auth_error
3. 按 state_token 查询对应记录
4. 若记录不存在、已过期或已消费，直接使用默认 redirectPath 重定向并带 auth_error
5. 若命中活跃记录，先缓存其 redirect_path
6. 在进行微信 code 兑换、身份查找、账号创建前，先执行单次消费：
   • consumed_at = now
   • updated_at = now
7. 若单次消费成功，再继续后续微信登录主链
8. 后续主链无论成功还是失败，都使用第 5 步缓存的 redirect_path 进行最终跳转

关键约束：

1. state 必须“先消费、后换取微信用户资料”，保持和当前 Node 行为一致，避免同一 state 被重复回放。
2. 消费成功后，即使后续 provider 失败、用户创建失败或绑定失败，也不回滚 consumed_at。
3. 竞争消费时只允许首个请求成功，后到请求一律视为无效或已失效回调。

9. 唯一约束与索引

9.1 必须具备的唯一约束

1. wechat_state_id 主键唯一
2. state_token 全局唯一

9.2 必须具备的查询索引

1. (state_token) 作用：支撑 callback 按 state 精确查找
2. (expires_at) 作用：支撑过期数据清理
3. (consumed_at) 作用：支撑已消费数据清理

说明：

1. 当前阶段不需要按 redirect_path、scene 建业务查询索引，因为主链只按 state_token 精确查找。
2. 清理作业以时间窗口为主，不需要复杂多列排序索引。

10. 读取规则

当前阶段 wechat_auth_state 不直接对外暴露 DTO。

它只支撑后端内部这几类读取：

1. find_by_state_token(state_token)
2. find_active_by_state_token(state_token)
3. list_expired_before(deadline)
4. list_consumed_before(deadline)

读取约束：

1. “是否活跃”由应用层按 consumed_at 与 expires_at 判定，不引入额外状态枚举列。
2. 读取命中后，redirect_path 只用于当前 callback 的最终跳转，不向前端原样暴露为查询接口。
3. 前端不允许直接查看自己仍持有多少个待消费微信 state。

11. 与当前 Node 内存状态仓的映射关系

Node 字段/行为	新字段/行为	迁移规则
state	state_token	原语义保留，继续作为微信 OAuth 回调校验值。
redirectPath	redirect_path	重命名迁移；写入前必须先归一化为站内路径。
createdAt	created_at	原样迁移为 UTC RFC3339。
无	wechat_state_id	新增内部主键。
无	scene	新增授权场景字段，值来自 userAgent 解析。
无	request_user_agent	新增请求上下文字段，用于短期排障。
无	expires_at	新增显式过期时间。
consume(state) 后直接删除	consumed_at 标记消费	改为“标记消费 + 延迟清理”，不再立刻硬删除。
无	updated_at	新增状态更新时间，用于消费与清理追踪。

12. reducer / service 落地约束

12.1 module-auth reducer 层

必须至少具备：

1. create_wechat_auth_state
2. consume_wechat_auth_state
3. purge_wechat_auth_state

说明：

1. create_wechat_auth_state 只负责插入新的待消费记录。
2. consume_wechat_auth_state 只允许消费“当前仍活跃”的记录。
3. purge_wechat_auth_state 只负责清理保留期外的已消费或已过期记录。

12.2 Axum 应用层

固定负责：

1. 归一化 redirectPath
2. 根据 userAgent 判定 scene
3. 生成随机 state_token
4. 计算 expires_at
5. 在 callback 中先读取、再执行单次消费、再继续微信 provider 主链
6. 对“无效 state / 过期 state / 已消费 state”统一生成兼容当前前端的 auth_error 跳转结果

13. 不允许的设计漂移

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

1. 继续把微信 OAuth state 只放在 Axum 进程内存里，当成多实例时代的真相源
2. 在普通手机浏览器非微信内打开时仍然先创建 wechat_auth_state
3. 为了省步骤，把 state 改成“登录成功后再消费”
4. 把微信 code、access_token、用户资料 JSON 直接写进 wechat_auth_state
5. 消费成功后立刻硬删除记录，导致无法区分“重复回调”与“从未发起过该 state”
6. 把 wechat_auth_state 暴露成前端可直接查询的公共表或订阅面

14. 本任务完成定义

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

1. 当前 Node 内存状态仓已被完整映射为可落表的短期状态模型。
2. wechat/start 与 wechat/callback 的写入、消费、过期、清理规则已固定。
3. 已和 auth_identity、refresh_session、auth_audit_log 明确切开职责。
4. 后续可以直接按这份文档编码 module-auth reducer、Axum 仓储接口与清理任务。

15. 依据文件

1. server-node/src/services/wechatAuthStateStore.ts
2. server-node/src/auth/authService.ts
3. server-node/src/routes/authRoutes.ts
4. server-node/src/services/wechatAuthService.ts
5. packages/shared/src/contracts/auth.ts
6. docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md
7. docs/technical/SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md
8. docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md