# SpacetimeDB 表说明与查询目录

> 维护状态：持续维护。凡是新增、删除或修改 `server-rs/crates/spacetime-module` 中的 `#[spacetimedb::table]`，必须同步更新本文。

## 维护规则

- 表结构以 `server-rs/crates/spacetime-module/src/lib.rs` 及其已挂载子模块为主；`server-rs/crates/spacetime-client/src/module_bindings/*_table.rs` 和 `*_type.rs` 用于校对当前生成绑定。
- `public` 表可以被客户端订阅；未标 `public` 的表是服务端真相表，通常通过 reducer / procedure / Axum facade 间接访问。
- SQL 示例使用 `<db>`、`<user_id>`、`<session_id>` 等占位符，实际执行时替换为真实值：

```powershell
spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
```

- 修改表后维护顺序：
  1. 更新 Rust 表定义和对应领域注释。
  2. 重新发布 / 生成绑定，确认 `module_bindings` 与源码一致。
  3. 更新本文的作用、结构、索引和查询 SQL。
  4. 运行 `npm run check:encoding`，避免中文文档或源码被写坏。

## 总览

| 领域       | 表                                                                                                                                                                                                                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 认证       | `auth_store_snapshot`, `user_account`, `auth_identity`, `refresh_session`                                                                                                                                            |
| 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_played_world`, `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`                  |
| 拼图       | `puzzle_agent_session`, `puzzle_agent_message`, `puzzle_work_profile`, `puzzle_runtime_run`                                                                                                                          |
| 大鱼吃小鱼 | `big_fish_creation_session`, `big_fish_agent_message`, `big_fish_asset_slot`, `big_fish_runtime_run`                                                                                                                 |
| 资产       | `asset_object`, `asset_entity_binding`                                                                                                                                                                               |
| AI 任务    | `ai_task`, `ai_task_stage`, `ai_text_chunk`, `ai_result_reference`                                                                                                                                                   |

## 认证表

### `auth_store_snapshot`

- 作用：保存旧内存认证仓储的整份 JSON 快照，用于迁移和恢复；后续正式表拆分后仍可作为导入/导出桥。
- 结构：`snapshot_id PK: String`, `snapshot_json: String`, `updated_at: Timestamp`。
- 索引：主键 `snapshot_id`。

```sql
SELECT * FROM auth_store_snapshot;
SELECT * FROM auth_store_snapshot WHERE snapshot_id = 'default';
```

### `user_account`

- 作用：用户账号主表，保存用户名、公开陶泥号、手机号掩码、登录方式、密码登录开关和 token 版本。
- 结构：`user_id PK: String`, `public_user_code: String`, `username: String`, `display_name: String`, `avatar_url: Option<String>`, `phone_number_masked: Option<String>`, `phone_number_e164: Option<String>`, `login_method: String`, `binding_status: String`, `wechat_bound: bool`, `password_hash: Option<String>`, `password_login_enabled: bool`, `token_version: u64`。
- 索引：`username`, `public_user_code`。

```sql
SELECT * FROM user_account WHERE user_id = '<user_id>';
SELECT * FROM user_account WHERE username = '<username>';
SELECT * FROM user_account WHERE public_user_code = '<public_user_code>';
```

### `auth_identity`

- 作用：第三方/手机号身份绑定表，把 provider 身份映射到内部 `user_id`。
- 结构：`identity_id PK: String`, `user_id: String`, `provider: String`, `provider_uid: String`, `provider_union_id: Option<String>`, `phone_e164: Option<String>`, `display_name: Option<String>`, `avatar_url: Option<String>`。
- 索引：`user_id`, `(provider, provider_uid)`。

```sql
SELECT * FROM auth_identity WHERE user_id = '<user_id>';
SELECT * FROM auth_identity WHERE provider = 'wechat' AND provider_uid = '<provider_uid>';
```

### `refresh_session`

- 作用：刷新令牌会话表，支持多端登录、吊销、过期和最近活跃时间查询。
- 结构：`session_id PK: String`, `user_id: String`, `refresh_token_hash: String`, `issued_by_provider: String`, `client_info_json: String`, `expires_at: String`, `revoked_at: Option<String>`, `created_at: String`, `updated_at: String`, `last_seen_at: String`。
- 索引：`user_id`, `refresh_token_hash`。

```sql
SELECT * FROM refresh_session WHERE session_id = '<session_id>';
SELECT * FROM refresh_session WHERE user_id = '<user_id>';
SELECT * FROM refresh_session WHERE refresh_token_hash = '<hash>';
```

## 运行时档案表

### `runtime_setting`

- 作用：保存用户运行时设置，目前承接音乐音量和平台主题。
- 结构：`user_id PK: String`, `music_volume: f32`, `platform_theme: RuntimePlatformTheme`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：主键 `user_id`。

```sql
SELECT * FROM runtime_setting WHERE user_id = '<user_id>';
```

### `runtime_snapshot`

- 作用：用户当前运行时快照，保存底部 Tab、游戏状态 JSON 和当前剧情 JSON。
- 结构：`user_id PK: String`, `version: u32`, `saved_at: Timestamp`, `bottom_tab: String`, `game_state_json: String`, `current_story_json: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：主键 `user_id`。

