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

use std::{
    collections::BTreeMap,
    time::{Duration, Instant, SystemTime, UNIX_EPOCH},
};

use axum::{
    Json,
    extract::{Extension, Path as AxumPath, State, rejection::JsonRejection},
    http::{HeaderName, StatusCode, header},
    response::{
        IntoResponse, Response,
        sse::{Event, Sse},
    },
};
use base64::{Engine as _, engine::general_purpose::STANDARD as BASE64_STANDARD};
use image::ImageFormat;
use module_assets::{
    AssetObjectAccessPolicy, AssetObjectFieldError, build_asset_entity_binding_input,
    build_asset_object_upsert_input, generate_asset_binding_id, generate_asset_object_id,
};
use module_puzzle::{PuzzleGeneratedImageCandidate, PuzzleRuntimeLevelStatus};
use platform_llm::{LlmMessage, LlmMessageContentPart, LlmTextRequest};
use platform_oss::{
    LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess, OssPutObjectRequest,
    OssSignedGetObjectUrlRequest,
};
use serde_json::{Map, Value, json};
use shared_contracts::{
    creation_audio::CreationAudioAsset,
    puzzle_agent::{
        CreatePuzzleAgentSessionRequest, ExecutePuzzleAgentActionRequest,
        PuzzleAgentActionResponse, PuzzleAgentMessageResponse, PuzzleAgentOperationResponse,
        PuzzleAgentSessionResponse, PuzzleAgentSessionSnapshotResponse,
        PuzzleAgentSuggestedActionResponse, PuzzleAnchorItemResponse, PuzzleAnchorPackResponse,
        PuzzleCreatorIntentResponse, PuzzleDraftLevelResponse, PuzzleFormDraftResponse,
        PuzzleGeneratedImageCandidateResponse, PuzzleResultDraftResponse,
        PuzzleResultPreviewBlockerResponse, PuzzleResultPreviewEnvelopeResponse,
        PuzzleResultPreviewFindingResponse, SendPuzzleAgentMessageRequest,
    },
    puzzle_gallery::{PuzzleGalleryDetailResponse, PuzzleGalleryResponse},
    puzzle_runtime::{
        AdvancePuzzleNextLevelRequest, DragPuzzlePieceRequest, PuzzleBoardSnapshotResponse,
        PuzzleCellPositionResponse, PuzzleLeaderboardEntryResponse, PuzzleMergedGroupStateResponse,
        PuzzlePieceStateResponse, PuzzleRecommendedNextWorkResponse, PuzzleRunResponse,
        PuzzleRunSnapshotResponse, PuzzleRuntimeLevelSnapshotResponse, StartPuzzleRunRequest,
        SubmitPuzzleLeaderboardRequest, SwapPuzzlePiecesRequest, UpdatePuzzleRuntimePauseRequest,
        UsePuzzleRuntimePropRequest,
    },
    puzzle_works::{
        PutPuzzleWorkRequest, PuzzleOnboardingGenerateRequest, PuzzleOnboardingGenerateResponse,
        PuzzleOnboardingSaveRequest, PuzzleWorkDetailResponse, PuzzleWorkMutationResponse,
        PuzzleWorkProfileResponse, PuzzleWorkSummaryResponse, PuzzleWorksResponse,
    },
};
use shared_kernel::{build_prefixed_uuid_id, format_timestamp_micros};
use spacetime_client::{
    PuzzleAgentMessageRecord, PuzzleAgentMessageSubmitRecordInput,
    PuzzleAgentSessionCreateRecordInput, PuzzleAgentSessionRecord,
    PuzzleAgentSuggestedActionRecord, PuzzleAnchorItemRecord, PuzzleAnchorPackRecord,
    PuzzleAudioAssetRecord, PuzzleCreatorIntentRecord, PuzzleDraftLevelRecord, PuzzleFormDraftRecord,
    PuzzleFormDraftSaveRecordInput, PuzzleGeneratedImageCandidateRecord,
    PuzzleGeneratedImagesSaveRecordInput, PuzzleLeaderboardEntryRecord,
    PuzzleLeaderboardSubmitRecordInput, PuzzlePublishRecordInput, PuzzleRecommendedNextWorkRecord,
    PuzzleResultDraftRecord, PuzzleResultPreviewBlockerRecord, PuzzleResultPreviewFindingRecord,
    PuzzleResultPreviewRecord, PuzzleRunDragRecordInput, PuzzleRunPauseRecordInput,
    PuzzleRunPropRecordInput, PuzzleRunRecord, PuzzleRunStartRecordInput, PuzzleRunSwapRecordInput,
    PuzzleSelectCoverImageRecordInput, PuzzleUiBackgroundSaveRecordInput,
    PuzzleWorkLikeReportRecordInput, PuzzleWorkPointIncentiveClaimRecordInput,
    PuzzleWorkProfileRecord, PuzzleWorkRemixRecordInput, PuzzleWorkUpsertRecordInput,
    SpacetimeClientError,
};
use std::convert::Infallible;

use crate::{
    ai_generation_drafts::{AiGenerationDraftContext, AiGenerationDraftWriter},
    api_response::json_success_body,
    asset_billing::{
        execute_billable_asset_operation, execute_billable_asset_operation_with_cost,
        should_skip_asset_operation_billing_for_connectivity,
    },
    auth::AuthenticatedAccessToken,
    http_error::AppError,
    llm_model_routing::{CREATION_TEMPLATE_LLM_MODEL, PUZZLE_LEVEL_NAME_VISION_LLM_MODEL},
    openai_image_generation::{
        DownloadedOpenAiImage, VECTOR_ENGINE_GPT_IMAGE_2_MODEL, build_openai_image_http_client,
        create_openai_image_generation, require_openai_image_settings,
    },
    platform_errors::map_oss_error,
    prompt::puzzle::{
        draft::{
            PuzzleFormSeedPromptParts, build_puzzle_form_seed_prompt,
            resolve_puzzle_draft_cover_prompt, resolve_puzzle_level_image_prompt,
        },
        image::{PUZZLE_DEFAULT_NEGATIVE_PROMPT, build_puzzle_image_prompt},
        level_name::{
            PUZZLE_FIRST_LEVEL_NAME_SYSTEM_PROMPT, build_puzzle_first_level_name_user_prompt,
            build_puzzle_first_level_name_vision_user_text,
        },
        tags::{PUZZLE_TAG_GENERATION_SYSTEM_PROMPT, build_puzzle_tag_generation_user_prompt},
    },
    puzzle_agent_turn::{
        PuzzleAgentTurnRequest, build_failed_finalize_record_input, build_finalize_record_input,
        run_puzzle_agent_turn,
    },
    request_context::RequestContext,
    state::AppState,
    vector_engine_audio_generation::{
        GeneratedCreationAudioTarget, generate_background_music_asset_for_creation,
    },
    work_author::resolve_work_author_by_user_id,
    work_play_tracking::{WorkPlayTrackingDraft, record_work_play_start_after_success},
};

const PUZZLE_AGENT_API_BASE_PROVIDER: &str = "puzzle-agent";
const PUZZLE_WORKS_PROVIDER: &str = "puzzle-works";
const PUZZLE_GALLERY_PROVIDER: &str = "puzzle-gallery";
const PUZZLE_RUNTIME_PROVIDER: &str = "puzzle-runtime";
const PUZZLE_IMAGE_MODEL_GPT_IMAGE_2: &str = "gpt-image-2";
const PUZZLE_IMAGE_MODEL_GEMINI_31_FLASH_PREVIEW: &str = "gemini-3.1-flash-image-preview";
const PUZZLE_IMAGE_GENERATION_POINTS_COST: u64 = 2;
const PUZZLE_ENTITY_KIND: &str = "puzzle_work";
#[cfg(test)]
const PUZZLE_GENERATED_IMAGE_SIZE: &str = "1024*1024";
const PUZZLE_VECTOR_ENGINE_GENERATED_IMAGE_SIZE: &str = "1024x1024";
const VECTOR_ENGINE_PROVIDER: &str = "vector-engine";
const PUZZLE_LEVEL_NAME_VISION_IMAGE_MAX_SIDE: u32 = 768;
const PUZZLE_REFERENCE_IMAGE_MAX_BYTES: usize = 8 * 1024 * 1024;
const PUZZLE_VECTOR_ENGINE_IMAGE_EDIT_MODEL: &str = "gpt-image-2";
const PUZZLE_UI_BACKGROUND_REFERENCE_IMAGE_PATH: &str =
    "public/ui-previews/puzzle-image-compact-ui-2026-05-08.png";
const PUZZLE_BACKGROUND_MUSIC_ASSET_KIND: &str = "puzzle_background_music";
const PUZZLE_BACKGROUND_MUSIC_SLOT: &str = "background_music";

pub async fn create_puzzle_agent_session(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<CreatePuzzleAgentSessionRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;

    let seed_text = build_puzzle_form_seed_text(&payload);
    let session = state
        .spacetime_client()
        .create_puzzle_agent_session(PuzzleAgentSessionCreateRecordInput {
            session_id: build_prefixed_uuid_id("puzzle-session-"),
            owner_user_id: authenticated.claims().user_id().to_string(),
            seed_text: seed_text.clone(),
            welcome_message_id: build_prefixed_uuid_id("puzzle-message-"),
            welcome_message_text: build_puzzle_welcome_text(&seed_text),
            created_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleAgentSessionResponse {
            session: map_puzzle_agent_session_response(session),
        },
    ))
}

pub async fn generate_puzzle_onboarding_work(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
    payload: Result<Json<PuzzleOnboardingGenerateRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;

    let prompt_text = payload.prompt_text.trim().to_string();
    ensure_non_empty(
        &request_context,
        PUZZLE_AGENT_API_BASE_PROVIDER,
        &prompt_text,
        "promptText",
    )?;

    let now = current_utc_micros();
    let session_id = build_prefixed_uuid_id("puzzle-onboarding-");
    let level_name = generate_puzzle_first_level_name(&state, prompt_text.as_str()).await;
    let tags = generate_puzzle_work_tags(&state, level_name.as_str(), prompt_text.as_str()).await;
    let candidates = generate_puzzle_image_candidates(
        &state,
        "onboarding-guest",
        session_id.as_str(),
        level_name.as_str(),
        prompt_text.as_str(),
        None,
        false,
        Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2),
        1,
        0,
    )
    .await
    .map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            map_puzzle_generation_endpoint_error(error),
        )
    })?
    .into_records();
    let selected = candidates.first().cloned().ok_or_else(|| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": "新手引导拼图图片生成结果为空",
            })),
        )
    })?;
    let level = PuzzleDraftLevelRecord {
        level_id: "onboarding-level-1".to_string(),
        level_name: level_name.clone(),
        picture_description: prompt_text.clone(),
        picture_reference: None,
        ui_background_prompt: None,
        ui_background_image_src: None,
        ui_background_image_object_key: None,
        background_music: None,
        candidates,
        selected_candidate_id: Some(selected.candidate_id.clone()),
        cover_image_src: Some(selected.image_src.clone()),
        cover_asset_id: Some(selected.asset_id.clone()),
        generation_status: "ready".to_string(),
    };
    let anchor_pack = map_puzzle_domain_anchor_pack(module_puzzle::build_form_anchor_pack(
        level_name.as_str(),
        level.picture_description.as_str(),
    ));
    let item = PuzzleWorkProfileRecord {
        work_id: format!("onboarding-work-{now}"),
        profile_id: format!("onboarding-profile-{now}"),
        owner_user_id: "onboarding-guest".to_string(),
        source_session_id: None,
        author_display_name: "百梦主".to_string(),
        work_title: level_name.clone(),
        work_description: prompt_text.clone(),
        level_name,
        summary: prompt_text,
        theme_tags: tags,
        cover_image_src: level.cover_image_src.clone(),
        cover_asset_id: level.cover_asset_id.clone(),
        publication_status: "draft".to_string(),
        updated_at: format_timestamp_micros(now),
        published_at: None,
        play_count: 0,
        remix_count: 0,
        like_count: 0,
        recent_play_count_7d: 0,
        point_incentive_total_half_points: 0,
        point_incentive_claimed_points: 0,
        anchor_pack,
        publish_ready: true,
        levels: vec![level.clone()],
    };

    Ok(json_success_body(
        Some(&request_context),
        PuzzleOnboardingGenerateResponse {
            item: map_puzzle_work_profile_response(&state, item.clone()).summary,
            level: map_puzzle_draft_level_response(level),
        },
    ))
}

pub async fn save_puzzle_onboarding_work(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<PuzzleOnboardingSaveRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_WORKS_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_WORKS_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;

    let prompt_text = payload.prompt_text.trim().to_string();
    ensure_non_empty(
        &request_context,
        PUZZLE_WORKS_PROVIDER,
        &prompt_text,
        "promptText",
    )?;

    let first_level = payload.item.levels.first().cloned().ok_or_else(|| {
        puzzle_error_response(
            &request_context,
            PUZZLE_WORKS_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_WORKS_PROVIDER,
                "message": "新手引导拼图缺少可保存关卡",
            })),
        )
    })?;
    let levels_json = serialize_puzzle_levels_response(&request_context, &payload.item.levels)?;
    let work_title = payload.item.work_title.trim();
    let work_title = if work_title.is_empty() {
        first_level.level_name.clone()
    } else {
        work_title.to_string()
    };
    let work_description = payload.item.work_description.trim();
    let work_description = if work_description.is_empty() {
        prompt_text.clone()
    } else {
        work_description.to_string()
    };
    let summary = payload.item.summary.trim();
    let summary = if summary.is_empty() {
        first_level.picture_description.clone()
    } else {
        summary.to_string()
    };
    let now = current_utc_micros();
    let owner_user_id = authenticated.claims().user_id().to_string();
    let session_id = build_prefixed_uuid_id("puzzle-session-");
    state
        .spacetime_client()
        .create_puzzle_agent_session(PuzzleAgentSessionCreateRecordInput {
            session_id: session_id.clone(),
            owner_user_id: owner_user_id.clone(),
            seed_text: prompt_text.clone(),
            welcome_message_id: build_prefixed_uuid_id("puzzle-message-"),
            welcome_message_text: build_puzzle_welcome_text(&prompt_text),
            created_at_micros: now,
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    let (_, profile_id) = build_stable_puzzle_work_ids(session_id.as_str());
    let item = state
        .spacetime_client()
        .update_puzzle_work(PuzzleWorkUpsertRecordInput {
            profile_id,
            owner_user_id,
            work_title,
            work_description,
            level_name: first_level.level_name,
            summary,
            theme_tags: payload.item.theme_tags,
            cover_image_src: first_level.cover_image_src,
            cover_asset_id: first_level.cover_asset_id,
            levels_json: Some(levels_json),
            updated_at_micros: now,
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleWorkMutationResponse {
            item: map_puzzle_work_profile_response(&state, item),
        },
    ))
}

pub async fn get_puzzle_agent_session(
    State(state): State<AppState>,
    AxumPath(session_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_AGENT_API_BASE_PROVIDER,
        &session_id,
        "sessionId",
    )?;

    let session = state
        .spacetime_client()
        .get_puzzle_agent_session(session_id, authenticated.claims().user_id().to_string())
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleAgentSessionResponse {
            session: map_puzzle_agent_session_response(session),
        },
    ))
}

