GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
49468441bc7892adca64de2e916d13fb288c9890
Genarrative/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
高物 e30b733b17 1
2026-05-11 16:15:48 +08:00

61 KiB
Raw Blame History

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，避免中文文档或源码被写坏。

总览

领域 表
运维迁移 database_migration_operator, database_migration_import_chunk
认证 auth_store_snapshot, 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
拼图 puzzle_agent_session, puzzle_agent_message, puzzle_work_profile, puzzle_event, puzzle_runtime_run, puzzle_leaderboard_entry
抓大鹅 Match3D match3d_agent_session, match3d_agent_message, match3d_work_profile, match3d_runtime_run
方洞挑战 square_hole_agent_session, square_hole_agent_message, square_hole_work_profile, square_hole_runtime_run
视觉小说 visual_novel_agent_session, visual_novel_agent_message, visual_novel_work_profile, visual_novel_runtime_run, visual_novel_runtime_history_entry, visual_novel_runtime_event
大鱼吃小鱼 big_fish_creation_session, big_fish_agent_message, big_fish_asset_slot, big_fish_event, big_fish_runtime_run
资产 asset_object, asset_entity_binding, asset_event
AI 任务 ai_task, ai_task_stage, ai_text_chunk, ai_result_reference, ai_task_event

运维迁移表

database_migration_operator

  • 作用：数据库迁移操作员授权表，用于限制导出、导入和增量导入等 private 表迁移能力，避免任意登录身份读取或覆盖全库真相。
  • 结构：operator_identity PK: Identity, created_at: Timestamp, created_by: Identity, note: String。
  • 索引：主键 operator_identity。
  • 迁移说明：该表是迁移权限本身，不纳入 migration.rs 的业务表导出白名单。
SELECT * FROM database_migration_operator;
SELECT * FROM database_migration_operator WHERE operator_identity = '<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: String, password_login_enabled: bool, token_version: u64, user_tags: Option<Vec<String>>。
  • 说明：user_tags 数据库默认 None，业务读取时按空数组归一化；只允许后端白名单投影到特定业务接口，不得在登录态、个人资料等通用前端响应中直接暴露。
  • 索引：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。
  • 新用户注册成功后默认写入 10 个光点，余额仍以后端钱包 projection 为准。
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)。
  • 注册赠送流水来源为 new_user_registration_reward，流水 ID 固定为 new-user-registration:{user_id}，用于保证重复调用不重复发放。
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;

analytics_date_dimension

  • 作用：分析日期维表，每个北京时间业务自然日一行，用于把日桶映射到周、月、季度和年。
  • 结构：date_key PK: i64, calendar_date: String, weekday: u8, iso_week_key: i32, week_start_date_key: i64, week_end_date_key: i64, month_key: i32, month_start_date_key: i64, month_end_date_key: i64, quarter_key: i32, quarter_start_date_key: i64, quarter_end_date_key: i64, year_key: i32, year_start_date_key: i64, year_end_date_key: i64, created_at: Timestamp, updated_at: Timestamp。
  • 索引：主键 date_key，iso_week_key，month_key，quarter_key，year_key。
  • 写入口：ensure_analytics_date_dimension_for_date({ date_key }) 幂等补单日；seed_analytics_date_dimensions({ start_date, end_date }) 按 YYYY-MM-DD 闭区间幂等批量补种，单次最多 3660 天；通用埋点写入 record_tracking_event_and_return 会在写入 tracking_event / tracking_daily_stat 前按同一 day_key 自动幂等补齐当日维表。
  • 口径：date_key 沿用当前埋点日桶 floor((occurred_at_micros + 8h) / 1d)，calendar_date 是该北京时间业务日的公历日期。
SELECT * FROM analytics_date_dimension WHERE date_key = <date_key>;
SELECT * FROM analytics_date_dimension WHERE iso_week_key = 202501 ORDER BY date_key;
SELECT * FROM analytics_date_dimension WHERE month_key = 202402 ORDER BY date_key;

