Genarrative/server-rs/crates/module-auth/README.md

module-auth 鉴权模块 crate 说明

日期：2026-04-21

1. crate 职责

module-auth 是鉴权与会话模块 crate，当前与后续负责：

1. 用户身份、会话、风控、审计相关领域模型。
2. 手机验证码、微信登录、密码登录的模块内用例编排。
3. 与 crates/api-server 的鉴权接口装配对接。
4. 与 crates/spacetime-module 的身份表、会话表聚合对接。

2. 当前阶段说明

当前阶段已经冻结前七张鉴权基础表设计，并已完成：

1. JWT claims 设计与 platform-auth 落地。
2. refresh cookie 读取适配。
3. module-auth 真实 crate 与首版密码登录用例落地。
4. WP-A Auth DDD 分层收口，账号、会话、验证码、微信 state/绑定规则、命令输入、应用返回、领域错误和领域事件已归位到 domain / commands / application / errors / events。
5. api-server / platform-auth / spacetime-module 认证边界已核查：真实短信、微信 OAuth、JWT、cookie 和密码哈希仍由平台层或 BFF 装配承接，SpacetimeDB 侧只保留快照与表适配。

当前已覆盖的鉴权用例：

1. 密码登录
2. refresh token 轮换
3. me 查询
4. 会话吊销
5. 手机验证码登录
6. 微信登录 state 创建/消费
7. 微信身份解析与手机号绑定

3. 当前已冻结文档

1. ../../../docs/technical/SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md
2. ../../../docs/technical/SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md
3. ../../../docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md
4. ../../../docs/technical/SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md
5. ../../../docs/technical/SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md
6. ../../../docs/technical/SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md
7. ../../../docs/technical/SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md
8. ../../../docs/technical/OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md
9. ../../../docs/technical/PLATFORM_AUTH_JWT_ADAPTER_DESIGN_2026-04-21.md
10. ../../../docs/technical/PLATFORM_AUTH_REFRESH_COOKIE_ADAPTER_DESIGN_2026-04-21.md
11. ../../../docs/technical/PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md
12. ../../../docs/technical/AUTH_REFRESH_ROTATION_DESIGN_2026-04-21.md
13. ../../../docs/technical/AUTH_LOGOUT_CURRENT_SESSION_DESIGN_2026-04-21.md
14. ../../../docs/technical/PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md
15. ../../../docs/technical/SERVER_RS_DDD_WP_A_AUTH_DOMAIN_VALUE_OBJECT_REFACTOR_2026-04-29.md

4. 边界约束

1. module-auth 负责鉴权领域规则与模块级编排，不直接把供应商 SDK 或阿里云 RPC 逻辑写进主工程。
2. 短信、微信、JWT、Cookie、密码哈希等平台适配优先通过 crates/platform-auth 承接。
3. 身份与会话状态最终由 crates/spacetime-module 聚合，前端接口由 crates/api-server 暴露。
4. 当前阶段允许先使用进程内适配器把用例跑通，但后续切到 SpacetimeDB 时应保持用例接口稳定。
5. 当前 PasswordEntryService 已承接用户名校验、密码哈希校验、自动建号与重复登录复用逻辑。
6. 当前 PasswordEntryService 已提供按 user_id 查询当前用户快照的能力，供 /api/auth/me 复用。
7. 当前 module-auth 已承接进程内 refresh session 创建与轮换能力，供 /api/auth/refresh 复用。
8. 当前 module-auth 已承接当前 refresh session 吊销与用户 token_version 递增能力，供 /api/auth/logout 复用。
9. 当前手机号验证码真实 provider 由 platform-auth 注入，module-auth 只保留冷却、TTL、失败次数和账号编排，不保存验证码明文。
10. 当前 lib.rs 仍保留进程内仓储和文件持久化支撑，但不再继续拥有命令、结果、错误、事件和纯领域值对象定义。