pub async fn submit_puzzle_agent_message(
    State(state): State<AppState>,
    AxumPath(session_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<SendPuzzleAgentMessageRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(
        &request_context,
        PUZZLE_AGENT_API_BASE_PROVIDER,
        &session_id,
        "sessionId",
    )?;

    let client_message_id = payload.client_message_id.trim().to_string();
    let message_text = payload.text.trim().to_string();
    if client_message_id.is_empty() || message_text.is_empty() {
        return Err(puzzle_bad_request(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            "clientMessageId and text are required",
        ));
    }

    let owner_user_id = authenticated.claims().user_id().to_string();
    let submitted_session = state
        .spacetime_client()
        .submit_puzzle_agent_message(PuzzleAgentMessageSubmitRecordInput {
            session_id: session_id.clone(),
            owner_user_id: owner_user_id.clone(),
            user_message_id: client_message_id,
            user_message_text: message_text,
            submitted_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;
    let turn_result = run_puzzle_agent_turn(
        PuzzleAgentTurnRequest {
            llm_client: state.llm_client(),
            session: &submitted_session,
            quick_fill_requested: payload.quick_fill_requested.unwrap_or(false),
            enable_web_search: state.config.creation_agent_llm_web_search_enabled,
        },
        |_| {},
    )
    .await;
    let finalize_input = match turn_result {
        Ok(turn_result) => build_finalize_record_input(
            session_id.clone(),
            owner_user_id.clone(),
            format!("assistant-{session_id}-{}", current_utc_micros()),
            turn_result,
            current_utc_micros(),
        ),
        Err(error) => build_failed_finalize_record_input(
            session_id.clone(),
            owner_user_id.clone(),
            &submitted_session,
            error.to_string(),
            current_utc_micros(),
        ),
    };
    let session = state
        .spacetime_client()
        .finalize_puzzle_agent_message(finalize_input)
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleAgentSessionResponse {
            session: map_puzzle_agent_session_response(session),
        },
    ))
}

pub async fn stream_puzzle_agent_message(
    State(state): State<AppState>,
    AxumPath(session_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<SendPuzzleAgentMessageRequest>, JsonRejection>,
) -> Result<Response, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(
        &request_context,
        PUZZLE_AGENT_API_BASE_PROVIDER,
        &session_id,
        "sessionId",
    )?;

    let owner_user_id = authenticated.claims().user_id().to_string();
    let quick_fill_requested = payload.quick_fill_requested.unwrap_or(false);
    let session = state
        .spacetime_client()
        .submit_puzzle_agent_message(PuzzleAgentMessageSubmitRecordInput {
            session_id: session_id.clone(),
            owner_user_id: owner_user_id.clone(),
            user_message_id: payload.client_message_id.trim().to_string(),
            user_message_text: payload.text.trim().to_string(),
            submitted_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;
    let state = state.clone();
    let session_id_for_stream = session_id.clone();
    let owner_user_id_for_stream = owner_user_id.clone();
    let stream = async_stream::stream! {
        let mut draft_writer = AiGenerationDraftWriter::new(AiGenerationDraftContext::new(
            "puzzle",
            owner_user_id_for_stream.as_str(),
            session_id_for_stream.as_str(),
            payload.client_message_id.as_str(),
            "拼图模板生成草稿",
        ));
        if let Err(error) = draft_writer.ensure_started(state.spacetime_client()).await {
            tracing::warn!(error = %error, "拼图模板生成草稿任务启动失败，主生成流程继续执行");
        }
        let (reply_tx, mut reply_rx) = tokio::sync::mpsc::unbounded_channel::<String>();
        let turn_result = {
            let run_turn = run_puzzle_agent_turn(
                PuzzleAgentTurnRequest {
                    llm_client: state.llm_client(),
                    session: &session,
                    quick_fill_requested,
                    enable_web_search: state.config.creation_agent_llm_web_search_enabled,
                },
                move |text| {
                    let _ = reply_tx.send(text.to_string());
                },
            );
            tokio::pin!(run_turn);

            loop {
                tokio::select! {
                    result = &mut run_turn => break result,
                    maybe_text = reply_rx.recv() => {
                        if let Some(text) = maybe_text {
                            draft_writer.persist_visible_text(state.spacetime_client(), text.as_str()).await;
                            yield Ok::<Event, Infallible>(puzzle_sse_json_event_or_error(
                                "reply_delta",
                                json!({ "text": text }),
                            ));
                        }
                    }
                }
            }
        };

        while let Some(text) = reply_rx.recv().await {
            draft_writer.persist_visible_text(state.spacetime_client(), text.as_str()).await;
            yield Ok::<Event, Infallible>(puzzle_sse_json_event_or_error(
                "reply_delta",
                json!({ "text": text }),
            ));
        }

        let finalize_input = match turn_result {
            Ok(turn_result) => build_finalize_record_input(
                session_id_for_stream.clone(),
                owner_user_id_for_stream.clone(),
                format!("assistant-{session_id_for_stream}-{}", current_utc_micros()),
                turn_result,
                current_utc_micros(),
            ),
            Err(error) => build_failed_finalize_record_input(
                session_id_for_stream.clone(),
                owner_user_id_for_stream.clone(),
                &session,
                error.to_string(),
                current_utc_micros(),
            ),
        };
        let finalize_result = state
            .spacetime_client()
            .finalize_puzzle_agent_message(finalize_input)
            .await;
        let _final_session = match finalize_result {
            Ok(session) => session,
            Err(error) => {
                yield Ok::<Event, Infallible>(puzzle_sse_json_event_or_error(
                    "error",
                    json!({ "message": error.to_string() }),
                ));
                return;
            }
        };
        let final_session = match state
            .spacetime_client()
            .get_puzzle_agent_session(session_id_for_stream, owner_user_id_for_stream)
            .await
        {
            Ok(session) => session,
            Err(error) => {
                yield Ok::<Event, Infallible>(puzzle_sse_json_event_or_error(
                    "error",
                    json!({ "message": error.to_string() }),
                ));
                return;
            }
        };
        let session_response = map_puzzle_agent_session_response(final_session);
        yield Ok::<Event, Infallible>(puzzle_sse_json_event_or_error(
            "session",
            json!({ "session": session_response }),
        ));
        yield Ok::<Event, Infallible>(puzzle_sse_json_event_or_error(
            "done",
            json!({ "ok": true }),
        ));
    };
    Ok(Sse::new(stream).into_response())
}

pub async fn execute_puzzle_agent_action(
    State(state): State<AppState>,
    AxumPath(session_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<ExecutePuzzleAgentActionRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(
        &request_context,
        PUZZLE_AGENT_API_BASE_PROVIDER,
        &session_id,
        "sessionId",
    )?;

    let owner_user_id = authenticated.claims().user_id().to_string();
    let now = current_utc_micros();
    let action = payload.action.trim().to_string();
    let billing_asset_id = format!("{session_id}:{now}");
    tracing::info!(
        provider = PUZZLE_AGENT_API_BASE_PROVIDER,
        session_id = %session_id,
        owner_user_id = %owner_user_id,
        action = %action,
        image_model = resolve_puzzle_image_model(payload.image_model.as_deref()).request_model_name(),
        prompt_chars = payload
            .prompt_text
            .as_deref()
            .map(|value| value.chars().count())
            .unwrap_or(0),
        has_reference_image = payload
            .reference_image_src
            .as_deref()
            .map(|value| !value.trim().is_empty())
            .unwrap_or(false),
        "拼图 Agent action 开始执行"
    );
    let (operation_type, phase_label, phase_detail, session) = match action.as_str() {
        "compile_puzzle_draft" => {
            let ai_redraw = payload.ai_redraw.unwrap_or(true);
            let prompt_text = payload
                .picture_description
                .as_deref()
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .or_else(|| payload.prompt_text.as_deref());
            let compile_session_id = match save_puzzle_form_payload_before_compile(
                &state,
                &request_context,
                &session_id,
                &owner_user_id,
                &payload,
                now,
            )
            .await
            {
                Ok(next_session_id) => next_session_id,
                Err(response) => return Err(response),
            };
            let session = if ai_redraw {
                execute_billable_asset_operation_with_cost(
                    &state,
                    &owner_user_id,
                    "puzzle_initial_image",
                    &billing_asset_id,
                    PUZZLE_IMAGE_GENERATION_POINTS_COST,
                    async {
                        compile_puzzle_draft_with_initial_cover(
                            &state,
                            compile_session_id.clone(),
                            owner_user_id.clone(),
                            prompt_text,
                            payload.reference_image_src.as_deref(),
                            payload.image_model.as_deref(),
                            now,
                        )
                        .await
                    },
                )
                .await
            } else {
                compile_puzzle_draft_with_uploaded_cover(
                    &state,
                    compile_session_id.clone(),
                    owner_user_id.clone(),
                    prompt_text,
                    payload.reference_image_src.as_deref(),
                    now,
                )
                .await
            }
            .map_err(|error| {
                puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
            });
            (
                "compile_puzzle_draft",
                "首关拼图草稿",
                if ai_redraw {
                    "已编译首关草稿、生成首关画面并写入正式草稿。"
                } else {
                    "已编译首关草稿，并直接应用上传图片为第一关图片。"
                },
                session,
            )
        }
        "save_puzzle_form_draft" => {
            let seed_text = build_puzzle_form_seed_text_from_parts(
                None,
                None,
                payload
                    .picture_description
                    .as_deref()
                    .or(payload.prompt_text.as_deref()),
            );
            let save_result = state
                .spacetime_client()
                .save_puzzle_form_draft(PuzzleFormDraftSaveRecordInput {
                    session_id: session_id.clone(),
                    owner_user_id: owner_user_id.clone(),
                    seed_text,
                    saved_at_micros: now,
                })
                .await;
            let session = match save_result {
                Ok(session) => Ok(session),
                Err(error) if is_missing_puzzle_form_draft_procedure_error(&error) => {
                    // 中文注释：旧 wasm 缺少该自动保存 procedure 时，返回当前 session，避免填表页被非关键错误打断。
                    tracing::warn!(
                        provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                        session_id = %session_id,
                        owner_user_id = %owner_user_id,
                        error = %error,
                        "拼图表单自动保存 procedure 缺失，降级返回当前会话"
                    );
                    state
                        .spacetime_client()
                        .get_puzzle_agent_session(session_id.clone(), owner_user_id.clone())
                        .await
                        .map_err(|fallback_error| {
                            puzzle_error_response(
                                &request_context,
                                PUZZLE_AGENT_API_BASE_PROVIDER,
                                map_puzzle_client_error(fallback_error),
                            )
                        })
                }
                Err(error) => Err(puzzle_error_response(
                    &request_context,
                    PUZZLE_AGENT_API_BASE_PROVIDER,
                    map_puzzle_client_error(error),
                )),
            };
            (
                "save_puzzle_form_draft",
                "表单草稿保存",
                "拼图表单草稿已保存。",
                session,
            )
        }
        "generate_puzzle_images" => {
            let target_level_id = payload.level_id.clone();
            let levels_json = normalize_puzzle_levels_json_for_module(
                payload.levels_json.as_deref(),
            )
            .map_err(|message| {
                AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                    "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                    "message": message,
                }))
            });
            let session = execute_billable_asset_operation_with_cost(
                &state,
                &owner_user_id,
                "puzzle_generated_image",
                &billing_asset_id,
                PUZZLE_IMAGE_GENERATION_POINTS_COST,
                async {
                    let levels_json = levels_json?;
                    let session = get_puzzle_session_for_image_generation(
                        &state,
                        session_id.clone(),
                        owner_user_id.clone(),
                        &payload,
                        levels_json.as_deref(),
                        now,
                    )
                    .await?;
                    let mut draft = session.draft.clone().ok_or_else(|| {
                        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                            "message": "拼图结果页草稿尚未生成",
                        }))
                    })?;
                    if let Some(levels_json) = levels_json.as_ref() {
                        draft.levels = parse_puzzle_level_records_from_module_json(levels_json)?;
                    }
                    let mut target_level =
                        select_puzzle_level_for_api(&draft, target_level_id.as_deref())?;
                    let fallback_level_name = target_level.level_name.clone();
                    let prompt = resolve_puzzle_level_image_prompt(
                        payload.prompt_text.as_deref(),
                        &target_level.picture_description,
                    );
                    // 拼图结果页从多候选抽卡收口为单图替换，前端传入的旧 candidateCount 只做兼容忽略。
                    let candidate_count = 1;
                    let candidate_start_index = target_level.candidates.len();
                    let candidates = generate_puzzle_image_candidates(
                        &state,
                        owner_user_id.as_str(),
                        &session.session_id,
                        &target_level.level_name,
                        &prompt,
                        payload.reference_image_src.as_deref(),
                        payload.ai_redraw.unwrap_or(true),
                        payload.image_model.as_deref(),
                        candidate_count,
                        candidate_start_index,
                    )
                    .await
                    .map_err(map_puzzle_generation_endpoint_error)?;
                    if candidates.is_empty() {
                        return Err(AppError::from_status(StatusCode::BAD_GATEWAY).with_details(
                            json!({
                                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                                "message": "拼图候选图生成结果为空",
                            }),
                        ));
                    }
                    if let Some(refined_level_name) = generate_puzzle_first_level_name_from_image(
                        &state,
                        target_level.picture_description.as_str(),
                        &candidates[0].downloaded_image,
                    )
                    .await
                    {
                        target_level.level_name = refined_level_name;
                    }
                    let generated_level_name = target_level.level_name.clone();
                    let levels_json_with_generated_name =
                        Some(serialize_puzzle_level_records_for_module(
                            &build_puzzle_levels_with_primary_update(
                                &draft,
                                &target_level,
                                payload.reference_image_src.as_deref(),
                            ),
                        )?);
                    let candidates_json = serde_json::to_string(
                        &candidates
                            .iter()
                            .map(|candidate| to_puzzle_generated_image_candidate(&candidate.record))
                            .collect::<Vec<_>>(),
                    )
                    .map_err(|error| {
                        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                            "message": format!("拼图候选图序列化失败：{error}"),
                        }))
                    })?;
                    let save_result = state
                        .spacetime_client()
                        .save_puzzle_generated_images(PuzzleGeneratedImagesSaveRecordInput {
                            session_id: session.session_id.clone(),
                            owner_user_id: owner_user_id.clone(),
                            level_id: Some(target_level.level_id.clone()),
                            levels_json: levels_json_with_generated_name,
                            candidates_json,
                            saved_at_micros: now,
                        })
                        .await;
                    match save_result {
                        Ok(session) => Ok(session),
                        Err(error)
                            if should_skip_asset_operation_billing_for_connectivity(&error) =>
                        {
                            // 中文注释：VectorEngine/OSS 已生成真实图片时，SpacetimeDB 短暂 503 不应让前端看不到本次图片；先返回内存合成快照，待后续操作恢复正常持久化。
                            tracing::warn!(
                                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                                session_id = %session.session_id,
                                owner_user_id = %owner_user_id,
                                error = %error,
                                "拼图图片已生成但 SpacetimeDB 草稿回写不可用，降级返回本次生成快照"
                            );
                            let fallback_session =
                                replace_puzzle_session_draft_snapshot(session, draft, now);
                            Ok(apply_generated_puzzle_candidates_to_session_snapshot(
                                apply_generated_puzzle_first_level_name_to_session_snapshot(
                                    fallback_session,
                                    target_level.level_id.as_str(),
                                    generated_level_name.as_str(),
                                    fallback_level_name.as_str(),
                                    now,
                                ),
                                target_level.level_id.as_str(),
                                candidates.into_records(),
                                payload.reference_image_src.as_deref(),
                                now,
                            ))
                        }
                        Err(error) => Err(map_puzzle_client_error(error)),
                    }
                },
            )
            .await
            .map_err(|error| {
                puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
            });
            (
                "generate_puzzle_images",
                "拼图图片生成",
                "已生成并替换当前拼图图片。",
                session,
            )
        }
        "generate_puzzle_ui_background" => {
            let target_level_id = payload.level_id.clone();
            let raw_prompt = payload
                .prompt_text
                .as_deref()
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .unwrap_or_default()
                .to_string();
            let levels_json = normalize_puzzle_levels_json_for_module(
                payload.levels_json.as_deref(),
            )
            .map_err(|message| {
                AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                    "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                    "message": message,
                }))
            });
            let session = execute_billable_asset_operation_with_cost(
                &state,
                &owner_user_id,
                "puzzle_ui_background_image",
                &billing_asset_id,
                PUZZLE_IMAGE_GENERATION_POINTS_COST,
                async {
                    let levels_json = levels_json?;
                    let session = get_puzzle_session_for_image_generation(
                        &state,
                        session_id.clone(),
                        owner_user_id.clone(),
                        &payload,
                        levels_json.as_deref(),
                        now,
                    )
                    .await?;
                    let mut draft = session.draft.clone().ok_or_else(|| {
                        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                            "message": "拼图结果页草稿尚未生成",
                        }))
                    })?;
                    if let Some(levels_json) = levels_json.as_ref() {
                        draft.levels = parse_puzzle_level_records_from_module_json(levels_json)?;
                    }
                    let target_level =
                        select_puzzle_level_for_api(&draft, target_level_id.as_deref())?;
                    let resolved_prompt = normalize_puzzle_ui_background_prompt(
                        raw_prompt.as_str(),
                        &draft,
                        &target_level,
                    );
                    let generated = generate_puzzle_ui_background_image(
                        &state,
                        owner_user_id.as_str(),
                        &session.session_id,
                        &target_level.level_name,
                        resolved_prompt.as_str(),
                    )
                    .await
                    .map_err(map_puzzle_generation_endpoint_error)?;
                    let save_result = state
                        .spacetime_client()
                        .save_puzzle_ui_background(PuzzleUiBackgroundSaveRecordInput {
                            session_id: session.session_id.clone(),
                            owner_user_id: owner_user_id.clone(),
                            level_id: Some(target_level.level_id.clone()),
                            levels_json,
                            prompt: resolved_prompt.clone(),
                            image_src: generated.image_src.clone(),
                            image_object_key: Some(generated.object_key.clone()),
                            saved_at_micros: now,
                        })
                        .await;
                    match save_result {
                        Ok(session) => Ok(session),
                        Err(error)
                            if should_skip_asset_operation_billing_for_connectivity(&error) =>
                        {
                            tracing::warn!(
                                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                                session_id = %session.session_id,
                                owner_user_id = %owner_user_id,
                                error = %error,
                                "拼图 UI 背景图已生成但 SpacetimeDB 草稿回写不可用，降级返回本次生成快照"
                            );
                            let fallback_session =
                                replace_puzzle_session_draft_snapshot(session, draft, now);
                            Ok(apply_generated_puzzle_ui_background_to_session_snapshot(
                                fallback_session,
                                target_level.level_id.as_str(),
                                resolved_prompt,
                                generated.image_src,
                                Some(generated.object_key),
                                now,
                            ))
                        }
                        Err(error) => Err(map_puzzle_client_error(error)),
                    }
                },
            )
            .await
            .map_err(|error| {
                puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
            });
            (
                "generate_puzzle_ui_background",
                "UI 背景图生成",
                "已生成拼图 UI 背景图。",
                session,
            )
        }
        "generate_puzzle_tags" => {
            let work_title = payload
                .work_title
                .as_deref()
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .ok_or_else(|| {
                    puzzle_bad_request(
                        &request_context,
                        PUZZLE_AGENT_API_BASE_PROVIDER,
                        "作品名称不能为空",
                    )
                })?;
            let work_description = payload
                .work_description
                .as_deref()
                .map(str::trim)
                .filter(|value| !value.is_empty())
                .ok_or_else(|| {
                    puzzle_bad_request(
                        &request_context,
                        PUZZLE_AGENT_API_BASE_PROVIDER,
                        "作品描述不能为空",
                    )
                })?;
            let levels_json = normalize_puzzle_levels_json_for_module(
                payload.levels_json.as_deref(),
            )
            .map_err(|message| {
                puzzle_error_response(
                    &request_context,
                    PUZZLE_AGENT_API_BASE_PROVIDER,
                    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                        "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                        "message": message,
                    })),
                )
            })?;
            let generated_tags =
                generate_puzzle_work_tags(&state, work_title, work_description).await;
            let session = save_generated_puzzle_tags_to_session(
                &state,
                &session_id,
                &owner_user_id,
                &payload,
                generated_tags,
                levels_json,
                now,
            )
            .await
            .map_err(|error| {
                puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
            });
            (
                "generate_puzzle_tags",
                "作品标签生成",
                "已生成 6 个作品标签。",
                session,
            )
        }
        "select_puzzle_image" => {
            let candidate_id = payload
                .candidate_id
                .clone()
                .filter(|value| !value.trim().is_empty())
                .ok_or_else(|| {
                    puzzle_bad_request(
                        &request_context,
                        PUZZLE_AGENT_API_BASE_PROVIDER,
                        "candidateId is required",
                    )
                })?;
            let session = state
                .spacetime_client()
                .select_puzzle_cover_image(PuzzleSelectCoverImageRecordInput {
                    session_id: session_id.clone(),
                    owner_user_id: owner_user_id.clone(),
                    level_id: payload.level_id.clone(),
                    candidate_id,
                    selected_at_micros: now,
                })
                .await
                .map_err(|error| {
                    puzzle_error_response(
                        &request_context,
                        PUZZLE_AGENT_API_BASE_PROVIDER,
                        map_puzzle_client_error(error),
                    )
                });
            (
                "select_puzzle_image",
                "正式图确认",
                "已应用正式拼图图片。",
                session,
            )
        }
        "publish_puzzle_work" => {
            let levels_json = normalize_puzzle_levels_json_for_module(
                payload.levels_json.as_deref(),
            )
            .map_err(|error| {
                puzzle_error_response(
                    &request_context,
                    PUZZLE_AGENT_API_BASE_PROVIDER,
                    AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                        "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                        "message": error,
                    })),
                )
            })?;
            let (work_id, profile_id) = build_stable_puzzle_work_ids(&session_id);
            let author_display_name = resolve_author_display_name(&state, &authenticated);
            let profile = execute_billable_asset_operation(
                &state,
                &owner_user_id,
                "puzzle_publish_work",
                &work_id,
                async {
                    state
                        .spacetime_client()
                        .publish_puzzle_work(PuzzlePublishRecordInput {
                            session_id: session_id.clone(),
                            owner_user_id: owner_user_id.clone(),
                            // 发布沿用 session 派生的稳定作品 ID，避免草稿卡与已发布卡重复。
                            work_id: work_id.clone(),
                            profile_id,
                            author_display_name,
                            work_title: payload.work_title.clone(),
                            work_description: payload.work_description.clone(),
                            level_name: payload.level_name.clone(),
                            summary: payload.summary.clone(),
                            theme_tags: payload.theme_tags.clone(),
                            levels_json,
                            published_at_micros: now,
                        })
                        .await
                        .map_err(map_puzzle_client_error)
                },
            )
            .await
            .map_err(|error| {
                puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
            })?;

            let session = state
                .spacetime_client()
                .get_puzzle_agent_session(session_id.clone(), owner_user_id.clone())
                .await
                .map_err(|error| {
                    puzzle_error_response(
                        &request_context,
                        PUZZLE_AGENT_API_BASE_PROVIDER,
                        map_puzzle_client_error(error),
                    )
                })?;

            return Ok(json_success_body(
                Some(&request_context),
                PuzzleAgentActionResponse {
                    operation: PuzzleAgentOperationResponse {
                        operation_id: profile.profile_id.clone(),
                        operation_type: "publish_puzzle_work".to_string(),
                        status: "completed".to_string(),
                        phase_label: "作品发布".to_string(),
                        phase_detail: "拼图作品已发布到广场。".to_string(),
                        progress: 100,
                        error: None,
                    },
                    session: map_puzzle_agent_session_response(session),
                },
            ));
        }
        other => {
            return Err(puzzle_bad_request(
                &request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                format!("action `{other}` is not supported").as_str(),
            ));
        }
    };

    let session = session?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleAgentActionResponse {
            operation: PuzzleAgentOperationResponse {
                operation_id: session.session_id.clone(),
                operation_type: operation_type.to_string(),
                status: "completed".to_string(),
                phase_label: phase_label.to_string(),
                phase_detail: phase_detail.to_string(),
                progress: 100,
                error: None,
            },
            session: map_puzzle_agent_session_response(session),
        },
    ))
}

pub async fn get_puzzle_works(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    let items = state
        .spacetime_client()
        .list_puzzle_works(authenticated.claims().user_id().to_string())
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleWorksResponse {
            items: items
                .into_iter()
                .map(|item| map_puzzle_work_summary_response(&state, item))
                .collect(),
        },
    ))
}

pub async fn get_puzzle_work_detail(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(_authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_WORKS_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let item = state
        .spacetime_client()
        .get_puzzle_work_detail(profile_id)
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleWorkDetailResponse {
            item: map_puzzle_work_profile_response(&state, item),
        },
    ))
}

pub async fn put_puzzle_work(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<PutPuzzleWorkRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_WORKS_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_WORKS_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(
        &request_context,
        PUZZLE_WORKS_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let item = state
        .spacetime_client()
        .update_puzzle_work(PuzzleWorkUpsertRecordInput {
            profile_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            work_title: payload.work_title,
            work_description: payload.work_description,
            level_name: payload.level_name,
            summary: payload.summary,
            theme_tags: payload.theme_tags,
            cover_image_src: payload.cover_image_src,
            cover_asset_id: payload.cover_asset_id,
            levels_json: Some(serialize_puzzle_levels_response(
                &request_context,
                &payload.levels,
            )?),
            updated_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleWorkMutationResponse {
            item: map_puzzle_work_profile_response(&state, item),
        },
    ))
}

pub async fn delete_puzzle_work(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_WORKS_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let items = state
        .spacetime_client()
        .delete_puzzle_work(profile_id, authenticated.claims().user_id().to_string())
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleWorksResponse {
            items: items
                .into_iter()
                .map(|item| map_puzzle_work_summary_response(&state, item))
                .collect(),
        },
    ))
}

pub async fn claim_puzzle_work_point_incentive(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_WORKS_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let item = state
        .spacetime_client()
        .claim_puzzle_work_point_incentive(PuzzleWorkPointIncentiveClaimRecordInput {
            profile_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            claimed_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_WORKS_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleWorkMutationResponse {
            item: map_puzzle_work_profile_response(&state, item),
        },
    ))
}

pub async fn list_puzzle_gallery(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
) -> Result<Json<Value>, Response> {
    let items = state
        .spacetime_client()
        .list_puzzle_gallery()
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_GALLERY_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleGalleryResponse {
            items: items
                .into_iter()
                .map(|item| map_puzzle_work_summary_response(&state, item))
                .collect(),
        },
    ))
}

pub async fn get_puzzle_gallery_detail(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_GALLERY_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let item = state
        .spacetime_client()
        .get_puzzle_gallery_detail(profile_id)
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_GALLERY_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleGalleryDetailResponse {
            item: map_puzzle_work_profile_response(&state, item),
        },
    ))
}

pub async fn record_puzzle_gallery_like(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_GALLERY_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let item = state
        .spacetime_client()
        .record_puzzle_work_like(PuzzleWorkLikeReportRecordInput {
            profile_id,
            user_id: authenticated.claims().user_id().to_string(),
            liked_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_GALLERY_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleGalleryDetailResponse {
            item: map_puzzle_work_profile_response(&state, item),
        },
    ))
}

