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 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, LlmTextRequest};
use platform_oss::{
    LegacyAssetPrefix, OssHeadObjectRequest, OssObjectAccess, OssPutObjectRequest,
    OssSignedGetObjectUrlRequest,
};
use serde_json::{Map, Value, json};
use shared_contracts::{
    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, 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,
    PuzzleCreatorIntentRecord, PuzzleDraftLevelRecord, PuzzleFormDraftRecord,
    PuzzleFormDraftSaveRecordInput, PuzzleGeneratedImageCandidateRecord,
    PuzzleGeneratedImagesSaveRecordInput, PuzzleLeaderboardEntryRecord,
    PuzzleLeaderboardSubmitRecordInput, PuzzlePublishRecordInput, PuzzleRecommendedNextWorkRecord,
    PuzzleResultDraftRecord, PuzzleResultPreviewBlockerRecord, PuzzleResultPreviewFindingRecord,
    PuzzleResultPreviewRecord, PuzzleRunDragRecordInput, PuzzleRunPauseRecordInput,
    PuzzleRunPropRecordInput, PuzzleRunRecord, PuzzleRunStartRecordInput, PuzzleRunSwapRecordInput,
    PuzzleSelectCoverImageRecordInput, PuzzleWorkLikeReportRecordInput,
    PuzzleWorkPointIncentiveClaimRecordInput, PuzzleWorkProfileRecord, PuzzleWorkRemixRecordInput,
    PuzzleWorkUpsertRecordInput, SpacetimeClientError,
};
use std::convert::Infallible;
use tokio::time::sleep;

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,
    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,
        },
        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,
    work_author::resolve_work_author_by_user_id,
};

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_APIMART_GENERATED_IMAGE_SIZE: &str = "1:1";
const PUZZLE_APIMART_GEMINI_RESOLUTION: &str = "1K";

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 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 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 = 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
            .map_err(|error| {
                puzzle_error_response(&request_context, PUZZLE_AGENT_API_BASE_PROVIDER, error)
            });
            (
                "compile_puzzle_draft",
                "首关拼图草稿",
                "已编译首关草稿、生成首关画面并写入正式草稿。",
                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 target_level =
                        select_puzzle_level_for_api(&draft, target_level_id.as_deref())?;
                    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.image_model.as_deref(),
                        candidate_count,
                        candidate_start_index,
                    )
                    .await
                    .map_err(map_puzzle_generation_endpoint_error)?;
                    let candidates_json = serde_json::to_string(
                        &candidates
                            .iter()
                            .map(to_puzzle_generated_image_candidate)
                            .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,
                            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) =>
                        {
                            // 中文注释：APIMart/OSS 已生成真实图片时，Maincloud 短暂 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(
                                fallback_session,
                                target_level.level_id.as_str(),
                                candidates,
                                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_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,
            level_id: payload.level_id,
            started_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 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,
        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_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,
        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,
        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,
            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,
                "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,
                "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)
}

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_name(
    draft: &PuzzleResultDraftRecord,
    target_level: &PuzzleDraftLevelRecord,
) -> 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
}

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 levels_json_with_generated_name = Some(serialize_puzzle_level_records_for_module(
        &build_puzzle_levels_with_primary_name(&draft, &target_level),
    )?);
    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,
        image_model,
        1,
        target_level.candidates.len(),
    )
    .await?;
    let selected_candidate_id = candidates
        .iter()
        .find(|candidate| candidate.selected)
        .or_else(|| candidates.first())
        .map(|candidate| candidate.candidate_id.clone())
        .ok_or_else(|| {
            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
                "message": "拼图候选图生成结果为空",
            }))
        })?;
    let candidates_json = serde_json::to_string(
        &candidates
            .iter()
            .map(to_puzzle_generated_image_candidate)
            .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,
            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 时，Maincloud 短暂不可用先返回本地快照，避免整次 APIMart 生图被判失败。
                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_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,
                    ),
                    target_level.level_id.as_str(),
                    candidates.clone(),
                    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)),
    }
}

