970 lines
61 KiB
Markdown
970 lines
61 KiB
Markdown
# 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`，避免中文文档或源码被写坏。
|
||
|
||
## 总览
|
||
|
||
| 领域 | 表 |
|
||
| --- | --- |
|
||
| 运维迁移 | `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` 的业务表导出白名单。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```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: String`, `password_login_enabled: bool`, `token_version: u64`, `user_tags: Option<Vec<String>>`。
|
||
- 说明：`user_tags` 数据库默认 `None`，业务读取时按空数组归一化；只允许后端白名单投影到特定业务接口，不得在登录态、个人资料等通用前端响应中直接暴露。
|
||
- 索引：`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`。
|
||
- 新用户注册成功后默认写入 `10` 个光点，余额仍以后端钱包 projection 为准。
|
||
|
||
```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)`。
|
||
- 注册赠送流水来源为 `new_user_registration_reward`，流水 ID 固定为 `new-user-registration:{user_id}`，用于保证重复调用不重复发放。
|
||
|
||
```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;
|
||
```
|
||
|
||
### `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` 是该北京时间业务日的公历日期。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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 修改同一条记录。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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`，不回改历史用户。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```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;
|
||
```
|
||
|
||
### `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)`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```sql
|
||
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。
|
||
|
||
```sql
|
||
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)`。
|
||
|
||
```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`。
|
||
- 说明：填表式拼图入口会在点击“拼图”时立即创建空 session；生成草稿前的表单自动保存复用 `seed_text` 与 `draft_json`，不新增表字段，`stage` 保持 `CollectingAnchors`。
|
||
- 索引：`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`, `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`。
|
||
|
||
```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_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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```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;
|
||
```
|
||
|
||
### `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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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_IMPLEMENTATION_HANDOFF_2026-05-07.md)。
|
||
|
||
### `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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```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_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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```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>';
|
||
```
|
||
|
||
### `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`。
|
||
|
||
```sql
|
||
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`。
|
||
|
||
```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;
|
||
```
|
||
|
||
### `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`。
|
||
|
||
```sql
|
||
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 流程重新生成，不要手写修改。
|