```sql
SELECT * FROM runtime_snapshot WHERE user_id = '<user_id>';
```

### `user_browse_history`

- 作用：用户浏览/进入世界历史，用于最近访问、继续浏览和去重展示。
- 结构：`browse_history_id PK: String`, `user_id: String`, `owner_user_id: String`, `profile_id: String`, `world_name: String`, `subtitle: String`, `summary_text: String`, `cover_image_src: Option<String>`, `theme_mode: RuntimeBrowseHistoryThemeMode`, `author_display_name: String`, `visited_at: Timestamp`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`user_id`, `(user_id, owner_user_id, profile_id)`。

```sql
SELECT * FROM user_browse_history WHERE user_id = '<user_id>';
SELECT * FROM user_browse_history WHERE user_id = '<user_id>' AND owner_user_id = '<owner_user_id>' AND profile_id = '<profile_id>';
```

### `profile_dashboard_state`

- 作用：个人主页聚合状态，保存钱包余额和总游玩时长。
- 结构：`user_id PK: String`, `wallet_balance: u64`, `total_play_time_ms: u64`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：主键 `user_id`。

```sql
SELECT * FROM profile_dashboard_state WHERE user_id = '<user_id>';
```

### `profile_wallet_ledger`

- 作用：钱包流水账，记录金币/货币变更来源与变更后的余额。
- 结构：`wallet_ledger_id PK: String`, `user_id: String`, `amount_delta: i64`, `balance_after: u64`, `source_type: RuntimeProfileWalletLedgerSourceType`, `created_at: Timestamp`。
- 索引：`user_id`, `(user_id, created_at)`。

```sql
SELECT * FROM profile_wallet_ledger WHERE user_id = '<user_id>';
SELECT * FROM profile_wallet_ledger WHERE user_id = '<user_id>' ORDER BY created_at DESC;
```

### `profile_redeem_code`

- 作用：运营发放的陶泥币兑换码，支持公共码、唯一码和私有码。
- 结构：`code PK: String`, `mode: RuntimeProfileRedeemCodeMode`, `reward_points: u64`, `max_uses: u32`, `global_used_count: u32`, `enabled: bool`, `allowed_user_ids: Vec<String>`, `created_by: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：主键 `code`。

```sql
SELECT * FROM profile_redeem_code WHERE code = '<CODE>';
```

### `profile_redeem_code_usage`

- 作用：记录每一次兑换行为，为公共码用户维度计次、唯一/私有码全局计次提供依据。
- 结构：`usage_id PK: String`, `code: String`, `user_id: String`, `amount_granted: u64`, `created_at: Timestamp`。
- 索引：`code`, `user_id`, `(code, user_id)`。

```sql
SELECT * FROM profile_redeem_code_usage WHERE code = '<CODE>';
SELECT * FROM profile_redeem_code_usage WHERE user_id = '<user_id>';
```

### `profile_played_world`

- 作用：记录用户玩过的世界及最后游玩时间，用于个人页历史和继续游戏入口。
- 结构：`played_world_id PK: String`, `user_id: String`, `world_key: String`, `owner_user_id: Option<String>`, `profile_id: Option<String>`, `world_type: Option<String>`, `world_title: String`, `world_subtitle: String`, `first_played_at: Timestamp`, `last_played_at: Timestamp`, `last_observed_play_time_ms: u64`。
- 索引：`user_id`, `(user_id, world_key)`, `(user_id, last_played_at)`。

```sql
SELECT * FROM profile_played_world WHERE user_id = '<user_id>';
SELECT * FROM profile_played_world WHERE user_id = '<user_id>' AND world_key = '<world_key>';
SELECT * FROM profile_played_world WHERE user_id = '<user_id>' ORDER BY last_played_at DESC;
```

### `profile_save_archive`

- 作用：用户存档列表，保存世界信息、封面、当前状态 JSON 和剧情 JSON。
- 结构：`archive_id PK: String`, `user_id: String`, `world_key: String`, `owner_user_id: Option<String>`, `profile_id: Option<String>`, `world_type: Option<String>`, `world_name: String`, `subtitle: String`, `summary_text: String`, `cover_image_src: Option<String>`, `saved_at: Timestamp`, `bottom_tab: String`, `game_state_json: String`, `current_story_json: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`user_id`, `(user_id, world_key)`, `(user_id, saved_at)`。