pub async fn remix_puzzle_gallery_work(
    State(state): State<AppState>,
    AxumPath(profile_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(
        &request_context,
        PUZZLE_GALLERY_PROVIDER,
        &profile_id,
        "profileId",
    )?;

    let owner_user_id = authenticated.claims().user_id().to_string();
    let session = state
        .spacetime_client()
        .remix_puzzle_work(PuzzleWorkRemixRecordInput {
            source_profile_id: profile_id,
            target_owner_user_id: owner_user_id,
            target_session_id: build_prefixed_uuid_id("puzzle-session-"),
            target_profile_id: build_prefixed_uuid_id("puzzle-profile-"),
            target_work_id: build_prefixed_uuid_id("puzzle-work-"),
            author_display_name: resolve_author_display_name(&state, &authenticated),
            welcome_message_id: build_prefixed_uuid_id("puzzle-message-"),
            remixed_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_GALLERY_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleAgentSessionResponse {
            session: map_puzzle_agent_session_response(session),
        },
    ))
}

pub async fn start_puzzle_run(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<StartPuzzleRunRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_RUNTIME_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_RUNTIME_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(
        &request_context,
        PUZZLE_RUNTIME_PROVIDER,
        &payload.profile_id,
        "profileId",
    )?;

    let run = state
        .spacetime_client()
        .start_puzzle_run(PuzzleRunStartRecordInput {
            run_id: build_prefixed_uuid_id("puzzle-run-"),
            owner_user_id: authenticated.claims().user_id().to_string(),
            profile_id: payload.profile_id.clone(),
            level_id: payload.level_id.clone(),
            started_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    record_work_play_start_after_success(
        &state,
        &request_context,
        WorkPlayTrackingDraft::new(
            "puzzle",
            payload.profile_id.clone(),
            &authenticated,
            "/api/runtime/puzzle/...",
        )
        .profile_id(payload.profile_id.clone())
        .extra(json!({
            "levelId": payload.level_id,
            "runId": run.run_id,
        })),
    )
    .await;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn get_puzzle_run(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;

    let run = state
        .spacetime_client()
        .get_puzzle_run(run_id, authenticated.claims().user_id().to_string())
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn swap_puzzle_pieces(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<SwapPuzzlePiecesRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_RUNTIME_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_RUNTIME_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;
    ensure_non_empty(
        &request_context,
        PUZZLE_RUNTIME_PROVIDER,
        &payload.first_piece_id,
        "firstPieceId",
    )?;
    ensure_non_empty(
        &request_context,
        PUZZLE_RUNTIME_PROVIDER,
        &payload.second_piece_id,
        "secondPieceId",
    )?;

    let run = state
        .spacetime_client()
        .swap_puzzle_pieces(PuzzleRunSwapRecordInput {
            run_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            first_piece_id: payload.first_piece_id,
            second_piece_id: payload.second_piece_id,
            swapped_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn drag_puzzle_piece_or_group(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<DragPuzzlePieceRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_RUNTIME_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_RUNTIME_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;
    ensure_non_empty(
        &request_context,
        PUZZLE_RUNTIME_PROVIDER,
        &payload.piece_id,
        "pieceId",
    )?;

    let run = state
        .spacetime_client()
        .drag_puzzle_piece_or_group(PuzzleRunDragRecordInput {
            run_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            piece_id: payload.piece_id,
            target_row: payload.target_row,
            target_col: payload.target_col,
            dragged_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn advance_puzzle_next_level(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<AdvancePuzzleNextLevelRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;
    let payload = match payload {
        Ok(Json(payload)) => payload,
        Err(error) if error.status() == StatusCode::UNSUPPORTED_MEDIA_TYPE => {
            AdvancePuzzleNextLevelRequest {
                target_profile_id: None,
            }
        }
        Err(error) => {
            return Err(puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                    "provider": PUZZLE_RUNTIME_PROVIDER,
                    "message": error.body_text(),
                })),
            ));
        }
    };

    let run = state
        .spacetime_client()
        .advance_puzzle_next_level(spacetime_client::PuzzleRunNextLevelRecordInput {
            run_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            target_profile_id: payload.target_profile_id,
            advanced_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn update_puzzle_run_pause(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<UpdatePuzzleRuntimePauseRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_RUNTIME_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_RUNTIME_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;

    let run = state
        .spacetime_client()
        .update_puzzle_run_pause(PuzzleRunPauseRecordInput {
            run_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            paused: payload.paused,
            updated_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn use_puzzle_runtime_prop(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<UsePuzzleRuntimePropRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_RUNTIME_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_RUNTIME_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;
    ensure_non_empty(
        &request_context,
        PUZZLE_RUNTIME_PROVIDER,
        &payload.prop_kind,
        "propKind",
    )?;

    let owner_user_id = authenticated.claims().user_id().to_string();
    let prop_kind = payload.prop_kind.trim().to_string();
    let billing_asset_kind = match prop_kind.as_str() {
        "hint" => "puzzle_prop_hint",
        "reference" => "puzzle_prop_preview",
        "freezeTime" | "freeze_time" => "puzzle_prop_freeze_time",
        "extendTime" | "extend_time" => "puzzle_prop_extend_time",
        _ => {
            return Err(puzzle_bad_request(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                "unknown puzzle prop kind",
            ));
        }
    };
    let should_sync_freeze_boundary = matches!(prop_kind.as_str(), "freezeTime" | "freeze_time");
    let billing_asset_id = format!("{}:{}:{}", run_id, prop_kind, current_utc_micros());
    let reducer_owner_user_id = owner_user_id.clone();
    let reducer_run_id = run_id.clone();
    let fallback_run_id = run_id.clone();
    let fallback_owner_user_id = owner_user_id.clone();
    let run_result = execute_billable_asset_operation(
        &state,
        &owner_user_id,
        billing_asset_kind,
        billing_asset_id.as_str(),
        async {
            state
                .spacetime_client()
                .use_puzzle_runtime_prop(PuzzleRunPropRecordInput {
                    run_id: reducer_run_id,
                    owner_user_id: reducer_owner_user_id,
                    prop_kind,
                    used_at_micros: current_utc_micros(),
                    spent_points: crate::asset_billing::ASSET_OPERATION_POINTS_COST,
                })
                .await
                .map_err(map_puzzle_client_error)
        },
    )
    .await;

    let run = match run_result {
        Ok(run) => run,
        Err(error) if should_sync_puzzle_freeze_boundary(&error, should_sync_freeze_boundary) => {
            // 中文注释：冻结确认窗打开时前端会暂停视觉计时，但正式 run 仍可能在服务端边界帧先结算失败。
            // 这类情况已由扣费包装器退款，此处只同步失败态快照，避免玩家看到“操作不合法”。
            state
                .spacetime_client()
                .get_puzzle_run(fallback_run_id, fallback_owner_user_id)
                .await
                .map_err(map_puzzle_client_error)
                .map_err(|error| {
                    puzzle_error_response(&request_context, PUZZLE_RUNTIME_PROVIDER, error)
                })?
        }
        Err(error) => {
            return Err(puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                error,
            ));
        }
    };

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

pub async fn submit_puzzle_leaderboard(
    State(state): State<AppState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
    Extension(authenticated): Extension<AuthenticatedAccessToken>,
    payload: Result<Json<SubmitPuzzleLeaderboardRequest>, JsonRejection>,
) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
        puzzle_error_response(
            &request_context,
            PUZZLE_RUNTIME_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_RUNTIME_PROVIDER,
                "message": error.body_text(),
            })),
        )
    })?;

    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;

    let run = state
        .spacetime_client()
        .submit_puzzle_leaderboard_entry(PuzzleLeaderboardSubmitRecordInput {
            run_id,
            owner_user_id: authenticated.claims().user_id().to_string(),
            profile_id: payload.profile_id,
            grid_size: payload.grid_size,
            elapsed_ms: payload.elapsed_ms.max(1_000),
            nickname: payload.nickname.trim().to_string(),
            submitted_at_micros: current_utc_micros(),
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                &request_context,
                PUZZLE_RUNTIME_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;

    Ok(json_success_body(
        Some(&request_context),
        PuzzleRunResponse {
            run: map_puzzle_run_response(enrich_puzzle_run_author_name(&state, run).await),
        },
    ))
}

fn map_puzzle_agent_session_response(
    session: PuzzleAgentSessionRecord,
) -> PuzzleAgentSessionSnapshotResponse {
    PuzzleAgentSessionSnapshotResponse {
        session_id: session.session_id,
        seed_text: session.seed_text,
        current_turn: session.current_turn,
        progress_percent: session.progress_percent,
        stage: session.stage,
        anchor_pack: map_puzzle_anchor_pack_response(session.anchor_pack),
        draft: session.draft.map(map_puzzle_result_draft_response),
        messages: session
            .messages
            .into_iter()
            .map(map_puzzle_agent_message_response)
            .collect(),
        last_assistant_reply: session.last_assistant_reply,
        published_profile_id: session.published_profile_id,
        suggested_actions: session
            .suggested_actions
            .into_iter()
            .map(map_puzzle_suggested_action_response)
            .collect(),
        result_preview: session
            .result_preview
            .map(map_puzzle_result_preview_response),
        updated_at: session.updated_at,
    }
}

fn map_puzzle_anchor_pack_response(
    anchor_pack: PuzzleAnchorPackRecord,
) -> PuzzleAnchorPackResponse {
    PuzzleAnchorPackResponse {
        theme_promise: map_puzzle_anchor_item_response(anchor_pack.theme_promise),
        visual_subject: map_puzzle_anchor_item_response(anchor_pack.visual_subject),
        visual_mood: map_puzzle_anchor_item_response(anchor_pack.visual_mood),
        composition_hooks: map_puzzle_anchor_item_response(anchor_pack.composition_hooks),
        tags_and_forbidden: map_puzzle_anchor_item_response(anchor_pack.tags_and_forbidden),
    }
}

fn map_puzzle_anchor_item_response(anchor: PuzzleAnchorItemRecord) -> PuzzleAnchorItemResponse {
    PuzzleAnchorItemResponse {
        key: anchor.key,
        label: anchor.label,
        value: anchor.value,
        status: anchor.status,
    }
}

fn map_puzzle_result_draft_response(draft: PuzzleResultDraftRecord) -> PuzzleResultDraftResponse {
    PuzzleResultDraftResponse {
        work_title: draft.work_title,
        work_description: draft.work_description,
        level_name: draft.level_name,
        summary: draft.summary,
        theme_tags: draft.theme_tags,
        forbidden_directives: draft.forbidden_directives,
        creator_intent: draft.creator_intent.map(map_puzzle_creator_intent_response),
        anchor_pack: map_puzzle_anchor_pack_response(draft.anchor_pack),
        candidates: draft
            .candidates
            .into_iter()
            .map(map_puzzle_generated_image_candidate_response)
            .collect(),
        selected_candidate_id: draft.selected_candidate_id,
        cover_image_src: draft.cover_image_src,
        cover_asset_id: draft.cover_asset_id,
        generation_status: draft.generation_status,
        levels: draft
            .levels
            .into_iter()
            .map(map_puzzle_draft_level_response)
            .collect(),
        form_draft: draft.form_draft.map(map_puzzle_form_draft_response),
    }
}

fn map_puzzle_form_draft_response(draft: PuzzleFormDraftRecord) -> PuzzleFormDraftResponse {
    PuzzleFormDraftResponse {
        work_title: draft.work_title,
        work_description: draft.work_description,
        picture_description: draft.picture_description,
    }
}

fn map_puzzle_draft_level_response(level: PuzzleDraftLevelRecord) -> PuzzleDraftLevelResponse {
    PuzzleDraftLevelResponse {
        level_id: level.level_id,
        level_name: level.level_name,
        picture_description: level.picture_description,
        picture_reference: level.picture_reference,
        ui_background_prompt: level.ui_background_prompt,
        ui_background_image_src: level.ui_background_image_src,
        ui_background_image_object_key: level.ui_background_image_object_key,
        background_music: level.background_music.map(map_puzzle_audio_asset_record_response),
        candidates: level
            .candidates
            .into_iter()
            .map(map_puzzle_generated_image_candidate_response)
            .collect(),
        selected_candidate_id: level.selected_candidate_id,
        cover_image_src: level.cover_image_src,
        cover_asset_id: level.cover_asset_id,
        generation_status: level.generation_status,
    }
}

fn map_puzzle_audio_asset_record_response(asset: PuzzleAudioAssetRecord) -> CreationAudioAsset {
    CreationAudioAsset {
        task_id: asset.task_id,
        provider: asset.provider,
        asset_object_id: asset.asset_object_id,
        asset_kind: asset.asset_kind,
        audio_src: asset.audio_src,
        prompt: asset.prompt,
        title: asset.title,
        updated_at: asset.updated_at,
    }
}

fn map_puzzle_audio_asset_domain_record(
    asset: module_puzzle::PuzzleAudioAsset,
) -> PuzzleAudioAssetRecord {
    PuzzleAudioAssetRecord {
        task_id: asset.task_id,
        provider: asset.provider,
        asset_object_id: asset.asset_object_id,
        asset_kind: asset.asset_kind,
        audio_src: asset.audio_src,
        prompt: asset.prompt,
        title: asset.title,
        updated_at: asset.updated_at,
    }
}

fn puzzle_audio_asset_response_module_json(asset: &Option<CreationAudioAsset>) -> Value {
    asset
        .as_ref()
        .map(|asset| {
            json!({
                "task_id": asset.task_id,
                "provider": asset.provider,
                "asset_object_id": asset.asset_object_id,
                "asset_kind": asset.asset_kind,
                "audio_src": asset.audio_src,
                "prompt": asset.prompt,
                "title": asset.title,
                "updated_at": asset.updated_at,
            })
        })
        .unwrap_or(Value::Null)
}

fn puzzle_audio_asset_record_module_json(asset: &Option<PuzzleAudioAssetRecord>) -> Value {
    asset
        .as_ref()
        .map(|asset| {
            json!({
                "task_id": asset.task_id,
                "provider": asset.provider,
                "asset_object_id": asset.asset_object_id,
                "asset_kind": asset.asset_kind,
                "audio_src": asset.audio_src,
                "prompt": asset.prompt,
                "title": asset.title,
                "updated_at": asset.updated_at,
            })
        })
        .unwrap_or(Value::Null)
}

fn map_puzzle_creator_intent_response(
    intent: PuzzleCreatorIntentRecord,
) -> PuzzleCreatorIntentResponse {
    PuzzleCreatorIntentResponse {
        source_mode: intent.source_mode,
        raw_messages_summary: intent.raw_messages_summary,
        theme_promise: intent.theme_promise,
        visual_subject: intent.visual_subject,
        visual_mood: intent.visual_mood,
        composition_hooks: intent.composition_hooks,
        theme_tags: intent.theme_tags,
        forbidden_directives: intent.forbidden_directives,
    }
}

fn map_puzzle_generated_image_candidate_response(
    candidate: PuzzleGeneratedImageCandidateRecord,
) -> PuzzleGeneratedImageCandidateResponse {
    PuzzleGeneratedImageCandidateResponse {
        candidate_id: candidate.candidate_id,
        image_src: candidate.image_src,
        asset_id: candidate.asset_id,
        prompt: candidate.prompt,
        actual_prompt: candidate.actual_prompt,
        source_type: candidate.source_type,
        selected: candidate.selected,
    }
}

fn map_puzzle_agent_message_response(
    message: PuzzleAgentMessageRecord,
) -> PuzzleAgentMessageResponse {
    PuzzleAgentMessageResponse {
        id: message.message_id,
        role: message.role,
        kind: message.kind,
        text: message.text,
        created_at: message.created_at,
    }
}

fn map_puzzle_suggested_action_response(
    action: PuzzleAgentSuggestedActionRecord,
) -> PuzzleAgentSuggestedActionResponse {
    PuzzleAgentSuggestedActionResponse {
        id: action.action_id,
        action_type: action.action_type,
        label: action.label,
    }
}

fn map_puzzle_result_preview_response(
    preview: PuzzleResultPreviewRecord,
) -> PuzzleResultPreviewEnvelopeResponse {
    PuzzleResultPreviewEnvelopeResponse {
        draft: map_puzzle_result_draft_response(preview.draft),
        blockers: preview
            .blockers
            .into_iter()
            .map(map_puzzle_result_preview_blocker_response)
            .collect(),
        quality_findings: preview
            .quality_findings
            .into_iter()
            .map(map_puzzle_result_preview_finding_response)
            .collect(),
        publish_ready: preview.publish_ready,
    }
}

fn map_puzzle_result_preview_blocker_response(
    blocker: PuzzleResultPreviewBlockerRecord,
) -> PuzzleResultPreviewBlockerResponse {
    PuzzleResultPreviewBlockerResponse {
        id: blocker.blocker_id,
        code: blocker.code,
        message: blocker.message,
    }
}

fn map_puzzle_result_preview_finding_response(
    finding: PuzzleResultPreviewFindingRecord,
) -> PuzzleResultPreviewFindingResponse {
    PuzzleResultPreviewFindingResponse {
        id: finding.finding_id,
        severity: finding.severity,
        code: finding.code,
        message: finding.message,
    }
}

fn map_puzzle_work_summary_response(
    state: &AppState,
    item: PuzzleWorkProfileRecord,
) -> PuzzleWorkSummaryResponse {
    let author = resolve_work_author_by_user_id(
        state,
        &item.owner_user_id,
        Some(&item.author_display_name),
        None,
    );
    PuzzleWorkSummaryResponse {
        work_id: item.work_id,
        profile_id: item.profile_id,
        owner_user_id: item.owner_user_id,
        source_session_id: item.source_session_id,
        author_display_name: author.display_name,
        work_title: item.work_title,
        work_description: item.work_description,
        level_name: item.level_name,
        summary: item.summary,
        theme_tags: item.theme_tags,
        cover_image_src: item.cover_image_src,
        cover_asset_id: item.cover_asset_id,
        publication_status: item.publication_status,
        updated_at: item.updated_at,
        published_at: item.published_at,
        play_count: item.play_count,
        remix_count: item.remix_count,
        like_count: item.like_count,
        recent_play_count_7d: item.recent_play_count_7d,
        point_incentive_total_half_points: item.point_incentive_total_half_points,
        point_incentive_claimed_points: item.point_incentive_claimed_points,
        point_incentive_total_points: item.point_incentive_total_half_points as f64 / 2.0,
        point_incentive_claimable_points: item
            .point_incentive_total_half_points
            .saturating_div(2)
            .saturating_sub(item.point_incentive_claimed_points),
        publish_ready: item.publish_ready,
        levels: Vec::new(),
    }
}

fn map_puzzle_work_profile_response(
    state: &AppState,
    item: PuzzleWorkProfileRecord,
) -> PuzzleWorkProfileResponse {
    let mut summary = map_puzzle_work_summary_response(state, item.clone());
    summary.levels = item
        .levels
        .into_iter()
        .map(map_puzzle_draft_level_response)
        .collect();

    PuzzleWorkProfileResponse {
        summary,
        anchor_pack: map_puzzle_anchor_pack_response(item.anchor_pack),
    }
}

fn map_puzzle_run_response(run: PuzzleRunRecord) -> PuzzleRunSnapshotResponse {
    PuzzleRunSnapshotResponse {
        run_id: run.run_id,
        entry_profile_id: run.entry_profile_id,
        cleared_level_count: run.cleared_level_count,
        current_level_index: run.current_level_index,
        current_grid_size: run.current_grid_size,
        played_profile_ids: run.played_profile_ids,
        previous_level_tags: run.previous_level_tags,
        current_level: run.current_level.map(map_puzzle_runtime_level_response),
        recommended_next_profile_id: run.recommended_next_profile_id,
        next_level_mode: run.next_level_mode,
        next_level_profile_id: run.next_level_profile_id,
        next_level_id: run.next_level_id,
        recommended_next_works: run
            .recommended_next_works
            .into_iter()
            .map(map_puzzle_recommended_next_work_response)
            .collect(),
        leaderboard_entries: run
            .leaderboard_entries
            .into_iter()
            .map(map_puzzle_leaderboard_entry_response)
            .collect(),
    }
}

fn map_puzzle_recommended_next_work_response(
    item: PuzzleRecommendedNextWorkRecord,
) -> PuzzleRecommendedNextWorkResponse {
    PuzzleRecommendedNextWorkResponse {
        profile_id: item.profile_id,
        level_name: item.level_name,
        author_display_name: item.author_display_name,
        theme_tags: item.theme_tags,
        cover_image_src: item.cover_image_src,
        similarity_score: item.similarity_score,
    }
}

async fn enrich_puzzle_run_author_name(
    state: &AppState,
    mut run: PuzzleRunRecord,
) -> PuzzleRunRecord {
    if let Some(level) = run.current_level.as_mut() {
        if let Ok(profile) = state
            .spacetime_client()
            .get_puzzle_gallery_detail(level.profile_id.clone())
            .await
        {
            level.author_display_name = resolve_work_author_by_user_id(
                state,
                &profile.owner_user_id,
                Some(&profile.author_display_name),
                None,
            )
            .display_name;
        }
    }

    run
}

fn map_puzzle_runtime_level_response(
    level: spacetime_client::PuzzleRuntimeLevelRecord,
) -> PuzzleRuntimeLevelSnapshotResponse {
    let timer_defaults =
        build_puzzle_runtime_timer_response_defaults(level.level_index, level.grid_size);
    let time_limit_ms = if level.time_limit_ms == 0 {
        timer_defaults.time_limit_ms
    } else {
        level.time_limit_ms
    };
    let remaining_ms =
        if level.remaining_ms == 0 && level.status == PuzzleRuntimeLevelStatus::Playing.as_str() {
            time_limit_ms
        } else {
            level.remaining_ms.min(time_limit_ms)
        };
    PuzzleRuntimeLevelSnapshotResponse {
        run_id: level.run_id,
        level_index: level.level_index,
        level_id: level.level_id,
        grid_size: level.grid_size,
        profile_id: level.profile_id,
        level_name: level.level_name,
        author_display_name: level.author_display_name,
        theme_tags: level.theme_tags,
        cover_image_src: level.cover_image_src,
        ui_background_image_src: level.ui_background_image_src,
        background_music: level.background_music.map(map_puzzle_audio_asset_record_response),
        board: map_puzzle_board_response(level.board),
        status: level.status,
        started_at_ms: level.started_at_ms,
        cleared_at_ms: level.cleared_at_ms,
        elapsed_ms: level.elapsed_ms,
        time_limit_ms,
        remaining_ms,
        paused_accumulated_ms: level.paused_accumulated_ms,
        pause_started_at_ms: level.pause_started_at_ms,
        freeze_accumulated_ms: level.freeze_accumulated_ms,
        freeze_started_at_ms: level.freeze_started_at_ms,
        freeze_until_ms: level.freeze_until_ms,
        leaderboard_entries: level
            .leaderboard_entries
            .into_iter()
            .map(map_puzzle_leaderboard_entry_response)
            .collect(),
    }
}

struct PuzzleRuntimeTimerResponseDefaults {
    time_limit_ms: u64,
}

fn build_puzzle_runtime_timer_response_defaults(
    level_index: u32,
    grid_size: u32,
) -> PuzzleRuntimeTimerResponseDefaults {
    let time_limit_ms = if level_index > 0 {
        module_puzzle::resolve_puzzle_level_time_limit_ms_by_index(level_index)
    } else {
        module_puzzle::resolve_puzzle_level_time_limit_ms(grid_size)
    };
    PuzzleRuntimeTimerResponseDefaults { time_limit_ms }
}

fn map_puzzle_leaderboard_entry_response(
    entry: PuzzleLeaderboardEntryRecord,
) -> PuzzleLeaderboardEntryResponse {
    PuzzleLeaderboardEntryResponse {
        rank: entry.rank,
        nickname: entry.nickname,
        elapsed_ms: entry.elapsed_ms,
        visible_tags: entry.visible_tags,
        is_current_player: entry.is_current_player,
    }
}

fn map_puzzle_board_response(
    board: spacetime_client::PuzzleBoardRecord,
) -> PuzzleBoardSnapshotResponse {
    PuzzleBoardSnapshotResponse {
        rows: board.rows,
        cols: board.cols,
        pieces: board
            .pieces
            .into_iter()
            .map(|piece| PuzzlePieceStateResponse {
                piece_id: piece.piece_id,
                correct_row: piece.correct_row,
                correct_col: piece.correct_col,
                current_row: piece.current_row,
                current_col: piece.current_col,
                merged_group_id: piece.merged_group_id,
            })
            .collect(),
        merged_groups: board
            .merged_groups
            .into_iter()
            .map(|group| PuzzleMergedGroupStateResponse {
                group_id: group.group_id,
                piece_ids: group.piece_ids,
                occupied_cells: group
                    .occupied_cells
                    .into_iter()
                    .map(|cell| PuzzleCellPositionResponse {
                        row: cell.row,
                        col: cell.col,
                    })
                    .collect(),
            })
            .collect(),
        selected_piece_id: board.selected_piece_id,
        all_tiles_resolved: board.all_tiles_resolved,
    }
}

fn resolve_author_display_name(
    state: &AppState,
    authenticated: &AuthenticatedAccessToken,
) -> String {
    state
        .auth_user_service()
        .get_user_by_id(authenticated.claims().user_id())
        .ok()
        .flatten()
        .map(|user| user.display_name)
        .filter(|value| !value.trim().is_empty())
        .unwrap_or_else(|| "玩家".to_string())
}

fn build_puzzle_welcome_text(seed_text: &str) -> String {
    if seed_text.trim().is_empty() {
        return "拼图创作信息已准备好。".to_string();
    }

    "拼图创作信息已准备好。".to_string()
}

fn build_puzzle_form_seed_text(payload: &CreatePuzzleAgentSessionRequest) -> String {
    build_puzzle_form_seed_prompt(PuzzleFormSeedPromptParts {
        title: None,
        work_description: None,
        picture_description: payload
            .picture_description
            .as_deref()
            .or(payload.seed_text.as_deref()),
    })
}

fn build_puzzle_form_seed_text_from_parts(
    title: Option<&str>,
    work_description: Option<&str>,
    picture_description: Option<&str>,
) -> String {
    build_puzzle_form_seed_prompt(PuzzleFormSeedPromptParts {
        title,
        work_description,
        picture_description,
    })
}

async fn save_puzzle_form_payload_before_compile(
    state: &AppState,
    request_context: &RequestContext,
    session_id: &str,
    owner_user_id: &str,
    payload: &ExecutePuzzleAgentActionRequest,
    now: i64,
) -> Result<String, Response> {
    let seed_text = build_puzzle_form_seed_text_from_parts(
        None,
        None,
        payload
            .picture_description
            .as_deref()
            .or(payload.prompt_text.as_deref()),
    );
    if seed_text.trim().is_empty() {
        return Ok(session_id.to_string());
    }

    let save_result = state
        .spacetime_client()
        .save_puzzle_form_draft(PuzzleFormDraftSaveRecordInput {
            session_id: session_id.to_string(),
            owner_user_id: owner_user_id.to_string(),
            seed_text: seed_text.clone(),
            saved_at_micros: now,
        })
        .await
        .map(|_| ());
    match save_result {
        Ok(()) => Ok(session_id.to_string()),
        Err(error) if is_missing_puzzle_form_draft_procedure_error(&error) => {
            create_seeded_puzzle_session_when_form_save_missing(
                state,
                request_context,
                session_id,
                owner_user_id,
                seed_text,
                now,
                &error,
            )
            .await
        }
        Err(error) => Err(puzzle_error_response(
            request_context,
            PUZZLE_AGENT_API_BASE_PROVIDER,
            map_puzzle_client_error(error),
        )),
    }
}

async fn create_seeded_puzzle_session_when_form_save_missing(
    state: &AppState,
    request_context: &RequestContext,
    session_id: &str,
    owner_user_id: &str,
    seed_text: String,
    now: i64,
    original_error: &SpacetimeClientError,
) -> Result<String, Response> {
    let current_session = state
        .spacetime_client()
        .get_puzzle_agent_session(session_id.to_string(), owner_user_id.to_string())
        .await
        .map_err(|error| {
            puzzle_error_response(
                request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;
    if !current_session.seed_text.trim().is_empty() {
        tracing::warn!(
            provider = PUZZLE_AGENT_API_BASE_PROVIDER,
            session_id,
            owner_user_id,
            error = %original_error,
            "拼图表单草稿保存 procedure 缺失，沿用已有 seed_text 编译"
        );
        return Ok(session_id.to_string());
    }

    // 中文注释：旧 wasm 缺自动保存 procedure 时，空 session 无法被编译；这里重建带表单 seed 的 session 保证生成主链可继续。
    let replacement_session_id = build_prefixed_uuid_id("puzzle-session-");
    let replacement = state
        .spacetime_client()
        .create_puzzle_agent_session(PuzzleAgentSessionCreateRecordInput {
            session_id: replacement_session_id.clone(),
            owner_user_id: owner_user_id.to_string(),
            seed_text: seed_text.clone(),
            welcome_message_id: build_prefixed_uuid_id("puzzle-message-"),
            welcome_message_text: build_puzzle_welcome_text(&seed_text),
            created_at_micros: now,
        })
        .await
        .map_err(|error| {
            puzzle_error_response(
                request_context,
                PUZZLE_AGENT_API_BASE_PROVIDER,
                map_puzzle_client_error(error),
            )
        })?;
    tracing::warn!(
        provider = PUZZLE_AGENT_API_BASE_PROVIDER,
        old_session_id = %session_id,
        new_session_id = %replacement.session_id,
        owner_user_id,
        error = %original_error,
        "拼图表单草稿保存 procedure 缺失，已创建带表单 seed 的替代 session"
    );
    Ok(replacement.session_id)
}

fn select_puzzle_level_for_api(
    draft: &PuzzleResultDraftRecord,
    level_id: Option<&str>,
) -> Result<PuzzleDraftLevelRecord, AppError> {
    let normalized_level_id = level_id.map(str::trim).filter(|value| !value.is_empty());
    if let Some(target_id) = normalized_level_id {
        return draft
            .levels
            .iter()
            .find(|level| level.level_id == target_id)
            .cloned()
            .ok_or_else(|| {
                AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                    "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                    "message": format!("拼图关卡不存在：{target_id}"),
                }))
            });
    }
    let level = draft.levels.first().cloned();
    level.ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": "拼图草稿缺少可编辑关卡",
        }))
    })
}

fn parse_puzzle_level_records_from_module_json(
    value: &str,
) -> Result<Vec<PuzzleDraftLevelRecord>, AppError> {
    let levels: Vec<module_puzzle::PuzzleDraftLevel> =
        serde_json::from_str(value).map_err(|error| {
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": format!("拼图关卡列表 JSON 非法：{error}"),
            }))
        })?;
    Ok(levels
        .into_iter()
        .map(|level| PuzzleDraftLevelRecord {
            level_id: level.level_id,
            level_name: level.level_name,
            picture_description: level.picture_description,
            picture_reference: level.picture_reference,
            ui_background_prompt: level.ui_background_prompt,
            ui_background_image_src: level.ui_background_image_src,
            ui_background_image_object_key: level.ui_background_image_object_key,
            background_music: level.background_music.map(map_puzzle_audio_asset_domain_record),
            candidates: level
                .candidates
                .into_iter()
                .map(|candidate| PuzzleGeneratedImageCandidateRecord {
                    candidate_id: candidate.candidate_id,
                    image_src: candidate.image_src,
                    asset_id: candidate.asset_id,
                    prompt: candidate.prompt,
                    actual_prompt: candidate.actual_prompt,
                    source_type: candidate.source_type,
                    selected: candidate.selected,
                })
                .collect(),
            selected_candidate_id: level.selected_candidate_id,
            cover_image_src: level.cover_image_src,
            cover_asset_id: level.cover_asset_id,
            generation_status: level.generation_status,
        })
        .collect())
}

async fn get_puzzle_session_for_image_generation(
    state: &AppState,
    session_id: String,
    owner_user_id: String,
    payload: &ExecutePuzzleAgentActionRequest,
    normalized_levels_json: Option<&str>,
    now: i64,
) -> Result<PuzzleAgentSessionRecord, AppError> {
    match state
        .spacetime_client()
        .get_puzzle_agent_session(session_id.clone(), owner_user_id.clone())
        .await
    {
        Ok(session) => Ok(session),
        Err(error) if should_skip_asset_operation_billing_for_connectivity(&error) => {
            // 中文注释：结果页已经带有当前草稿快照；Maincloud 读取 session 短暂 503 时不应阻断外部生图。
            let fallback_session = build_puzzle_session_snapshot_from_action_payload(
                session_id.as_str(),
                payload,
                normalized_levels_json,
                now,
            )?;
            tracing::warn!(
                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                session_id = %session_id,
                owner_user_id = %owner_user_id,
                error = %error,
                "拼图图片生成读取 session 因 SpacetimeDB 连接不可用而降级使用前端草稿快照"
            );
            Ok(fallback_session)
        }
        Err(error) => Err(map_puzzle_client_error(error)),
    }
}

fn build_puzzle_session_snapshot_from_action_payload(
    session_id: &str,
    payload: &ExecutePuzzleAgentActionRequest,
    normalized_levels_json: Option<&str>,
    now: i64,
) -> Result<PuzzleAgentSessionRecord, AppError> {
    let levels_json = normalized_levels_json.ok_or_else(|| {
        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
            "provider": "spacetimedb",
            "message": "SpacetimeDB 暂不可用，且请求缺少拼图关卡快照，无法继续生成图片",
        }))
    })?;
    let levels = parse_puzzle_level_records_from_module_json(levels_json)?;
    let first_level = levels.first().cloned().ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": "拼图草稿缺少可编辑关卡",
        }))
    })?;
    let work_title = payload
        .work_title
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .unwrap_or(first_level.level_name.as_str())
        .to_string();
    let work_description = payload
        .work_description
        .as_deref()
        .map(str::trim)
        .unwrap_or_default()
        .to_string();
    let summary = payload
        .summary
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .unwrap_or(first_level.picture_description.as_str())
        .to_string();
    let theme_tags = payload.theme_tags.clone().unwrap_or_default();
    let anchor_pack = map_puzzle_domain_anchor_pack(module_puzzle::empty_anchor_pack());
    let draft = PuzzleResultDraftRecord {
        work_title,
        work_description,
        level_name: first_level.level_name.clone(),
        summary,
        theme_tags,
        forbidden_directives: Vec::new(),
        creator_intent: None,
        anchor_pack: anchor_pack.clone(),
        candidates: first_level.candidates.clone(),
        selected_candidate_id: first_level.selected_candidate_id.clone(),
        cover_image_src: first_level.cover_image_src.clone(),
        cover_asset_id: first_level.cover_asset_id.clone(),
        generation_status: first_level.generation_status.clone(),
        levels,
        form_draft: None,
    };

    Ok(PuzzleAgentSessionRecord {
        session_id: session_id.to_string(),
        seed_text: String::new(),
        current_turn: 0,
        progress_percent: 94,
        stage: "ready_to_publish".to_string(),
        anchor_pack,
        draft: Some(draft),
        messages: Vec::new(),
        last_assistant_reply: None,
        published_profile_id: None,
        suggested_actions: Vec::new(),
        result_preview: None,
        updated_at: format_timestamp_micros(now),
    })
}

