Persist auth store into formal tables

docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md

@@ -40,12 +40,12 @@ HTTP status server error (503 Service Unavailable)
 
 ### 3.1 认证快照同步改为非阻断
 
-`AppState::sync_auth_store_snapshot_to_spacetime` 保持导出本地快照、写入 SpacetimeDB、导入正式表的顺序，但当远端写入或导入失败时只写 warn 日志并返回 `Ok(())`。
+`AppState::sync_auth_store_snapshot_to_spacetime` 保持先导出本地认证快照，但运行期会直接调用 `import_auth_store_snapshot_json` 覆盖导入 SpacetimeDB 正式认证表，不再刷新 `auth_store_snapshot/default`；当远端导入失败时只写 warn 日志并返回 `Ok(())`。
 
 设计边界：
 
 1. 当前认证请求的即时真相源是本地 `auth_store`。
-2. SpacetimeDB 认证快照用于跨进程恢复和正式表投影。
+2. SpacetimeDB 正式认证表用于跨进程恢复；`auth_store_snapshot/default` 只保留为历史迁移和兜底恢复记录。
 3. 远端库挂起或网络异常只降级远端恢复能力，不回滚已经成功的登录、刷新、退出和资料更新。
 
 ### 3.2 Vite 补齐创作接口代理
@@ -98,7 +98,7 @@ npm run dev:web
 1. `GET http://127.0.0.1:3000/api/auth/login-options` 返回 `["phone","password"]`。
 2. `GET http://127.0.0.1:3000/api/runtime/match3d/gallery` 返回 `{"items":[]}`，不再返回 SpacetimeDB 503。
 3. 未登录请求 `POST http://127.0.0.1:3000/api/creation/match3d/sessions` 返回 `401`，说明同源请求已进入 Rust 鉴权层，不再被 Vite `404`。
-4. 隔离端口指向挂起的远端库并使用 mock 短信时，手机号验证码登录返回 `200` 和 token；日志只记录“认证快照写入 SpacetimeDB 失败，当前认证流程继续”。
+4. 隔离端口指向挂起的远端库并使用 mock 短信时，手机号验证码登录返回 `200` 和 token；日志只记录“认证快照导入 SpacetimeDB 正式表失败，当前认证流程继续”。
 
 ## 6. 后续
 

docs/technical/AUTH_SPACETIMEDB_FORMAL_TABLE_RECOVERY_STAGE3_2026-04-24.md

@@ -6,8 +6,9 @@
 
 落地口径：
 - `user_account`、`auth_identity`、`refresh_session` 作为 SpacetimeDB 中的正式认证持久化表。
+- `auth_store_projection_meta` 只记录正式认证表最近一次由认证快照导入的时间，不保存用户快照内容。
 - API 启动时优先从正式表导出兼容 `module-auth` 的认证快照，再恢复到内存认证服务。
-- 运行期认证变更仍先复用现有 `module-auth` 逻辑生成一致快照，随后同步快照并导入正式表，保证正式表与快照一致。
+- 运行期认证变更仍先复用现有 `module-auth` 逻辑生成一致快照，随后调用 `import_auth_store_snapshot_json` 直接覆盖导入正式表；不再继续刷新 `auth_store_snapshot/default`。
 - 本阶段不重写登录、刷新、登出内部业务规则，避免在 JWT、refresh rotation、微信绑定合并等复杂语义中引入行为漂移。
 
 ## 2. 非目标
@@ -21,7 +22,7 @@
 ### 3.1 启动恢复
 
 1. API 调用 `export_auth_store_snapshot_from_tables`。
-2. 若正式表已有用户、身份或会话数据，则返回兼容 `module-auth` 的 JSON 快照。
+2. 若正式表已有用户、身份或会话数据，则返回兼容 `module-auth` 的 JSON 快照，并带上 `auth_store_projection_meta/default.updated_at`。
 3. API 用 `InMemoryAuthStore::from_snapshot_json` 恢复认证服务。
 4. 若正式表为空或调用失败，则回退到 Stage 1 的 `auth_store_snapshot`。
 5. 若 Stage 1 也不可用，则回退本地 JSON 热修复文件。
@@ -29,9 +30,10 @@
 ### 3.2 运行期同步
 
 1. 登录、刷新、登出等路径继续调用当前内存认证服务。