```sql
SELECT * FROM profile_save_archive WHERE archive_id = '<archive_id>';
SELECT * FROM profile_save_archive WHERE user_id = '<user_id>' ORDER BY saved_at DESC;
SELECT * FROM profile_save_archive WHERE user_id = '<user_id>' AND world_key = '<world_key>';
```

## RPG 运行时表

### `story_session`

- 作用：RPG 剧情会话主表，保存运行时会话、玩家、世界、最近叙事文本和可选选择函数。
- 结构：`story_session_id PK: String`, `runtime_session_id: String`, `actor_user_id: String`, `world_profile_id: String`, `initial_prompt: String`, `opening_summary: Option<String>`, `latest_narrative_text: String`, `latest_choice_function_id: Option<String>`, `status: StorySessionStatus`, `version: u32`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`runtime_session_id`, `actor_user_id`。

```sql
SELECT * FROM story_session WHERE story_session_id = '<story_session_id>';
SELECT * FROM story_session WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM story_session WHERE actor_user_id = '<user_id>' ORDER BY updated_at DESC;
```

### `story_event`

- 作用：剧情事件流水，记录每次开场/推进生成的叙事文本和选择函数。
- 结构：`event_id PK: String`, `story_session_id: String`, `event_kind: StoryEventKind`, `narrative_text: String`, `choice_function_id: Option<String>`, `created_at: Timestamp`。
- 索引：`story_session_id`。

```sql
SELECT * FROM story_event WHERE story_session_id = '<story_session_id>' ORDER BY created_at ASC;
SELECT * FROM story_event WHERE event_id = '<event_id>';
```

### `npc_state`

- 作用：NPC 在某个运行时会话中的关系、好感、招募、传闻和已见剧情状态。
- 结构：`npc_state_id PK: String`, `runtime_session_id: String`, `npc_id: String`, `npc_name: String`, `affinity: i32`, `relation_state: NpcRelationState`, `help_used: bool`, `chatted_count: u32`, `gifts_given: u32`, `recruited: bool`, `trade_stock_signature: Option<String>`, `revealed_facts: Vec<String>`, `known_attribute_rumors: Vec<String>`, `first_meaningful_contact_resolved: bool`, `seen_backstory_chapter_ids: Vec<String>`, `stance_profile: NpcStanceProfile`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`runtime_session_id`, `npc_id`, `(runtime_session_id, npc_id)`。

```sql
SELECT * FROM npc_state WHERE npc_state_id = '<npc_state_id>';
SELECT * FROM npc_state WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM npc_state WHERE runtime_session_id = '<runtime_session_id>' AND npc_id = '<npc_id>';
```

### `inventory_slot`