fn map_puzzle_domain_anchor_pack(
    anchor_pack: module_puzzle::PuzzleAnchorPack,
) -> PuzzleAnchorPackRecord {
    PuzzleAnchorPackRecord {
        theme_promise: map_puzzle_domain_anchor_item(anchor_pack.theme_promise),
        visual_subject: map_puzzle_domain_anchor_item(anchor_pack.visual_subject),
        visual_mood: map_puzzle_domain_anchor_item(anchor_pack.visual_mood),
        composition_hooks: map_puzzle_domain_anchor_item(anchor_pack.composition_hooks),
        tags_and_forbidden: map_puzzle_domain_anchor_item(anchor_pack.tags_and_forbidden),
    }
}

fn map_puzzle_domain_anchor_item(
    anchor: module_puzzle::PuzzleAnchorItem,
) -> PuzzleAnchorItemRecord {
    PuzzleAnchorItemRecord {
        key: anchor.key,
        label: anchor.label,
        value: anchor.value,
        status: anchor.status.as_str().to_string(),
    }
}

fn serialize_puzzle_levels_response(
    request_context: &RequestContext,
    levels: &[PuzzleDraftLevelResponse],
) -> Result<String, Response> {
    let payload = levels
        .iter()
        .map(|level| {
            json!({
                "level_id": level.level_id,
                "level_name": level.level_name,
                "picture_description": level.picture_description,
                "picture_reference": level.picture_reference,
                "ui_background_prompt": level.ui_background_prompt,
                "ui_background_image_src": level.ui_background_image_src,
                "ui_background_image_object_key": level.ui_background_image_object_key,
                "background_music": puzzle_audio_asset_response_module_json(&level.background_music),
                "candidates": level
                    .candidates
                    .iter()
                    .map(|candidate| {
                        json!({
                            "candidate_id": candidate.candidate_id,
                            "image_src": candidate.image_src,
                            "asset_id": candidate.asset_id,
                            "prompt": candidate.prompt,
                            "actual_prompt": candidate.actual_prompt,
                            "source_type": candidate.source_type,
                            "selected": candidate.selected,
                        })
                    })
                    .collect::<Vec<_>>(),
                "selected_candidate_id": level.selected_candidate_id,
                "cover_image_src": level.cover_image_src,
                "cover_asset_id": level.cover_asset_id,
                "generation_status": level.generation_status,
            })
        })
        .collect::<Vec<_>>();
    serde_json::to_string(&payload).map_err(|error| {
        puzzle_error_response(
            request_context,
            PUZZLE_WORKS_PROVIDER,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_WORKS_PROVIDER,
                "message": format!("拼图关卡列表序列化失败：{error}"),
            })),
        )
    })
}

fn normalize_puzzle_levels_json_for_module(value: Option<&str>) -> Result<Option<String>, String> {
    let Some(raw) = value.map(str::trim).filter(|raw| !raw.is_empty()) else {
        return Ok(None);
    };
    let levels: Vec<PuzzleDraftLevelResponse> =
        serde_json::from_str(raw).map_err(|error| format!("拼图关卡列表 JSON 非法：{error}"))?;
    let payload = levels
        .iter()
        .map(|level| {
            json!({
                "level_id": level.level_id,
                "level_name": level.level_name,
                "picture_description": level.picture_description,
                "picture_reference": level.picture_reference,
                "ui_background_prompt": level.ui_background_prompt,
                "ui_background_image_src": level.ui_background_image_src,
                "ui_background_image_object_key": level.ui_background_image_object_key,
                "background_music": puzzle_audio_asset_response_module_json(&level.background_music),
                "candidates": level
                    .candidates
                    .iter()
                    .map(|candidate| {
                        json!({
                            "candidate_id": candidate.candidate_id,
                            "image_src": candidate.image_src,
                            "asset_id": candidate.asset_id,
                            "prompt": candidate.prompt,
                            "actual_prompt": candidate.actual_prompt,
                            "source_type": candidate.source_type,
                            "selected": candidate.selected,
                        })
                    })
                    .collect::<Vec<_>>(),
                "selected_candidate_id": level.selected_candidate_id,
                "cover_image_src": level.cover_image_src,
                "cover_asset_id": level.cover_asset_id,
                "generation_status": level.generation_status,
            })
        })
        .collect::<Vec<_>>();
    serde_json::to_string(&payload)
        .map(Some)
        .map_err(|error| format!("拼图关卡列表序列化失败：{error}"))
}

fn build_stable_puzzle_work_ids(session_id: &str) -> (String, String) {
    let stable_suffix = session_id
        .strip_prefix("puzzle-session-")
        .unwrap_or(session_id);
    (
        format!("puzzle-work-{stable_suffix}"),
        format!("puzzle-profile-{stable_suffix}"),
    )
}

async fn generate_puzzle_first_level_name(state: &AppState, picture_description: &str) -> String {
    if let Some(llm_client) = state.llm_client() {
        let user_prompt = build_puzzle_first_level_name_user_prompt(picture_description);
        let response = llm_client
            .request_text(
                LlmTextRequest::new(vec![
                    LlmMessage::system(PUZZLE_FIRST_LEVEL_NAME_SYSTEM_PROMPT),
                    LlmMessage::user(user_prompt),
                ])
                .with_model(CREATION_TEMPLATE_LLM_MODEL)
                .with_responses_api(),
            )
            .await;
        match response {
            Ok(response) => {
                if let Some(level_name) =
                    parse_puzzle_first_level_name_from_text(response.content.as_str())
                {
                    return level_name;
                }
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    picture_chars = picture_description.chars().count(),
                    "拼图首关名模型返回非法，降级使用关键词名"
                );
            }
            Err(error) => {
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    picture_chars = picture_description.chars().count(),
                    error = %error,
                    "拼图首关名生成失败，降级使用关键词名"
                );
            }
        }
    }

    build_fallback_puzzle_first_level_name(picture_description)
}

async fn generate_puzzle_first_level_name_from_image(
    state: &AppState,
    picture_description: &str,
    image: &PuzzleDownloadedImage,
) -> Option<String> {
    let Some(llm_client) = state.creative_agent_gpt5_client() else {
        return None;
    };
    let Some(image_data_url) = build_puzzle_level_name_image_data_url(image) else {
        tracing::warn!(
            provider = PUZZLE_AGENT_API_BASE_PROVIDER,
            picture_chars = picture_description.chars().count(),
            "拼图首关名图片输入压缩失败，保留文本关卡名"
        );
        return None;
    };
    let user_text = build_puzzle_first_level_name_vision_user_text(picture_description);
    let response = llm_client
        .request_text(
            LlmTextRequest::new(vec![
                LlmMessage::system(PUZZLE_FIRST_LEVEL_NAME_SYSTEM_PROMPT),
                LlmMessage::user_multimodal(vec![
                    LlmMessageContentPart::InputText { text: user_text },
                    LlmMessageContentPart::InputImage {
                        image_url: image_data_url,
                    },
                ]),
            ])
            .with_model(PUZZLE_LEVEL_NAME_VISION_LLM_MODEL)
            .with_max_tokens(80),
        )
        .await;

    match response {
        Ok(response) => {
            parse_puzzle_first_level_name_from_text(response.content.as_str()).or_else(|| {
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    model = PUZZLE_LEVEL_NAME_VISION_LLM_MODEL,
                    picture_chars = picture_description.chars().count(),
                    "拼图首关名视觉模型返回非法，保留文本关卡名"
                );
                None
            })
        }
        Err(error) => {
            tracing::warn!(
                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                model = PUZZLE_LEVEL_NAME_VISION_LLM_MODEL,
                picture_chars = picture_description.chars().count(),
                error = %error,
                "拼图首关名视觉生成失败，保留文本关卡名"
            );
            None
        }
    }
}

fn build_puzzle_level_name_image_data_url(image: &PuzzleDownloadedImage) -> Option<String> {
    let bytes = resize_puzzle_level_name_image_bytes(image.bytes.as_slice())
        .unwrap_or_else(|| image.bytes.clone());
    let mime_type = if bytes.starts_with(b"\x89PNG\r\n\x1A\n") {
        "image/png"
    } else {
        image.mime_type.as_str()
    };
    Some(format!(
        "data:{};base64,{}",
        normalize_puzzle_downloaded_image_mime_type(mime_type),
        BASE64_STANDARD.encode(bytes)
    ))
}

fn resize_puzzle_level_name_image_bytes(bytes: &[u8]) -> Option<Vec<u8>> {
    let image = image::load_from_memory(bytes).ok()?;
    let resized = image.resize(
        PUZZLE_LEVEL_NAME_VISION_IMAGE_MAX_SIDE,
        PUZZLE_LEVEL_NAME_VISION_IMAGE_MAX_SIDE,
        image::imageops::FilterType::Triangle,
    );
    let mut cursor = std::io::Cursor::new(Vec::new());
    resized.write_to(&mut cursor, ImageFormat::Png).ok()?;
    Some(cursor.into_inner())
}

fn parse_puzzle_first_level_name_from_text(text: &str) -> Option<String> {
    let trimmed = text.trim();
    let json_text = if let Some(start) = trimmed.find('{')
        && let Some(end) = trimmed.rfind('}')
        && end > start
    {
        &trimmed[start..=end]
    } else {
        trimmed
    };
    let parsed = serde_json::from_str::<Value>(json_text).ok();
    let raw_name = parsed
        .as_ref()
        .and_then(|value| value.get("levelName").and_then(Value::as_str))
        .or_else(|| {
            parsed
                .as_ref()
                .and_then(|value| value.get("level_name").and_then(Value::as_str))
        })
        .unwrap_or(trimmed);
    normalize_puzzle_first_level_name(raw_name)
}

fn normalize_puzzle_first_level_name(value: &str) -> Option<String> {
    let normalized = value
        .trim()
        .trim_matches(|ch: char| {
            ch.is_ascii_punctuation()
                || matches!(
                    ch,
                    '，' | '。' | '、' | '；' | '：' | '！' | '？' | '“' | '”' | '《' | '》'
                )
        })
        .trim_start_matches(|ch: char| ch.is_ascii_digit() || matches!(ch, '.' | '、' | ')' | '）'))
        .chars()
        .filter(|ch| {
            !matches!(
                ch,
                '#' | '"'
                    | '\''
                    | '`'
                    | ' '
                    | '\t'
                    | '\r'
                    | '\n'
                    | '，'
                    | '。'
                    | '、'
                    | '；'
                    | '：'
                    | '！'
                    | '？'
                    | '“'
                    | '”'
                    | '《'
                    | '》'
            )
        })
        .take(12)
        .collect::<String>();
    let normalized = strip_puzzle_level_name_generic_words(normalized);
    if normalized.chars().count() >= 2
        && !matches!(
            normalized.as_str(),
            "第一关" | "画面" | "拼图" | "作品" | "关卡"
        )
    {
        Some(normalized)
    } else {
        None
    }
}

fn strip_puzzle_level_name_generic_words(mut value: String) -> String {
    for prefix in ["第一关", "关卡名", "关卡"] {
        value = value.trim_start_matches(prefix).to_string();
    }
    for suffix in ["第一关", "关卡名", "关卡", "画面", "拼图", "作品"] {
        value = value.trim_end_matches(suffix).to_string();
    }
    value.chars().take(8).collect()
}

fn build_fallback_puzzle_first_level_name(picture_description: &str) -> String {
    let source = picture_description.trim();
    if source.contains("猫") && (source.contains("雨夜") || source.contains('雨')) {
        return "雨夜猫街".to_string();
    }
    if source.contains("猫") && source.contains('灯') {
        return "暖灯猫街".to_string();
    }
    for (keyword, level_name) in [
        ("雨夜", "雨夜灯街"),
        ("猫", "暖灯猫街"),
        ("狗", "花园小狗"),
        ("神庙", "神庙遗光"),
        ("遗迹", "遗迹谜光"),
        ("森林", "森林秘境"),
        ("城市", "霓虹城市"),
        ("机械", "机械迷城"),
        ("蒸汽", "蒸汽街区"),
        ("海", "海岸微光"),
        ("花", "花园晨光"),
        ("雪", "雪境小径"),
        ("龙", "龙影高塔"),
        ("灯", "暖灯街角"),
        ("塔", "塔顶星光"),
    ] {
        if source.contains(keyword) {
            return level_name.to_string();
        }
    }
    "奇境初见".to_string()
}

fn build_puzzle_levels_with_primary_update(
    draft: &PuzzleResultDraftRecord,
    target_level: &PuzzleDraftLevelRecord,
    picture_reference: Option<&str>,
) -> Vec<PuzzleDraftLevelRecord> {
    let mut levels = draft.levels.clone();
    if let Some(index) = levels
        .iter()
        .position(|level| level.level_id == target_level.level_id)
        .or_else(|| (!levels.is_empty()).then_some(0))
    {
        levels[index].level_name = target_level.level_name.clone();
        levels[index].ui_background_prompt = target_level.ui_background_prompt.clone();
        levels[index].ui_background_image_src = target_level.ui_background_image_src.clone();
        levels[index].ui_background_image_object_key =
            target_level.ui_background_image_object_key.clone();
        if let Some(picture_reference) = picture_reference
            .map(str::trim)
            .filter(|value| !value.is_empty())
        {
            levels[index].picture_reference = Some(picture_reference.to_string());
        }
    }
    levels
}

fn resolve_puzzle_background_music_title(
    draft: &PuzzleResultDraftRecord,
    target_level: &PuzzleDraftLevelRecord,
) -> String {
    let work_title = draft.work_title.trim();
    if !work_title.is_empty() {
        return work_title.to_string();
    }
    target_level.level_name.trim().to_string()
}

fn normalize_puzzle_ui_background_prompt(
    raw_prompt: &str,
    draft: &PuzzleResultDraftRecord,
    target_level: &PuzzleDraftLevelRecord,
) -> String {
    let prompt = raw_prompt.trim();
    if !prompt.is_empty() {
        return prompt.chars().take(420).collect();
    }

    let title = draft.work_title.trim();
    let title = if title.is_empty() {
        target_level.level_name.trim()
    } else {
        title
    };
    let tags = draft
        .theme_tags
        .iter()
        .map(|tag| tag.trim())
        .filter(|tag| !tag.is_empty())
        .collect::<Vec<_>>()
        .join("，");
    [
        title,
        draft.work_description.trim(),
        target_level.picture_description.trim(),
        tags.as_str(),
        "移动端拼图游戏 UI 背景，中央正方形拼图区边界清晰",
    ]
    .into_iter()
    .filter(|value| !value.is_empty())
    .collect::<Vec<_>>()
    .join("。")
    .chars()
    .take(420)
    .collect()
}

fn build_puzzle_ui_background_generation_prompt(level_name: &str, prompt: &str) -> String {
    let level_name = level_name.trim();
    let title_clause = if level_name.is_empty() {
        String::new()
    } else {
        format!("当前拼图关卡名称：{level_name}。")
    };
    format!(
        "{title_clause}{prompt}\n严格参考输入图的构图关系：生成一张 9:16 竖屏拼图游戏 UI 背景图，中央必须预留清晰正方形拼图区，拼图区与外部 UI 背景必须有明确边界、描边或容器层次；拼图区之外可以生成与作品名称相关的氛围背景、顶部安全区和底部工具区背景，但不要画文字、按钮文字、数字、拼图碎片、完整拼图图像、教程浮层或水印。"
    )
}

fn attach_puzzle_level_background_music(
    levels: &mut [PuzzleDraftLevelRecord],
    level_id: &str,
    music: CreationAudioAsset,
) {
    let Some(index) = levels
        .iter()
        .position(|level| level.level_id == level_id)
        .or_else(|| (!levels.is_empty()).then_some(0))
    else {
        return;
    };
    levels[index].background_music = Some(PuzzleAudioAssetRecord {
        task_id: music.task_id,
        provider: music.provider,
        asset_object_id: music.asset_object_id,
        asset_kind: music.asset_kind,
        audio_src: music.audio_src,
        prompt: music.prompt,
        title: music.title,
        updated_at: music.updated_at,
    });
}

async fn try_generate_puzzle_background_music(
    state: &AppState,
    owner_user_id: &str,
    session_id: &str,
    profile_id: &str,
    title: &str,
) -> Option<CreationAudioAsset> {
    let normalized_title = title.trim();
    if normalized_title.is_empty() {
        return None;
    }
    match 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
    {
        Ok(music) => Some(music),
        Err(error) => {
            tracing::warn!(
                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                session_id,
                profile_id,
                error = %error,
                "拼图草稿背景音乐生成失败，保留草稿并允许结果页重试"
            );
            None
        }
    }
}