tracking_event

  • 作用：埋点原始事件表，保存整站、作品、模块和用户层的原始事实。
  • 结构：event_id PK: String, event_key: String, scope_kind: RuntimeTrackingScopeKind, scope_id: String, day_key: i64, user_id: Option<String>, owner_user_id: Option<String>, profile_id: Option<String>, module_key: Option<String>, metadata_json: String, occurred_at: Timestamp。
  • 索引：event_key, (scope_kind, scope_id), (user_id, occurred_at)。
SELECT * FROM tracking_event WHERE event_id = '<event_id>';
SELECT * FROM tracking_event WHERE event_key = '<event_key>' ORDER BY occurred_at DESC;
SELECT * FROM tracking_event WHERE scope_kind = 'User' AND scope_id = '<user_id>' ORDER BY occurred_at DESC;

tracking_daily_stat

  • 作用：埋点按北京时间自然日聚合后的真实表，供任务统计和快速查询使用。
  • 结构：stat_id PK: String, event_key: String, scope_kind: RuntimeTrackingScopeKind, scope_id: String, day_key: i64, count: u32, first_occurred_at: Timestamp, last_occurred_at: Timestamp, updated_at: Timestamp。
  • 索引：(event_key, day_key), (scope_kind, scope_id, day_key)。
SELECT * FROM tracking_daily_stat WHERE stat_id = '<stat_id>';
SELECT * FROM tracking_daily_stat WHERE scope_kind = 'User' AND scope_id = '<user_id>' ORDER BY day_key DESC;

profile_task_config

  • 作用：个人任务配置表，后台可修改每日登录等任务的奖励、阈值、启用状态和排序。
  • 结构：task_id PK: String, title: String, description: String, event_key: String, cycle: RuntimeProfileTaskCycle, scope_kind: RuntimeTrackingScopeKind, threshold: u32, reward_points: u64, enabled: bool, sort_order: i32, created_by: String, created_at: Timestamp, updated_by: String, updated_at: Timestamp。
  • 索引：主键 task_id。
SELECT * FROM profile_task_config WHERE task_id = 'daily_login';
SELECT * FROM profile_task_config ORDER BY updated_at DESC;

profile_task_progress

  • 作用：个人任务进度表，保存用户在某个自然日的任务进度和状态快照。
  • 结构：progress_id PK: String, user_id: String, task_id: String, day_key: i64, progress_count: u32, threshold: u32, status: RuntimeProfileTaskStatus, updated_at: Timestamp。
  • 索引：user_id, (user_id, task_id)。
SELECT * FROM profile_task_progress WHERE user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM profile_task_progress WHERE user_id = '<user_id>' AND task_id = 'daily_login' ORDER BY day_key DESC;

profile_task_reward_claim

  • 作用：个人任务领奖记录表，记录用户、任务、自然日、奖励和对应钱包流水。
  • 结构：claim_id PK: String, user_id: String, task_id: String, day_key: i64, reward_points: u64, wallet_ledger_id: String, claimed_at: Timestamp。
  • 索引：user_id, (user_id, task_id)。
SELECT * FROM profile_task_reward_claim WHERE user_id = '<user_id>' ORDER BY claimed_at DESC;
SELECT * FROM profile_task_reward_claim WHERE claim_id = '<user_id>:daily_login:<day_key>';

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。
  • 后台读取：GET /admin/api/profile/redeem-codes 从该表返回已有兑换码，后台列表点击后通过 upsert 修改同一条记录。
SELECT * FROM profile_redeem_code WHERE code = '<CODE>';
SELECT * FROM profile_redeem_code ORDER BY updated_at DESC;

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_invite_code

  • 作用：用户邀请中心的邀请码主表，也承载后台运营预置邀请码和使用后授予账号的运营标签配置。
  • 结构：user_id PK: String, invite_code: String, metadata_json: String, created_at: Timestamp, updated_at: Timestamp, starts_at: Option<Timestamp>, expires_at: Option<Timestamp>。
  • 索引：主键 user_id，唯一索引 invite_code。
  • 后台读取：GET /admin/api/profile/invite-codes 只返回 user_id 以 admin: 开头的后台预置码；普通用户自己的邀请码不得进入后台运营列表。
  • 说明：使用该邀请码后授予的标签存放在 metadata_json.userTags，服务端兼容读取 metadata_json.user_tags；用户注册填写该邀请码后合并进 user_account.user_tags，不回改历史用户。