fn apply_generated_puzzle_candidates_to_session_snapshot(
    mut session: PuzzleAgentSessionRecord,
    target_level_id: &str,
    candidates: Vec<PuzzleGeneratedImageCandidateRecord>,
    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());
    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_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
}

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,
                "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();
    let provider = if message.contains("APIMart")
        || message.contains("apimart")
        || message.contains("APIMART")
    {
        "apimart"
    } else if message.contains("OSS") || message.contains("oss") || message.contains("参考图") {
        "puzzle-assets"
    } else {
        "spacetimedb"
    };
    let status = if provider == "apimart"
        && (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("APIMart")
            || message.contains("apimart")
            || message.contains("APIMART")
            || 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,
        }
    };

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

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>,
    image_model: Option<&str>,
    candidate_count: u32,
    candidate_start_index: usize,
) -> Result<Vec<PuzzleGeneratedImageCandidateRecord>, AppError> {
    let count = candidate_count.clamp(1, 1);
    let resolved_model = resolve_puzzle_image_model(image_model);
    let actual_prompt = build_puzzle_image_prompt(level_name, prompt);
    let http_client = build_puzzle_image_http_client(state, resolved_model)?;
    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 = reference_image_src
            .map(str::trim)
            .map(|value| !value.is_empty())
            .unwrap_or(false),
        "拼图图片生成请求已准备"
    );
    let reference_image = match reference_image_src
        .map(str::trim)
        .filter(|value| !value.is_empty())
    {
        Some(source) => {
            Some(resolve_puzzle_reference_image_as_data_url(state, &http_client, source).await?)
        }
        None => None,
    };
    // 中文注释：SpacetimeDB reducer 不能做外部 I/O，参考图读取与外部生图都必须停留在 api-server。
    // 中文注释：拼图作品资产统一按 1:1 正方形生成，前端运行时也按正方形棋盘切块承载。
    let settings = require_puzzle_apimart_settings(state)?;
    let generated = create_puzzle_apimart_image_generation(
        &http_client,
        &settings,
        resolved_model,
        actual_prompt.as_str(),
        PUZZLE_DEFAULT_NEGATIVE_PROMPT,
        PUZZLE_APIMART_GENERATED_IMAGE_SIZE,
        count,
        reference_image.as_deref(),
    )
    .await
    .map_err(map_puzzle_generation_endpoint_error)?;
    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 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)?;
        items.push(PuzzleGeneratedImageCandidateResponse {
            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,
        });
    }

    Ok(items
        .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())
}

#[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_APIMART_GENERATED_IMAGE_SIZE, "1:1");
    }

    #[test]
    fn puzzle_apimart_request_uses_selected_model_and_reference_images() {
        let body = build_puzzle_apimart_image_request_body(
            PuzzleImageModel::Gemini31FlashPreview,
            "一只猫在雨夜灯牌下回头。",
            PUZZLE_DEFAULT_NEGATIVE_PROMPT,
            PUZZLE_APIMART_GENERATED_IMAGE_SIZE,
            4,
            Some("data:image/png;base64,abcd"),
        );

        assert_eq!(body["model"], PUZZLE_IMAGE_MODEL_GEMINI_31_FLASH_PREVIEW);
        assert_eq!(body["size"], PUZZLE_APIMART_GENERATED_IMAGE_SIZE);
        assert_eq!(body["resolution"], PUZZLE_APIMART_GEMINI_RESOLUTION);
        assert_eq!(body["n"], 1);
        assert_eq!(body["image_urls"][0], "data:image/png;base64,abcd");
        assert!(
            body["prompt"]
                .as_str()
                .unwrap_or_default()
                .contains("文字水印")
        );
    }

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

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

    #[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()),
            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_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()),
            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 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 {
        "apimart"
    }

    fn request_model_name(self) -> &'static str {
        match self {
            Self::GptImage2 => PUZZLE_IMAGE_MODEL_GPT_IMAGE_2,
            Self::Gemini31FlashPreview => PUZZLE_IMAGE_MODEL_GEMINI_31_FLASH_PREVIEW,
        }
    }

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