async fn compile_puzzle_draft_with_initial_cover(
    state: &AppState,
    session_id: String,
    owner_user_id: String,
    prompt_text: Option<&str>,
    reference_image_src: Option<&str>,
    image_model: Option<&str>,
    now: i64,
) -> Result<PuzzleAgentSessionRecord, AppError> {
    let compiled_session = state
        .spacetime_client()
        .compile_puzzle_agent_draft(session_id.clone(), owner_user_id.clone(), now)
        .await
        .map_err(map_puzzle_compile_error)?;
    let draft = compiled_session.draft.clone().ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": "拼图结果页草稿尚未生成",
        }))
    })?;
    let mut target_level = select_puzzle_level_for_api(&draft, None)?;
    let fallback_level_name = target_level.level_name.clone();
    let generated_level_name =
        generate_puzzle_first_level_name(state, &target_level.picture_description).await;
    target_level.level_name = generated_level_name.clone();
    let image_prompt = resolve_puzzle_draft_cover_prompt(
        prompt_text,
        &target_level.picture_description,
        &draft.summary,
    );
    // 点击生成草稿时一次性完成首图生成与正式图选定，前端只展示进度，不再承担业务编排。
    let candidates = generate_puzzle_image_candidates(
        state,
        owner_user_id.as_str(),
        &compiled_session.session_id,
        &target_level.level_name,
        &image_prompt,
        reference_image_src,
        true,
        image_model,
        1,
        target_level.candidates.len(),
    )
    .await?;
    let selected_candidate_id = candidates
        .iter()
        .find(|candidate| candidate.record.selected)
        .or_else(|| candidates.first())
        .map(|candidate| candidate.record.candidate_id.clone())
        .ok_or_else(|| {
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": "拼图候选图生成结果为空",
            }))
        })?;
    if let Some(refined_level_name) = generate_puzzle_first_level_name_from_image(
        state,
        target_level.picture_description.as_str(),
        &candidates[0].downloaded_image,
    )
    .await
    {
        target_level.level_name = refined_level_name;
    }
    let generated_level_name = target_level.level_name.clone();
    let (_, profile_id) = build_stable_puzzle_work_ids(session_id.as_str());
    let mut updated_levels =
        build_puzzle_levels_with_primary_update(&draft, &target_level, reference_image_src);
    let music_title = resolve_puzzle_background_music_title(&draft, &target_level);
    if let Some(music) = try_generate_puzzle_background_music(
        state,
        owner_user_id.as_str(),
        compiled_session.session_id.as_str(),
        profile_id.as_str(),
        music_title.as_str(),
    )
    .await
    {
        attach_puzzle_level_background_music(
            &mut updated_levels,
            target_level.level_id.as_str(),
            music,
        );
    }
    let levels_json_with_generated_name = Some(serialize_puzzle_level_records_for_module(
        &updated_levels,
    )?);
    let candidates_json = serde_json::to_string(
        &candidates
            .iter()
            .map(|candidate| to_puzzle_generated_image_candidate(&candidate.record))
            .collect::<Vec<_>>(),
    )
    .map_err(|error| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": format!("拼图候选图序列化失败：{error}"),
        }))
    })?;
    let (saved_session, save_used_fallback) = state
        .spacetime_client()
        .save_puzzle_generated_images(PuzzleGeneratedImagesSaveRecordInput {
            session_id: compiled_session.session_id.clone(),
            owner_user_id: owner_user_id.clone(),
            level_id: Some(target_level.level_id.clone()),
            levels_json: levels_json_with_generated_name.clone(),
            candidates_json,
            saved_at_micros: current_utc_micros(),
        })
        .await
        .map_err(map_puzzle_client_error)
        .map(|session| (session, false))
        .or_else(|error| {
            if is_spacetimedb_connectivity_app_error(&error) {
                // 中文注释：首图已落 OSS 时，SpacetimeDB 短暂不可用先返回本地快照，避免整次 VectorEngine 生图被判失败。
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    session_id = %compiled_session.session_id,
                    owner_user_id = %owner_user_id,
                    message = %error.body_text(),
                    "拼图首图已生成但 SpacetimeDB 草稿回写不可用，降级返回本次生成快照"
                );
                let session = apply_generated_puzzle_candidates_to_session_snapshot(
                    apply_generated_puzzle_levels_to_session_snapshot(
                        apply_generated_puzzle_first_level_name_to_session_snapshot(
                            compiled_session.clone(),
                            target_level.level_id.as_str(),
                            generated_level_name.as_str(),
                            fallback_level_name.as_str(),
                            now,
                        ),
                        updated_levels.clone(),
                        now,
                    ),
                    target_level.level_id.as_str(),
                    candidates.into_records(),
                    reference_image_src,
                    now,
                );
                Ok((session, true))
            } else {
                Err(error)
            }
        })?;
    if save_used_fallback {
        return Ok(saved_session);
    }
    match state
        .spacetime_client()
        .select_puzzle_cover_image(PuzzleSelectCoverImageRecordInput {
            session_id,
            owner_user_id,
            level_id: Some(target_level.level_id),
            candidate_id: selected_candidate_id,
            selected_at_micros: current_utc_micros(),
        })
        .await
    {
        Ok(session) => Ok(session),
        Err(error) if should_skip_asset_operation_billing_for_connectivity(&error) => {
            tracing::warn!(
                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                session_id = %saved_session.session_id,
                error = %error,
                "拼图首图选定回写因 SpacetimeDB 连接不可用而降级使用已生成快照"
            );
            Ok(saved_session)
        }
        Err(error) => Err(map_puzzle_client_error(error)),
    }
}

async fn compile_puzzle_draft_with_uploaded_cover(
    state: &AppState,
    session_id: String,
    owner_user_id: String,
    prompt_text: Option<&str>,
    reference_image_src: Option<&str>,
    now: i64,
) -> Result<PuzzleAgentSessionRecord, AppError> {
    let uploaded_image_src = reference_image_src
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "field": "referenceImageSrc",
                "message": "关闭 AI 重绘时必须上传拼图图片。",
            }))
        })?;
    let uploaded_image = parse_puzzle_image_data_url(uploaded_image_src).ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "field": "referenceImageSrc",
            "message": "关闭 AI 重绘时上传图必须是图片 Data URL。",
        }))
    })?;
    let compiled_session = state
        .spacetime_client()
        .compile_puzzle_agent_draft(session_id.clone(), owner_user_id.clone(), now)
        .await
        .map_err(map_puzzle_compile_error)?;
    let draft = compiled_session.draft.clone().ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": "拼图结果页草稿尚未生成",
        }))
    })?;
    let mut target_level = select_puzzle_level_for_api(&draft, None)?;
    let fallback_level_name = target_level.level_name.clone();
    let generated_level_name =
        generate_puzzle_first_level_name(state, &target_level.picture_description).await;
    target_level.level_name = generated_level_name.clone();
    let image_prompt = resolve_puzzle_draft_cover_prompt(
        prompt_text,
        &target_level.picture_description,
        &draft.summary,
    );
    // 中文注释：关闭 AI 重绘时不请求 VectorEngine，也不进入光点扣费流程；上传图直接成为首关正式图候选。
    let candidate_id = format!(
        "{}-candidate-{}",
        compiled_session.session_id,
        target_level.candidates.len() + 1
    );
    let uploaded_downloaded_image = PuzzleDownloadedImage {
        extension: puzzle_mime_to_extension(uploaded_image.mime_type.as_str()).to_string(),
        mime_type: normalize_puzzle_downloaded_image_mime_type(uploaded_image.mime_type.as_str()),
        bytes: uploaded_image.bytes,
    };
    if let Some(refined_level_name) = generate_puzzle_first_level_name_from_image(
        state,
        target_level.picture_description.as_str(),
        &uploaded_downloaded_image,
    )
    .await
    {
        target_level.level_name = refined_level_name;
    }
    let generated_level_name = target_level.level_name.clone();
    let (_, profile_id) = build_stable_puzzle_work_ids(session_id.as_str());
    let mut updated_levels =
        build_puzzle_levels_with_primary_update(&draft, &target_level, reference_image_src);
    let music_title = resolve_puzzle_background_music_title(&draft, &target_level);
    if let Some(music) = try_generate_puzzle_background_music(
        state,
        owner_user_id.as_str(),
        compiled_session.session_id.as_str(),
        profile_id.as_str(),
        music_title.as_str(),
    )
    .await
    {
        attach_puzzle_level_background_music(
            &mut updated_levels,
            target_level.level_id.as_str(),
            music,
        );
    }
    let levels_json_with_generated_name = Some(serialize_puzzle_level_records_for_module(
        &updated_levels,
    )?);
    let persisted_upload = persist_puzzle_generated_asset(
        state,
        owner_user_id.as_str(),
        &compiled_session.session_id,
        &target_level.level_name,
        candidate_id.as_str(),
        "uploaded-direct",
        uploaded_downloaded_image,
        current_utc_micros(),
    )
    .await?;
    let candidate = PuzzleGeneratedImageCandidateRecord {
        candidate_id: candidate_id.clone(),
        image_src: persisted_upload.image_src,
        asset_id: persisted_upload.asset_id,
        prompt: image_prompt,
        actual_prompt: None,
        source_type: "uploaded".to_string(),
        selected: true,
    };
    let candidates_json = serde_json::to_string(&vec![to_puzzle_generated_image_candidate(
        &candidate,
    )])
    .map_err(|error| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": format!("拼图上传图候选序列化失败：{error}"),
        }))
    })?;
    let (saved_session, save_used_fallback) = state
        .spacetime_client()
        .save_puzzle_generated_images(PuzzleGeneratedImagesSaveRecordInput {
            session_id: compiled_session.session_id.clone(),
            owner_user_id: owner_user_id.clone(),
            level_id: Some(target_level.level_id.clone()),
            levels_json: levels_json_with_generated_name.clone(),
            candidates_json,
            saved_at_micros: current_utc_micros(),
        })
        .await
        .map_err(map_puzzle_client_error)
        .map(|session| (session, false))
        .or_else(|error| {
            if is_spacetimedb_connectivity_app_error(&error) {
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    session_id = %compiled_session.session_id,
                    owner_user_id = %owner_user_id,
                    message = %error.body_text(),
                    "拼图上传图草稿回写不可用，降级返回本地快照"
                );
                let session = apply_generated_puzzle_candidates_to_session_snapshot(
                    apply_generated_puzzle_levels_to_session_snapshot(
                        apply_generated_puzzle_first_level_name_to_session_snapshot(
                            compiled_session.clone(),
                            target_level.level_id.as_str(),
                            generated_level_name.as_str(),
                            fallback_level_name.as_str(),
                            now,
                        ),
                        updated_levels.clone(),
                        now,
                    ),
                    target_level.level_id.as_str(),
                    vec![candidate.clone()],
                    reference_image_src,
                    now,
                );
                Ok((session, true))
            } else {
                Err(error)
            }
        })?;
    if save_used_fallback {
        return Ok(saved_session);
    }
    match state
        .spacetime_client()
        .select_puzzle_cover_image(PuzzleSelectCoverImageRecordInput {
            session_id,
            owner_user_id,
            level_id: Some(target_level.level_id),
            candidate_id,
            selected_at_micros: current_utc_micros(),
        })
        .await
    {
        Ok(session) => Ok(session),
        Err(error) if should_skip_asset_operation_billing_for_connectivity(&error) => {
            tracing::warn!(
                provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                session_id = %saved_session.session_id,
                error = %error,
                "拼图上传图选定回写因 SpacetimeDB 连接不可用而降级使用已保存快照"
            );
            Ok(saved_session)
        }
        Err(error) => Err(map_puzzle_client_error(error)),
    }
}

fn apply_generated_puzzle_candidates_to_session_snapshot(
    mut session: PuzzleAgentSessionRecord,
    target_level_id: &str,
    candidates: Vec<PuzzleGeneratedImageCandidateRecord>,
    picture_reference: Option<&str>,
    updated_at_micros: i64,
) -> PuzzleAgentSessionRecord {
    let Some(draft) = session.draft.as_mut() else {
        return session;
    };
    let Some(target_index) = draft
        .levels
        .iter()
        .position(|level| level.level_id == target_level_id)
        .or_else(|| (!draft.levels.is_empty()).then_some(0))
    else {
        return session;
    };
    let mut candidates = candidates
        .into_iter()
        .take(1)
        .map(|mut candidate| {
            candidate.selected = true;
            candidate
        })
        .collect::<Vec<_>>();
    let Some(selected) = candidates.first().cloned() else {
        return session;
    };
    let level = &mut draft.levels[target_index];
    level.candidates.clear();
    level.candidates.append(&mut candidates);
    level.selected_candidate_id = Some(selected.candidate_id.clone());
    level.cover_image_src = Some(selected.image_src.clone());
    level.cover_asset_id = Some(selected.asset_id.clone());
    if let Some(picture_reference) = picture_reference
        .map(str::trim)
        .filter(|value| !value.is_empty())
    {
        level.picture_reference = Some(picture_reference.to_string());
    }
    level.generation_status = "ready".to_string();
    if target_index == 0 {
        sync_puzzle_primary_draft_fields_from_level(draft);
    }
    session.progress_percent = session.progress_percent.max(94);
    session.stage = "ready_to_publish".to_string();
    session.last_assistant_reply = Some("拼图图片已经生成，并已替换当前正式图。".to_string());
    session.updated_at = format_timestamp_micros(updated_at_micros);
    session
}

fn apply_generated_puzzle_levels_to_session_snapshot(
    mut session: PuzzleAgentSessionRecord,
    levels: Vec<PuzzleDraftLevelRecord>,
    updated_at_micros: i64,
) -> PuzzleAgentSessionRecord {
    let Some(draft) = session.draft.as_mut() else {
        return session;
    };
    if levels.is_empty() {
        return session;
    }
    draft.levels = levels;
    sync_puzzle_primary_draft_fields_from_level(draft);
    session.updated_at = format_timestamp_micros(updated_at_micros);
    session
}

fn apply_generated_puzzle_first_level_name_to_session_snapshot(
    mut session: PuzzleAgentSessionRecord,
    target_level_id: &str,
    level_name: &str,
    previous_level_name: &str,
    updated_at_micros: i64,
) -> PuzzleAgentSessionRecord {
    let Some(draft) = session.draft.as_mut() else {
        return session;
    };
    let normalized_name = level_name.trim();
    if normalized_name.is_empty() {
        return session;
    }
    let Some(target_index) = draft
        .levels
        .iter()
        .position(|level| level.level_id == target_level_id)
        .or_else(|| (!draft.levels.is_empty()).then_some(0))
    else {
        return session;
    };
    draft.levels[target_index].level_name = normalized_name.to_string();
    let should_default_work_title =
        draft.work_title.trim().is_empty() || draft.work_title.trim() == previous_level_name.trim();
    if target_index == 0 && should_default_work_title {
        draft.work_title = normalized_name.to_string();
    }
    sync_puzzle_primary_draft_fields_from_level(draft);
    session.updated_at = format_timestamp_micros(updated_at_micros);
    session
}

fn sync_puzzle_primary_draft_fields_from_level(draft: &mut PuzzleResultDraftRecord) {
    let Some(primary_level) = draft.levels.first() else {
        return;
    };
    draft.level_name = primary_level.level_name.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();
    draft.generation_status = primary_level.generation_status.clone();
}

fn replace_puzzle_session_draft_snapshot(
    mut session: PuzzleAgentSessionRecord,
    draft: PuzzleResultDraftRecord,
    updated_at_micros: i64,
) -> PuzzleAgentSessionRecord {
    session.draft = Some(draft);
    session.updated_at = format_timestamp_micros(updated_at_micros);
    session
}

fn apply_generated_puzzle_ui_background_to_session_snapshot(
    mut session: PuzzleAgentSessionRecord,
    target_level_id: &str,
    prompt: String,
    image_src: String,
    image_object_key: Option<String>,
    updated_at_micros: i64,
) -> PuzzleAgentSessionRecord {
    let Some(draft) = session.draft.as_mut() else {
        return session;
    };
    let Some(target_index) = draft
        .levels
        .iter()
        .position(|level| level.level_id == target_level_id)
        .or_else(|| (!draft.levels.is_empty()).then_some(0))
    else {
        return session;
    };
    let level = &mut draft.levels[target_index];
    level.ui_background_prompt = Some(prompt);
    level.ui_background_image_src = Some(image_src);
    level.ui_background_image_object_key = image_object_key;
    if target_index == 0 {
        sync_puzzle_primary_draft_fields_from_level(draft);
    }
    session.progress_percent = session.progress_percent.max(96);
    session.last_assistant_reply = Some("拼图 UI 背景图已生成。".to_string());
    session.updated_at = format_timestamp_micros(updated_at_micros);
    session
}

async fn generate_puzzle_work_tags(
    state: &AppState,
    work_title: &str,
    work_description: &str,
) -> Vec<String> {
    if let Some(llm_client) = state.llm_client() {
        let user_prompt = build_puzzle_tag_generation_user_prompt(work_title, work_description);
        let response = llm_client
            .request_text(
                LlmTextRequest::new(vec![
                    LlmMessage::system(PUZZLE_TAG_GENERATION_SYSTEM_PROMPT),
                    LlmMessage::user(user_prompt),
                ])
                .with_model(CREATION_TEMPLATE_LLM_MODEL)
                .with_responses_api(),
            )
            .await;
        match response {
            Ok(response) => {
                let tags = normalize_puzzle_tag_candidates(parse_puzzle_tags_from_text(
                    response.content.as_str(),
                ));
                if tags.len() == module_puzzle::PUZZLE_MAX_TAG_COUNT {
                    return tags;
                }
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    work_title,
                    "拼图 AI 标签数量不足，降级使用关键词补齐"
                );
            }
            Err(error) => {
                tracing::warn!(
                    provider = PUZZLE_AGENT_API_BASE_PROVIDER,
                    work_title,
                    error = %error,
                    "拼图 AI 标签生成失败，降级使用关键词标签"
                );
            }
        }
    }

    normalize_puzzle_tag_candidates(build_fallback_puzzle_tags(work_title, work_description))
}

fn parse_puzzle_tags_from_text(text: &str) -> Vec<String> {
    let trimmed = text.trim();
    let json_text = if let Some(start) = trimmed.find('{')
        && let Some(end) = trimmed.rfind('}')
        && end > start
    {
        &trimmed[start..=end]
    } else {
        trimmed
    };
    let Ok(value) = serde_json::from_str::<Value>(json_text) else {
        return normalize_puzzle_tag_candidates(trimmed.split([',', '，', '、', '\n']));
    };
    let Some(tags) = value.get("tags").and_then(Value::as_array) else {
        return Vec::new();
    };
    normalize_puzzle_tag_candidates(tags.iter().filter_map(Value::as_str))
}

fn normalize_puzzle_tag_candidates<S>(candidates: impl IntoIterator<Item = S>) -> Vec<String>
where
    S: AsRef<str>,
{
    let mut tags = Vec::new();
    for candidate in candidates {
        let normalized = normalize_puzzle_tag(candidate.as_ref());
        if normalized.is_empty() || tags.iter().any(|tag| tag == &normalized) {
            continue;
        }
        tags.push(normalized);
        if tags.len() >= module_puzzle::PUZZLE_MAX_TAG_COUNT {
            break;
        }
    }
    for fallback in ["拼图", "插画", "清晰构图", "奇幻", "场景", "氛围"] {
        if tags.len() >= module_puzzle::PUZZLE_MAX_TAG_COUNT {
            break;
        }
        if !tags.iter().any(|tag| tag == fallback) {
            tags.push(fallback.to_string());
        }
    }
    tags
}

fn normalize_puzzle_tag(value: &str) -> String {
    value
        .trim()
        .trim_matches(|ch: char| {
            ch.is_ascii_punctuation()
                || matches!(
                    ch,
                    '，' | '。' | '、' | '；' | '：' | '！' | '？' | '“' | '”' | '《' | '》'
                )
        })
        .trim_start_matches(|ch: char| ch.is_ascii_digit() || matches!(ch, '.' | '、' | ')' | '）'))
        .trim()
        .chars()
        .filter(|ch| !matches!(ch, '#' | '"' | '\'' | '`'))
        .take(6)
        .collect::<String>()
}

fn build_fallback_puzzle_tags(work_title: &str, work_description: &str) -> Vec<&'static str> {
    let source = format!("{work_title} {work_description}");
    let mut tags = Vec::new();
    for (keyword, tag) in [
        ("猫", "猫咪"),
        ("狗", "小狗"),
        ("神庙", "神庙遗迹"),
        ("遗迹", "神庙遗迹"),
        ("森林", "童话森林"),
        ("雨", "雨夜"),
        ("夜", "夜景"),
        ("城市", "城市奇景"),
        ("蒸汽", "蒸汽城市"),
        ("机械", "机械幻想"),
        ("海", "海岸"),
        ("花", "花园"),
        ("雪", "雪景"),
        ("龙", "幻想生物"),
        ("灯", "暖灯"),
        ("塔", "高塔"),
    ] {
        if source.contains(keyword) && !tags.contains(&tag) {
            tags.push(tag);
        }
    }
    tags.extend(["拼图", "插画", "清晰构图", "奇幻", "场景", "氛围"]);
    tags
}

async fn save_generated_puzzle_tags_to_session(
    state: &AppState,
    session_id: &str,
    owner_user_id: &str,
    payload: &ExecutePuzzleAgentActionRequest,
    generated_tags: Vec<String>,
    levels_json: Option<String>,
    now: i64,
) -> Result<PuzzleAgentSessionRecord, AppError> {
    let session = state
        .spacetime_client()
        .get_puzzle_agent_session(session_id.to_string(), owner_user_id.to_string())
        .await
        .map_err(map_puzzle_client_error)?;
    let draft = session.draft.clone().ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": "拼图结果页草稿尚未生成",
        }))
    })?;
    let mut levels = if let Some(levels_json) = levels_json.as_deref() {
        parse_puzzle_level_records_from_module_json(levels_json)?
    } else {
        draft.levels.clone()
    };
    if levels.is_empty() {
        levels = draft.levels.clone();
    }
    let first_level = levels.first().cloned().ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": "拼图草稿缺少可编辑关卡",
        }))
    })?;
    let work_title = payload
        .work_title
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .unwrap_or(draft.work_title.as_str())
        .to_string();
    let work_description = payload
        .work_description
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .unwrap_or(draft.work_description.as_str())
        .to_string();
    let levels_json = Some(serialize_puzzle_level_records_for_module(&levels)?);
    let (_, profile_id) = build_stable_puzzle_work_ids(session_id);
    state
        .spacetime_client()
        .update_puzzle_work(PuzzleWorkUpsertRecordInput {
            profile_id,
            owner_user_id: owner_user_id.to_string(),
            work_title: work_title.clone(),
            work_description: work_description.clone(),
            level_name: first_level.level_name.clone(),
            summary: work_description.clone(),
            theme_tags: generated_tags.clone(),
            cover_image_src: first_level.cover_image_src.clone(),
            cover_asset_id: first_level.cover_asset_id.clone(),
            levels_json,
            updated_at_micros: now,
        })
        .await
        .map_err(map_puzzle_client_error)?;

    Ok(apply_generated_puzzle_tags_to_session_snapshot(
        session,
        generated_tags,
        work_title,
        work_description,
        levels,
        now,
    ))
}