SELECT * FROM profile_invite_code WHERE user_id = '<user_id>';
SELECT * FROM profile_invite_code WHERE invite_code = '<invite_code>';
SELECT * FROM profile_invite_code WHERE user_id LIKE 'admin:%' ORDER BY updated_at DESC;

profile_referral_relation

  • 作用：邀请关系表，记录被邀请人与邀请人之间的一次性绑定关系，以及双方奖励是否已发放。
  • 结构：invitee_user_id PK: String, inviter_user_id: String, invite_code: String, inviter_reward_granted: bool, invitee_reward_granted: bool, bound_at: Timestamp。
  • 索引：inviter_user_id, (inviter_user_id, bound_at)。
SELECT * FROM profile_referral_relation WHERE invitee_user_id = '<invitee_user_id>';
SELECT * FROM profile_referral_relation WHERE inviter_user_id = '<inviter_user_id>';
SELECT * FROM profile_referral_relation WHERE inviter_user_id = '<inviter_user_id>' ORDER BY bound_at DESC;

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;

public_work_play_daily_stat

  • 作用：跨玩法公开作品的每日游玩聚合表，用于 gallery 近 7 日热度和排序，不把运行统计散落在各玩法私有表。
  • 结构：stat_id PK: String, source_type: String, owner_user_id: String, profile_id: String, played_day: i64, play_count: u32, updated_at: Timestamp。
  • 索引：主键 stat_id，(source_type, profile_id, played_day)。
SELECT * FROM public_work_play_daily_stat WHERE stat_id = '<stat_id>';
SELECT * FROM public_work_play_daily_stat WHERE source_type = '<source_type>' AND profile_id = '<profile_id>';

public_work_like

  • 作用：跨玩法公开作品的点赞去重表，按用户维度保证同一用户对同一作品只计一次点赞。
  • 结构：like_id PK: String, source_type: String, owner_user_id: String, profile_id: String, user_id: String, liked_at: Timestamp。
  • 索引：主键 like_id，(source_type, profile_id)，user_id。
SELECT * FROM public_work_like WHERE like_id = '<like_id>';
SELECT * FROM public_work_like WHERE source_type = '<source_type>' AND profile_id = '<profile_id>';
SELECT * FROM public_work_like WHERE user_id = '<user_id>';

profile_membership

  • 作用：用户会员状态表，保存会员状态、档位、起止时间和最近更新时间。
  • 结构：user_id PK: String, status: RuntimeProfileMembershipStatus, tier: RuntimeProfileMembershipTier, started_at: Timestamp, expires_at: Timestamp, updated_at: Timestamp。
  • 索引：主键 user_id。
SELECT * FROM profile_membership WHERE user_id = '<user_id>';

profile_recharge_order

  • 作用：充值订单表，记录用户购买光点或会员的订单、支付渠道、支付时间、积分变更和会员到期时间。
  • 结构：order_id PK: String, user_id: String, product_id: String, product_title: String, kind: RuntimeProfileRechargeProductKind, amount_cents: u64, status: RuntimeProfileRechargeOrderStatus, payment_channel: String, paid_at: Timestamp, created_at: Timestamp, points_delta: i64, membership_expires_at: Option<Timestamp>。
  • 索引：user_id, (user_id, created_at)。
SELECT * FROM profile_recharge_order WHERE order_id = '<order_id>';
SELECT * FROM profile_recharge_order WHERE user_id = '<user_id>' ORDER BY created_at DESC;

