Enforce Genarrative play-type SOP and update docs

Rewrite Genarrative play-type integration guidance across .codex and .hermes to define a platform-level SOP: default to form/image workbench, unify single-image asset slots (CreativeImageInputPanel), standardize series-material sheet->cut->transparent->OSS pipeline, and forbid copying legacy chat/agent workflows as the default. Add decision-log entry freezing the SOP and a pitfalls note warning against direct reuse of old play tools. Update CONTEXT.md and docs/README.md, add a new PRD file, and apply related small server-side changes (module-auth, spacetime-client mappers and runtime) to align back-end code with the new contracts and flows.
2026-05-20 12:12:00 +08:00
parent f370539a6f
commit 3931442249
123 changed files with 15514 additions and 3419 deletions
--- a/server-rs/crates/spacetime-module/src/jump_hop/tables.rs
+++ b/server-rs/crates/spacetime-module/src/jump_hop/tables.rs
@@ -0,0 +1,91 @@
+use crate::*;
+
+#[spacetimedb::table(
+    accessor = jump_hop_agent_session,
+    index(accessor = by_jump_hop_agent_session_owner_user_id, btree(columns = [owner_user_id]))
+)]
+pub struct JumpHopAgentSessionRow {
+    #[primary_key]
+    pub(crate) session_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) seed_text: String,
+    pub(crate) current_turn: u32,
+    pub(crate) progress_percent: u32,
+    pub(crate) stage: String,
+    pub(crate) config_json: String,
+    pub(crate) draft_json: String,
+    pub(crate) last_assistant_reply: String,
+    pub(crate) published_profile_id: String,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = jump_hop_work_profile,
+    index(accessor = by_jump_hop_work_owner_user_id, btree(columns = [owner_user_id])),
+    index(accessor = by_jump_hop_work_publication_status, btree(columns = [publication_status]))
+)]
+pub struct JumpHopWorkProfileRow {
+    #[primary_key]
+    pub(crate) profile_id: String,
+    pub(crate) work_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) source_session_id: String,
+    pub(crate) author_display_name: String,
+    pub(crate) work_title: String,
+    pub(crate) work_description: String,
+    pub(crate) theme_tags_json: String,
+    pub(crate) difficulty: String,
+    pub(crate) style_preset: String,
+    pub(crate) character_prompt: String,
+    pub(crate) tile_prompt: String,
+    pub(crate) end_mood_prompt: String,
+    pub(crate) character_asset_json: String,
+    pub(crate) tile_atlas_asset_json: String,
+    pub(crate) tile_assets_json: String,
+    pub(crate) path_json: String,
+    pub(crate) cover_image_src: String,
+    pub(crate) cover_composite: String,
+    pub(crate) generation_status: String,
+    pub(crate) publication_status: String,
+    pub(crate) play_count: u32,
+    pub(crate) updated_at: Timestamp,
+    pub(crate) published_at: Option<Timestamp>,
+}
+
+#[spacetimedb::table(
+    accessor = jump_hop_runtime_run,
+    index(accessor = by_jump_hop_run_owner_user_id, btree(columns = [owner_user_id])),
+    index(accessor = by_jump_hop_run_profile_id, btree(columns = [profile_id]))
+)]
+pub struct JumpHopRuntimeRunRow {
+    #[primary_key]
+    pub(crate) run_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) profile_id: String,
+    pub(crate) status: String,
+    pub(crate) started_at_ms: i64,
+    pub(crate) finished_at_ms: i64,
+    pub(crate) current_platform_index: u32,
+    pub(crate) score: u32,
+    pub(crate) combo: u32,
+    pub(crate) snapshot_json: String,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = jump_hop_event,
+    index(accessor = by_jump_hop_event_profile_id, btree(columns = [profile_id])),
+    index(accessor = by_jump_hop_event_run_id, btree(columns = [run_id]))
+)]
+pub struct JumpHopEventRow {
+    #[primary_key]
+    pub(crate) event_id: String,
+    pub(crate) owner_user_id: String,
+    pub(crate) profile_id: String,
+    pub(crate) run_id: String,
+    pub(crate) event_type: String,
+    pub(crate) result: String,
+    pub(crate) occurred_at: Timestamp,
+}
--- a/server-rs/crates/spacetime-module/src/jump_hop/types.rs
+++ b/server-rs/crates/spacetime-module/src/jump_hop/types.rs
@@ -0,0 +1,261 @@
+use crate::*;
+use serde::{Deserialize, Serialize};
+
+pub const JUMP_HOP_TEMPLATE_ID: &str = "jump-hop";
+pub const JUMP_HOP_TEMPLATE_NAME: &str = "跳一跳";
+pub const JUMP_HOP_STYLE_MINIMAL_BLOCKS: &str = "minimal-blocks";
+pub const JUMP_HOP_STAGE_COLLECTING: &str = "Collecting";
+pub const JUMP_HOP_STAGE_DRAFT_COMPILED: &str = "DraftCompiled";
+pub const JUMP_HOP_STAGE_PUBLISHED: &str = "Published";
+pub const JUMP_HOP_PUBLICATION_DRAFT: &str = "Draft";
+pub const JUMP_HOP_PUBLICATION_PUBLISHED: &str = "Published";
+pub const JUMP_HOP_GENERATION_DRAFT: &str = "draft";
+pub const JUMP_HOP_GENERATION_READY: &str = "ready";
+pub const JUMP_HOP_EVENT_RUN_STARTED: &str = "run-started";
+pub const JUMP_HOP_EVENT_RUN_RESTARTED: &str = "run-restarted";
+pub const JUMP_HOP_EVENT_JUMP: &str = "jump";
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopAgentSessionCreateInput {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub seed_text: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags_json: Option<String>,
+    pub welcome_message_text: String,
+    pub config_json: Option<String>,
+    pub created_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopAgentSessionGetInput {
+    pub session_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopDraftCompileInput {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub profile_id: String,
+    pub author_display_name: String,
+    pub seed_text: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags_json: Option<String>,
+    pub theme_text: Option<String>,
+    pub difficulty: Option<String>,
+    pub style_preset: Option<String>,
+    pub character_prompt: Option<String>,
+    pub tile_prompt: Option<String>,
+    pub end_mood_prompt: Option<String>,
+    pub character_asset_json: Option<String>,
+    pub tile_atlas_asset_json: Option<String>,
+    pub tile_assets_json: Option<String>,
+    pub cover_composite: Option<String>,
+    pub generation_status: Option<String>,
+    pub compiled_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorkUpdateInput {
+    pub profile_id: String,
+    pub owner_user_id: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags_json: String,
+    pub difficulty: Option<String>,
+    pub style_preset: Option<String>,
+    pub cover_image_src: Option<String>,
+    pub cover_composite: Option<String>,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorkPublishInput {
+    pub profile_id: String,
+    pub owner_user_id: String,
+    pub published_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorksListInput {
+    pub owner_user_id: String,
+    pub published_only: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopWorkGetInput {
+    pub profile_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunStartInput {
+    pub run_id: String,
+    pub owner_user_id: String,
+    pub profile_id: String,
+    pub client_event_id: String,
+    pub started_at_ms: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunGetInput {
+    pub run_id: String,
+    pub owner_user_id: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunJumpInput {
+    pub run_id: String,
+    pub owner_user_id: String,
+    pub charge_ms: u32,
+    pub client_event_id: String,
+    pub jumped_at_ms: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, SpacetimeType)]
+pub struct JumpHopRunRestartInput {
+    pub source_run_id: String,
+    pub next_run_id: String,
+    pub owner_user_id: String,
+    pub client_action_id: String,
+    pub restarted_at_ms: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopAgentSessionProcedureResult {
+    pub ok: bool,
+    pub session: Option<JumpHopAgentSessionSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopWorkProcedureResult {
+    pub ok: bool,
+    pub work: Option<JumpHopWorkSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopWorksProcedureResult {
+    pub ok: bool,
+    pub items: Vec<JumpHopWorkSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, SpacetimeType)]
+pub struct JumpHopRunProcedureResult {
+    pub ok: bool,
+    pub run: Option<module_jump_hop::JumpHopRunSnapshot>,
+    pub error_message: Option<String>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopCreatorConfigSnapshot {
+    pub theme_text: String,
+    pub difficulty: String,
+    pub style_preset: String,
+    pub character_prompt: String,
+    pub tile_prompt: String,
+    #[serde(default)]
+    pub end_mood_prompt: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopCharacterAssetSnapshot {
+    pub asset_id: String,
+    pub image_src: String,
+    pub image_object_key: String,
+    pub asset_object_id: String,
+    pub generation_provider: String,
+    pub prompt: String,
+    pub width: u32,
+    pub height: u32,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopTileAssetSnapshot {
+    pub tile_type: String,
+    pub image_src: String,
+    pub image_object_key: String,
+    pub asset_object_id: String,
+    pub source_atlas_cell: String,
+    pub visual_width: u32,
+    pub visual_height: u32,
+    pub top_surface_radius: f32,
+    pub landing_radius: f32,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopDraftSnapshot {
+    pub template_id: String,
+    pub template_name: String,
+    pub profile_id: Option<String>,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags: Vec<String>,
+    pub difficulty: String,
+    pub style_preset: String,
+    pub character_prompt: String,
+    pub tile_prompt: String,
+    pub end_mood_prompt: Option<String>,
+    pub character_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_atlas_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_assets: Vec<JumpHopTileAssetSnapshot>,
+    pub path: Option<module_jump_hop::JumpHopPath>,
+    pub cover_composite: Option<String>,
+    pub generation_status: String,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopAgentSessionSnapshot {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub seed_text: String,
+    pub current_turn: u32,
+    pub progress_percent: u32,
+    pub stage: String,
+    pub config: JumpHopCreatorConfigSnapshot,
+    pub draft: Option<JumpHopDraftSnapshot>,
+    pub last_assistant_reply: String,
+    pub published_profile_id: Option<String>,
+    pub created_at_micros: i64,
+    pub updated_at_micros: i64,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, SpacetimeType)]
+#[serde(rename_all = "camelCase")]
+pub struct JumpHopWorkSnapshot {
+    pub work_id: String,
+    pub profile_id: String,
+    pub owner_user_id: String,
+    pub source_session_id: String,
+    pub author_display_name: String,
+    pub work_title: String,
+    pub work_description: String,
+    pub theme_tags: Vec<String>,
+    pub difficulty: String,
+    pub style_preset: String,
+    pub character_prompt: String,
+    pub tile_prompt: String,
+    pub end_mood_prompt: Option<String>,
+    pub character_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_atlas_asset: Option<JumpHopCharacterAssetSnapshot>,
+    pub tile_assets: Vec<JumpHopTileAssetSnapshot>,
+    pub path: module_jump_hop::JumpHopPath,
+    pub cover_image_src: String,
+    pub cover_composite: Option<String>,
+    pub publication_status: String,
+    pub publish_ready: bool,
+    pub play_count: u32,
+    pub generation_status: String,
+    pub updated_at_micros: i64,
+    pub published_at_micros: Option<i64>,
+}