fn apply_generated_puzzle_tags_to_session_snapshot(
    mut session: PuzzleAgentSessionRecord,
    generated_tags: Vec<String>,
    work_title: String,
    work_description: String,
    levels: Vec<PuzzleDraftLevelRecord>,
    updated_at_micros: i64,
) -> PuzzleAgentSessionRecord {
    let Some(draft) = session.draft.as_mut() else {
        return session;
    };
    draft.work_title = work_title;
    draft.work_description = work_description.clone();
    draft.summary = work_description;
    draft.theme_tags = generated_tags;
    draft.levels = levels;
    sync_puzzle_primary_draft_fields_from_level(draft);
    session.progress_percent = session.progress_percent.max(96);
    session.stage = if is_puzzle_session_snapshot_publish_ready(draft) {
        "ready_to_publish".to_string()
    } else {
        "image_refining".to_string()
    };
    session.last_assistant_reply = Some("作品标签已生成。".to_string());
    session.updated_at = format_timestamp_micros(updated_at_micros);
    session
}

fn is_puzzle_session_snapshot_publish_ready(draft: &PuzzleResultDraftRecord) -> bool {
    !draft.work_title.trim().is_empty()
        && !draft.work_description.trim().is_empty()
        && draft.theme_tags.len() >= module_puzzle::PUZZLE_MIN_TAG_COUNT
        && draft.theme_tags.len() <= module_puzzle::PUZZLE_MAX_TAG_COUNT
        && !draft.levels.is_empty()
        && draft.levels.iter().all(|level| {
            !level.level_name.trim().is_empty()
                && level
                    .cover_image_src
                    .as_deref()
                    .map(str::trim)
                    .is_some_and(|value| !value.is_empty())
        })
}

fn serialize_puzzle_level_records_for_module(
    levels: &[PuzzleDraftLevelRecord],
) -> Result<String, AppError> {
    let payload = levels
        .iter()
        .map(|level| {
            json!({
                "level_id": level.level_id,
                "level_name": level.level_name,
                "picture_description": level.picture_description,
                "picture_reference": level.picture_reference,
                "ui_background_prompt": level.ui_background_prompt,
                "ui_background_image_src": level.ui_background_image_src,
                "ui_background_image_object_key": level.ui_background_image_object_key,
                "background_music": puzzle_audio_asset_record_module_json(&level.background_music),
                "candidates": level
                    .candidates
                    .iter()
                    .map(|candidate| {
                        json!({
                            "candidate_id": candidate.candidate_id,
                            "image_src": candidate.image_src,
                            "asset_id": candidate.asset_id,
                            "prompt": candidate.prompt,
                            "actual_prompt": candidate.actual_prompt,
                            "source_type": candidate.source_type,
                            "selected": candidate.selected,
                        })
                    })
                    .collect::<Vec<_>>(),
                "selected_candidate_id": level.selected_candidate_id,
                "cover_image_src": level.cover_image_src,
                "cover_asset_id": level.cover_asset_id,
                "generation_status": level.generation_status,
            })
        })
        .collect::<Vec<_>>();
    serde_json::to_string(&payload).map_err(|error| {
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": format!("拼图关卡列表序列化失败：{error}"),
        }))
    })
}

fn is_spacetimedb_connectivity_app_error(error: &AppError) -> bool {
    matches!(
        error.status_code(),
        StatusCode::SERVICE_UNAVAILABLE | StatusCode::GATEWAY_TIMEOUT
    )
}

fn ensure_non_empty(
    request_context: &RequestContext,
    provider: &str,
    value: &str,
    field_name: &str,
) -> Result<(), Response> {
    if value.trim().is_empty() {
        return Err(puzzle_error_response(
            request_context,
            provider,
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": provider,
                "message": format!("{field_name} is required"),
            })),
        ));
    }
    Ok(())
}

fn puzzle_bad_request(request_context: &RequestContext, provider: &str, message: &str) -> Response {
    puzzle_error_response(
        request_context,
        provider,
        AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
            "provider": provider,
            "message": message,
        })),
    )
}

fn map_puzzle_client_error(error: SpacetimeClientError) -> AppError {
    let status = match &error {
        SpacetimeClientError::ConnectDropped => StatusCode::SERVICE_UNAVAILABLE,
        SpacetimeClientError::Timeout => StatusCode::GATEWAY_TIMEOUT,
        error if should_skip_asset_operation_billing_for_connectivity(error) => {
            StatusCode::SERVICE_UNAVAILABLE
        }
        SpacetimeClientError::Runtime(_) => StatusCode::BAD_REQUEST,
        SpacetimeClientError::Procedure(message)
            if message.contains("不存在")
                || message.contains("not found")
                || message.contains("does not exist") =>
        {
            StatusCode::NOT_FOUND
        }
        SpacetimeClientError::Procedure(message)
            if message.contains("当前模型不可用")
                || message.contains("生成失败")
                || message.contains("解析失败")
                || message.contains("缺少有效回复") =>
        {
            StatusCode::BAD_GATEWAY
        }
        _ => StatusCode::BAD_GATEWAY,
    };

    AppError::from_status(status).with_details(json!({
        "provider": "spacetimedb",
        "message": error.to_string(),
    }))
}

fn should_sync_puzzle_freeze_boundary(error: &AppError, is_freeze_time: bool) -> bool {
    is_freeze_time && error.body_text().contains("操作不合法")
}

fn is_missing_puzzle_form_draft_procedure_error(error: &SpacetimeClientError) -> bool {
    matches!(error, SpacetimeClientError::Procedure(message) if
        message.contains("save_puzzle_form_draft")
            && (message.contains("No such procedure")
                || message.contains("不存在")
                || message.contains("does not exist")
                || message.contains("not found")))
}

fn map_puzzle_compile_error(error: SpacetimeClientError) -> AppError {
    let message = error.to_string();
    // 中文注释：历史运行态或旧 SpacetimeDB 错误快照可能仍带 APIMart 图片网关文案；当前 GPT-image-2 已统一迁移到 VectorEngine，返回给前端前先归一，避免误导排障。
    let is_legacy_apimart_image_error =
        message.contains("APIMart") || message.contains("apimart") || message.contains("APIMART");
    let provider = if message.contains("VectorEngine")
        || message.contains("vector-engine")
        || message.contains("VECTOR_ENGINE")
        || is_legacy_apimart_image_error
    {
        VECTOR_ENGINE_PROVIDER
    } else if message.contains("OSS") || message.contains("oss") || message.contains("参考图") {
        "puzzle-assets"
    } else {
        "spacetimedb"
    };
    let status = if provider == VECTOR_ENGINE_PROVIDER
        && (message.contains("VECTOR_ENGINE_API_KEY")
            || message.contains("VECTOR_ENGINE_BASE_URL")
            || message.contains("APIMART_API_KEY")
            || message.contains("APIMART_BASE_URL")
            || message.contains("未配置"))
    {
        StatusCode::SERVICE_UNAVAILABLE
    } else if matches!(
        error,
        SpacetimeClientError::ConnectDropped | SpacetimeClientError::Timeout
    ) || should_skip_asset_operation_billing_for_connectivity(&error)
    {
        StatusCode::SERVICE_UNAVAILABLE
    } else if matches!(error, SpacetimeClientError::Runtime(_))
        && (message.contains("生成")
            || message.contains("上游")
            || message.contains("VectorEngine")
            || message.contains("vector-engine")
            || message.contains("VECTOR_ENGINE")
            || is_legacy_apimart_image_error
            || message.contains("参考图")
            || message.contains("图片")
            || message.contains("OSS")
            || message.contains("oss"))
    {
        StatusCode::BAD_GATEWAY
    } else {
        match &error {
            SpacetimeClientError::Procedure(message)
                if message.contains("不存在")
                    || message.contains("not found")
                    || message.contains("does not exist") =>
            {
                StatusCode::NOT_FOUND
            }
            SpacetimeClientError::Procedure(message)
                if message.contains("当前模型不可用")
                    || message.contains("生成失败")
                    || message.contains("解析失败")
                    || message.contains("缺少有效回复") =>
            {
                StatusCode::BAD_GATEWAY
            }
            SpacetimeClientError::ConnectDropped => StatusCode::SERVICE_UNAVAILABLE,
            SpacetimeClientError::Timeout => StatusCode::GATEWAY_TIMEOUT,
            SpacetimeClientError::Runtime(_) => StatusCode::BAD_REQUEST,
            _ => StatusCode::BAD_GATEWAY,
        }
    };
    let user_message = normalize_legacy_puzzle_image_error_message(message.as_str());

    AppError::from_status(status).with_details(json!({
        "provider": provider,
        "message": user_message,
    }))
}

fn normalize_legacy_puzzle_image_error_message(message: &str) -> String {
    message
        .replace(
            "APIMart 图片生成密钥未配置",
            "VectorEngine 图片生成密钥未配置",
        )
        .replace(
            "APIMart 图片生成地址未配置",
            "VectorEngine 图片生成地址未配置",
        )
        .replace("APIMART_API_KEY", "VECTOR_ENGINE_API_KEY")
        .replace("APIMART_BASE_URL", "VECTOR_ENGINE_BASE_URL")
}

fn puzzle_error_response(
    request_context: &RequestContext,
    provider: &str,
    error: AppError,
) -> Response {
    let mut response = error.into_response_with_context(Some(request_context));
    response.headers_mut().insert(
        HeaderName::from_static("x-genarrative-provider"),
        header::HeaderValue::from_str(provider)
            .unwrap_or_else(|_| header::HeaderValue::from_static("puzzle")),
    );
    response
}

fn puzzle_sse_json_event(event_name: &str, payload: Value) -> Result<Event, AppError> {
    Event::default()
        .event(event_name)
        .json_data(payload)
        .map_err(|error| {
            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
                "provider": "sse",
                "message": format!("SSE payload 序列化失败：{error}"),
            }))
        })
}

fn puzzle_sse_json_event_or_error(event_name: &str, payload: Value) -> Event {
    match puzzle_sse_json_event(event_name, payload) {
        Ok(event) => event,
        Err(_) => puzzle_sse_error_event_message("SSE payload 序列化失败".to_string()),
    }
}

fn puzzle_sse_error_event_message(message: String) -> Event {
    let payload = format!(
        "{{\"message\":{}}}",
        serde_json::to_string(&message)
            .unwrap_or_else(|_| "\"SSE 错误事件序列化失败\"".to_string())
    );
    Event::default().event("error").data(payload)
}

fn map_puzzle_generation_endpoint_error(error: AppError) -> AppError {
    if error.code() == "UPSTREAM_ERROR" {
        let body_text = error.body_text();
        return AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
            "message": format!("拼图图片生成失败：{body_text}"),
        }));
    }

    error
}

async fn generate_puzzle_image_candidates(
    state: &AppState,
    owner_user_id: &str,
    session_id: &str,
    level_name: &str,
    prompt: &str,
    reference_image_src: Option<&str>,
    use_reference_image_edit: bool,
    image_model: Option<&str>,
    candidate_count: u32,
    candidate_start_index: usize,
) -> Result<Vec<GeneratedPuzzleImageCandidate>, AppError> {
    let total_started_at = Instant::now();
    let count = candidate_count.clamp(1, 1);
    let resolved_model = resolve_puzzle_image_model(image_model);
    let http_client = build_puzzle_image_http_client(state, resolved_model)?;
    let has_reference_image = has_puzzle_reference_image(reference_image_src);
    let should_use_reference_image_edit =
        should_use_puzzle_reference_image_edit(reference_image_src, use_reference_image_edit);
    let actual_prompt = build_puzzle_vector_engine_generation_prompt(
        build_puzzle_image_prompt(level_name, prompt).as_str(),
        should_use_reference_image_edit,
    );
    tracing::info!(
        provider = resolved_model.provider_name(),
        image_model = resolved_model.request_model_name(),
        session_id,
        level_name,
        prompt_chars = prompt.chars().count(),
        actual_prompt_chars = actual_prompt.chars().count(),
        has_reference_image,
        use_reference_image_edit = should_use_reference_image_edit,
        "拼图图片生成请求已准备"
    );
    let reference_image_started_at = Instant::now();
    let reference_image = match reference_image_src
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .filter(|_| should_use_reference_image_edit)
    {
        Some(source) => {
            let resolved =
                resolve_puzzle_reference_image_as_data_url(state, &http_client, source).await?;
            tracing::info!(
                provider = resolved_model.provider_name(),
                image_model = resolved_model.request_model_name(),
                session_id,
                level_name,
                reference_mime = %resolved.mime_type,
                reference_bytes = resolved.bytes_len,
                elapsed_ms = reference_image_started_at.elapsed().as_millis() as u64,
                "拼图参考图解析完成"
            );
            Some(resolved)
        }
        None => None,
    };
    if !should_use_reference_image_edit {
        tracing::info!(
            provider = resolved_model.provider_name(),
            image_model = resolved_model.request_model_name(),
            session_id,
            level_name,
            has_reference_image,
            use_reference_image_edit = should_use_reference_image_edit,
            elapsed_ms = reference_image_started_at.elapsed().as_millis() as u64,
            "拼图参考图解析跳过"
        );
    }
    // 中文注释：SpacetimeDB reducer 不能做外部 I/O，参考图读取与外部生图都必须停留在 api-server。
    // 中文注释：拼图作品资产统一按 1:1 正方形生成，前端运行时也按正方形棋盘切块承载。
    let settings = require_puzzle_vector_engine_settings(state)?;
    let vector_engine_started_at = Instant::now();
    let generated = if should_use_reference_image_edit {
        let reference_image = reference_image.as_ref().ok_or_else(|| {
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": "puzzle",
                "field": "referenceImageSrc",
                "message": "AI 重绘需要提供参考图。",
            }))
        })?;
        create_puzzle_vector_engine_image_edit(
            &http_client,
            &settings,
            actual_prompt.as_str(),
            PUZZLE_DEFAULT_NEGATIVE_PROMPT,
            PUZZLE_VECTOR_ENGINE_GENERATED_IMAGE_SIZE,
            count,
            reference_image,
        )
        .await
    } else {
        create_puzzle_vector_engine_image_generation(
            &http_client,
            &settings,
            resolved_model,
            actual_prompt.as_str(),
            PUZZLE_DEFAULT_NEGATIVE_PROMPT,
            PUZZLE_VECTOR_ENGINE_GENERATED_IMAGE_SIZE,
            count,
        )
        .await
    }
    .map_err(map_puzzle_generation_endpoint_error)?;
    tracing::info!(
        provider = resolved_model.provider_name(),
        image_model = resolved_model.request_model_name(),
        session_id,
        level_name,
        generated_image_count = generated.images.len(),
        elapsed_ms = vector_engine_started_at.elapsed().as_millis() as u64,
        "拼图 VectorEngine 生图与下载完成"
    );
    let mut items = Vec::with_capacity(generated.images.len());

    for (index, image) in generated.images.into_iter().enumerate() {
        let candidate_id = format!(
            "{session_id}-candidate-{}",
            candidate_start_index + index + 1
        );
        let downloaded_image = image.clone();
        let persist_started_at = Instant::now();
        let asset = persist_puzzle_generated_asset(
            state,
            owner_user_id,
            session_id,
            level_name,
            candidate_id.as_str(),
            generated.task_id.as_str(),
            image,
            current_utc_micros(),
        )
        .await
        .map_err(map_puzzle_generation_endpoint_error)?;
        tracing::info!(
            provider = resolved_model.provider_name(),
            image_model = resolved_model.request_model_name(),
            session_id,
            level_name,
            candidate_id = %candidate_id,
            image_bytes = downloaded_image.bytes.len(),
            image_mime = %downloaded_image.mime_type,
            elapsed_ms = persist_started_at.elapsed().as_millis() as u64,
            "拼图生成图片已写入 OSS 与资产索引"
        );
        items.push(GeneratedPuzzleImageCandidate {
            record: PuzzleGeneratedImageCandidateRecord {
                candidate_id,
                image_src: asset.image_src,
                asset_id: asset.asset_id,
                prompt: prompt.to_string(),
                actual_prompt: Some(actual_prompt.clone()),
                source_type: resolved_model.candidate_source_type().to_string(),
                // 单图生成结果总是直接成为当前正式图。
                selected: index == 0,
            },
            downloaded_image,
        });
    }

    tracing::info!(
        provider = resolved_model.provider_name(),
        image_model = resolved_model.request_model_name(),
        session_id,
        level_name,
        candidate_count = items.len(),
        has_reference_image,
        elapsed_ms = total_started_at.elapsed().as_millis() as u64,
        "拼图图片候选生成完成"
    );
    Ok(items)
}

async fn generate_puzzle_ui_background_image(
    state: &AppState,
    owner_user_id: &str,
    session_id: &str,
    level_name: &str,
    prompt: &str,
) -> Result<GeneratedPuzzleUiBackgroundResponse, AppError> {
    let settings = require_openai_image_settings(state)?;
    let http_client = build_openai_image_http_client(&settings)?;
    let reference_image = load_puzzle_ui_background_reference_data_url().await?;
    let generated = create_openai_image_generation(
        &http_client,
        &settings,
        build_puzzle_ui_background_generation_prompt(level_name, prompt).as_str(),
        Some("文字、水印、按钮文字、数字、教程浮层、拼图碎片、完整拼图图像、角色手指、模糊边界"),
        "9:16",
        1,
        &[reference_image],
        "拼图 UI 背景图生成失败",
    )
    .await?;
    let image = generated.images.into_iter().next().ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": VECTOR_ENGINE_PROVIDER,
            "message": "拼图 UI 背景图生成失败：未返回图片",
        }))
    })?;
    persist_puzzle_ui_background_image(
        state,
        owner_user_id,
        session_id,
        level_name,
        generated.task_id.as_str(),
        image,
    )
    .await
}

#[cfg(test)]
fn build_puzzle_ui_background_request_prompt_for_test(level_name: &str, prompt: &str) -> String {
    build_puzzle_ui_background_generation_prompt(level_name, prompt)
}