profile_feedback_submission

  • 作用：保存“我的”页签帮助与反馈提交记录，关联当前登录用户的问题描述、选填联系电话和图片凭证快照。
  • 结构：feedback_id PK: String, user_id: String, description: String, contact_phone: Option<String>, evidence_json: String, status: RuntimeProfileFeedbackStatus, created_at: Timestamp, updated_at: Timestamp。
  • 索引：user_id, (user_id, created_at)。
  • 访问边界：私有表。前端只通过 POST /api/profile/feedback 提交，HTTP 回包只返回凭证元数据，不回显 evidence_json 中的 Data URL。
SELECT * FROM profile_feedback_submission WHERE feedback_id = '<feedback_id>';
SELECT * FROM profile_feedback_submission WHERE user_id = '<user_id>' ORDER BY created_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。
  • 说明：填表式拼图入口会在点击“拼图”时立即创建空 session；生成草稿前的表单自动保存复用 seed_text 与 draft_json，不新增表字段，stage 保持 CollectingAnchors。
  • 索引：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, work_title: String, work_description: String, level_name: String, summary: String, theme_tags_json: String, cover_image_src: Option<String>, cover_asset_id: Option<String>, levels_json: String, publication_status: PuzzlePublicationStatus, play_count: u32, anchor_pack_json: String, publish_ready: bool, created_at: Timestamp, updated_at: Timestamp, published_at: Option<Timestamp>。
  • 说明：work_title/work_description 是作品详情页展示来源；levels_json 保存拼图关卡列表，level_name/summary 继续作为首关兼容字段和旧数据回退来源。
  • 说明：拼图初始表单草稿也写入本表作为创作中心卡片投影；未生成图片前 cover_image_src = None、publish_ready = false，再次打开草稿时通过 source_session_id 恢复表单。
  • 索引：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_event

  • 作用：拼图创作事件表，目前记录作品发布成功事实，供订阅端、BFF 或审计流程感知创作流已产出公开作品；正式作品状态仍以 puzzle_work_profile 和 puzzle_agent_session 为准。
  • 可见性：public event。
  • 结构：event_id PK: String, profile_id: String, work_id: String, session_id: Option<String>, owner_user_id: String, event_kind: PuzzleEventKind, occurred_at: Timestamp。
  • 索引：profile_id, owner_user_id。
SELECT * FROM puzzle_event WHERE profile_id = '<profile_id>' ORDER BY occurred_at ASC;
SELECT * FROM puzzle_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_at DESC;

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;

puzzle_leaderboard_entry

  • 作用：拼图关卡真实成绩表，按用户、作品和网格规格保留最佳成绩，用于结算弹窗排行榜。
  • 结构：entry_id PK: String, profile_id: String, grid_size: u32, user_id: String, nickname: String, best_elapsed_ms: u64, last_run_id: String, updated_at: Timestamp。
  • 索引：profile_id + grid_size, user_id + profile_id + grid_size。
SELECT * FROM puzzle_leaderboard_entry WHERE profile_id = '<profile_id>' AND grid_size = 4 ORDER BY best_elapsed_ms ASC;
SELECT * FROM puzzle_leaderboard_entry WHERE user_id = '<user_id>' AND profile_id = '<profile_id>' AND grid_size = 4;

抓大鹅 Match3D 表

match3d_agent_session

  • 作用：抓大鹅 Match3D 创作 Agent 会话表，保存种子、配置 JSON、草稿 JSON 和发布 profile 指针。
  • 结构：session_id PK: String, owner_user_id: String, seed_text: String, current_turn: u32, progress_percent: u32, stage: String, config_json: String, draft_json: String, last_assistant_reply: String, published_profile_id: String, created_at: Timestamp, updated_at: Timestamp。
  • 索引：owner_user_id。
SELECT * FROM match3d_agent_session WHERE session_id = '<session_id>';
SELECT * FROM match3d_agent_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;

match3d_agent_message

  • 作用：抓大鹅 Match3D 创作 Agent 消息流水。
  • 结构：message_id PK: String, session_id: String, role: String, kind: String, text: String, created_at: Timestamp。
  • 索引：session_id。
SELECT * FROM match3d_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;