-2. 每次认证状态变更后调用 `upsert_auth_store_snapshot`。
-3. 快照写入成功后调用 `import_auth_store_snapshot`，覆盖导入正式表。
-4. 导入失败时返回错误，避免用户误以为状态已经持久化。
+2. 每次认证状态变更后导出当前内存认证快照 JSON。
+3. API 调用 `import_auth_store_snapshot_json`，在同一 SpacetimeDB transaction 中清空并重建 `user_account/auth_identity/refresh_session`，同时更新 `auth_store_projection_meta/default.updated_at`。
+4. `upsert_auth_store_snapshot` 和 `import_auth_store_snapshot` 保留为旧库迁移入口，只服务 `auth_store_snapshot/default` 到正式认证表的历史导入，不作为运行期同步路径。
+5. 远端导入失败只记录 warn 并继续当前认证响应，避免远端库挂起时回滚已经成功的登录、刷新、退出和资料更新。
 
 ## 4. 数据重建规则
 

docs/technical/AUTH_SPACETIMEDB_TABLE_SPLIT_STAGE2_2026-04-24.md

@@ -23,7 +23,7 @@ Stage 1 已把 Rust 鉴权快照同步到 SpacetimeDB 的 `auth_store_snapshot`
 1. `POST /api/auth/refresh` 改写 `refresh_session` 表。
 2. 登录成功写 `user_account/auth_identity/refresh_session`。
 3. `logout/logout-all/revoke-session` 改写细粒度表。
-4. `auth_store_snapshot` 退化为迁移备份。
+4. `auth_store_snapshot` 退化为迁移备份；运行期若仍复用内存认证快照，也应通过 `import_auth_store_snapshot_json` 直接导入正式认证表，不再刷新 `auth_store_snapshot/default`。
 
 ## 3. 表设计落地口径
 
@@ -94,4 +94,3 @@ Stage 1 已把 Rust 鉴权快照同步到 SpacetimeDB 的 `auth_store_snapshot`
 2. Rust bindings 已刷新。
 3. `spacetime-client` 暴露导入 procedure facade。
 4. `api-server/spacetime-client/module-auth` 定向检查通过。
-

docs/technical/SPACETIMEDB_TABLE_CATALOG.md

@@ -23,7 +23,7 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
 | 领域 | 表 |
 | --- | --- |
 | 运维迁移 | `database_migration_operator`, `database_migration_import_chunk` |
-| 认证 | `auth_store_snapshot`, `user_account`, `auth_identity`, `refresh_session` |
+| 认证 | `auth_store_snapshot`, `auth_store_projection_meta`, `user_account`, `auth_identity`, `refresh_session` |
 | 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `analytics_date_dimension`, `tracking_event`, `tracking_daily_stat`, `profile_task_config`, `profile_task_progress`, `profile_task_reward_claim`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_invite_code`, `profile_referral_relation`, `profile_played_world`, `profile_membership`, `profile_recharge_order`, `profile_feedback_submission`, `profile_save_archive` |
 | RPG 运行时 | `story_session`, `story_event`, `npc_state`, `inventory_slot`, `battle_state`, `treasure_record`, `quest_record`, `quest_log`, `player_progression`, `chapter_progression` |
 | 世界创作 | `custom_world_profile`, `custom_world_session`, `custom_world_agent_session`, `custom_world_agent_message`, `custom_world_agent_operation`, `custom_world_draft_card`, `custom_world_gallery_entry` |
@@ -60,7 +60,7 @@ SELECT * FROM database_migration_operator WHERE operator_identity = '<identity>'
 
 ### `auth_store_snapshot`
 
-- 作用：保存旧内存认证仓储的整份 JSON 快照，用于迁移和恢复；后续正式表拆分后仍可作为导入/导出桥。
+- 作用：保存旧内存认证仓储的整份 JSON 快照，用于历史迁移和兜底恢复；运行期认证同步不再继续刷新 `snapshot_id = 'default'`，而是直接导入正式认证表。
 - 结构：`snapshot_id PK: String`, `snapshot_json: String`, `updated_at: Timestamp`。
 - 索引：主键 `snapshot_id`。
 
@@ -69,6 +69,17 @@ SELECT * FROM auth_store_snapshot;
 SELECT * FROM auth_store_snapshot WHERE snapshot_id = 'default';
 ```
 
+### `auth_store_projection_meta`
+
+- 作用：记录正式认证表最近一次由认证快照导入的时间，避免启动恢复时旧 `auth_store_snapshot/default` 因带有时间戳而覆盖较新的正式认证表。
+- 结构：`meta_id PK: String`, `updated_at: Timestamp`。
+- 索引：主键 `meta_id`。
+
+```sql
+SELECT * FROM auth_store_projection_meta;
+SELECT * FROM auth_store_projection_meta WHERE meta_id = 'default';
+```
+
 ### `user_account`
 
 - 作用：用户账号主表，保存用户名、公开百梦号、手机号掩码、登录方式、密码登录开关、token 版本和默认不前端展示的运营标签。