refactor(api-server): narrow puzzle state surface

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

@@ -24,7 +24,7 @@ pub(crate) fn build_puzzle_form_seed_text_from_parts(
 }
 
 pub(crate) async fn save_puzzle_form_payload_before_compile(
-    state: &AppState,
+    state: &PuzzleApiState,
     request_context: &RequestContext,
     session_id: &str,
     owner_user_id: &str,
@@ -76,7 +76,7 @@ pub(crate) async fn save_puzzle_form_payload_before_compile(
 }
 
 pub(crate) async fn create_seeded_puzzle_session_when_form_save_missing(
-    state: &AppState,
+    state: &PuzzleApiState,
     request_context: &RequestContext,
     session_id: &str,
     owner_user_id: &str,
@@ -209,7 +209,7 @@ pub(crate) fn parse_puzzle_level_records_from_module_json(
 }
 
 pub(crate) async fn get_puzzle_session_for_image_generation(
-    state: &AppState,
+    state: &PuzzleApiState,
     session_id: String,
     owner_user_id: String,
     payload: &ExecutePuzzleAgentActionRequest,
@@ -469,7 +469,7 @@ impl PuzzleLevelNaming {
 }
 
 pub(crate) async fn generate_puzzle_first_level_name(
-    state: &AppState,
+    state: &PuzzleApiState,
     picture_description: &str,
 ) -> PuzzleLevelNaming {
     if let Some(llm_client) = state.llm_client() {
@@ -511,7 +511,7 @@ pub(crate) async fn generate_puzzle_first_level_name(
 }
 
 pub(crate) async fn generate_puzzle_first_level_name_from_image(
-    state: &AppState,
+    state: &PuzzleApiState,
     picture_description: &str,
     image: &PuzzleDownloadedImage,
 ) -> Option<PuzzleLevelNaming> {
@@ -1033,42 +1033,8 @@ pub(crate) fn attach_puzzle_level_ui_background(
     levels[index].ui_background_image_object_key = Some(generated.object_key);
 }
 
-pub(crate) async fn generate_puzzle_background_music_required(
-    state: &AppState,
-    owner_user_id: &str,
-    profile_id: &str,
-    title: &str,
-) -> Result<CreationAudioAsset, AppError> {
-    let normalized_title = title.trim();
-    if normalized_title.is_empty() {
-        return Err(
-            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
-                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
-                "message": "拼图草稿背景音乐名称为空，无法完成背景音乐生成",
-            })),
-        );
-    }
-    generate_background_music_asset_for_creation(
-        state,
-        owner_user_id,
-        String::new(),
-        normalized_title.to_string(),
-        Some("轻快, 拼图, 循环, instrumental".to_string()),
-        None,
-        GeneratedCreationAudioTarget {
-            entity_kind: PUZZLE_ENTITY_KIND.to_string(),
-            entity_id: profile_id.to_string(),
-            slot: PUZZLE_BACKGROUND_MUSIC_SLOT.to_string(),
-            asset_kind: PUZZLE_BACKGROUND_MUSIC_ASSET_KIND.to_string(),
-            profile_id: Some(profile_id.to_string()),
-            storage_prefix: LegacyAssetPrefix::PuzzleAssets,
-        },
-    )
-    .await
-}
-
 pub(crate) async fn generate_puzzle_initial_ui_background_required(
-    state: &AppState,
+    state: &PuzzleApiState,
     owner_user_id: &str,
     session_id: &str,
     draft: &PuzzleResultDraftRecord,
@@ -1128,7 +1094,7 @@ pub(crate) fn find_puzzle_level_for_initial_asset_check<'a>(
 }
 
 pub(crate) async fn compile_puzzle_draft_with_initial_cover(
-    state: &AppState,
+    state: &PuzzleApiState,
     session_id: String,
     owner_user_id: String,
     prompt_text: Option<&str>,
@@ -1398,7 +1364,7 @@ pub(crate) async fn compile_puzzle_draft_with_initial_cover(
 }
 
 pub(crate) async fn compile_puzzle_draft_with_uploaded_cover(
-    state: &AppState,
+    state: &PuzzleApiState,
     session_id: String,
     owner_user_id: String,
     prompt_text: Option<&str>,
@@ -1417,7 +1383,12 @@ pub(crate) async fn compile_puzzle_draft_with_uploaded_cover(
         })?;
     let http_client = reqwest::Client::new();
     let uploaded_downloaded_image =
-        resolve_puzzle_reference_image_as_data_url(state, &http_client, uploaded_image_src)
+        resolve_puzzle_reference_image(
+            state,
+            &http_client,
+            uploaded_image_src,
+            Some(owner_user_id.as_str()),
+        )
             .await
             .map(PuzzleDownloadedImage::from_resolved_reference_image)
             .map_err(|error| {
@@ -1425,7 +1396,7 @@ pub(crate) async fn compile_puzzle_draft_with_uploaded_cover(
                     AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                         "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                         "field": "referenceImageSrc",
-                        "message": "关闭 AI 重绘时上传图必须是图片 Data URL 或历史生成图片路径。",
+                        "message": "关闭 AI 重绘时上传图必须是拼图图片 assetObjectId、图片 Data URL 或历史生成图片路径。",
                     }))
                 } else {
                     error