- 作用：背包/装备槽真相表，避免继续把物品状态塞在运行时 JSON 中。
- 结构：`slot_id PK: String`, `runtime_session_id: String`, `story_session_id: Option<String>`, `actor_user_id: String`, `container_kind: InventoryContainerKind`, `slot_key: String`, `item_id: String`, `category: String`, `name: String`, `description: Option<String>`, `quantity: u32`, `rarity: InventoryItemRarity`, `tags: Vec<String>`, `stackable: bool`, `stack_key: String`, `equipment_slot_id: Option<InventoryEquipmentSlot>`, `source_kind: InventoryItemSourceKind`, `source_reference_id: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`runtime_session_id`, `actor_user_id`, `(container_kind, slot_key)`, `item_id`。

```sql
SELECT * FROM inventory_slot WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM inventory_slot WHERE actor_user_id = '<user_id>';
SELECT * FROM inventory_slot WHERE container_kind = 'Backpack' AND slot_key = '<slot_key>';
SELECT * FROM inventory_slot WHERE item_id = '<item_id>';
```

### `battle_state`

- 作用：战斗状态真相表，保存玩家/目标血蓝、回合、奖励、上次动作和结算结果。
- 结构：`battle_state_id PK: String`, `story_session_id: String`, `runtime_session_id: String`, `actor_user_id: String`, `chapter_id: Option<String>`, `target_npc_id: String`, `target_name: String`, `battle_mode: BattleMode`, `status: BattleStatus`, `player_hp: i32`, `player_max_hp: i32`, `player_mana: i32`, `player_max_mana: i32`, `target_hp: i32`, `target_max_hp: i32`, `experience_reward: u32`, `reward_items: Vec<RuntimeItemRewardItemSnapshot>`, `turn_index: u32`, `last_action_function_id: Option<String>`, `last_action_text: Option<String>`, `last_result_text: Option<String>`, `last_damage_dealt: i32`, `last_damage_taken: i32`, `last_outcome: CombatOutcome`, `version: u32`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`story_session_id`, `runtime_session_id`, `actor_user_id`。

```sql
SELECT * FROM battle_state WHERE battle_state_id = '<battle_state_id>';
SELECT * FROM battle_state WHERE story_session_id = '<story_session_id>';
SELECT * FROM battle_state WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM battle_state WHERE actor_user_id = '<user_id>' ORDER BY updated_at DESC;
```

### `treasure_record`

- 作用：宝箱/奇遇结算记录，保存奖励物品、生命/法力/货币奖励和剧情提示。
- 结构：`treasure_record_id PK: String`, `runtime_session_id: String`, `story_session_id: String`, `actor_user_id: String`, `encounter_id: String`, `encounter_name: String`, `scene_id: Option<String>`, `scene_name: Option<String>`, `action: TreasureInteractionAction`, `reward_items: Vec<RuntimeItemRewardItemSnapshot>`, `reward_hp: u32`, `reward_mana: u32`, `reward_currency: u32`, `story_hint: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`story_session_id`, `runtime_session_id`, `actor_user_id`, `encounter_id`。

```sql
SELECT * FROM treasure_record WHERE treasure_record_id = '<treasure_record_id>';
SELECT * FROM treasure_record WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM treasure_record WHERE encounter_id = '<encounter_id>';
```

### `quest_record`

- 作用：任务主表，保存任务来源、目标、进度、奖励、叙事绑定、步骤和完成/交付时间。
- 结构：`quest_id PK: String`, `runtime_session_id: String`, `story_session_id: Option<String>`, `actor_user_id: String`, `issuer_npc_id: String`, `issuer_npc_name: String`, `scene_id: Option<String>`, `chapter_id: Option<String>`, `act_id: Option<String>`, `thread_id: Option<String>`, `contract_id: Option<String>`, `title: String`, `description: String`, `summary: String`, `objective: QuestObjectiveSnapshot`, `progress: u32`, `status: QuestStatus`, `completion_notified: bool`, `reward: QuestRewardSnapshot`, `reward_text: String`, `narrative_binding: QuestNarrativeBindingSnapshot`, `steps: Vec<QuestStepSnapshot>`, `active_step_id: Option<String>`, `visible_stage: u32`, `hidden_flags: Vec<String>`, `discovered_fact_ids: Vec<String>`, `related_carrier_ids: Vec<String>`, `consequence_ids: Vec<String>`, `created_at: Timestamp`, `updated_at: Timestamp`, `completed_at: Option<Timestamp>`, `turned_in_at: Option<Timestamp>`。
- 索引：`runtime_session_id`, `actor_user_id`, `issuer_npc_id`。

```sql
SELECT * FROM quest_record WHERE quest_id = '<quest_id>';
SELECT * FROM quest_record WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM quest_record WHERE actor_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM quest_record WHERE issuer_npc_id = '<npc_id>';
```

### `quest_log`

- 作用：任务事件流水，记录领取、信号推进、完成通知、交付等状态变化。
- 结构：`log_id PK: String`, `quest_id: String`, `runtime_session_id: String`, `actor_user_id: String`, `event_kind: QuestLogEventKind`, `status_after: QuestStatus`, `signal_kind: Option<QuestSignalKind>`, `signal: Option<QuestProgressSignal>`, `step_id: Option<String>`, `step_progress: Option<u32>`, `created_at: Timestamp`。
- 索引：`quest_id`, `runtime_session_id`, `actor_user_id`。

```sql
SELECT * FROM quest_log WHERE quest_id = '<quest_id>' ORDER BY created_at ASC;
SELECT * FROM quest_log WHERE runtime_session_id = '<runtime_session_id>';
SELECT * FROM quest_log WHERE actor_user_id = '<user_id>' ORDER BY created_at DESC;
```

