fix: decouple puzzle draft generation lifecycle

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

@@ -1,5 +1,6 @@
 use std::{
-    collections::BTreeMap,
+    collections::{BTreeMap, HashSet},
+    sync::{Mutex, OnceLock},
     time::{Instant, SystemTime, UNIX_EPOCH},
 };
 
@@ -130,6 +131,73 @@ const PUZZLE_UI_BACKGROUND_PROMPT_FALLBACK_MARKER: &str =
 const PUZZLE_VECTOR_ENGINE_SQUARE_IMAGE_SIZE: &str = "1024x1024";
 const PUZZLE_VECTOR_ENGINE_PORTRAIT_IMAGE_SIZE: &str = "1024x1536";
 
+static PUZZLE_BACKGROUND_COMPILE_TASKS: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();
+
+fn puzzle_background_compile_tasks() -> &'static Mutex<HashSet<String>> {
+    PUZZLE_BACKGROUND_COMPILE_TASKS.get_or_init(|| Mutex::new(HashSet::new()))
+}
+
+fn try_register_puzzle_background_compile_task(session_id: &str) -> bool {
+    match puzzle_background_compile_tasks().lock() {
+        Ok(mut tasks) => tasks.insert(session_id.to_string()),
+        Err(error) => {
+            tracing::warn!(
+                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
+                session_id,
+                error = %error,
+                "拼图后台生成任务注册表锁已损坏，允许本次任务继续"
+            );
+            true
+        }
+    }
+}
+
+fn unregister_puzzle_background_compile_task(session_id: &str) {
+    match puzzle_background_compile_tasks().lock() {
+        Ok(mut tasks) => {
+            tasks.remove(session_id);
+        }
+        Err(error) => {
+            tracing::warn!(
+                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
+                session_id,
+                error = %error,
+                "拼图后台生成任务注册表解锁失败，忽略清理"
+            );
+        }
+    }
+}
+
+fn has_puzzle_cover_image_src(value: &Option<String>) -> bool {
+    value
+        .as_deref()
+        .map(str::trim)
+        .is_some_and(|value| !value.is_empty())
+}
+
+fn mark_puzzle_initial_generation_started_snapshot(
+    mut session: PuzzleAgentSessionRecord,
+) -> PuzzleAgentSessionRecord {
+    session.stage = "image_refining".to_string();
+    session.progress_percent = session.progress_percent.max(88);
+    if let Some(draft) = session.draft.as_mut() {
+        let draft_needs_cover = !has_puzzle_cover_image_src(&draft.cover_image_src);
+        if let Some(primary_level) = draft.levels.first_mut() {
+            if !has_puzzle_cover_image_src(&primary_level.cover_image_src) {
+                primary_level.generation_status = "generating".to_string();
+            }
+            draft.generation_status = primary_level.generation_status.clone();
+            draft.candidates = primary_level.candidates.clone();
+            draft.selected_candidate_id = primary_level.selected_candidate_id.clone();
+            draft.cover_image_src = primary_level.cover_image_src.clone();
+            draft.cover_asset_id = primary_level.cover_asset_id.clone();
+        } else if draft_needs_cover {
+            draft.generation_status = "generating".to_string();
+        }
+    }
+    session
+}
+
 pub(crate) fn format_puzzle_reference_image_upload_bytes(bytes: usize) -> String {
     format!("{:.1}MB", bytes as f64 / 1024.0 / 1024.0)
 }