扩展外部生成Worker队列

新增外部生成队列概览和单任务状态契约

将跳一跳、拼消消、敲木鱼图片生成动作接入worker队列

前端生成等待页展示当前任务和队列数量

更新外部生成worker运维文档和团队决策记录

server-rs/crates/api-server/src/jump_hop.rs

@@ -9,7 +9,11 @@ use module_assets::{
     generate_asset_binding_id, generate_asset_object_id,
 };
 use platform_oss::{LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess};
+use serde::{Deserialize, Serialize};
 use serde_json::{Value, json};
+use shared_contracts::external_generation::{
+    ExternalGenerationJobStatus, ExternalGenerationJobStatusRecord,
+};
 use shared_contracts::jump_hop::{
     JumpHopActionRequest, JumpHopActionType, JumpHopCharacterAsset, JumpHopDraftResponse,
     JumpHopGalleryDetailResponse, JumpHopGenerationStatus, JumpHopJumpRequest, JumpHopJumpResponse,
@@ -20,7 +24,9 @@ use shared_contracts::jump_hop::{
     JumpHopWorksResponse, JumpHopWorkspaceCreateRequest,
 };
 use shared_kernel::{build_prefixed_uuid_id, format_timestamp_micros};
-use spacetime_client::SpacetimeClientError;
+use spacetime_client::{
+    ExternalGenerationJobEnqueueRecordInput, ExternalGenerationJobRecord, SpacetimeClientError,
+};
 use std::{
     collections::BTreeMap,
     time::{SystemTime, UNIX_EPOCH},
@@ -49,6 +55,7 @@ use crate::{
 };
 
 const JUMP_HOP_TILE_ITEM_COUNT: usize = 18;
+pub(crate) const JUMP_HOP_COMPILE_DRAFT_JOB_KIND: &str = "jump_hop_compile_draft";
 
 const JUMP_HOP_PROVIDER: &str = "jump-hop";
 const JUMP_HOP_CREATION_PROVIDER: &str = "jump-hop-creation";
@@ -72,6 +79,14 @@ const JUMP_HOP_BACK_BUTTON_IMAGE_SIZE: &str = "1024*1024";
 const JUMP_HOP_BACK_BUTTON_IMAGE_WIDTH: u32 = 1024;
 const JUMP_HOP_BACK_BUTTON_IMAGE_HEIGHT: u32 = 1024;
 
+#[derive(Clone, Debug, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub(crate) struct JumpHopCompileDraftWorkerPayload {
+    pub session_id: String,
+    pub owner_user_id: String,
+    pub payload: JumpHopActionRequest,
+}
+
 #[derive(Clone, Debug, PartialEq, Eq)]
 struct JumpHopTileAtlasSlice {
     tile_type: JumpHopTileType,
@@ -174,6 +189,37 @@ pub async fn execute_jump_hop_action(
     let owner_user_id = authenticated.claims().user_id().to_string();
     let mut payload = payload;
     let is_compile_draft = matches!(payload.action_type, JumpHopActionType::CompileDraft);
+    let should_queue_generation = matches!(
+        payload.action_type,
+        JumpHopActionType::CompileDraft | JumpHopActionType::RegenerateTiles
+    ) && !state.config.external_generation_mode.is_inline();
+    if should_queue_generation {
+        let mut queued_response = state
+            .spacetime_client()
+            .mark_jump_hop_generation_queued(
+                session_id.clone(),
+                owner_user_id.clone(),
+                payload.clone(),
+            )
+            .await
+            .map_err(|error| {
+                jump_hop_error_response(
+                    &request_context,
+                    JUMP_HOP_CREATION_PROVIDER,
+                    map_jump_hop_client_error(error),
+                )
+            })?;
+        let queue_job = enqueue_jump_hop_compile_draft_job(
+            &state,
+            &request_context,
+            &session_id,
+            owner_user_id.as_str(),
+            payload,
+        )
+        .await?;
+        queued_response.queue_state = Some(map_jump_hop_queue_job_status(queue_job));
+        return Ok(json_success_body(Some(&request_context), queued_response));
+    }
     let generation_points_cost = if is_compile_draft {
         resolve_jump_hop_generation_points_cost(&state).await
     } else {
@@ -246,6 +292,99 @@ pub async fn execute_jump_hop_action(
     }
 }
 
+async fn enqueue_jump_hop_compile_draft_job(
+    state: &AppState,
+    request_context: &RequestContext,
+    session_id: &str,
+    owner_user_id: &str,
+    payload: JumpHopActionRequest,
+) -> Result<ExternalGenerationJobRecord, Response> {
+    let job_id = build_prefixed_uuid_id("extgen-");
+    let now_micros = current_utc_micros();
+    let request_payload_json = serde_json::to_string(&JumpHopCompileDraftWorkerPayload {
+        session_id: session_id.to_string(),
+        owner_user_id: owner_user_id.to_string(),
+        payload,
+    })
+    .map_err(|error| {
+        jump_hop_error_response(
+            request_context,
+            JUMP_HOP_CREATION_PROVIDER,
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
+                "message": format!("跳一跳 worker 任务参数序列化失败：{error}"),
+            })),
+        )
+    })?;
+    state
+        .spacetime_client()
+        .enqueue_external_generation_job(ExternalGenerationJobEnqueueRecordInput {
+            dedupe_key: format!("jump-hop:compile-draft:{session_id}:{job_id}"),
+            job_id,
+            job_kind: JUMP_HOP_COMPILE_DRAFT_JOB_KIND.to_string(),
+            owner_user_id: owner_user_id.to_string(),
+            source_module: "jump-hop".to_string(),
+            source_entity_id: session_id.to_string(),
+            request_label: "跳一跳草稿生成".to_string(),
+            request_payload_json,
+            max_attempts: 1,
+            available_at_micros: now_micros,
+            created_at_micros: now_micros,
+        })
+        .await
+        .map_err(|error| {
+            jump_hop_error_response(
+                request_context,
+                JUMP_HOP_CREATION_PROVIDER,
+                map_jump_hop_client_error(error),
+            )
+        })
+}
+
+fn map_jump_hop_queue_job_status(
+    job: ExternalGenerationJobRecord,
+) -> ExternalGenerationJobStatusRecord {
+    ExternalGenerationJobStatusRecord {
+        operation_id: job.job_id,
+        status: ExternalGenerationJobStatus::Queued,
+        phase_label: job.request_label,
+        phase_detail: "排队中。".to_string(),
+        progress: 8,
+        error: job.last_error_message,
+        updated_at_micros: job.updated_at_micros,
+    }
+}
+
+pub(crate) async fn execute_jump_hop_compile_draft_worker_job(
+    state: &AppState,
+    request_context: &RequestContext,
+    mut worker_payload: JumpHopCompileDraftWorkerPayload,
+) -> Result<JumpHopSessionSnapshotResponse, Response> {
+    maybe_generate_jump_hop_assets(
+        state,
+        request_context,
+        worker_payload.session_id.as_str(),
+        worker_payload.owner_user_id.as_str(),
+        &mut worker_payload.payload,
+    )
+    .await?;
+    let response = state
+        .spacetime_client()
+        .execute_jump_hop_action(
+            worker_payload.session_id,
+            worker_payload.owner_user_id,
+            worker_payload.payload,
+        )
+        .await
+        .map_err(|error| {
+            jump_hop_error_response(
+                request_context,
+                JUMP_HOP_CREATION_PROVIDER,
+                map_jump_hop_client_error(error),
+            )
+        })?;
+    Ok(response.session)
+}
+
 async fn resolve_jump_hop_generation_points_cost(state: &AppState) -> u64 {
     crate::creation_entry_config::resolve_creation_entry_mud_point_cost(
         state,
@@ -1005,15 +1144,8 @@ fn slice_jump_hop_tile_atlas(
         let y1 = (row.saturating_add(1)).saturating_mul(height) / JUMP_HOP_TILE_ATLAS_ROWS;
         let tile_width = x1.saturating_sub(x0).max(1);
         let tile_height = y1.saturating_sub(y0).max(1);
-        let faces = slice_jump_hop_tile_uv_faces(
-            &source,
-            x0,
-            y0,
-            tile_width,
-            tile_height,
-            row,
-            col,
-        )?;
+        let faces =
+            slice_jump_hop_tile_uv_faces(&source, x0, y0, tile_width, tile_height, row, col)?;
         slices.push(JumpHopTileAtlasSlice {
             tile_type: jump_hop_tile_type_by_index(index),
             source_atlas_cell: format!("row-{}-col-{}", row + 1, col + 1),
@@ -1043,22 +1175,70 @@ fn slice_jump_hop_tile_uv_faces(
 
     Ok(JumpHopTileFaceSlices {
         top: slice_jump_hop_tile_uv_face(
-            source, uv_x, uv_y, face_side, atlas_row, atlas_col, JumpHopTileFaceKey::Top, 1, 0,
+            source,
+            uv_x,
+            uv_y,
+            face_side,
+            atlas_row,
+            atlas_col,
+            JumpHopTileFaceKey::Top,
+            1,
+            0,
         )?,
         front: slice_jump_hop_tile_uv_face(
-            source, uv_x, uv_y, face_side, atlas_row, atlas_col, JumpHopTileFaceKey::Front, 1, 1,
+            source,
+            uv_x,
+            uv_y,
+            face_side,
+            atlas_row,
+            atlas_col,
+            JumpHopTileFaceKey::Front,
+            1,
+            1,
         )?,
         right: slice_jump_hop_tile_uv_face(
-            source, uv_x, uv_y, face_side, atlas_row, atlas_col, JumpHopTileFaceKey::Right, 2, 1,
+            source,
+            uv_x,
+            uv_y,
+            face_side,
+            atlas_row,
+            atlas_col,
+            JumpHopTileFaceKey::Right,
+            2,
+            1,
         )?,
         back: slice_jump_hop_tile_uv_face(
-            source, uv_x, uv_y, face_side, atlas_row, atlas_col, JumpHopTileFaceKey::Back, 3, 1,
+            source,
+            uv_x,
+            uv_y,
+            face_side,
+            atlas_row,
+            atlas_col,
+            JumpHopTileFaceKey::Back,
+            3,
+            1,
         )?,
         left: slice_jump_hop_tile_uv_face(
-            source, uv_x, uv_y, face_side, atlas_row, atlas_col, JumpHopTileFaceKey::Left, 0, 1,
+            source,
+            uv_x,
+            uv_y,
+            face_side,
+            atlas_row,
+            atlas_col,
+            JumpHopTileFaceKey::Left,
+            0,
+            1,
         )?,
         bottom: slice_jump_hop_tile_uv_face(
-            source, uv_x, uv_y, face_side, atlas_row, atlas_col, JumpHopTileFaceKey::Bottom, 1, 2,
+            source,
+            uv_x,
+            uv_y,
+            face_side,
+            atlas_row,
+            atlas_col,
+            JumpHopTileFaceKey::Bottom,
+            1,
+            2,
         )?,
     })
 }
@@ -1095,12 +1275,7 @@ fn slice_jump_hop_tile_uv_face(
 
     Ok(JumpHopTileFaceSlice {
         face,
-        source_atlas_cell: format!(
-            "row-{}-col-{}/{}",
-            atlas_row + 1,
-            atlas_col + 1,
-            face_label
-        ),
+        source_atlas_cell: format!("row-{}-col-{}/{}", atlas_row + 1, atlas_col + 1, face_label),
         bytes: cursor.into_inner(),
     })
 }
@@ -1827,7 +2002,9 @@ mod tests {
         assert!(prompt.contains("18个用于跳一跳地板的立方体主题物体 UV 展开包装图"));
         assert!(prompt.contains("按三列六行均匀排布"));
         assert!(prompt.contains("每个大单元格代表一个完整的 1x1x1 立方体方块物体"));
-        assert!(prompt.contains("该单元内的六张面贴图精确贴到 Three.js 标准极小倒角立方体的六个面上"));
+        assert!(
+            prompt.contains("该单元内的六张面贴图精确贴到 Three.js 标准极小倒角立方体的六个面上")
+        );
         assert!(prompt.contains("cube object UV unwrap atlas / 立方体主题物体六面展开图集"));
         assert!(prompt.contains("不是单纯平铺材质、不是抽象纹理、不是只把主题颜色铺满"));
         assert!(prompt.contains("游戏界面或图标集页面"));
@@ -1850,7 +2027,9 @@ mod tests {
         assert!(prompt.contains("full-bleed opaque square face texture"));
         assert!(prompt.contains("四角、边缘和中心都要有可识别内容"));
         assert!(prompt.contains("不留透明、不留空白、不留实底背景"));
-        assert!(prompt.contains("允许大面积水果切面、果柄叶片、剥皮条带、籽点、条纹和轮廓图案作为包装身份锚点"));
+        assert!(prompt.contains(
+            "允许大面积水果切面、果柄叶片、剥皮条带、籽点、条纹和轮廓图案作为包装身份锚点"
+        ));
         assert!(prompt.contains("不要把一个小水果、小叶片、小石头或小物体放在面中央"));
         assert!(prompt.contains("这不是透视渲染图"));
         assert!(prompt.contains("不要画摄像机视角、透视块、已烘焙侧壁"));
@@ -1868,14 +2047,18 @@ mod tests {
         assert!(prompt.contains("小贴纸图标、小物体居中、纯果皮材质、纯果肉纹理"));
         assert!(prompt.contains("English guardrail"));
         assert!(prompt.contains("one vertical 1024x1536 image"));
-        assert!(prompt.contains("exactly 18 cube object UV unwraps in a 3 columns by 6 rows atlas"));
+        assert!(
+            prompt.contains("exactly 18 cube object UV unwraps in a 3 columns by 6 rows atlas")
+        );
         assert!(prompt.contains("row1 col2 top"));
         assert!(prompt.contains("row2 col1 left"));
         assert!(prompt.contains("row2 col2 front"));
         assert!(prompt.contains("row2 col3 right"));
         assert!(prompt.contains("row2 col4 back"));
         assert!(prompt.contains("row3 col2 bottom"));
-        assert!(prompt.contains("six different face textures that stitch into one recognizable cubified theme object"));
+        assert!(prompt.contains(
+            "six different face textures that stitch into one recognizable cubified theme object"
+        ));
         assert!(prompt.contains("no generic flat material"));
         assert!(prompt.contains("no small centered stickers"));
         assert!(prompt.contains("every face is full-bleed opaque square texture"));
@@ -2022,7 +2205,9 @@ mod tests {
             "科幻芯片主题的俯视角清爽游戏化立体感平台素材",
         );
 
-        assert!(prompt.contains("画面内容是科幻芯片主题的正交平面清爽游戏化立方体主题身份方块包装贴图"));
+        assert!(
+            prompt.contains("画面内容是科幻芯片主题的正交平面清爽游戏化立方体主题身份方块包装贴图")
+        );
         assert!(!prompt.contains("画面内容是科幻芯片主题的俯视角清爽游戏化立体感平台素材"));
         assert!(!prompt.contains("画面内容是科幻芯片主题的俯视角"));
 
@@ -2118,12 +2303,10 @@ mod tests {
             .max(1);
         let tile_x = atlas_col.saturating_mul(cell_width);
         let tile_y = atlas_row.saturating_mul(cell_height);
-        let uv_x = tile_x.saturating_add(
-            cell_width.saturating_sub(face_side * JUMP_HOP_TILE_UV_FACE_COLS) / 2,
-        );
-        let uv_y = tile_y.saturating_add(
-            cell_height.saturating_sub(face_side * JUMP_HOP_TILE_UV_FACE_ROWS) / 2,
-        );
+        let uv_x = tile_x
+            .saturating_add(cell_width.saturating_sub(face_side * JUMP_HOP_TILE_UV_FACE_COLS) / 2);
+        let uv_y = tile_y
+            .saturating_add(cell_height.saturating_sub(face_side * JUMP_HOP_TILE_UV_FACE_ROWS) / 2);
         for y in uv_y + face_row * face_side..uv_y + (face_row + 1) * face_side {
             for x in uv_x + face_col * face_side..uv_x + (face_col + 1) * face_side {
                 atlas.put_pixel(x, y, color);
@@ -2159,14 +2342,8 @@ mod tests {
             ),
             "{message}"
         );
-        assert!(
-            decoded.pixels().any(|pixel| pixel.0 == color),
-            "{message}"
-        );
-        assert!(
-            decoded.pixels().all(|pixel| pixel.0[3] == 255),
-            "{message}"
-        );
+        assert!(decoded.pixels().any(|pixel| pixel.0 == color), "{message}");
+        assert!(decoded.pixels().all(|pixel| pixel.0[3] == 255), "{message}");
     }
 
     #[test]