### `player_progression`

- 作用：玩家成长主表，按用户保存等级、当前等级经验、总经验和待处理升级数。
- 结构：`user_id PK: String`, `level: u32`, `current_level_xp: u32`, `total_xp: u32`, `xp_to_next_level: u32`, `pending_level_ups: u32`, `last_granted_source: Option<PlayerProgressionGrantSource>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：主键 `user_id`。

```sql
SELECT * FROM player_progression WHERE user_id = '<user_id>';
```

### `chapter_progression`

- 作用：章节成长预算和实际记账表，承接计划经验、实际任务/敌对经验、击败数和节奏档位。
- 结构：`chapter_progression_id PK: String`, `user_id: String`, `chapter_id: String`, `chapter_index: u32`, `total_chapters: u32`, `entry_pseudo_level_millis: u32`, `exit_pseudo_level_millis: u32`, `entry_level: u32`, `exit_level: u32`, `planned_total_xp: u32`, `planned_quest_xp: u32`, `planned_hostile_xp: u32`, `actual_quest_xp: u32`, `actual_hostile_xp: u32`, `expected_hostile_defeat_count: u32`, `actual_hostile_defeat_count: u32`, `level_at_entry: u32`, `level_at_exit: Option<u32>`, `pace_band: ChapterPaceBand`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`user_id`, `chapter_id`, `(user_id, chapter_id)`。

```sql
SELECT * FROM chapter_progression WHERE chapter_progression_id = '<chapter_progression_id>';
SELECT * FROM chapter_progression WHERE user_id = '<user_id>';
SELECT * FROM chapter_progression WHERE user_id = '<user_id>' AND chapter_id = '<chapter_id>';
```

## 世界创作表

### `custom_world_profile`

- 作用：自定义世界正式工件真相表，承接作品库、发布、进入世界和软删除审计。
- 结构：`profile_id PK: String`, `owner_user_id: String`, `public_work_code: Option<String>`, `author_public_user_code: Option<String>`, `source_agent_session_id: Option<String>`, `publication_status: CustomWorldPublicationStatus`, `world_name: String`, `subtitle: String`, `summary_text: String`, `theme_mode: CustomWorldThemeMode`, `cover_image_src: Option<String>`, `profile_payload_json: String`, `playable_npc_count: u32`, `landmark_count: u32`, `author_display_name: String`, `published_at: Option<Timestamp>`, `deleted_at: Option<Timestamp>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`, `publication_status`。

```sql
SELECT * FROM custom_world_profile WHERE profile_id = '<profile_id>';
SELECT * FROM custom_world_profile WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM custom_world_profile WHERE publication_status = 'Published';
```

### `custom_world_session`

- 作用：旧 custom-world/sessions 传统问答流会话表，不与 Agent 会话混存。
- 结构：`session_id PK: String`, `owner_user_id: String`, `generation_mode: CustomWorldGenerationMode`, `status: CustomWorldSessionStatus`, `setting_text: String`, `creator_intent_json: Option<String>`, `question_snapshot_json: String`, `result_payload_json: Option<String>`, `last_error_message: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`。

```sql
SELECT * FROM custom_world_session WHERE session_id = '<session_id>';
SELECT * FROM custom_world_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
```

### `custom_world_agent_session`

- 作用：RPG 创作 Agent 会话聚合表，保存八锚点、草稿、发布门禁、进度、建议和 checkpoint。
- 结构：`session_id PK: String`, `owner_user_id: String`, `seed_text: String`, `current_turn: u32`, `progress_percent: u32`, `stage: RpgAgentStage`, `focus_card_id: Option<String>`, `anchor_content_json: String`, `creator_intent_json: Option<String>`, `creator_intent_readiness_json: String`, `anchor_pack_json: Option<String>`, `lock_state_json: Option<String>`, `draft_profile_json: Option<String>`, `last_assistant_reply: Option<String>`, `publish_gate_json: Option<String>`, `result_preview_json: Option<String>`, `pending_clarifications_json: String`, `quality_findings_json: String`, `suggested_actions_json: String`, `recommended_replies_json: String`, `asset_coverage_json: String`, `checkpoints_json: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`, `stage`。

```sql
SELECT * FROM custom_world_agent_session WHERE session_id = '<session_id>';
SELECT * FROM custom_world_agent_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM custom_world_agent_session WHERE stage = '<stage>';
```

### `custom_world_agent_message`

- 作用：RPG 创作 Agent 消息流水表，避免把聊天记录继续塞回 session 大 JSON。
- 结构：`message_id PK: String`, `session_id: String`, `role: RpgAgentMessageRole`, `kind: RpgAgentMessageKind`, `text: String`, `related_operation_id: Option<String>`, `created_at: Timestamp`。
- 索引：`session_id`。

```sql
SELECT * FROM custom_world_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;
```

### `custom_world_agent_operation`

- 作用：RPG 创作 Agent 异步操作真相表，承接操作阶段、进度和错误。
- 结构：`operation_id PK: String`, `session_id: String`, `operation_type: RpgAgentOperationType`, `status: RpgAgentOperationStatus`, `phase_label: String`, `phase_detail: String`, `progress: u32`, `error_message: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`session_id`。