match3d_work_profile

  • 作用：抓大鹅 Match3D 作品主表，保存作品基础信息、配置、发布状态、游玩次数和草稿生成出的独立物品素材引用。
  • 结构：profile_id PK: String, owner_user_id: String, source_session_id: String, author_display_name: String, game_name: String, theme_text: String, summary_text: String, tags_json: String, cover_image_src: String, cover_asset_id: String, clear_count: u32, difficulty: u32, config_json: String, publication_status: String, play_count: u32, updated_at: Timestamp, published_at: Option<Timestamp>, generated_item_assets_json: Option<String>。
  • 说明：generated_item_assets_json 保存 Match3DGeneratedItemAsset 数组 JSON，用于草稿页退出后从作品架重进时恢复 3D素材 Tab 中的切割图片和 GLB 模型预览；运行态也通过该字段拿到 modelSrc / modelObjectKey 并优先渲染生成模型。基础信息自动保存和发布必须保留该字段。
  • 索引：owner_user_id, publication_status。
SELECT * FROM match3d_work_profile WHERE profile_id = '<profile_id>';
SELECT * FROM match3d_work_profile WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM match3d_work_profile WHERE publication_status = 'Published';

match3d_runtime_run

  • 作用：抓大鹅 Match3D 单局运行态表，保存权威快照、快照版本、胜负状态和成绩基础字段。
  • 结构：run_id PK: String, owner_user_id: String, profile_id: String, status: String, snapshot_version: u32, started_at_ms: i64, duration_limit_ms: i64, finished_at_ms: i64, elapsed_ms: i64, clear_count: u32, total_item_count: u32, cleared_item_count: u32, failure_reason: String, snapshot_json: String, created_at: Timestamp, updated_at: Timestamp。
  • 索引：owner_user_id, profile_id。
SELECT * FROM match3d_runtime_run WHERE run_id = '<run_id>';
SELECT * FROM match3d_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM match3d_runtime_run WHERE profile_id = '<profile_id>';

方洞挑战表

square_hole_agent_session

  • 作用：方洞挑战创作 Agent 会话表，保存种子、配置 JSON、草稿 JSON 和发布 profile 指针。
  • 结构：session_id PK: String, owner_user_id: String, seed_text: String, current_turn: u32, progress_percent: u32, stage: String, config_json: String, draft_json: String, last_assistant_reply: String, published_profile_id: String, created_at: Timestamp, updated_at: Timestamp。
  • 索引：owner_user_id。
SELECT * FROM square_hole_agent_session WHERE session_id = '<session_id>';
SELECT * FROM square_hole_agent_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;

square_hole_agent_message

  • 作用：方洞挑战创作 Agent 消息流水。
  • 结构：message_id PK: String, session_id: String, role: String, kind: String, text: String, created_at: Timestamp。
  • 索引：session_id。
SELECT * FROM square_hole_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;

square_hole_work_profile

  • 作用：方洞挑战作品主表，保存作品基础信息、反直觉规则、配置、发布状态和游玩次数。
  • 结构：profile_id PK: String, work_id: String, owner_user_id: String, source_session_id: String, author_display_name: String, game_name: String, theme_text: String, twist_rule: String, summary_text: String, tags_json: String, cover_image_src: String, shape_count: u32, difficulty: u32, config_json: String, publication_status: String, play_count: u32, updated_at: Timestamp, published_at: Option<Timestamp>。
  • 索引：owner_user_id, publication_status。
SELECT * FROM square_hole_work_profile WHERE profile_id = '<profile_id>';
SELECT * FROM square_hole_work_profile WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM square_hole_work_profile WHERE publication_status = 'Published';

square_hole_runtime_run

  • 作用：方洞挑战单局运行态表，保存后端权威快照、快照版本、胜负状态和成绩基础字段。
  • 结构：run_id PK: String, owner_user_id: String, profile_id: String, status: String, snapshot_version: u64, started_at_ms: i64, duration_limit_ms: i64, finished_at_ms: i64, elapsed_ms: i64, total_shape_count: u32, completed_shape_count: u32, score: u32, snapshot_json: String, created_at: Timestamp, updated_at: Timestamp。
  • 索引：owner_user_id, profile_id。
