Genarrative/docs/technical/SPACETIMEDB_TABLE_CATALOG.md

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> 等占位符，实际执行时替换为真实值：

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
运维迁移	database_migration_operator, database_migration_import_chunk

运维迁移表

database_migration_operator

• 作用：迁移操作员白名单，控制导出、导入、授权和撤销迁移 procedure 的调用权限。
• 结构：operator_identity PK: Identity, created_at: Timestamp, created_by: Identity, note: String。
• 索引：主键 operator_identity。

database_migration_import_chunk

• 作用：大迁移 JSON 分片导入的私有临时表，用于规避单次 HTTP request body 过大导致的 HTTP 413；提交成功后由导入 procedure 自动清理，失败时由脚本尽量清理。
• 结构：chunk_key PK: String, upload_id: String, chunk_index: u32, chunk_count: u32, operator_identity: Identity, created_at: Timestamp, chunk: String。
• 索引：主键 chunk_key，upload_id。
• 迁移边界：不加入迁移白名单，不导出到业务迁移 JSON。

认证表

auth_store_snapshot

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

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。

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)。

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。

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。

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。

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)。

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。

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)。

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。

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)。

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)。

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)。

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。

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。

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)。

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。

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。

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。

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。

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。

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。

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)。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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。

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)。

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。

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。

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)。

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)。

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。

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 索引。维护时不要只看子模块文件。