async fn load_puzzle_ui_background_reference_data_url() -> Result<String, AppError> {
    let bytes = tokio::fs::read(PUZZLE_UI_BACKGROUND_REFERENCE_IMAGE_PATH)
        .await
        .map_err(|error| {
            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": format!("读取拼图 UI 背景参考图失败：{error}"),
            }))
        })?;
    if bytes.is_empty() {
        return Err(AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(
            json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": "拼图 UI 背景参考图为空",
            }),
        ));
    }
    Ok(format!(
        "data:image/png;base64,{}",
        BASE64_STANDARD.encode(bytes)
    ))
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn puzzle_generated_image_size_is_square_1_1() {
        assert_eq!(PUZZLE_GENERATED_IMAGE_SIZE, "1024*1024");
        assert_eq!(PUZZLE_VECTOR_ENGINE_GENERATED_IMAGE_SIZE, "1024x1024");
    }

    #[test]
    fn puzzle_vector_engine_request_uses_gpt_image_2_all_and_reference_images() {
        let body = build_puzzle_vector_engine_image_request_body(
            PuzzleImageModel::Gemini31FlashPreview,
            "一只猫在雨夜灯牌下回头。",
            PUZZLE_DEFAULT_NEGATIVE_PROMPT,
            PUZZLE_VECTOR_ENGINE_GENERATED_IMAGE_SIZE,
            4,
        );

        assert_eq!(body["model"], VECTOR_ENGINE_GPT_IMAGE_2_MODEL);
        assert_eq!(body["size"], PUZZLE_VECTOR_ENGINE_GENERATED_IMAGE_SIZE);
        assert_eq!(body["n"], 1);
        assert!(body.get("official_fallback").is_none());
        assert!(body.get("image").is_none());
        assert!(
            body["prompt"]
                .as_str()
                .unwrap_or_default()
                .contains("文字水印")
        );
    }

    #[test]
    fn puzzle_vector_engine_edit_url_uses_images_edits_endpoint() {
        let settings = PuzzleVectorEngineSettings {
            base_url: "https://vector.example/v1".to_string(),
            api_key: "test-key".to_string(),
        };

        assert_eq!(
            puzzle_vector_engine_images_edit_url(&settings),
            "https://vector.example/v1/images/edits"
        );
    }

    #[test]
    fn puzzle_vector_engine_edit_response_decodes_b64_image() {
        let images = puzzle_images_from_base64(
            "edit-1".to_string(),
            vec![BASE64_STANDARD.encode(b"\x89PNG\r\n\x1A\nrest")],
            1,
        );

        assert_eq!(images.images.len(), 1);
        assert_eq!(images.images[0].mime_type, "image/png");
        assert_eq!(images.images[0].extension, "png");
    }

    #[test]
    fn puzzle_vector_engine_prompt_strongly_uses_reference_image() {
        let prompt = build_puzzle_vector_engine_generation_prompt("请生成雨夜猫街。", true);

        assert!(prompt.contains("参考图作为第一优先级"));
        assert!(prompt.contains("严格保留参考图的主要主体、构图关系、视角、姿态、配色和光影氛围"));
        assert!(prompt.contains("请生成雨夜猫街。"));
    }

    #[test]
    fn puzzle_vector_engine_prompt_keeps_text_only_prompt_unchanged() {
        let prompt = build_puzzle_vector_engine_generation_prompt("请生成雨夜猫街。", false);

        assert_eq!(prompt, "请生成雨夜猫街。");
    }

    #[test]
    fn puzzle_reference_image_edit_requires_ai_redraw() {
        assert!(!should_use_puzzle_reference_image_edit(None, true));
        assert!(!should_use_puzzle_reference_image_edit(
            Some("data:image/png;base64,abcd"),
            false
        ));
        assert!(should_use_puzzle_reference_image_edit(
            Some("data:image/png;base64,abcd"),
            true
        ));
    }

    #[test]
    fn puzzle_compile_error_preserves_vector_engine_unavailable_status() {
        let error = map_puzzle_compile_error(SpacetimeClientError::Runtime(
            "VECTOR_ENGINE_API_KEY 未配置".to_string(),
        ));

        let response = error.into_response();
        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
    }

    #[tokio::test]
    async fn puzzle_compile_error_normalizes_legacy_apimart_image_message() {
        let error = map_puzzle_compile_error(SpacetimeClientError::Runtime(
            "APIMart 图片生成密钥未配置".to_string(),
        ));

        let response = error.into_response();
        assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
        let body = response.into_body();
        let bytes = axum::body::to_bytes(body, usize::MAX)
            .await
            .expect("body bytes should read");
        let payload: Value =
            serde_json::from_slice(&bytes).expect("error response should be valid json");
        assert_eq!(
            payload["error"]["details"]["provider"],
            Value::String(VECTOR_ENGINE_PROVIDER.to_string())
        );
        assert_eq!(
            payload["error"]["details"]["message"],
            Value::String("VectorEngine 图片生成密钥未配置".to_string())
        );
    }

    #[test]
    fn puzzle_image_generation_builds_fallback_session_from_levels_snapshot() {
        let levels_json = serde_json::to_string(&vec![json!({
            "level_id": "puzzle-level-1",
            "level_name": "雨夜猫街",
            "picture_description": "一只猫在雨夜灯牌下回头。",
            "candidates": [],
            "selected_candidate_id": null,
            "cover_image_src": null,
            "cover_asset_id": null,
            "generation_status": "idle",
        })])
        .expect("levels json");
        let payload = ExecutePuzzleAgentActionRequest {
            action: "generate_puzzle_images".to_string(),
            prompt_text: None,
            reference_image_src: None,
            image_model: Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2.to_string()),
            ai_redraw: None,
            candidate_count: Some(1),
            candidate_id: None,
            level_id: Some("puzzle-level-1".to_string()),
            work_title: Some("暖灯猫街作品".to_string()),
            work_description: Some("一套雨夜猫街主题拼图。".to_string()),
            picture_description: None,
            level_name: None,
            summary: Some("当前关卡画面。".to_string()),
            theme_tags: Some(vec!["猫咪".to_string(), "雨夜".to_string()]),
            levels_json: Some(levels_json.clone()),
        };

        let session = build_puzzle_session_snapshot_from_action_payload(
            "puzzle-session-1",
            &payload,
            Some(levels_json.as_str()),
            1_713_686_401_234_567,
        )
        .expect("fallback session");

        let draft = session.draft.expect("draft");
        assert_eq!(session.stage, "ready_to_publish");
        assert_eq!(draft.work_title, "暖灯猫街作品");
        assert_eq!(draft.theme_tags, vec!["猫咪", "雨夜"]);
        assert_eq!(draft.levels[0].level_id, "puzzle-level-1");
        assert_eq!(
            draft.levels[0].picture_description,
            "一只猫在雨夜灯牌下回头。"
        );
    }

    #[test]
    fn puzzle_first_level_name_parser_accepts_json_and_normalizes_text() {
        assert_eq!(
            parse_puzzle_first_level_name_from_text(r#"{"levelName":"雨夜猫街"}"#),
            Some("雨夜猫街".to_string())
        );
        assert_eq!(
            parse_puzzle_first_level_name_from_text("1. 《暖灯猫街》"),
            Some("暖灯猫街".to_string())
        );
        assert_eq!(
            parse_puzzle_first_level_name_from_text(r#"{"levelName":"雨夜猫街画面"}"#),
            Some("雨夜猫街".to_string())
        );
    }

    #[test]
    fn puzzle_first_level_name_fallback_uses_picture_keywords() {
        assert_eq!(
            build_fallback_puzzle_first_level_name("一只猫在雨夜灯牌下回头。"),
            "雨夜猫街"
        );
        assert_eq!(
            build_fallback_puzzle_first_level_name("看不出关键词的抽象色块。"),
            "奇境初见"
        );
    }

    #[test]
    fn puzzle_level_name_image_data_url_downsizes_generated_image() {
        let image = image::DynamicImage::ImageRgb8(image::RgbImage::new(4, 4));
        let mut cursor = std::io::Cursor::new(Vec::new());
        image
            .write_to(&mut cursor, ImageFormat::Png)
            .expect("test image should encode");
        let downloaded = PuzzleDownloadedImage {
            extension: "png".to_string(),
            mime_type: "image/png".to_string(),
            bytes: cursor.into_inner(),
        };

        let data_url = build_puzzle_level_name_image_data_url(&downloaded)
            .expect("data url should be generated");

        assert!(data_url.starts_with("data:image/png;base64,"));
        assert!(data_url.len() > "data:image/png;base64,".len());
    }

    #[test]
    fn puzzle_first_level_name_snapshot_defaults_work_title() {
        let levels_json = serde_json::to_string(&vec![json!({
            "level_id": "puzzle-level-1",
            "level_name": "猫画面",
            "picture_description": "一只猫在雨夜灯牌下回头。",
            "candidates": [],
            "selected_candidate_id": null,
            "cover_image_src": null,
            "cover_asset_id": null,
            "generation_status": "idle",
        })])
        .expect("levels json");
        let payload = ExecutePuzzleAgentActionRequest {
            action: "generate_puzzle_images".to_string(),
            prompt_text: None,
            reference_image_src: None,
            image_model: Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2.to_string()),
            ai_redraw: None,
            candidate_count: Some(1),
            candidate_id: None,
            level_id: Some("puzzle-level-1".to_string()),
            work_title: Some("猫画面".to_string()),
            work_description: None,
            picture_description: None,
            level_name: None,
            summary: None,
            theme_tags: Some(vec![]),
            levels_json: Some(levels_json.clone()),
        };
        let session = build_puzzle_session_snapshot_from_action_payload(
            "puzzle-session-1",
            &payload,
            Some(levels_json.as_str()),
            1_713_686_401_234_567,
        )
        .expect("fallback session");

        let renamed = apply_generated_puzzle_first_level_name_to_session_snapshot(
            session,
            "puzzle-level-1",
            "雨夜猫街",
            "猫画面",
            1_713_686_401_234_568,
        );
        let draft = renamed.draft.expect("draft");
        assert_eq!(draft.level_name, "雨夜猫街");
        assert_eq!(draft.work_title, "雨夜猫街");
        assert_eq!(draft.levels[0].level_name, "雨夜猫街");
    }

    #[test]
    fn puzzle_level_audio_asset_roundtrips_between_response_and_module_json() {
        let level = PuzzleDraftLevelResponse {
            level_id: "puzzle-level-1".to_string(),
            level_name: "雨夜猫街".to_string(),
            picture_description: "一只猫在雨夜灯牌下回头。".to_string(),
            picture_reference: None,
            ui_background_prompt: None,
            ui_background_image_src: None,
            ui_background_image_object_key: None,
            background_music: Some(CreationAudioAsset {
                task_id: "suno-task-1".to_string(),
                provider: "vector-engine-suno".to_string(),
                asset_object_id: Some("assetobj_1".to_string()),
                asset_kind: Some("puzzle_background_music".to_string()),
                audio_src: "/generated-puzzle-assets/audio.mp3".to_string(),
                prompt: Some("轻快拼图音乐".to_string()),
                title: Some("雨夜猫街背景音乐".to_string()),
                updated_at: Some("2026-05-11T00:00:00Z".to_string()),
            }),
            candidates: vec![],
            selected_candidate_id: None,
            cover_image_src: None,
            cover_asset_id: None,
            generation_status: "ready".to_string(),
        };
        let request_context = RequestContext::new(
            "test-request".to_string(),
            "PUT /api/runtime/puzzle/works/test".to_string(),
            Duration::ZERO,
            false,
        );

        let levels_json = serialize_puzzle_levels_response(&request_context, &[level])
            .expect("levels should serialize");
        let payload: Value =
            serde_json::from_str(&levels_json).expect("levels json should parse");
        assert_eq!(
            payload[0]["background_music"]["audio_src"],
            Value::String("/generated-puzzle-assets/audio.mp3".to_string())
        );
        assert!(payload[0]["background_music"].get("audioSrc").is_none());

        let records = parse_puzzle_level_records_from_module_json(&levels_json)
            .expect("levels should map back into records");
        let music = records[0]
            .background_music
            .as_ref()
            .expect("background music should exist");
        assert_eq!(music.audio_src, "/generated-puzzle-assets/audio.mp3");
        assert_eq!(music.asset_kind.as_deref(), Some("puzzle_background_music"));

        let response = map_puzzle_draft_level_response(records[0].clone());
        assert_eq!(
            response
                .background_music
                .as_ref()
                .map(|asset| asset.audio_src.as_str()),
            Some("/generated-puzzle-assets/audio.mp3")
        );
    }

    #[test]
    fn puzzle_ui_background_fields_roundtrip_between_response_and_module_json() {
        let level = PuzzleDraftLevelResponse {
            level_id: "puzzle-level-1".to_string(),
            level_name: "雨夜猫街".to_string(),
            picture_description: "一只猫在雨夜灯牌下回头。".to_string(),
            picture_reference: None,
            ui_background_prompt: Some("雨夜猫街竖屏拼图UI背景".to_string()),
            ui_background_image_src: Some(
                "/generated-puzzle-assets/session/ui/background.png".to_string(),
            ),
            ui_background_image_object_key: Some(
                "generated-puzzle-assets/session/ui/background.png".to_string(),
            ),
            background_music: None,
            candidates: vec![],
            selected_candidate_id: None,
            cover_image_src: Some("/generated-puzzle-assets/session/cover.png".to_string()),
            cover_asset_id: Some("asset-1".to_string()),
            generation_status: "ready".to_string(),
        };
        let request_context = RequestContext::new(
            "test-request".to_string(),
            "PUT /api/runtime/puzzle/works/test".to_string(),
            Duration::ZERO,
            false,
        );

        let levels_json = serialize_puzzle_levels_response(&request_context, &[level])
            .expect("levels should serialize");
        let payload: Value =
            serde_json::from_str(&levels_json).expect("levels json should parse");
        assert_eq!(
            payload[0]["ui_background_prompt"],
            Value::String("雨夜猫街竖屏拼图UI背景".to_string())
        );
        assert!(payload[0].get("uiBackgroundPrompt").is_none());

        let records = parse_puzzle_level_records_from_module_json(&levels_json)
            .expect("levels should map back into records");
        assert_eq!(
            records[0].ui_background_image_src.as_deref(),
            Some("/generated-puzzle-assets/session/ui/background.png")
        );

        let response = map_puzzle_draft_level_response(records[0].clone());
        assert_eq!(
            response.ui_background_image_object_key.as_deref(),
            Some("generated-puzzle-assets/session/ui/background.png")
        );
    }

    #[test]
    fn puzzle_ui_background_prompt_keeps_square_boundary_constraint() {
        let prompt = build_puzzle_ui_background_request_prompt_for_test(
            "雨夜猫街",
            "雨夜猫街主题背景",
        );

        assert!(prompt.contains("9:16"));
        assert!(prompt.contains("中央必须预留清晰正方形拼图区"));
        assert!(prompt.contains("明确边界"));
        assert!(prompt.contains("不要画文字"));
    }

    fn test_puzzle_anchor_pack_record() -> PuzzleAnchorPackRecord {
        let item = PuzzleAnchorItemRecord {
            key: "visualSubject".to_string(),
            label: "画面".to_string(),
            value: "雨夜猫街".to_string(),
            status: "confirmed".to_string(),
        };

        PuzzleAnchorPackRecord {
            theme_promise: item.clone(),
            visual_subject: item.clone(),
            visual_mood: item.clone(),
            composition_hooks: item.clone(),
            tags_and_forbidden: item,
        }
    }

    fn test_puzzle_draft_record() -> PuzzleResultDraftRecord {
        let anchor_pack = test_puzzle_anchor_pack_record();
        PuzzleResultDraftRecord {
            work_title: "雨夜猫街".to_string(),
            work_description: "一只猫在雨夜灯牌下回头。".to_string(),
            level_name: "猫画面".to_string(),
            summary: "一只猫在雨夜灯牌下回头。".to_string(),
            theme_tags: vec![],
            forbidden_directives: vec![],
            creator_intent: None,
            anchor_pack,
            candidates: vec![],
            selected_candidate_id: None,
            cover_image_src: None,
            cover_asset_id: None,
            generation_status: "idle".to_string(),
            levels: vec![PuzzleDraftLevelRecord {
                level_id: "puzzle-level-1".to_string(),
                level_name: "猫画面".to_string(),
                picture_description: "一只猫在雨夜灯牌下回头。".to_string(),
                picture_reference: None,
                ui_background_prompt: None,
                ui_background_image_src: None,
                ui_background_image_object_key: None,
                background_music: None,
                candidates: vec![],
                selected_candidate_id: None,
                cover_image_src: None,
                cover_asset_id: None,
                generation_status: "idle".to_string(),
            }],
            form_draft: None,
        }
    }

    #[test]
    fn puzzle_primary_level_update_preserves_reference_for_regeneration() {
        let draft = test_puzzle_draft_record();
        let mut target_level = draft.levels[0].clone();
        target_level.level_name = "雨夜猫街".to_string();

        let levels = build_puzzle_levels_with_primary_update(
            &draft,
            &target_level,
            Some("data:image/png;base64,abcd"),
        );

        assert_eq!(levels[0].level_name, "雨夜猫街");
        assert_eq!(
            levels[0].picture_reference.as_deref(),
            Some("data:image/png;base64,abcd")
        );
    }

    #[test]
    fn puzzle_generated_fallback_snapshot_preserves_picture_reference() {
        let anchor_pack = test_puzzle_anchor_pack_record();
        let session = PuzzleAgentSessionRecord {
            session_id: "puzzle-session-1".to_string(),
            seed_text: "雨夜猫街".to_string(),
            current_turn: 1,
            progress_percent: 0,
            stage: "draft_ready".to_string(),
            anchor_pack: anchor_pack.clone(),
            draft: Some(test_puzzle_draft_record()),
            messages: Vec::new(),
            last_assistant_reply: None,
            published_profile_id: None,
            suggested_actions: Vec::new(),
            result_preview: None,
            updated_at: "2024-01-01T00:00:00Z".to_string(),
        };
        let candidate = PuzzleGeneratedImageCandidateRecord {
            candidate_id: "puzzle-session-1-candidate-1".to_string(),
            image_src: "/generated-puzzle-assets/puzzle-session-1/1/cover.png".to_string(),
            asset_id: "puzzle-cover-1".to_string(),
            prompt: "雨夜猫街".to_string(),
            actual_prompt: Some("雨夜猫街".to_string()),
            source_type: "generated:gpt-image-2".to_string(),
            selected: true,
        };

        let session = apply_generated_puzzle_candidates_to_session_snapshot(
            session,
            "puzzle-level-1",
            vec![candidate],
            Some("data:image/png;base64,abcd"),
            1_713_686_401_234_568,
        );

        let draft = session.draft.expect("draft");
        assert_eq!(
            draft.levels[0].picture_reference.as_deref(),
            Some("data:image/png;base64,abcd")
        );
    }

    #[test]
    fn freeze_boundary_sync_only_matches_freeze_invalid_operation() {
        let invalid_operation =
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": "spacetimedb",
                "message": "操作不合法",
            }));
        let other_error = AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": "spacetimedb",
            "message": "光点余额不足",
        }));

        assert!(should_sync_puzzle_freeze_boundary(&invalid_operation, true));
        assert!(!should_sync_puzzle_freeze_boundary(
            &invalid_operation,
            false
        ));
        assert!(!should_sync_puzzle_freeze_boundary(&other_error, true));
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum PuzzleImageModel {
    GptImage2,
    Gemini31FlashPreview,
}

impl PuzzleImageModel {
    fn provider_name(self) -> &'static str {
        VECTOR_ENGINE_PROVIDER
    }

    fn request_model_name(self) -> &'static str {
        VECTOR_ENGINE_GPT_IMAGE_2_MODEL
    }

    fn candidate_source_type(self) -> &'static str {
        match self {
            Self::GptImage2 => "generated:gpt-image-2",
            Self::Gemini31FlashPreview => "generated:nanobanana2",
        }
    }
}

struct PuzzleVectorEngineSettings {
    base_url: String,
    api_key: String,
}

struct PuzzleGeneratedImages {
    task_id: String,
    images: Vec<PuzzleDownloadedImage>,
}

struct PuzzleResolvedReferenceImage {
    mime_type: String,
    bytes_len: usize,
    bytes: Vec<u8>,
}

struct GeneratedPuzzleImageCandidate {
    record: PuzzleGeneratedImageCandidateRecord,
    downloaded_image: PuzzleDownloadedImage,
}

impl GeneratedPuzzleImageCandidate {
    fn into_record(self) -> PuzzleGeneratedImageCandidateRecord {
        self.record
    }
}

trait GeneratedPuzzleImageCandidatesExt {
    fn into_records(self) -> Vec<PuzzleGeneratedImageCandidateRecord>;
}

impl GeneratedPuzzleImageCandidatesExt for Vec<GeneratedPuzzleImageCandidate> {
    fn into_records(self) -> Vec<PuzzleGeneratedImageCandidateRecord> {
        self.into_iter()
            .map(GeneratedPuzzleImageCandidate::into_record)
            .collect()
    }
}

#[derive(Clone)]
struct PuzzleDownloadedImage {
    extension: String,
    mime_type: String,
    bytes: Vec<u8>,
}

struct ParsedPuzzleImageDataUrl {
    mime_type: String,
    bytes: Vec<u8>,
}

struct GeneratedPuzzleAssetResponse {
    image_src: String,
    asset_id: String,
}

struct GeneratedPuzzleUiBackgroundResponse {
    image_src: String,
    object_key: String,
}

fn resolve_puzzle_image_model(value: Option<&str>) -> PuzzleImageModel {
    match value.map(str::trim).filter(|value| !value.is_empty()) {
        Some(PUZZLE_IMAGE_MODEL_GEMINI_31_FLASH_PREVIEW) => {
            tracing::warn!(
                requested_model = PUZZLE_IMAGE_MODEL_GEMINI_31_FLASH_PREVIEW,
                effective_model = VECTOR_ENGINE_GPT_IMAGE_2_MODEL,
                "拼图 nanobanana2 历史选项已回落到 VectorEngine GPT-image-2-all"
            );
            PuzzleImageModel::Gemini31FlashPreview
        }
        _ => PuzzleImageModel::GptImage2,
    }
}

fn require_puzzle_vector_engine_settings(
    state: &AppState,
) -> Result<PuzzleVectorEngineSettings, AppError> {
    let base_url = state
        .config
        .vector_engine_base_url
        .trim()
        .trim_end_matches('/');
    if base_url.is_empty() {
        return Err(
            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
                "provider": VECTOR_ENGINE_PROVIDER,
                "message": "VectorEngine 图片生成地址未配置",
                "reason": "VECTOR_ENGINE_BASE_URL 未配置",
            })),
        );
    }

    let api_key = state
        .config
        .vector_engine_api_key
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
                "provider": VECTOR_ENGINE_PROVIDER,
                "message": "VectorEngine 图片生成密钥未配置",
                "reason": "VECTOR_ENGINE_API_KEY 未配置",
            }))
        })?;

    Ok(PuzzleVectorEngineSettings {
        base_url: base_url.to_string(),
        api_key: api_key.to_string(),
    })
}

fn build_puzzle_image_http_client(
    state: &AppState,
    image_model: PuzzleImageModel,
) -> Result<reqwest::Client, AppError> {
    let provider = image_model.provider_name();
    let request_timeout_ms = state.config.vector_engine_image_request_timeout_ms;

    reqwest::Client::builder()
        .timeout(Duration::from_millis(request_timeout_ms.max(1)))
        .build()
        .map_err(|error| {
            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
                "provider": provider,
                "message": format!("构造拼图图片生成 HTTP 客户端失败：{error}"),
            }))
        })
}

fn to_puzzle_generated_image_candidate(
    candidate: &PuzzleGeneratedImageCandidateRecord,
) -> PuzzleGeneratedImageCandidate {
    // SpacetimeDB 模块反序列化的是 module-puzzle 的持久化结构，必须保留 snake_case 字段名；HTTP 响应层再单独映射为 camelCase。
    PuzzleGeneratedImageCandidate {
        candidate_id: candidate.candidate_id.clone(),
        image_src: candidate.image_src.clone(),
        asset_id: candidate.asset_id.clone(),
        prompt: candidate.prompt.clone(),
        actual_prompt: candidate.actual_prompt.clone(),
        source_type: candidate.source_type.clone(),
        selected: candidate.selected,
    }
}

async fn create_puzzle_vector_engine_image_generation(
    http_client: &reqwest::Client,
    settings: &PuzzleVectorEngineSettings,
    image_model: PuzzleImageModel,
    prompt: &str,
    negative_prompt: &str,
    size: &str,
    candidate_count: u32,
) -> Result<PuzzleGeneratedImages, AppError> {
    let request_body = build_puzzle_vector_engine_image_request_body(
        image_model,
        prompt,
        negative_prompt,
        size,
        candidate_count,
    );
    let request_url = puzzle_vector_engine_images_generation_url(settings);
    let request_started_at = Instant::now();
    let response = http_client
        .post(request_url.as_str())
        .header(
            reqwest::header::AUTHORIZATION,
            format!("Bearer {}", settings.api_key),
        )
        .header(reqwest::header::ACCEPT, "application/json")
        .header(reqwest::header::CONTENT_TYPE, "application/json")
        .json(&request_body)
        .send()
        .await
        .map_err(|error| {
            map_puzzle_vector_engine_request_error(format!(
                "创建拼图 VectorEngine 图片生成任务失败：{error}"
            ))
        })?;
    let status = response.status();
    let upstream_elapsed_ms = request_started_at.elapsed().as_millis() as u64;
    tracing::info!(
        provider = VECTOR_ENGINE_PROVIDER,
        image_model = image_model.request_model_name(),
        endpoint = %request_url,
        status = status.as_u16(),
        prompt_chars = prompt.chars().count(),
        size,
        has_reference_image = false,
        elapsed_ms = upstream_elapsed_ms,
        "拼图 VectorEngine 图片生成 HTTP 返回"
    );
    let response_text = response.text().await.map_err(|error| {
        map_puzzle_vector_engine_request_error(format!(
            "读取拼图 VectorEngine 图片生成响应失败：{error}"
        ))
    })?;
    if !status.is_success() {
        return Err(map_puzzle_vector_engine_upstream_error(
            status,
            response_text.as_str(),
            "创建拼图 VectorEngine 图片生成任务失败",
        ));
    }

    let payload = parse_puzzle_json_payload(
        response_text.as_str(),
        "解析拼图 VectorEngine 图片生成响应失败",
    )?;
    let image_urls = extract_puzzle_image_urls(&payload);
    if !image_urls.is_empty() {
        let download_started_at = Instant::now();
        let images = download_puzzle_images_from_urls(
            http_client,
            format!("vector-engine-{}", current_utc_micros()),
            image_urls,
            candidate_count,
        )
        .await?;
        tracing::info!(
            provider = VECTOR_ENGINE_PROVIDER,
            image_model = image_model.request_model_name(),
            image_count = images.images.len(),
            elapsed_ms = download_started_at.elapsed().as_millis() as u64,
            "拼图 VectorEngine 图片下载完成"
        );
        return Ok(images);
    }

    Err(
        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": VECTOR_ENGINE_PROVIDER,
            "message": "拼图 VectorEngine 图片生成未返回图片地址",
        })),
    )
}

async fn create_puzzle_vector_engine_image_edit(
    http_client: &reqwest::Client,
    settings: &PuzzleVectorEngineSettings,
    prompt: &str,
    negative_prompt: &str,
    size: &str,
    candidate_count: u32,
    reference_image: &PuzzleResolvedReferenceImage,
) -> Result<PuzzleGeneratedImages, AppError> {
    let request_url = puzzle_vector_engine_images_edit_url(settings);
    let task_id = format!("vector-engine-edit-{}", current_utc_micros());
    let file_name = format!(
        "puzzle-reference.{}",
        puzzle_mime_to_extension(reference_image.mime_type.as_str())
    );
    let image_part = reqwest::multipart::Part::bytes(reference_image.bytes.clone())
        .file_name(file_name)
        .mime_str(reference_image.mime_type.as_str())
        .map_err(|error| {
            map_puzzle_vector_engine_request_error(format!(
                "构造拼图 VectorEngine 图片编辑参考图失败：{error}"
            ))
        })?;
    let form = reqwest::multipart::Form::new()
        .part("image", image_part)
        .text("model", PUZZLE_VECTOR_ENGINE_IMAGE_EDIT_MODEL.to_string())
        .text(
            "prompt",
            build_puzzle_vector_engine_prompt(prompt, negative_prompt),
        )
        .text("n", candidate_count.clamp(1, 1).to_string())
        .text("size", size.to_string());
    let request_started_at = Instant::now();
    let response = http_client
        .post(request_url.as_str())
        .header(
            reqwest::header::AUTHORIZATION,
            format!("Bearer {}", settings.api_key),
        )
        .header(reqwest::header::ACCEPT, "application/json")
        .multipart(form)
        .send()
        .await
        .map_err(|error| {
            map_puzzle_vector_engine_request_error(format!(
                "创建拼图 VectorEngine 图片编辑任务失败：{error}"
            ))
        })?;
    let status = response.status();
    tracing::info!(
        provider = VECTOR_ENGINE_PROVIDER,
        image_model = PUZZLE_VECTOR_ENGINE_IMAGE_EDIT_MODEL,
        endpoint = %request_url,
        status = status.as_u16(),
        prompt_chars = prompt.chars().count(),
        size,
        reference_mime = %reference_image.mime_type,
        reference_bytes = reference_image.bytes_len,
        elapsed_ms = request_started_at.elapsed().as_millis() as u64,
        "拼图 VectorEngine 图片编辑 HTTP 返回"
    );
    let response_text = response.text().await.map_err(|error| {
        map_puzzle_vector_engine_request_error(format!(
            "读取拼图 VectorEngine 图片编辑响应失败：{error}"
        ))
    })?;
    if !status.is_success() {
        return Err(map_puzzle_vector_engine_upstream_error(
            status,
            response_text.as_str(),
            "创建拼图 VectorEngine 图片编辑任务失败",
        ));
    }

    let payload = parse_puzzle_json_payload(
        response_text.as_str(),
        "解析拼图 VectorEngine 图片编辑响应失败",
    )?;
    let image_urls = extract_puzzle_image_urls(&payload);
    if !image_urls.is_empty() {
        return download_puzzle_images_from_urls(http_client, task_id, image_urls, candidate_count)
            .await;
    }
    let b64_images = extract_puzzle_b64_images(&payload);
    if !b64_images.is_empty() {
        return Ok(puzzle_images_from_base64(
            task_id,
            b64_images,
            candidate_count,
        ));
    }

    Err(
        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": VECTOR_ENGINE_PROVIDER,
            "message": "拼图 VectorEngine 图片编辑未返回图片",
        })),
    )
}