```sql
SELECT * FROM custom_world_agent_operation WHERE operation_id = '<operation_id>';
SELECT * FROM custom_world_agent_operation WHERE session_id = '<session_id>' ORDER BY updated_at DESC;
```

### `custom_world_draft_card`

- 作用：RPG 创作草稿卡片表，拆出角色/地点/章节等卡片实体，支持详情、更新和资产状态查询。
- 结构：`card_id PK: String`, `session_id: String`, `kind: RpgAgentDraftCardKind`, `status: RpgAgentDraftCardStatus`, `title: String`, `subtitle: String`, `summary: String`, `linked_ids_json: String`, `warning_count: u32`, `asset_status: Option<CustomWorldRoleAssetStatus>`, `asset_status_label: Option<String>`, `detail_payload_json: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`session_id`, `kind`。

```sql
SELECT * FROM custom_world_draft_card WHERE card_id = '<card_id>';
SELECT * FROM custom_world_draft_card WHERE session_id = '<session_id>';
SELECT * FROM custom_world_draft_card WHERE kind = '<kind>';
```

### `custom_world_gallery_entry`

- 作用：公开画廊读模型，专供客户端订阅和广场展示，避免运行时从 profile 即席拼装。
- 可见性：`public`。
- 结构：`profile_id PK: String`, `owner_user_id: String`, `public_work_code: String`, `author_public_user_code: String`, `author_display_name: String`, `world_name: String`, `subtitle: String`, `summary_text: String`, `cover_image_src: Option<String>`, `theme_mode: CustomWorldThemeMode`, `playable_npc_count: u32`, `landmark_count: u32`, `published_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`, `theme_mode`, `public_work_code`。

```sql
SELECT * FROM custom_world_gallery_entry;
SELECT * FROM custom_world_gallery_entry WHERE owner_user_id = '<user_id>';
SELECT * FROM custom_world_gallery_entry WHERE theme_mode = '<theme_mode>';
SELECT * FROM custom_world_gallery_entry WHERE public_work_code = '<public_work_code>';
```

## 拼图表

### `puzzle_agent_session`

- 作用：拼图创作 Agent 会话表，保存种子、阶段、锚点包、草稿和已发布 profile。
- 结构：`session_id PK: String`, `owner_user_id: String`, `seed_text: String`, `current_turn: u32`, `progress_percent: u32`, `stage: PuzzleAgentStage`, `anchor_pack_json: String`, `draft_json: Option<String>`, `last_assistant_reply: Option<String>`, `published_profile_id: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`。

```sql
SELECT * FROM puzzle_agent_session WHERE session_id = '<session_id>';
SELECT * FROM puzzle_agent_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
```

### `puzzle_agent_message`

- 作用：拼图创作 Agent 聊天消息流水。
- 结构：`message_id PK: String`, `session_id: String`, `role: PuzzleAgentMessageRole`, `kind: PuzzleAgentMessageKind`, `text: String`, `created_at: Timestamp`。
- 索引：`session_id`。

```sql
SELECT * FROM puzzle_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;
```

### `puzzle_work_profile`

- 作用：拼图作品主表，保存作品信息、封面、发布状态、游玩次数和锚点包。
- 结构：`profile_id PK: String`, `work_id: String`, `owner_user_id: String`, `source_session_id: Option<String>`, `author_display_name: String`, `level_name: String`, `summary: String`, `theme_tags_json: String`, `cover_image_src: Option<String>`, `cover_asset_id: Option<String>`, `publication_status: PuzzlePublicationStatus`, `play_count: u32`, `anchor_pack_json: String`, `publish_ready: bool`, `created_at: Timestamp`, `updated_at: Timestamp`, `published_at: Option<Timestamp>`。
- 索引：`owner_user_id`, `publication_status`。

```sql
SELECT * FROM puzzle_work_profile WHERE profile_id = '<profile_id>';
SELECT * FROM puzzle_work_profile WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM puzzle_work_profile WHERE publication_status = 'Published';
```

### `puzzle_runtime_run`

- 作用：拼图游玩运行态，保存当前关卡、网格、已玩 profile 列表、标签和运行快照。
- 结构：`run_id PK: String`, `owner_user_id: String`, `entry_profile_id: String`, `current_profile_id: String`, `cleared_level_count: u32`, `current_level_index: u32`, `current_grid_size: u32`, `played_profile_ids_json: String`, `previous_level_tags_json: String`, `snapshot_json: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`。

```sql
SELECT * FROM puzzle_runtime_run WHERE run_id = '<run_id>';
SELECT * FROM puzzle_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
```

## 大鱼吃小鱼表

### `big_fish_creation_session`

- 作用：大鱼吃小鱼创作会话表，保存种子、阶段、锚点包、草稿、资产覆盖和发布就绪状态。
- 结构：`session_id PK: String`, `owner_user_id: String`, `seed_text: String`, `current_turn: u32`, `progress_percent: u32`, `stage: BigFishCreationStage`, `anchor_pack_json: String`, `draft_json: Option<String>`, `asset_coverage_json: String`, `last_assistant_reply: Option<String>`, `publish_ready: bool`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`。