struct PuzzleApimartSettings {
    base_url: String,
    api_key: String,
    request_timeout_ms: u64,
}

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

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,
}

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) => PuzzleImageModel::Gemini31FlashPreview,
        _ => PuzzleImageModel::GptImage2,
    }
}

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

    let api_key = state
        .config
        .apimart_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": "apimart",
                "message": "APIMart 图片生成密钥未配置",
                "reason": "APIMART_API_KEY 未配置",
            }))
        })?;

    Ok(PuzzleApimartSettings {
        base_url: base_url.to_string(),
        api_key: api_key.to_string(),
        request_timeout_ms: state.config.apimart_image_request_timeout_ms.max(1),
    })
}

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.apimart_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_apimart_image_generation(
    http_client: &reqwest::Client,
    settings: &PuzzleApimartSettings,
    image_model: PuzzleImageModel,
    prompt: &str,
    negative_prompt: &str,
    size: &str,
    candidate_count: u32,
    reference_image: Option<&str>,
) -> Result<PuzzleGeneratedImages, AppError> {
    let request_body = build_puzzle_apimart_image_request_body(
        image_model,
        prompt,
        negative_prompt,
        size,
        candidate_count,
        reference_image,
    );
    let response = http_client
        .post(format!("{}/images/generations", settings.base_url))
        .header(
            reqwest::header::AUTHORIZATION,
            format!("Bearer {}", settings.api_key),
        )
        .header(reqwest::header::CONTENT_TYPE, "application/json")
        .json(&request_body)
        .send()
        .await
        .map_err(|error| {
            map_puzzle_apimart_request_error(format!("创建拼图 APIMart 图片生成任务失败：{error}"))
        })?;
    let status = response.status();
    let response_text = response.text().await.map_err(|error| {
        map_puzzle_apimart_request_error(format!("读取拼图 APIMart 图片生成响应失败：{error}"))
    })?;
    if !status.is_success() {
        return Err(map_puzzle_apimart_upstream_error(
            status,
            response_text.as_str(),
            "创建拼图 APIMart 图片生成任务失败",
        ));
    }

    let payload =
        parse_puzzle_json_payload(response_text.as_str(), "解析拼图 APIMart 图片生成响应失败")?;
    let image_urls = extract_puzzle_image_urls(&payload);
    if !image_urls.is_empty() {
        return download_puzzle_images_from_urls(
            http_client,
            format!("apimart-{}", current_utc_micros()),
            image_urls,
            candidate_count,
        )
        .await;
    }

    let task_id = extract_puzzle_task_id(&payload).ok_or_else(|| {
        AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
            "provider": "apimart",
            "message": "拼图 APIMart 图片生成未返回 task_id 或图片地址",
        }))
    })?;

    wait_puzzle_apimart_generated_images(
        http_client,
        settings,
        task_id.as_str(),
        candidate_count,
        "拼图 APIMart 图片生成任务失败",
    )
    .await
}

fn build_puzzle_apimart_image_request_body(
    image_model: PuzzleImageModel,
    prompt: &str,
    negative_prompt: &str,
    size: &str,
    candidate_count: u32,
    reference_image: Option<&str>,
) -> Value {
    let mut body = Map::from_iter([
        (
            "model".to_string(),
            Value::String(image_model.request_model_name().to_string()),
        ),
        (
            "prompt".to_string(),
            Value::String(build_puzzle_apimart_prompt(prompt, negative_prompt)),
        ),
        ("n".to_string(), json!(candidate_count.clamp(1, 1))),
        ("size".to_string(), Value::String(size.to_string())),
    ]);
    body.insert(
        "resolution".to_string(),
        Value::String(
            match image_model {
                PuzzleImageModel::Gemini31FlashPreview => PUZZLE_APIMART_GEMINI_RESOLUTION,
                _ => "1k",
            }
            .to_string(),
        ),
    );

    if let Some(reference_image) = reference_image
        .map(str::trim)
        .filter(|value| !value.is_empty())
    {
        body.insert("image_urls".to_string(), json!([reference_image]));
    }

    Value::Object(body)
}