fn build_puzzle_vector_engine_image_request_body(
    image_model: PuzzleImageModel,
    prompt: &str,
    negative_prompt: &str,
    size: &str,
    candidate_count: u32,
) -> Value {
    Value::Object(Map::from_iter([
        (
            "model".to_string(),
            Value::String(image_model.request_model_name().to_string()),
        ),
        (
            "prompt".to_string(),
            Value::String(build_puzzle_vector_engine_prompt(prompt, negative_prompt)),
        ),
        ("n".to_string(), json!(candidate_count.clamp(1, 1))),
        ("size".to_string(), Value::String(size.to_string())),
    ]))
}

fn build_puzzle_vector_engine_generation_prompt(prompt: &str, has_reference_image: bool) -> String {
    let prompt = prompt.trim();
    if !has_reference_image {
        return prompt.to_string();
    }

    format!(
        concat!(
            "请以随请求提供的参考图作为第一优先级生成依据，严格保留参考图的主要主体、构图关系、视角、姿态、配色和光影氛围；",
            "允许按下面文字要求做风格化和细节增强，但不要改成与参考图无关的新画面。\n",
            "{prompt}"
        ),
        prompt = prompt,
    )
}

fn has_puzzle_reference_image(reference_image_src: Option<&str>) -> bool {
    reference_image_src
        .map(str::trim)
        .map(|value| !value.is_empty())
        .unwrap_or(false)
}

fn should_use_puzzle_reference_image_edit(
    reference_image_src: Option<&str>,
    use_reference_image_edit: bool,
) -> bool {
    use_reference_image_edit && has_puzzle_reference_image(reference_image_src)
}

fn build_puzzle_vector_engine_prompt(prompt: &str, negative_prompt: &str) -> String {
    let prompt = prompt.trim();
    let negative_prompt = negative_prompt.trim();
    if negative_prompt.is_empty() {
        return prompt.to_string();
    }

    format!("{prompt}\n避免：{negative_prompt}")
}

fn puzzle_vector_engine_images_generation_url(settings: &PuzzleVectorEngineSettings) -> String {
    if settings.base_url.ends_with("/v1") {
        format!("{}/images/generations", settings.base_url)
    } else {
        format!("{}/v1/images/generations", settings.base_url)
    }
}

fn puzzle_vector_engine_images_edit_url(settings: &PuzzleVectorEngineSettings) -> String {
    if settings.base_url.ends_with("/v1") {
        format!("{}/images/edits", settings.base_url)
    } else {
        format!("{}/v1/images/edits", settings.base_url)
    }
}

async fn download_puzzle_images_from_urls(
    http_client: &reqwest::Client,
    task_id: String,
    image_urls: Vec<String>,
    candidate_count: u32,
) -> Result<PuzzleGeneratedImages, AppError> {
    let mut images = Vec::with_capacity(candidate_count.clamp(1, 1) as usize);
    for image_url in image_urls
        .into_iter()
        .take(candidate_count.clamp(1, 1) as usize)
    {
        images.push(download_puzzle_remote_image(http_client, image_url.as_str()).await?);
    }
    Ok(PuzzleGeneratedImages { task_id, images })
}

async fn resolve_puzzle_reference_image_as_data_url(
    state: &AppState,
    http_client: &reqwest::Client,
    source: &str,
) -> Result<PuzzleResolvedReferenceImage, AppError> {
    let trimmed = source.trim();
    if trimmed.is_empty() {
        return Err(
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": "puzzle",
                "field": "referenceImageSrc",
                "message": "参考图不能为空。",
            })),
        );
    }

    if let Some(parsed) = parse_puzzle_image_data_url(trimmed) {
        let bytes_len = parsed.bytes.len();
        if bytes_len > PUZZLE_REFERENCE_IMAGE_MAX_BYTES {
            return Err(
                AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                    "provider": "puzzle",
                    "field": "referenceImageSrc",
                    "message": "参考图过大，请压缩后重试。",
                    "maxBytes": PUZZLE_REFERENCE_IMAGE_MAX_BYTES,
                    "actualBytes": bytes_len,
                })),
            );
        }
        return Ok(PuzzleResolvedReferenceImage {
            mime_type: parsed.mime_type,
            bytes_len,
            bytes: parsed.bytes,
        });
    }

    if !trimmed.starts_with('/') {
        return Err(
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": "puzzle",
                "field": "referenceImageSrc",
                "message": "参考图必须是 Data URL 或 /generated-* 旧路径。",
            })),
        );
    }

    let object_key = trimmed.trim_start_matches('/');
    if LegacyAssetPrefix::from_object_key(object_key).is_none() {
        return Err(
            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
                "provider": "puzzle",
                "field": "referenceImageSrc",
                "message": "参考图当前只支持 /generated-* 旧路径。",
            })),
        );
    }

    let oss_client = state.oss_client().ok_or_else(|| {
        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
            "provider": "aliyun-oss",
            "reason": "OSS 未完成环境变量配置",
        }))
    })?;
    let signed = oss_client
        .sign_get_object_url(OssSignedGetObjectUrlRequest {
            object_key: object_key.to_string(),
            expire_seconds: Some(60),
        })
        .map_err(map_puzzle_asset_oss_error)?;
    let response = http_client
        .get(signed.signed_url)
        .send()
        .await
        .map_err(|error| map_puzzle_image_request_error(format!("读取拼图参考图失败：{error}")))?;
    let status = response.status();
    let content_type = response
        .headers()
        .get(reqwest::header::CONTENT_TYPE)
        .and_then(|value| value.to_str().ok())
        .unwrap_or("image/png")
        .to_string();
    let body = response.bytes().await.map_err(|error| {
        map_puzzle_image_request_error(format!("读取拼图参考图内容失败：{error}"))
    })?;
    if !status.is_success() {
        return Err(
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": "aliyun-oss",
                "message": format!("读取参考图失败，状态码：{status}"),
                "objectKey": object_key,
            })),
        );
    }
    if body.is_empty() {
        return Err(
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": "aliyun-oss",
                "message": "读取参考图失败：对象内容为空",
                "objectKey": object_key,
            })),
        );
    }

    let mime_type = normalize_puzzle_downloaded_image_mime_type(content_type.as_str());
    let bytes_len = body.len();
    Ok(PuzzleResolvedReferenceImage {
        mime_type,
        bytes_len,
        bytes: body.to_vec(),
    })
}

async fn download_puzzle_remote_image(
    http_client: &reqwest::Client,
    image_url: &str,
) -> Result<PuzzleDownloadedImage, AppError> {
    let response = http_client.get(image_url).send().await.map_err(|error| {
        map_puzzle_image_request_error(format!("下载拼图正式图片失败：{error}"))
    })?;
    let status = response.status();
    let content_type = response
        .headers()
        .get(reqwest::header::CONTENT_TYPE)
        .and_then(|value| value.to_str().ok())
        .unwrap_or("image/jpeg")
        .to_string();
    let bytes = response.bytes().await.map_err(|error| {
        map_puzzle_image_request_error(format!("读取拼图正式图片内容失败：{error}"))
    })?;
    if !status.is_success() {
        return Err(
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": "puzzle-image",
                "message": "下载拼图正式图片失败",
                "status": status.as_u16(),
            })),
        );
    }
    let mime_type = normalize_puzzle_downloaded_image_mime_type(content_type.as_str());
    Ok(PuzzleDownloadedImage {
        extension: puzzle_mime_to_extension(mime_type.as_str()).to_string(),
        mime_type,
        bytes: bytes.to_vec(),
    })
}

async fn persist_puzzle_generated_asset(
    state: &AppState,
    owner_user_id: &str,
    session_id: &str,
    level_name: &str,
    candidate_id: &str,
    task_id: &str,
    image: PuzzleDownloadedImage,
    generated_at_micros: i64,
) -> Result<GeneratedPuzzleAssetResponse, AppError> {
    let oss_client = state.oss_client().ok_or_else(|| {
        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
            "provider": "aliyun-oss",
            "reason": "OSS 未完成环境变量配置",
        }))
    })?;
    let http_client = reqwest::Client::new();
    let asset_id = format!("asset-{generated_at_micros}");
    let put_result = oss_client
        .put_object(
            &http_client,
            OssPutObjectRequest {
                prefix: LegacyAssetPrefix::PuzzleAssets,
                path_segments: vec![
                    sanitize_path_segment(session_id, "session"),
                    sanitize_path_segment(level_name, "puzzle"),
                    sanitize_path_segment(candidate_id, "candidate"),
                    asset_id.clone(),
                ],
                file_name: format!("image.{}", image.extension),
                content_type: Some(image.mime_type.clone()),
                access: OssObjectAccess::Private,
                metadata: build_puzzle_asset_metadata(owner_user_id, session_id, candidate_id),
                body: image.bytes,
            },
        )
        .await
        .map_err(map_puzzle_asset_oss_error)?;
    let head = oss_client
        .head_object(
            &http_client,
            OssHeadObjectRequest {
                object_key: put_result.object_key.clone(),
            },
        )
        .await
        .map_err(map_puzzle_asset_oss_error)?;
    let asset_object = state
        .spacetime_client()
        .confirm_asset_object(
            build_asset_object_upsert_input(
                generate_asset_object_id(generated_at_micros),
                head.bucket,
                head.object_key,
                AssetObjectAccessPolicy::Private,
                head.content_type.or(Some(image.mime_type)),
                head.content_length,
                head.etag,
                "puzzle_cover_image".to_string(),
                Some(task_id.to_string()),
                Some(owner_user_id.to_string()),
                None,
                Some(session_id.to_string()),
                generated_at_micros,
            )
            .map_err(map_puzzle_asset_field_error)?,
        )
        .await;
    match asset_object {
        Ok(asset_object) => {
            if let Err(error) = state
                .spacetime_client()
                .bind_asset_object_to_entity(
                    build_asset_entity_binding_input(
                        generate_asset_binding_id(generated_at_micros),
                        asset_object.asset_object_id,
                        PUZZLE_ENTITY_KIND.to_string(),
                        session_id.to_string(),
                        candidate_id.to_string(),
                        "puzzle_cover_image".to_string(),
                        Some(owner_user_id.to_string()),
                        None,
                        generated_at_micros,
                    )
                    .map_err(map_puzzle_asset_field_error)?,
                )
                .await
            {
                handle_puzzle_asset_spacetime_index_error(
                    error,
                    owner_user_id,
                    session_id,
                    candidate_id,
                    "绑定拼图资产对象到实体",
                )?;
            }
        }
        Err(error) => handle_puzzle_asset_spacetime_index_error(
            error,
            owner_user_id,
            session_id,
            candidate_id,
            "确认拼图资产对象",
        )?,
    }

    Ok(GeneratedPuzzleAssetResponse {
        image_src: put_result.legacy_public_path,
        asset_id,
    })
}

async fn persist_puzzle_ui_background_image(
    state: &AppState,
    owner_user_id: &str,
    session_id: &str,
    level_name: &str,
    task_id: &str,
    image: DownloadedOpenAiImage,
) -> Result<GeneratedPuzzleUiBackgroundResponse, AppError> {
    let oss_client = state.oss_client().ok_or_else(|| {
        AppError::from_status(StatusCode::SERVICE_UNAVAILABLE).with_details(json!({
            "provider": "aliyun-oss",
            "reason": "OSS 未完成环境变量配置",
        }))
    })?;
    let http_client = reqwest::Client::new();
    let put_result = oss_client
        .put_object(
            &http_client,
            OssPutObjectRequest {
                prefix: LegacyAssetPrefix::PuzzleAssets,
                path_segments: vec![
                    sanitize_path_segment(session_id, "session"),
                    sanitize_path_segment(level_name, "puzzle"),
                    "ui-background".to_string(),
                    sanitize_path_segment(task_id, "task"),
                ],
                file_name: format!("background.{}", image.extension),
                content_type: Some(image.mime_type.clone()),
                access: OssObjectAccess::Private,
                metadata: build_puzzle_ui_background_asset_metadata(owner_user_id, session_id),
                body: image.bytes,
            },
        )
        .await
        .map_err(map_puzzle_asset_oss_error)?;
    Ok(GeneratedPuzzleUiBackgroundResponse {
        image_src: put_result.legacy_public_path,
        object_key: put_result.object_key,
    })
}

fn handle_puzzle_asset_spacetime_index_error(
    error: SpacetimeClientError,
    owner_user_id: &str,
    session_id: &str,
    candidate_id: &str,
    stage: &str,
) -> Result<(), AppError> {
    if should_skip_asset_operation_billing_for_connectivity(&error) {
        // 中文注释：OSS 已经持有真实图片，资产索引的 SpacetimeDB 短暂失败只影响历史检索，不应阻断本次生图展示。
        tracing::warn!(
            provider = "spacetimedb",
            owner_user_id,
            session_id,
            candidate_id,
            stage,
            error = %error,
            "拼图图片资产索引写入因 SpacetimeDB 连接不可用而降级跳过"
        );
        return Ok(());
    }

    Err(map_puzzle_asset_spacetime_error(error))
}

fn build_puzzle_asset_metadata(
    owner_user_id: &str,
    session_id: &str,
    candidate_id: &str,
) -> BTreeMap<String, String> {
    BTreeMap::from([
        ("asset_kind".to_string(), "puzzle_cover_image".to_string()),
        ("owner_user_id".to_string(), owner_user_id.to_string()),
        ("entity_kind".to_string(), PUZZLE_ENTITY_KIND.to_string()),
        ("entity_id".to_string(), session_id.to_string()),
        ("slot".to_string(), candidate_id.to_string()),
    ])
}

fn build_puzzle_ui_background_asset_metadata(
    owner_user_id: &str,
    session_id: &str,
) -> BTreeMap<String, String> {
    BTreeMap::from([
        (
            "asset_kind".to_string(),
            "puzzle_ui_background_image".to_string(),
        ),
        ("owner_user_id".to_string(), owner_user_id.to_string()),
        ("entity_kind".to_string(), PUZZLE_ENTITY_KIND.to_string()),
        ("entity_id".to_string(), session_id.to_string()),
        ("slot".to_string(), "ui_background".to_string()),
    ])
}

fn parse_puzzle_json_payload(raw_text: &str, fallback_message: &str) -> Result<Value, AppError> {
    serde_json::from_str::<Value>(raw_text).map_err(|error| {
        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": VECTOR_ENGINE_PROVIDER,
            "message": format!("{fallback_message}：{error}"),
        }))
    })
}

fn parse_puzzle_image_data_url(value: &str) -> Option<ParsedPuzzleImageDataUrl> {
    let body = value.strip_prefix("data:")?;
    let (mime_type, data) = body.split_once(";base64,")?;
    if !mime_type.starts_with("image/") {
        return None;
    }
    let bytes = decode_puzzle_base64(data)?;
    Some(ParsedPuzzleImageDataUrl {
        mime_type: mime_type.to_string(),
        bytes,
    })
}

fn decode_puzzle_base64(value: &str) -> Option<Vec<u8>> {
    let cleaned = value.trim().replace(char::is_whitespace, "");
    let mut output = Vec::with_capacity(cleaned.len() * 3 / 4);
    let mut buffer = 0u32;
    let mut bits = 0u8;

    for byte in cleaned.bytes() {
        let value = match byte {
            b'A'..=b'Z' => byte - b'A',
            b'a'..=b'z' => byte - b'a' + 26,
            b'0'..=b'9' => byte - b'0' + 52,
            b'+' => 62,
            b'/' => 63,
            b'=' => break,
            _ => return None,
        } as u32;
        buffer = (buffer << 6) | value;
        bits += 6;
        while bits >= 8 {
            bits -= 8;
            output.push(((buffer >> bits) & 0xFF) as u8);
        }
    }

    Some(output)
}

fn extract_puzzle_image_urls(payload: &Value) -> Vec<String> {
    let mut urls = Vec::new();
    collect_puzzle_strings_by_key(payload, "image", &mut urls);
    collect_puzzle_strings_by_key(payload, "url", &mut urls);
    let mut deduped = Vec::new();
    for url in urls {
        if !deduped.contains(&url) {
            deduped.push(url);
        }
    }
    deduped
}

fn extract_puzzle_b64_images(payload: &Value) -> Vec<String> {
    let mut values = Vec::new();
    collect_puzzle_strings_by_key(payload, "b64_json", &mut values);
    values
}

fn puzzle_images_from_base64(
    task_id: String,
    b64_images: Vec<String>,
    candidate_count: u32,
) -> PuzzleGeneratedImages {
    let images = b64_images
        .into_iter()
        .take(candidate_count.clamp(1, 1) as usize)
        .filter_map(|raw| decode_puzzle_generated_image_base64(raw.as_str()))
        .collect();

    PuzzleGeneratedImages { task_id, images }
}

fn decode_puzzle_generated_image_base64(raw: &str) -> Option<PuzzleDownloadedImage> {
    let bytes = BASE64_STANDARD.decode(raw.trim()).ok()?;
    let mime_type = infer_puzzle_image_mime_type(bytes.as_slice());
    Some(PuzzleDownloadedImage {
        extension: puzzle_mime_to_extension(mime_type.as_str()).to_string(),
        mime_type,
        bytes,
    })
}

fn find_first_puzzle_string_by_key(payload: &Value, target_key: &str) -> Option<String> {
    let mut results = Vec::new();
    collect_puzzle_strings_by_key(payload, target_key, &mut results);
    results.into_iter().next()
}

fn collect_puzzle_strings_by_key(payload: &Value, target_key: &str, results: &mut Vec<String>) {
    match payload {
        Value::Array(entries) => {
            for entry in entries {
                collect_puzzle_strings_by_key(entry, target_key, results);
            }
        }
        Value::Object(object) => {
            for (key, value) in object {
                if key == target_key {
                    collect_puzzle_string_values(value, results);
                }
                collect_puzzle_strings_by_key(value, target_key, results);
            }
        }
        _ => {}
    }
}

fn collect_puzzle_string_values(payload: &Value, results: &mut Vec<String>) {
    match payload {
        Value::String(text) => results.push(text.to_string()),
        Value::Array(items) => {
            for item in items {
                collect_puzzle_string_values(item, results);
            }
        }
        _ => {}
    }
}

fn infer_puzzle_image_mime_type(bytes: &[u8]) -> String {
    if bytes.starts_with(b"\x89PNG\r\n\x1A\n") {
        return "image/png".to_string();
    }
    if bytes.starts_with(b"\xFF\xD8\xFF") {
        return "image/jpeg".to_string();
    }
    if bytes.starts_with(b"RIFF") && bytes.get(8..12) == Some(b"WEBP") {
        return "image/webp".to_string();
    }
    if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
        return "image/gif".to_string();
    }
    "image/png".to_string()
}

fn normalize_puzzle_downloaded_image_mime_type(content_type: &str) -> String {
    let mime_type = content_type
        .split(';')
        .next()
        .map(str::trim)
        .unwrap_or("image/jpeg");
    match mime_type {
        "image/png" | "image/webp" | "image/jpeg" | "image/jpg" | "image/gif" => {
            mime_type.to_string()
        }
        _ => "image/jpeg".to_string(),
    }
}

fn puzzle_mime_to_extension(mime_type: &str) -> &str {
    match mime_type {
        "image/png" => "png",
        "image/webp" => "webp",
        "image/gif" => "gif",
        _ => "jpg",
    }
}

fn map_puzzle_image_request_error(message: String) -> AppError {
    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
        "provider": "puzzle-image",
        "message": message,
    }))
}

fn map_puzzle_vector_engine_request_error(message: String) -> AppError {
    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
        "provider": VECTOR_ENGINE_PROVIDER,
        "message": message,
    }))
}

fn map_puzzle_vector_engine_upstream_error(
    upstream_status: reqwest::StatusCode,
    raw_text: &str,
    fallback_message: &str,
) -> AppError {
    let message = parse_puzzle_api_error_message(raw_text, fallback_message);
    let raw_excerpt = trim_puzzle_upstream_excerpt(raw_text, 800);
    tracing::warn!(
        provider = VECTOR_ENGINE_PROVIDER,
        upstream_status = upstream_status.as_u16(),
        message = %message,
        raw_excerpt = %raw_excerpt,
        "拼图 VectorEngine 上游请求失败"
    );

    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
        "provider": VECTOR_ENGINE_PROVIDER,
        "upstreamStatus": upstream_status.as_u16(),
        "message": message,
        "rawExcerpt": raw_excerpt,
    }))
}

fn parse_puzzle_api_error_message(raw_text: &str, fallback_message: &str) -> String {
    let trimmed = raw_text.trim();
    if trimmed.is_empty() {
        return fallback_message.to_string();
    }
    if let Ok(payload) = serde_json::from_str::<Value>(trimmed)
        && let Some(message) = find_first_puzzle_string_by_key(&payload, "message")
    {
        return message;
    }
    fallback_message.to_string()
}

fn trim_puzzle_upstream_excerpt(raw_text: &str, max_chars: usize) -> String {
    let normalized = raw_text.split_whitespace().collect::<Vec<_>>().join(" ");
    if normalized.chars().count() <= max_chars {
        return normalized;
    }

    let keep_chars = max_chars.saturating_sub(3);
    format!(
        "{}...",
        normalized.chars().take(keep_chars).collect::<String>()
    )
}

fn map_puzzle_asset_oss_error(error: platform_oss::OssError) -> AppError {
    map_oss_error(error, "aliyun-oss")
}

fn map_puzzle_asset_spacetime_error(error: SpacetimeClientError) -> AppError {
    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
        "provider": "spacetimedb",
        "message": error.to_string(),
    }))
}

fn map_puzzle_asset_field_error(error: AssetObjectFieldError) -> AppError {
    AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR).with_details(json!({
        "provider": "asset-object",
        "message": error.to_string(),
    }))
}

fn sanitize_path_segment(value: &str, fallback: &str) -> String {
    let sanitized = value
        .trim()
        .chars()
        .map(|ch| {
            if ch.is_ascii_alphanumeric() || ('\u{4e00}'..='\u{9fff}').contains(&ch) {
                ch
            } else {
                '-'
            }
        })
        .collect::<String>()
        .trim_matches('-')
        .to_string();
    if sanitized.is_empty() {
        fallback.to_string()
    } else {
        sanitized
    }
}

fn current_utc_micros() -> i64 {
    let duration = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap_or_default();
    (duration.as_secs() as i64) * 1_000_000 + i64::from(duration.subsec_micros())
}