SELECT * FROM square_hole_runtime_run WHERE run_id = '<run_id>';
SELECT * FROM square_hole_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM square_hole_runtime_run WHERE profile_id = '<profile_id>';

视觉小说表

VN-13 复核：当前视觉小说首版只保留本节 6 张表；visual_novel_runtime_history_entry 和 visual_novel_runtime_event 均不得扩展成回放数据源。维护入口见 视觉小说模板实现收口与交接说明。

visual_novel_agent_session

  • 作用：视觉小说创作 Agent 会话主表，保存创建起点、源资产、当前阶段、底稿 JSON、待执行 action 和发布 profile 指针。
  • 结构：session_id PK: String, owner_user_id: String, source_mode: String, status: String, seed_text: String, source_asset_ids_json: String, current_turn: u32, progress_percent: u32, draft_json: String, pending_action_json: String, last_assistant_reply: String, published_profile_id: String, created_at: Timestamp, updated_at: Timestamp。
  • 索引：owner_user_id。
SELECT * FROM visual_novel_agent_session WHERE session_id = '<session_id>';
SELECT * FROM visual_novel_agent_session WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;

visual_novel_agent_message

  • 作用：视觉小说创作 Agent 消息流水，保存用户输入和模型回复。
  • 结构：message_id PK: String, session_id: String, role: String, kind: String, text: String, created_at: Timestamp。
  • 索引：session_id。
SELECT * FROM visual_novel_agent_message WHERE session_id = '<session_id>' ORDER BY created_at ASC;

visual_novel_work_profile

  • 作用：视觉小说作品草稿 / 发布 profile 表，保存平台作品摘要字段、源资产引用、完整 VisualNovelResultDraft JSON、发布状态和游玩次数。
  • 结构：profile_id PK: String, work_id: String, owner_user_id: String, source_session_id: String, author_display_name: String, work_title: String, work_description: String, tags_json: String, cover_image_src: String, source_asset_ids_json: String, draft_json: String, publication_status: String, publish_ready: bool, play_count: u32, created_at: Timestamp, updated_at: Timestamp, published_at: Option<Timestamp>。
  • 索引：owner_user_id, publication_status。
SELECT * FROM visual_novel_work_profile WHERE profile_id = '<profile_id>';
SELECT * FROM visual_novel_work_profile WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM visual_novel_work_profile WHERE publication_status = 'published';

visual_novel_runtime_run

  • 作用：视觉小说测试或正式运行态表，保存当前场景、阶段、可见角色、旗标、指标、可选项和运行快照 JSON。
  • 结构：run_id PK: String, owner_user_id: String, profile_id: String, mode: String, status: String, current_scene_id: String, current_phase_id: String, visible_character_ids_json: String, flags_json: String, metrics_json: String, available_choices_json: String, text_mode_enabled: bool, snapshot_json: String, created_at: Timestamp, updated_at: Timestamp。
  • 索引：owner_user_id, profile_id。
SELECT * FROM visual_novel_runtime_run WHERE run_id = '<run_id>';
SELECT * FROM visual_novel_runtime_run WHERE owner_user_id = '<user_id>' ORDER BY updated_at DESC;
SELECT * FROM visual_novel_runtime_run WHERE profile_id = '<profile_id>';

visual_novel_runtime_history_entry

  • 作用：视觉小说运行时历史表，保存每轮玩家 / 模型 / 系统事实、step JSON 和快照哈希，用于继续体验与历史重生成边界；不是回放表。
  • 结构：entry_id PK: String, run_id: String, owner_user_id: String, profile_id: String, turn_index: u32, source: String, action_text: String, steps_json: String, snapshot_before_hash: String, snapshot_after_hash: String, created_at: Timestamp。
  • 索引：run_id, owner_user_id。