fn build_puzzle_apimart_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}")
}

async fn wait_puzzle_apimart_generated_images(
    http_client: &reqwest::Client,
    settings: &PuzzleApimartSettings,
    task_id: &str,
    candidate_count: u32,
    failure_message: &str,
) -> Result<PuzzleGeneratedImages, AppError> {
    let deadline = Instant::now() + Duration::from_millis(settings.request_timeout_ms);
    sleep(Duration::from_secs(10)).await;

    while Instant::now() < deadline {
        let poll_response = http_client
            .get(format!("{}/tasks/{}", settings.base_url, task_id))
            .header(
                reqwest::header::AUTHORIZATION,
                format!("Bearer {}", settings.api_key),
            )
            .send()
            .await
            .map_err(|error| {
                map_puzzle_apimart_request_error(format!(
                    "查询拼图 APIMart 图片生成任务失败：{error}"
                ))
            })?;
        let poll_status = poll_response.status();
        let poll_text = poll_response.text().await.map_err(|error| {
            map_puzzle_apimart_request_error(format!(
                "读取拼图 APIMart 图片生成任务响应失败：{error}"
            ))
        })?;
        if !poll_status.is_success() {
            return Err(map_puzzle_apimart_upstream_error(
                poll_status,
                poll_text.as_str(),
                "查询拼图 APIMart 图片生成任务失败",
            ));
        }

        let poll_payload =
            parse_puzzle_json_payload(poll_text.as_str(), "解析拼图 APIMart 图片生成任务响应失败")?;
        let task_status = find_first_puzzle_string_by_key(&poll_payload, "status")
            .unwrap_or_default()
            .trim()
            .to_ascii_lowercase();
        if matches!(task_status.as_str(), "completed" | "succeeded" | "success") {
            let image_urls = extract_puzzle_image_urls(&poll_payload);
            if image_urls.is_empty() {
                return Err(
                    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
                        "provider": "apimart",
                        "message": "拼图 APIMart 图片生成成功但未返回图片地址",
                    })),
                );
            }

            return download_puzzle_images_from_urls(
                http_client,
                task_id.to_string(),
                image_urls,
                candidate_count,
            )
            .await;
        }
        if matches!(
            task_status.as_str(),
            "failed" | "error" | "canceled" | "cancelled"
        ) {
            return Err(map_puzzle_apimart_upstream_error(
                poll_status,
                poll_text.as_str(),
                failure_message,
            ));
        }
        sleep(Duration::from_secs(3)).await;
    }

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

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<String, 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) {
        return Ok(format!(
            "data:{};base64,{}",
            parsed.mime_type,
            BASE64_STANDARD.encode(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,
            })),
        );
    }

    Ok(format!(
        "data:{};base64,{}",
        content_type,
        BASE64_STANDARD.encode(body)
    ))
}

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,
    })
}

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 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": "apimart",
            "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_task_id(payload: &Value) -> Option<String> {
    find_first_puzzle_string_by_key(payload, "task_id")
}

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 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 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_apimart_request_error(message: String) -> AppError {
    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
        "provider": "apimart",
        "message": message,
    }))
}

fn map_puzzle_apimart_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 = "apimart",
        upstream_status = upstream_status.as_u16(),
        message = %message,
        raw_excerpt = %raw_excerpt,
        "拼图 APIMart 上游请求失败"
    );

    AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
        "provider": "apimart",
        "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())
}