```sql
SELECT * FROM big_fish_creation_session WHERE session_id = '<session_id>';
SELECT * FROM big_fish_creation_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
```

### `big_fish_agent_message`

- 作用：大鱼吃小鱼创作 Agent 消息流水。
- 结构：`message_id PK: String`, `session_id: String`, `role: BigFishAgentMessageRole`, `kind: BigFishAgentMessageKind`, `text: String`, `created_at: Timestamp`。
- 索引：`session_id`。

```sql
SELECT * FROM big_fish_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;
```

### `big_fish_asset_slot`

- 作用：大鱼吃小鱼资产槽位表，记录背景、鱼、动作等资产生成状态、URL 与 prompt 快照。
- 结构：`slot_id PK: String`, `session_id: String`, `asset_kind: BigFishAssetKind`, `level: Option<u32>`, `motion_key: Option<String>`, `status: BigFishAssetStatus`, `asset_url: Option<String>`, `prompt_snapshot: String`, `updated_at: Timestamp`。
- 索引：`session_id`。

```sql
SELECT * FROM big_fish_asset_slot WHERE slot_id = '<slot_id>';
SELECT * FROM big_fish_asset_slot WHERE session_id = '<session_id>';
```

### `big_fish_runtime_run`

- 作用：大鱼吃小鱼运行态表，保存当前 run 的快照、最后输入方向和 tick。
- 结构：`run_id PK: String`, `session_id: String`, `owner_user_id: String`, `status: BigFishRunStatus`, `snapshot_json: String`, `last_input_x: f32`, `last_input_y: f32`, `tick: u64`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`owner_user_id`, `session_id`。

```sql
SELECT * FROM big_fish_runtime_run WHERE run_id = '<run_id>';
SELECT * FROM big_fish_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM big_fish_runtime_run WHERE session_id = '<session_id>';
```

## 资产表

### `asset_object`