SELECT * FROM visual_novel_runtime_history_entry WHERE run_id = '<run_id>' ORDER BY turn_index ASC;
SELECT * FROM visual_novel_runtime_history_entry WHERE owner_user_id = '<user_id>' ORDER BY created_at DESC;

visual_novel_runtime_event

  • 作用：视觉小说运行时审计事件表，用于订阅端、BFF 或排障流程感知 run 事实；该表明确不是 replay、分享回放或片段回放数据源。
  • 可见性：public event。
  • 结构：event_id PK: String, run_id: String, owner_user_id: String, profile_id: String, event_kind: String, client_event_id: String, history_entry_id: String, payload_json: String, occurred_at: Timestamp。
  • 索引：run_id, owner_user_id。
SELECT * FROM visual_novel_runtime_event WHERE run_id = '<run_id>' ORDER BY occurred_at ASC;
SELECT * FROM visual_novel_runtime_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_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, play_count: u32, 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_event

  • 作用：大鱼吃小鱼创作事件表，目前记录发布门禁评估结果，供订阅端、BFF 或审计流程感知草稿是否达到发布条件；正式作品状态仍以 big_fish_creation_session 和 big_fish_asset_slot 为准。
  • 可见性：public event。
  • 结构：event_id PK: String, session_id: String, owner_user_id: String, event_kind: BigFishEventKind, publish_ready: bool, blockers_json: String, occurred_at: Timestamp。
  • 索引：session_id, owner_user_id。
SELECT * FROM big_fish_event WHERE session_id = '<session_id>' ORDER BY occurred_at ASC;
SELECT * FROM big_fish_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_at DESC;

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>';

asset_event

  • 作用：资产事件表，目前记录对象确认和实体槽位绑定变更事实，供订阅端、BFF 或审计流程感知资产主链变化；正式资产状态仍以 asset_object 和 asset_entity_binding 为准。
  • 可见性：public event。
  • 结构：event_id PK: String, asset_object_id: String, binding_id: Option<String>, event_kind: AssetEventKind, asset_kind: String, owner_user_id: Option<String>, profile_id: Option<String>, entity_kind: Option<String>, entity_id: Option<String>, slot: Option<String>, occurred_at: Timestamp。
  • 索引：asset_object_id, owner_user_id, profile_id。
SELECT * FROM asset_event WHERE asset_object_id = '<asset_object_id>' ORDER BY occurred_at ASC;
SELECT * FROM asset_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_at DESC;
SELECT * FROM asset_event WHERE profile_id = '<profile_id>' ORDER BY occurred_at DESC;

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;

ai_task_event

  • 作用：AI 任务事件表，用于把任务创建、状态变化、阶段变化、流式文本和结果引用挂接广播给订阅端；任务真相仍以 ai_task、ai_task_stage、ai_text_chunk 和 ai_result_reference 为准。
  • 可见性：public event。
  • 结构：event_id PK: String, task_id: String, owner_user_id: String, event_kind: AiTaskEventKind, task_status: Option<AiTaskStatus>, stage_kind: Option<AiTaskStageKind>, text_chunk_row_id: Option<String>, result_reference_row_id: Option<String>, occurred_at: Timestamp。
  • 索引：task_id, owner_user_id。
SELECT * FROM ai_task_event WHERE task_id = '<task_id>' ORDER BY occurred_at ASC;
SELECT * FROM ai_task_event WHERE owner_user_id = '<user_id>' ORDER BY occurred_at DESC;

当前维护风险

  • scripts/check-server-rs-ddd-boundaries.mjs 已检查 spacetime-module/src/** 中的表定义、migration.rs 白名单和本文目录项是否一致；新增或删除表后必须先让该检查通过。
  • database_migration_operator 是迁移权限表，不导出到业务迁移包；除此之外的业务表都必须进入 migration.rs。
  • spacetime-client/src/module_bindings/** 是生成物，表、reducer 或 procedure 发生 shape 变化后必须通过 npm.cmd run spacetime:generate -- --rust-only 或对应 SpacetimeDB CLI 流程重新生成，不要手写修改。
Reference in New Issue View Git Blame Copy Permalink