- 作用：正式资产对象元数据表，保存 OSS bucket/key、访问策略、大小、hash、版本和业务归属。
- 结构：`asset_object_id PK: String`, `bucket: String`, `object_key: String`, `access_policy: AssetObjectAccessPolicy`, `content_type: Option<String>`, `content_length: u64`, `content_hash: Option<String>`, `version: u32`, `source_job_id: Option<String>`, `owner_user_id: Option<String>`, `profile_id: Option<String>`, `entity_id: Option<String>`, `asset_kind: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`asset_kind`, `(bucket, object_key)`。

```sql
SELECT * FROM asset_object WHERE asset_object_id = '<asset_object_id>';
SELECT * FROM asset_object WHERE bucket = '<bucket>' AND object_key = '<object_key>';
SELECT * FROM asset_object WHERE asset_kind = '<asset_kind>';
```

### `asset_entity_binding`

- 作用：资产到业务实体槽位的绑定表，例如把角色主图、场景背景、动作视频绑定到 profile/entity/slot。
- 结构：`binding_id PK: String`, `asset_object_id: String`, `entity_kind: String`, `entity_id: String`, `slot: String`, `asset_kind: String`, `owner_user_id: Option<String>`, `profile_id: Option<String>`, `created_at: Timestamp`, `updated_at: Timestamp`。
- 索引：`(entity_kind, entity_id, slot)`, `asset_object_id`。

```sql
SELECT * FROM asset_entity_binding WHERE binding_id = '<binding_id>';
SELECT * FROM asset_entity_binding WHERE entity_kind = '<entity_kind>' AND entity_id = '<entity_id>' AND slot = '<slot>';
SELECT * FROM asset_entity_binding WHERE asset_object_id = '<asset_object_id>';
```

## AI 任务表

### `ai_task`

- 作用：AI 任务主表，保存任务类型、所属用户、来源模块、请求载荷、状态、最新输出和生命周期时间。
- 结构：`task_id PK: String`, `task_kind: AiTaskKind`, `owner_user_id: String`, `request_label: String`, `source_module: String`, `source_entity_id: Option<String>`, `request_payload_json: Option<String>`, `status: AiTaskStatus`, `failure_message: Option<String>`, `latest_text_output: Option<String>`, `latest_structured_payload_json: Option<String>`, `version: u32`, `created_at: Timestamp`, `started_at: Option<Timestamp>`, `completed_at: Option<Timestamp>`, `updated_at: Timestamp`。
- 索引：`owner_user_id`, `status`, `task_kind`。

```sql
SELECT * FROM ai_task WHERE task_id = '<task_id>';
SELECT * FROM ai_task WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM ai_task WHERE status = '<status>';
SELECT * FROM ai_task WHERE task_kind = '<task_kind>';
```

### `ai_task_stage`

- 作用：AI 任务阶段表，保存每个阶段的标签、详情、顺序、状态、输出和警告。
- 结构：`task_stage_id PK: String`, `task_id: String`, `stage_kind: AiTaskStageKind`, `label: String`, `detail: String`, `stage_order: u32`, `status: AiTaskStageStatus`, `text_output: Option<String>`, `structured_payload_json: Option<String>`, `warning_messages: Vec<String>`, `started_at: Option<Timestamp>`, `completed_at: Option<Timestamp>`。
- 索引：`task_id`, `(task_id, stage_order)`。

```sql
SELECT * FROM ai_task_stage WHERE task_id = '<task_id>' ORDER BY stage_order ASC;
SELECT * FROM ai_task_stage WHERE task_stage_id = '<task_stage_id>';
```

### `ai_text_chunk`

- 作用：AI 流式文本增量表，按任务、阶段和 sequence 保存文本 delta。
- 结构：`text_chunk_row_id PK: String`, `chunk_id: String`, `task_id: String`, `stage_kind: AiTaskStageKind`, `sequence: u32`, `delta_text: String`, `created_at: Timestamp`。
- 索引：`task_id`, `(task_id, stage_kind, sequence)`。

```sql
SELECT * FROM ai_text_chunk WHERE task_id = '<task_id>' ORDER BY sequence ASC;
SELECT * FROM ai_text_chunk WHERE task_id = '<task_id>' AND stage_kind = '<stage_kind>' ORDER BY sequence ASC;
```

### `ai_result_reference`

- 作用：AI 任务产物引用表，把任务结果关联到资产、profile、业务实体等外部结果。
- 结构：`result_reference_row_id PK: String`, `result_ref_id: String`, `task_id: String`, `reference_kind: AiResultReferenceKind`, `reference_id: String`, `label: Option<String>`, `created_at: Timestamp`。
- 索引：`task_id`。

```sql
SELECT * FROM ai_result_reference WHERE result_reference_row_id = '<row_id>';
SELECT * FROM ai_result_reference WHERE task_id = '<task_id>' ORDER BY created_at ASC;
```

## 当前维护风险

- `story_session`、`story_event`、`npc_state`、`inventory_slot`、`battle_state`、`treasure_record`、`quest_record`、`quest_log`、`player_progression`、`chapter_progression` 在 `src/lib.rs` 与 `src/gameplay/mod.rs` 都能看到表定义。当前编译入口以 `src/lib.rs` 为准；后续完成拆分时，需要删除重复定义或正式挂载子模块，并同步更新本文。
- `custom_world/*` 子模块中也保留了一份表骨架；当前生成绑定与 `src/lib.rs` 对齐，包含 `public_work_code`、`author_public_user_code` 和 `custom_world_gallery_entry.public_work_code` 索引。维护时不要只看子模块文件。