Genarrative/server-rs/crates/spacetime-module/src/puzzle.rs

use module_puzzle::{
    PUZZLE_MAX_TAG_COUNT, PuzzleAgentMessageFinalizeInput, PuzzleAgentMessageKind,
    PuzzleAgentMessageRole, PuzzleAgentMessageSnapshot, PuzzleAgentSessionCreateInput,
    PuzzleAgentSessionGetInput, PuzzleAgentSessionProcedureResult, PuzzleAgentSessionSnapshot,
    PuzzleAgentStage, PuzzleAnchorPack, PuzzleDraftCompileInput, PuzzleGeneratedImageCandidate,
    PuzzleGeneratedImagesSaveInput, PuzzlePublicationStatus, PuzzlePublishInput, PuzzleResultDraft,
    PuzzleRunDragInput, PuzzleRunGetInput, PuzzleRunNextLevelInput, PuzzleRunProcedureResult,
    PuzzleRunSnapshot, PuzzleRunStartInput, PuzzleRunSwapInput, PuzzleRuntimeLevelStatus,
    PuzzleSelectCoverImageInput, PuzzleWorkDeleteInput, PuzzleWorkGetInput,
    PuzzleWorkProcedureResult, PuzzleWorkProfile, PuzzleWorkUpsertInput, PuzzleWorksListInput,
    PuzzleWorksProcedureResult, apply_publish_overrides_to_draft, apply_selected_candidate,
    build_result_preview, compile_result_draft, create_work_profile, infer_anchor_pack,
    normalize_theme_tags, publish_work_profile, resolve_puzzle_grid_size, select_next_profile,
    start_run, swap_pieces,
};
use serde_json::from_str as json_from_str;
use serde_json::to_string as json_to_string;
use spacetimedb::{ProcedureContext, Table, Timestamp, TxContext};

/// 拼图 Agent session 真相表。
/// 当前只保存结构化字段与 JSON 草稿，不提前拆出更多编辑态子表。
#[spacetimedb::table(
    accessor = puzzle_agent_session,
    index(accessor = by_puzzle_agent_session_owner_user_id, btree(columns = [owner_user_id]))
)]
pub struct PuzzleAgentSessionRow {
    #[primary_key]
    session_id: String,
    owner_user_id: String,
    seed_text: String,
    current_turn: u32,
    progress_percent: u32,
    stage: PuzzleAgentStage,
    anchor_pack_json: String,
    draft_json: Option<String>,
    last_assistant_reply: Option<String>,
    published_profile_id: Option<String>,
    created_at: Timestamp,
    updated_at: Timestamp,
}

/// 拼图 Agent 消息真相表。
#[spacetimedb::table(
    accessor = puzzle_agent_message,
    index(accessor = by_puzzle_agent_message_session_id, btree(columns = [session_id]))
)]
pub struct PuzzleAgentMessageRow {
    #[primary_key]
    message_id: String,
    session_id: String,
    role: PuzzleAgentMessageRole,
    kind: PuzzleAgentMessageKind,
    text: String,
    created_at: Timestamp,
}

/// 已发布与草稿作品统一作品表。
#[spacetimedb::table(
    accessor = puzzle_work_profile,
    index(accessor = by_puzzle_work_owner_user_id, btree(columns = [owner_user_id])),
    index(accessor = by_puzzle_work_publication_status, btree(columns = [publication_status]))
)]
pub struct PuzzleWorkProfileRow {
    #[primary_key]
    profile_id: String,
    work_id: String,
    owner_user_id: String,
    source_session_id: Option<String>,
    author_display_name: String,
    level_name: String,
    summary: String,
    theme_tags_json: String,
    cover_image_src: Option<String>,
    cover_asset_id: Option<String>,
    publication_status: PuzzlePublicationStatus,
    play_count: u32,
    anchor_pack_json: String,
    publish_ready: bool,
    created_at: Timestamp,
    updated_at: Timestamp,
    published_at: Option<Timestamp>,
}

/// 运行态 run 快照表。
#[spacetimedb::table(
    accessor = puzzle_runtime_run,
    index(accessor = by_puzzle_runtime_run_owner_user_id, btree(columns = [owner_user_id]))
)]
pub struct PuzzleRuntimeRunRow {
    #[primary_key]
    run_id: String,
    owner_user_id: String,
    entry_profile_id: String,
    current_profile_id: String,
    cleared_level_count: u32,
    current_level_index: u32,
    current_grid_size: u32,
    played_profile_ids_json: String,
    previous_level_tags_json: String,
    snapshot_json: String,
    created_at: Timestamp,
    updated_at: Timestamp,
}

#[spacetimedb::procedure]
pub fn create_puzzle_agent_session(
    ctx: &mut ProcedureContext,
    input: PuzzleAgentSessionCreateInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| create_puzzle_agent_session_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn get_puzzle_agent_session(
    ctx: &mut ProcedureContext,
    input: PuzzleAgentSessionGetInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| get_puzzle_agent_session_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn submit_puzzle_agent_message(
    ctx: &mut ProcedureContext,
    input: module_puzzle::PuzzleAgentMessageSubmitInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| submit_puzzle_agent_message_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn finalize_puzzle_agent_message_turn(
    ctx: &mut ProcedureContext,
    input: PuzzleAgentMessageFinalizeInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| finalize_puzzle_agent_message_turn_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn compile_puzzle_agent_draft(
    ctx: &mut ProcedureContext,
    input: PuzzleDraftCompileInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| compile_puzzle_agent_draft_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn save_puzzle_generated_images(
    ctx: &mut ProcedureContext,
    input: PuzzleGeneratedImagesSaveInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| save_puzzle_generated_images_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn select_puzzle_cover_image(
    ctx: &mut ProcedureContext,
    input: PuzzleSelectCoverImageInput,
) -> PuzzleAgentSessionProcedureResult {
    match ctx.try_with_tx(|tx| select_puzzle_cover_image_tx(tx, input.clone())) {
        Ok(session) => PuzzleAgentSessionProcedureResult {
            ok: true,
            session_json: Some(serialize_json(&session)),
            error_message: None,
        },
        Err(message) => PuzzleAgentSessionProcedureResult {
            ok: false,
            session_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn publish_puzzle_work(
    ctx: &mut ProcedureContext,
    input: PuzzlePublishInput,
) -> PuzzleWorkProcedureResult {
    match ctx.try_with_tx(|tx| publish_puzzle_work_tx(tx, input.clone())) {
        Ok(item) => PuzzleWorkProcedureResult {
            ok: true,
            item_json: Some(serialize_json(&item)),
            error_message: None,
        },
        Err(message) => PuzzleWorkProcedureResult {
            ok: false,
            item_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn list_puzzle_works(
    ctx: &mut ProcedureContext,
    input: PuzzleWorksListInput,
) -> PuzzleWorksProcedureResult {
    match ctx.try_with_tx(|tx| list_puzzle_works_tx(tx, input.clone())) {
        Ok(items) => PuzzleWorksProcedureResult {
            ok: true,
            items_json: Some(serialize_json(&items)),
            error_message: None,
        },
        Err(message) => PuzzleWorksProcedureResult {
            ok: false,
            items_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn get_puzzle_work_detail(
    ctx: &mut ProcedureContext,
    input: PuzzleWorkGetInput,
) -> PuzzleWorkProcedureResult {
    match ctx.try_with_tx(|tx| get_puzzle_work_detail_tx(tx, input.clone())) {
        Ok(item) => PuzzleWorkProcedureResult {
            ok: true,
            item_json: Some(serialize_json(&item)),
            error_message: None,
        },
        Err(message) => PuzzleWorkProcedureResult {
            ok: false,
            item_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn update_puzzle_work(
    ctx: &mut ProcedureContext,
    input: PuzzleWorkUpsertInput,
) -> PuzzleWorkProcedureResult {
    match ctx.try_with_tx(|tx| update_puzzle_work_tx(tx, input.clone())) {
        Ok(item) => PuzzleWorkProcedureResult {
            ok: true,
            item_json: Some(serialize_json(&item)),
            error_message: None,
        },
        Err(message) => PuzzleWorkProcedureResult {
            ok: false,
            item_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn delete_puzzle_work(
    ctx: &mut ProcedureContext,
    input: PuzzleWorkDeleteInput,
) -> PuzzleWorksProcedureResult {
    match ctx.try_with_tx(|tx| delete_puzzle_work_tx(tx, input.clone())) {
        Ok(items) => PuzzleWorksProcedureResult {
            ok: true,
            items_json: Some(serialize_json(&items)),
            error_message: None,
        },
        Err(message) => PuzzleWorksProcedureResult {
            ok: false,
            items_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn list_puzzle_gallery(ctx: &mut ProcedureContext) -> PuzzleWorksProcedureResult {
    match ctx.try_with_tx(|tx| list_puzzle_gallery_tx(tx)) {
        Ok(items) => PuzzleWorksProcedureResult {
            ok: true,
            items_json: Some(serialize_json(&items)),
            error_message: None,
        },
        Err(message) => PuzzleWorksProcedureResult {
            ok: false,
            items_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn get_puzzle_gallery_detail(
    ctx: &mut ProcedureContext,
    input: PuzzleWorkGetInput,
) -> PuzzleWorkProcedureResult {
    match ctx.try_with_tx(|tx| get_puzzle_gallery_detail_tx(tx, input.clone())) {
        Ok(item) => PuzzleWorkProcedureResult {
            ok: true,
            item_json: Some(serialize_json(&item)),
            error_message: None,
        },
        Err(message) => PuzzleWorkProcedureResult {
            ok: false,
            item_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn start_puzzle_run(
    ctx: &mut ProcedureContext,
    input: PuzzleRunStartInput,
) -> PuzzleRunProcedureResult {
    match ctx.try_with_tx(|tx| start_puzzle_run_tx(tx, input.clone())) {
        Ok(run) => PuzzleRunProcedureResult {
            ok: true,
            run_json: Some(serialize_json(&run)),
            error_message: None,
        },
        Err(message) => PuzzleRunProcedureResult {
            ok: false,
            run_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn get_puzzle_run(
    ctx: &mut ProcedureContext,
    input: PuzzleRunGetInput,
) -> PuzzleRunProcedureResult {
    match ctx.try_with_tx(|tx| get_puzzle_run_tx(tx, input.clone())) {
        Ok(run) => PuzzleRunProcedureResult {
            ok: true,
            run_json: Some(serialize_json(&run)),
            error_message: None,
        },
        Err(message) => PuzzleRunProcedureResult {
            ok: false,
            run_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn swap_puzzle_pieces(
    ctx: &mut ProcedureContext,
    input: PuzzleRunSwapInput,
) -> PuzzleRunProcedureResult {
    match ctx.try_with_tx(|tx| swap_puzzle_pieces_tx(tx, input.clone())) {
        Ok(run) => PuzzleRunProcedureResult {
            ok: true,
            run_json: Some(serialize_json(&run)),
            error_message: None,
        },
        Err(message) => PuzzleRunProcedureResult {
            ok: false,
            run_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn drag_puzzle_piece_or_group(
    ctx: &mut ProcedureContext,
    input: PuzzleRunDragInput,
) -> PuzzleRunProcedureResult {
    match ctx.try_with_tx(|tx| drag_puzzle_piece_or_group_tx(tx, input.clone())) {
        Ok(run) => PuzzleRunProcedureResult {
            ok: true,
            run_json: Some(serialize_json(&run)),
            error_message: None,
        },
        Err(message) => PuzzleRunProcedureResult {
            ok: false,
            run_json: None,
            error_message: Some(message),
        },
    }
}

#[spacetimedb::procedure]
pub fn advance_puzzle_next_level(
    ctx: &mut ProcedureContext,
    input: PuzzleRunNextLevelInput,
) -> PuzzleRunProcedureResult {
    match ctx.try_with_tx(|tx| advance_puzzle_next_level_tx(tx, input.clone())) {
        Ok(run) => PuzzleRunProcedureResult {
            ok: true,
            run_json: Some(serialize_json(&run)),
            error_message: None,
        },
        Err(message) => PuzzleRunProcedureResult {
            ok: false,
            run_json: None,
            error_message: Some(message),
        },
    }
}

fn create_puzzle_agent_session_tx(
    ctx: &TxContext,
    input: PuzzleAgentSessionCreateInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    ensure_session_missing(ctx, &input.session_id)?;
    ensure_message_missing(ctx, &input.welcome_message_id)?;
    let created_at = Timestamp::from_micros_since_unix_epoch(input.created_at_micros);
    let anchor_pack = infer_anchor_pack(&input.seed_text, Some(&input.seed_text));
    ctx.db.puzzle_agent_session().insert(PuzzleAgentSessionRow {
        session_id: input.session_id.clone(),
        owner_user_id: input.owner_user_id.clone(),
        seed_text: input.seed_text.clone(),
        current_turn: 1,
        progress_percent: 18,
        stage: PuzzleAgentStage::CollectingAnchors,
        anchor_pack_json: serialize_json(&anchor_pack),
        draft_json: None,
        last_assistant_reply: Some(input.welcome_message_text.clone()),
        published_profile_id: None,
        created_at,
        updated_at: created_at,
    });
    ctx.db.puzzle_agent_message().insert(PuzzleAgentMessageRow {
        message_id: input.welcome_message_id,
        session_id: input.session_id.clone(),
        role: PuzzleAgentMessageRole::Assistant,
        kind: PuzzleAgentMessageKind::Chat,
        text: input.welcome_message_text,
        created_at,
    });
    get_puzzle_agent_session_tx(
        ctx,
        PuzzleAgentSessionGetInput {
            session_id: input.session_id,
            owner_user_id: input.owner_user_id,
        },
    )
}

fn get_puzzle_agent_session_tx(
    ctx: &TxContext,
    input: PuzzleAgentSessionGetInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    let row = get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    build_puzzle_agent_session_snapshot(ctx, &row)
}

fn submit_puzzle_agent_message_tx(
    ctx: &TxContext,
    input: module_puzzle::PuzzleAgentMessageSubmitInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    ensure_message_missing(ctx, &input.user_message_id)?;
    let submitted_at = Timestamp::from_micros_since_unix_epoch(input.submitted_at_micros);

    ctx.db.puzzle_agent_message().insert(PuzzleAgentMessageRow {
        message_id: input.user_message_id.clone(),
        session_id: input.session_id.clone(),
        role: PuzzleAgentMessageRole::User,
        kind: PuzzleAgentMessageKind::Chat,
        text: input.user_message_text.clone(),
        created_at: submitted_at,
    });

    get_puzzle_agent_session_tx(
        ctx,
        PuzzleAgentSessionGetInput {
            session_id: input.session_id,
            owner_user_id: input.owner_user_id,
        },
    )
}

fn finalize_puzzle_agent_message_turn_tx(
    ctx: &TxContext,
    input: PuzzleAgentMessageFinalizeInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    let row = get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    let updated_at = Timestamp::from_micros_since_unix_epoch(input.updated_at_micros);

    if let Some(error_message) = input
        .error_message
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
    {
        replace_puzzle_agent_session(
            ctx,
            &row,
            PuzzleAgentSessionRow {
                session_id: row.session_id.clone(),
                owner_user_id: row.owner_user_id.clone(),
                seed_text: row.seed_text.clone(),
                current_turn: row.current_turn,
                progress_percent: row.progress_percent,
                stage: row.stage,
                anchor_pack_json: row.anchor_pack_json.clone(),
                draft_json: row.draft_json.clone(),
                last_assistant_reply: row.last_assistant_reply.clone(),
                published_profile_id: row.published_profile_id.clone(),
                created_at: row.created_at,
                updated_at,
            },
        );
        return Err(error_message.to_string());
    }

    let assistant_message_id = input
        .assistant_message_id
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .ok_or_else(|| "拼图 assistant_message_id 不能为空".to_string())?
        .to_string();
    let assistant_reply_text = input
        .assistant_reply_text
        .as_deref()
        .map(str::trim)
        .filter(|value| !value.is_empty())
        .ok_or_else(|| "拼图 assistant_reply_text 不能为空".to_string())?
        .to_string();
    ensure_message_missing(ctx, &assistant_message_id)?;
    let next_anchor_pack = deserialize_anchor_pack(&input.anchor_pack_json)?;

    ctx.db.puzzle_agent_message().insert(PuzzleAgentMessageRow {
        message_id: assistant_message_id,
        session_id: input.session_id.clone(),
        role: PuzzleAgentMessageRole::Assistant,
        kind: PuzzleAgentMessageKind::Chat,
        text: assistant_reply_text.clone(),
        created_at: updated_at,
    });
    replace_puzzle_agent_session(
        ctx,
        &row,
        PuzzleAgentSessionRow {
            session_id: row.session_id.clone(),
            owner_user_id: row.owner_user_id.clone(),
            seed_text: row.seed_text.clone(),
            current_turn: row.current_turn.saturating_add(1),
            progress_percent: input.progress_percent.min(100),
            stage: input.stage,
            anchor_pack_json: serialize_json(&next_anchor_pack),
            draft_json: row.draft_json.clone(),
            last_assistant_reply: Some(assistant_reply_text),
            published_profile_id: row.published_profile_id.clone(),
            created_at: row.created_at,
            updated_at,
        },
    );

    get_puzzle_agent_session_tx(
        ctx,
        PuzzleAgentSessionGetInput {
            session_id: input.session_id,
            owner_user_id: input.owner_user_id,
        },
    )
}

fn compile_puzzle_agent_draft_tx(
    ctx: &TxContext,
    input: PuzzleDraftCompileInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    let row = get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    let anchor_pack = deserialize_anchor_pack(&row.anchor_pack_json)?;
    let messages = list_session_messages(ctx, &row.session_id);
    let draft = compile_result_draft(&anchor_pack, &messages);
    // 创作中心的拼图草稿卡只是 Agent session 的列表投影，
    // 每次编译结果页时同步 upsert，保证后续能按 source_session_id 恢复聊天。
    upsert_puzzle_draft_work_profile(
        ctx,
        &row.session_id,
        &row.owner_user_id,
        &draft,
        input.compiled_at_micros,
    )?;
    let compiled_at = Timestamp::from_micros_since_unix_epoch(input.compiled_at_micros);
    replace_puzzle_agent_session(
        ctx,
        &row,
        PuzzleAgentSessionRow {
            session_id: row.session_id.clone(),
            owner_user_id: row.owner_user_id.clone(),
            seed_text: row.seed_text.clone(),
            current_turn: row.current_turn,
            progress_percent: 88,
            stage: PuzzleAgentStage::DraftReady,
            anchor_pack_json: serialize_json(&anchor_pack),
            draft_json: Some(serialize_json(&draft)),
            last_assistant_reply: Some(
                "拼图结果页草稿已经生成，可以开始出图并确认标签。".to_string(),
            ),
            published_profile_id: row.published_profile_id.clone(),
            created_at: row.created_at,
            updated_at: compiled_at,
        },
    );
    append_system_message(
        ctx,
        &row.session_id,
        input.compiled_at_micros,
        "拼图结果页草稿已生成。",
    )?;
    get_puzzle_agent_session_tx(
        ctx,
        PuzzleAgentSessionGetInput {
            session_id: input.session_id,
            owner_user_id: input.owner_user_id,
        },
    )
}

fn save_puzzle_generated_images_tx(
    ctx: &TxContext,
    input: PuzzleGeneratedImagesSaveInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    let row = get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    let mut draft = deserialize_draft_required(&row.draft_json)?;
    let candidates: Vec<PuzzleGeneratedImageCandidate> = json_from_str(&input.candidates_json)
        .map_err(|error| format!("拼图候选图 JSON 非法: {error}"))?;
    if candidates.is_empty() {
        return Err("拼图候选图不能为空".to_string());
    }
    append_generated_candidates(&mut draft, candidates);
    draft.generation_status = "ready".to_string();
    if let Some(selected) = draft
        .candidates
        .iter()
        .find(|entry| entry.selected)
        .cloned()
    {
        draft.selected_candidate_id = Some(selected.candidate_id);
        draft.cover_image_src = Some(selected.image_src);
        draft.cover_asset_id = Some(selected.asset_id);
    }

    let saved_at = Timestamp::from_micros_since_unix_epoch(input.saved_at_micros);
    let next_stage = if build_result_preview(&draft, Some("创作者")).publish_ready {
        PuzzleAgentStage::ReadyToPublish
    } else {
        PuzzleAgentStage::ImageRefining
    };
    // 结果页草稿封面和候选图发生变化后，草稿卡需要同步刷新。
    upsert_puzzle_draft_work_profile(
        ctx,
        &row.session_id,
        &row.owner_user_id,
        &draft,
        input.saved_at_micros,
    )?;
    replace_puzzle_agent_session(
        ctx,
        &row,
        PuzzleAgentSessionRow {
            session_id: row.session_id.clone(),
            owner_user_id: row.owner_user_id.clone(),
            seed_text: row.seed_text.clone(),
            current_turn: row.current_turn,
            progress_percent: 94,
            stage: next_stage,
            anchor_pack_json: row.anchor_pack_json.clone(),
            draft_json: Some(serialize_json(&draft)),
            last_assistant_reply: Some("候选图已经生成，请选择正式拼图图片。".to_string()),
            published_profile_id: row.published_profile_id.clone(),
            created_at: row.created_at,
            updated_at: saved_at,
        },
    );
    get_puzzle_agent_session_tx(
        ctx,
        PuzzleAgentSessionGetInput {
            session_id: input.session_id,
            owner_user_id: input.owner_user_id,
        },
    )
}

fn select_puzzle_cover_image_tx(
    ctx: &TxContext,
    input: PuzzleSelectCoverImageInput,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    let row = get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    let draft = deserialize_draft_required(&row.draft_json)?;
    let draft =
        apply_selected_candidate(draft, &input.candidate_id).map_err(|error| error.to_string())?;
    let selected_at = Timestamp::from_micros_since_unix_epoch(input.selected_at_micros);
    let next_stage = if build_result_preview(&draft, Some("创作者")).publish_ready {
        PuzzleAgentStage::ReadyToPublish
    } else {
        PuzzleAgentStage::ImageRefining
    };
    // 选定正式封面后，创作中心草稿卡要立即反映最新正式图。
    upsert_puzzle_draft_work_profile(
        ctx,
        &row.session_id,
        &row.owner_user_id,
        &draft,
        input.selected_at_micros,
    )?;
    replace_puzzle_agent_session(
        ctx,
        &row,
        PuzzleAgentSessionRow {
            session_id: row.session_id.clone(),
            owner_user_id: row.owner_user_id.clone(),
            seed_text: row.seed_text.clone(),
            current_turn: row.current_turn,
            progress_percent: 96,
            stage: next_stage,
            anchor_pack_json: row.anchor_pack_json.clone(),
            draft_json: Some(serialize_json(&draft)),
            last_assistant_reply: Some("正式拼图图片已确定，可以准备发布。".to_string()),
            published_profile_id: row.published_profile_id.clone(),
            created_at: row.created_at,
            updated_at: selected_at,
        },
    );
    get_puzzle_agent_session_tx(
        ctx,
        PuzzleAgentSessionGetInput {
            session_id: input.session_id,
            owner_user_id: input.owner_user_id,
        },
    )
}

fn publish_puzzle_work_tx(
    ctx: &TxContext,
    input: PuzzlePublishInput,
) -> Result<PuzzleWorkProfile, String> {
    let row = get_owned_session_row(ctx, &input.session_id, &input.owner_user_id)?;
    let draft = deserialize_draft_required(&row.draft_json)?;
    let draft = apply_publish_overrides_to_draft(
        &draft,
        input.level_name.clone(),
        input.summary.clone(),
        input.theme_tags.clone(),
    )
    .map_err(|error| error.to_string())?;
    let (work_id, profile_id) = build_puzzle_work_ids_from_session_id(&input.session_id);
    let mut profile = create_work_profile(
        work_id,
        profile_id,
        input.owner_user_id.clone(),
        Some(input.session_id.clone()),
        input.author_display_name.clone(),
        &draft,
        input.published_at_micros,
    )
    .map_err(|error| error.to_string())?;
    profile = publish_work_profile(profile, &draft, input.published_at_micros)
        .map_err(|error| error.to_string())?;

    upsert_puzzle_work_profile(ctx, profile.clone())?;
    replace_puzzle_agent_session(
        ctx,
        &row,
        PuzzleAgentSessionRow {
            session_id: row.session_id.clone(),
            owner_user_id: row.owner_user_id.clone(),
            seed_text: row.seed_text.clone(),
            current_turn: row.current_turn,
            progress_percent: 100,
            stage: PuzzleAgentStage::Published,
            anchor_pack_json: row.anchor_pack_json.clone(),
            draft_json: Some(serialize_json(&draft)),
            last_assistant_reply: Some("拼图作品已经发布到广场。".to_string()),
            published_profile_id: Some(profile.profile_id.clone()),
            created_at: row.created_at,
            updated_at: Timestamp::from_micros_since_unix_epoch(input.published_at_micros),
        },
    );

    Ok(profile)
}

fn list_puzzle_works_tx(
    ctx: &TxContext,
    input: PuzzleWorksListInput,
) -> Result<Vec<PuzzleWorkProfile>, String> {
    let mut items = ctx
        .db
        .puzzle_work_profile()
        .iter()
        .filter(|row| row.owner_user_id == input.owner_user_id)
        .map(|row| build_puzzle_work_profile_from_row(&row))
        .collect::<Result<Vec<_>, _>>()?;
    items.sort_by(|left, right| right.updated_at_micros.cmp(&left.updated_at_micros));
    Ok(items)
}

fn get_puzzle_work_detail_tx(
    ctx: &TxContext,
    input: PuzzleWorkGetInput,
) -> Result<PuzzleWorkProfile, String> {
    let row = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&input.profile_id)
        .ok_or_else(|| "拼图作品不存在".to_string())?;
    build_puzzle_work_profile_from_row(&row)
}

fn update_puzzle_work_tx(
    ctx: &TxContext,
    input: PuzzleWorkUpsertInput,
) -> Result<PuzzleWorkProfile, String> {
    let row = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&input.profile_id)
        .ok_or_else(|| "拼图作品不存在".to_string())?;
    if row.owner_user_id != input.owner_user_id {
        return Err("无权修改该拼图作品".to_string());
    }
    let theme_tags = normalize_theme_tags(input.theme_tags);
    if theme_tags.is_empty() || theme_tags.len() > PUZZLE_MAX_TAG_COUNT {
        return Err("拼图标签数量不合法".to_string());
    }
    let next_row = PuzzleWorkProfileRow {
        profile_id: row.profile_id.clone(),
        work_id: row.work_id.clone(),
        owner_user_id: row.owner_user_id.clone(),
        source_session_id: row.source_session_id.clone(),
        author_display_name: row.author_display_name.clone(),
        level_name: input.level_name,
        summary: input.summary,
        theme_tags_json: serialize_json(&theme_tags),
        cover_image_src: input.cover_image_src,
        cover_asset_id: input.cover_asset_id,
        publication_status: row.publication_status,
        play_count: row.play_count,
        anchor_pack_json: row.anchor_pack_json.clone(),
        publish_ready: row.publish_ready,
        created_at: row.created_at,
        updated_at: Timestamp::from_micros_since_unix_epoch(input.updated_at_micros),
        published_at: row.published_at,
    };
    replace_puzzle_work_profile(ctx, &row, next_row);
    get_puzzle_work_detail_tx(
        ctx,
        PuzzleWorkGetInput {
            profile_id: input.profile_id,
        },
    )
}

fn delete_puzzle_work_tx(
    ctx: &TxContext,
    input: PuzzleWorkDeleteInput,
) -> Result<Vec<PuzzleWorkProfile>, String> {
    let row = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&input.profile_id)
        .ok_or_else(|| "拼图作品不存在".to_string())?;
    if row.owner_user_id != input.owner_user_id {
        return Err("无权删除该拼图作品".to_string());
    }

    // 删除作品时同步清理来源 Agent 会话和运行快照，保持创作页列表与运行态数据一致。
    ctx.db
        .puzzle_work_profile()
        .profile_id()
        .delete(&row.profile_id);
    if let Some(session_id) = row.source_session_id.as_ref() {
        if let Some(session) = ctx.db.puzzle_agent_session().session_id().find(session_id) {
            ctx.db
                .puzzle_agent_session()
                .session_id()
                .delete(&session.session_id);
        }
        for message in ctx
            .db
            .puzzle_agent_message()
            .iter()
            .filter(|message| message.session_id == *session_id)
            .collect::<Vec<_>>()
        {
            ctx.db
                .puzzle_agent_message()
                .message_id()
                .delete(&message.message_id);
        }
    }
    for run in ctx
        .db
        .puzzle_runtime_run()
        .iter()
        .filter(|run| {
            run.owner_user_id == input.owner_user_id && run.entry_profile_id == input.profile_id
        })
        .collect::<Vec<_>>()
    {
        ctx.db.puzzle_runtime_run().run_id().delete(&run.run_id);
    }

    list_puzzle_works_tx(
        ctx,
        PuzzleWorksListInput {
            owner_user_id: input.owner_user_id,
        },
    )
}

fn list_puzzle_gallery_tx(ctx: &TxContext) -> Result<Vec<PuzzleWorkProfile>, String> {
    let mut items = ctx
        .db
        .puzzle_work_profile()
        .iter()
        .filter(|row| row.publication_status == PuzzlePublicationStatus::Published)
        .map(|row| build_puzzle_work_profile_from_row(&row))
        .collect::<Result<Vec<_>, _>>()?;
    items.sort_by(|left, right| right.updated_at_micros.cmp(&left.updated_at_micros));
    Ok(items)
}

fn get_puzzle_gallery_detail_tx(
    ctx: &TxContext,
    input: PuzzleWorkGetInput,
) -> Result<PuzzleWorkProfile, String> {
    let row = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&input.profile_id)
        .ok_or_else(|| "拼图作品不存在".to_string())?;
    if row.publication_status != PuzzlePublicationStatus::Published {
        return Err("拼图作品尚未发布".to_string());
    }
    build_puzzle_work_profile_from_row(&row)
}

fn start_puzzle_run_tx(
    ctx: &TxContext,
    input: PuzzleRunStartInput,
) -> Result<PuzzleRunSnapshot, String> {
    if ctx
        .db
        .puzzle_runtime_run()
        .run_id()
        .find(&input.run_id)
        .is_some()
    {
        return Err("拼图 run 已存在".to_string());
    }
    let entry_profile_row = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&input.profile_id)
        .ok_or_else(|| "入口拼图作品不存在".to_string())?;
    if entry_profile_row.publication_status != PuzzlePublicationStatus::Published {
        return Err("入口拼图作品未发布".to_string());
    }
    let entry_profile = build_puzzle_work_profile_from_row(&entry_profile_row)?;
    let mut run =
        start_run(input.run_id.clone(), &entry_profile, 0).map_err(|error| error.to_string())?;
    run.recommended_next_profile_id = select_next_profile(
        &entry_profile,
        &run.played_profile_ids,
        &list_published_puzzle_profiles(ctx)?,
    )
    .map(|value| value.profile_id.clone());

    increment_puzzle_profile_play_count(ctx, &entry_profile_row, input.started_at_micros);
    insert_puzzle_runtime_run(ctx, &run, &input.owner_user_id, input.started_at_micros)?;
    Ok(run)
}

fn get_puzzle_run_tx(
    ctx: &TxContext,
    input: PuzzleRunGetInput,
) -> Result<PuzzleRunSnapshot, String> {
    let row = get_owned_run_row(ctx, &input.run_id, &input.owner_user_id)?;
    deserialize_run(&row.snapshot_json)
}

fn swap_puzzle_pieces_tx(
    ctx: &TxContext,
    input: PuzzleRunSwapInput,
) -> Result<PuzzleRunSnapshot, String> {
    let row = get_owned_run_row(ctx, &input.run_id, &input.owner_user_id)?;
    let current_run = deserialize_run(&row.snapshot_json)?;
    let mut next_run = swap_pieces(&current_run, &input.first_piece_id, &input.second_piece_id)
        .map_err(|error| error.to_string())?;
    refresh_next_profile_recommendation(ctx, &mut next_run)?;
    replace_puzzle_runtime_run(ctx, &row, &next_run, input.swapped_at_micros);
    Ok(next_run)
}

fn drag_puzzle_piece_or_group_tx(
    ctx: &TxContext,
    input: PuzzleRunDragInput,
) -> Result<PuzzleRunSnapshot, String> {
    let row = get_owned_run_row(ctx, &input.run_id, &input.owner_user_id)?;
    let current_run = deserialize_run(&row.snapshot_json)?;
    let mut next_run = module_puzzle::drag_piece_or_group(
        &current_run,
        &input.piece_id,
        input.target_row,
        input.target_col,
    )
    .map_err(|error| error.to_string())?;
    refresh_next_profile_recommendation(ctx, &mut next_run)?;
    replace_puzzle_runtime_run(ctx, &row, &next_run, input.dragged_at_micros);
    Ok(next_run)
}

fn advance_puzzle_next_level_tx(
    ctx: &TxContext,
    input: PuzzleRunNextLevelInput,
) -> Result<PuzzleRunSnapshot, String> {
    let row = get_owned_run_row(ctx, &input.run_id, &input.owner_user_id)?;
    let current_run = deserialize_run(&row.snapshot_json)?;
    let current_level = current_run
        .current_level
        .as_ref()
        .ok_or_else(|| "拼图关卡不存在".to_string())?;
    if current_level.status != PuzzleRuntimeLevelStatus::Cleared {
        return Err("当前关卡尚未通关".to_string());
    }
    let current_profile = build_puzzle_work_profile_from_row(
        &ctx.db
            .puzzle_work_profile()
            .profile_id()
            .find(&current_level.profile_id)
            .ok_or_else(|| "当前拼图作品不存在".to_string())?,
    )?;
    let candidates = list_published_puzzle_profiles(ctx)?;
    let next_profile = select_next_profile(
        &current_profile,
        &current_run.played_profile_ids,
        &candidates,
    )
    .ok_or_else(|| "没有可用的下一关候选".to_string())?
    .clone();
    let mut next_run = module_puzzle::advance_next_level(&current_run, &next_profile)
        .map_err(|error| error.to_string())?;
    next_run.recommended_next_profile_id =
        select_next_profile(&next_profile, &next_run.played_profile_ids, &candidates)
            .map(|value| value.profile_id.clone());

    if let Some(next_profile_row) = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&next_profile.profile_id)
    {
        increment_puzzle_profile_play_count(ctx, &next_profile_row, input.advanced_at_micros);
    }
    replace_puzzle_runtime_run(ctx, &row, &next_run, input.advanced_at_micros);
    Ok(next_run)
}

fn build_puzzle_agent_session_snapshot(
    ctx: &TxContext,
    row: &PuzzleAgentSessionRow,
) -> Result<PuzzleAgentSessionSnapshot, String> {
    let anchor_pack = deserialize_anchor_pack(&row.anchor_pack_json)?;
    let draft = deserialize_optional_draft(&row.draft_json)?;
    let messages = list_session_messages(ctx, &row.session_id);
    let result_preview = draft
        .as_ref()
        .map(|value| build_result_preview(value, Some("创作者")));

    Ok(PuzzleAgentSessionSnapshot {
        session_id: row.session_id.clone(),
        owner_user_id: row.owner_user_id.clone(),
        seed_text: row.seed_text.clone(),
        current_turn: row.current_turn,
        progress_percent: row.progress_percent,
        stage: row.stage,
        anchor_pack,
        draft,
        messages,
        last_assistant_reply: row.last_assistant_reply.clone(),
        published_profile_id: row.published_profile_id.clone(),
        suggested_actions: build_puzzle_suggested_actions(row.stage),
        result_preview,
        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
    })
}

fn build_puzzle_work_profile_from_row(
    row: &PuzzleWorkProfileRow,
) -> Result<PuzzleWorkProfile, String> {
    Ok(PuzzleWorkProfile {
        work_id: row.work_id.clone(),
        profile_id: row.profile_id.clone(),
        owner_user_id: row.owner_user_id.clone(),
        source_session_id: row.source_session_id.clone(),
        author_display_name: row.author_display_name.clone(),
        level_name: row.level_name.clone(),
        summary: row.summary.clone(),
        theme_tags: deserialize_theme_tags(&row.theme_tags_json)?,
        cover_image_src: row.cover_image_src.clone(),
        cover_asset_id: row.cover_asset_id.clone(),
        publication_status: row.publication_status,
        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
        published_at_micros: row
            .published_at
            .map(|value| value.to_micros_since_unix_epoch()),
        play_count: row.play_count,
        publish_ready: row.publish_ready,
        anchor_pack: deserialize_anchor_pack(&row.anchor_pack_json)?,
    })
}

fn build_puzzle_work_ids_from_session_id(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}"),
    )
}

fn upsert_puzzle_draft_work_profile(
    ctx: &TxContext,
    session_id: &str,
    owner_user_id: &str,
    draft: &PuzzleResultDraft,
    updated_at_micros: i64,
) -> Result<(), String> {
    let (work_id, profile_id) = build_puzzle_work_ids_from_session_id(session_id);
    if let Some(existing) = ctx.db.puzzle_work_profile().profile_id().find(&profile_id) {
        if existing.publication_status == PuzzlePublicationStatus::Published {
            return Ok(());
        }
    }
    let profile = create_work_profile(
        work_id,
        profile_id,
        owner_user_id.to_string(),
        Some(session_id.to_string()),
        "创作者".to_string(),
        draft,
        updated_at_micros,
    )
    .map_err(|error| error.to_string())?;
    upsert_puzzle_work_profile(ctx, profile)
}

fn list_session_messages(ctx: &TxContext, session_id: &str) -> Vec<PuzzleAgentMessageSnapshot> {
    let mut items = ctx
        .db
        .puzzle_agent_message()
        .iter()
        .filter(|message| message.session_id == session_id)
        .map(|message| PuzzleAgentMessageSnapshot {
            message_id: message.message_id.clone(),
            session_id: message.session_id.clone(),
            role: message.role,
            kind: message.kind,
            text: message.text.clone(),
            created_at_micros: message.created_at.to_micros_since_unix_epoch(),
        })
        .collect::<Vec<_>>();
    items.sort_by(|left, right| left.created_at_micros.cmp(&right.created_at_micros));
    items
}

fn build_puzzle_suggested_actions(
    stage: PuzzleAgentStage,
) -> Vec<module_puzzle::PuzzleAgentSuggestedAction> {
    match stage {
        PuzzleAgentStage::CollectingAnchors => vec![module_puzzle::PuzzleAgentSuggestedAction {
            id: "compile-draft".to_string(),
            action_type: "compile_puzzle_draft".to_string(),
            label: "进入结果页".to_string(),
        }],
        PuzzleAgentStage::DraftReady | PuzzleAgentStage::ImageRefining => vec![
            module_puzzle::PuzzleAgentSuggestedAction {
                id: "generate-images".to_string(),
                action_type: "generate_puzzle_images".to_string(),
                label: "生成候选图".to_string(),
            },
            module_puzzle::PuzzleAgentSuggestedAction {
                id: "publish-work".to_string(),
                action_type: "publish_puzzle_work".to_string(),
                label: "发布作品".to_string(),
            },
        ],
        PuzzleAgentStage::ReadyToPublish => vec![module_puzzle::PuzzleAgentSuggestedAction {
            id: "publish-work".to_string(),
            action_type: "publish_puzzle_work".to_string(),
            label: "发布作品".to_string(),
        }],
        PuzzleAgentStage::Published => Vec::new(),
    }
}

fn append_system_message(
    ctx: &TxContext,
    session_id: &str,
    created_at_micros: i64,
    text: &str,
) -> Result<(), String> {
    let message_id = format!("{session_id}-system-{created_at_micros}");
    ensure_message_missing(ctx, &message_id)?;
    ctx.db.puzzle_agent_message().insert(PuzzleAgentMessageRow {
        message_id,
        session_id: session_id.to_string(),
        role: PuzzleAgentMessageRole::Assistant,
        kind: PuzzleAgentMessageKind::ActionResult,
        text: text.to_string(),
        created_at: Timestamp::from_micros_since_unix_epoch(created_at_micros),
    });
    Ok(())
}

fn ensure_session_missing(ctx: &TxContext, session_id: &str) -> Result<(), String> {
    if ctx
        .db
        .puzzle_agent_session()
        .session_id()
        .find(&session_id.to_string())
        .is_some()
    {
        return Err("拼图 session 已存在".to_string());
    }
    Ok(())
}

fn ensure_message_missing(ctx: &TxContext, message_id: &str) -> Result<(), String> {
    if ctx
        .db
        .puzzle_agent_message()
        .message_id()
        .find(&message_id.to_string())
        .is_some()
    {
        return Err("拼图消息已存在".to_string());
    }
    Ok(())
}

fn get_owned_session_row(
    ctx: &TxContext,
    session_id: &str,
    owner_user_id: &str,
) -> Result<PuzzleAgentSessionRow, String> {
    let row = ctx
        .db
        .puzzle_agent_session()
        .session_id()
        .find(&session_id.to_string())
        .ok_or_else(|| "拼图 session 不存在".to_string())?;
    if row.owner_user_id != owner_user_id {
        return Err("无权访问该拼图 session".to_string());
    }
    Ok(row)
}

fn get_owned_run_row(
    ctx: &TxContext,
    run_id: &str,
    owner_user_id: &str,
) -> Result<PuzzleRuntimeRunRow, String> {
    let row = ctx
        .db
        .puzzle_runtime_run()
        .run_id()
        .find(&run_id.to_string())
        .ok_or_else(|| "拼图 run 不存在".to_string())?;
    if row.owner_user_id != owner_user_id {
        return Err("无权访问该拼图 run".to_string());
    }
    Ok(row)
}

fn replace_puzzle_agent_session(
    ctx: &TxContext,
    current: &PuzzleAgentSessionRow,
    next: PuzzleAgentSessionRow,
) {
    ctx.db
        .puzzle_agent_session()
        .session_id()
        .delete(&current.session_id);
    ctx.db.puzzle_agent_session().insert(next);
}

fn replace_puzzle_work_profile(
    ctx: &TxContext,
    current: &PuzzleWorkProfileRow,
    next: PuzzleWorkProfileRow,
) {
    ctx.db
        .puzzle_work_profile()
        .profile_id()
        .delete(&current.profile_id);
    ctx.db.puzzle_work_profile().insert(next);
}

fn upsert_puzzle_work_profile(ctx: &TxContext, profile: PuzzleWorkProfile) -> Result<(), String> {
    if let Some(existing) = ctx
        .db
        .puzzle_work_profile()
        .profile_id()
        .find(&profile.profile_id)
    {
        replace_puzzle_work_profile(
            ctx,
            &existing,
            PuzzleWorkProfileRow {
                profile_id: profile.profile_id,
                work_id: profile.work_id,
                owner_user_id: profile.owner_user_id,
                source_session_id: profile.source_session_id,
                author_display_name: profile.author_display_name,
                level_name: profile.level_name,
                summary: profile.summary,
                theme_tags_json: serialize_json(&profile.theme_tags),
                cover_image_src: profile.cover_image_src,
                cover_asset_id: profile.cover_asset_id,
                publication_status: profile.publication_status,
                // 二次编辑发布同一个 profile 时，作品内容可以覆盖，但历史游玩数属于
                // 广场消费数据，不能因为重新发布被清零。
                play_count: existing.play_count.max(profile.play_count),
                anchor_pack_json: serialize_json(&profile.anchor_pack),
                publish_ready: profile.publish_ready,
                created_at: existing.created_at,
                updated_at: Timestamp::from_micros_since_unix_epoch(profile.updated_at_micros),
                published_at: profile
                    .published_at_micros
                    .map(Timestamp::from_micros_since_unix_epoch),
            },
        );
        return Ok(());
    }

    ctx.db.puzzle_work_profile().insert(PuzzleWorkProfileRow {
        profile_id: profile.profile_id,
        work_id: profile.work_id,
        owner_user_id: profile.owner_user_id,
        source_session_id: profile.source_session_id,
        author_display_name: profile.author_display_name,
        level_name: profile.level_name,
        summary: profile.summary,
        theme_tags_json: serialize_json(&profile.theme_tags),
        cover_image_src: profile.cover_image_src,
        cover_asset_id: profile.cover_asset_id,
        publication_status: profile.publication_status,
        play_count: profile.play_count,
        anchor_pack_json: serialize_json(&profile.anchor_pack),
        publish_ready: profile.publish_ready,
        created_at: Timestamp::from_micros_since_unix_epoch(profile.updated_at_micros),
        updated_at: Timestamp::from_micros_since_unix_epoch(profile.updated_at_micros),
        published_at: profile
            .published_at_micros
            .map(Timestamp::from_micros_since_unix_epoch),
    });
    Ok(())
}

fn insert_puzzle_runtime_run(
    ctx: &TxContext,
    run: &PuzzleRunSnapshot,
    owner_user_id: &str,
    created_at_micros: i64,
) -> Result<(), String> {
    let timestamp = Timestamp::from_micros_since_unix_epoch(created_at_micros);
    let current_profile_id = run
        .current_level
        .as_ref()
        .map(|level| level.profile_id.clone())
        .ok_or_else(|| "拼图关卡不存在".to_string())?;
    ctx.db.puzzle_runtime_run().insert(PuzzleRuntimeRunRow {
        run_id: run.run_id.clone(),
        owner_user_id: owner_user_id.to_string(),
        entry_profile_id: run.entry_profile_id.clone(),
        current_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_json: serialize_json(&run.played_profile_ids),
        previous_level_tags_json: serialize_json(&run.previous_level_tags),
        snapshot_json: serialize_json(run),
        created_at: timestamp,
        updated_at: timestamp,
    });
    Ok(())
}

fn replace_puzzle_runtime_run(
    ctx: &TxContext,
    current: &PuzzleRuntimeRunRow,
    run: &PuzzleRunSnapshot,
    updated_at_micros: i64,
) {
    ctx.db.puzzle_runtime_run().run_id().delete(&current.run_id);
    ctx.db.puzzle_runtime_run().insert(PuzzleRuntimeRunRow {
        run_id: run.run_id.clone(),
        owner_user_id: current.owner_user_id.clone(),
        entry_profile_id: run.entry_profile_id.clone(),
        current_profile_id: run
            .current_level
            .as_ref()
            .map(|level| level.profile_id.clone())
            .unwrap_or_else(|| current.current_profile_id.clone()),
        cleared_level_count: run.cleared_level_count,
        current_level_index: run.current_level_index,
        current_grid_size: resolve_puzzle_grid_size(run.cleared_level_count),
        played_profile_ids_json: serialize_json(&run.played_profile_ids),
        previous_level_tags_json: serialize_json(&run.previous_level_tags),
        snapshot_json: serialize_json(run),
        created_at: current.created_at,
        updated_at: Timestamp::from_micros_since_unix_epoch(updated_at_micros),
    });
}

fn increment_puzzle_profile_play_count(
    ctx: &TxContext,
    row: &PuzzleWorkProfileRow,
    updated_at_micros: i64,
) {
    replace_puzzle_work_profile(
        ctx,
        row,
        PuzzleWorkProfileRow {
            profile_id: row.profile_id.clone(),
            work_id: row.work_id.clone(),
            owner_user_id: row.owner_user_id.clone(),
            source_session_id: row.source_session_id.clone(),
            author_display_name: row.author_display_name.clone(),
            level_name: row.level_name.clone(),
            summary: row.summary.clone(),
            theme_tags_json: row.theme_tags_json.clone(),
            cover_image_src: row.cover_image_src.clone(),
            cover_asset_id: row.cover_asset_id.clone(),
            publication_status: row.publication_status,
            play_count: row.play_count.saturating_add(1),
            anchor_pack_json: row.anchor_pack_json.clone(),
            publish_ready: row.publish_ready,
            created_at: row.created_at,
            updated_at: Timestamp::from_micros_since_unix_epoch(updated_at_micros),
            published_at: row.published_at,
        },
    );
}

fn append_generated_candidates(
    draft: &mut PuzzleResultDraft,
    candidates: Vec<PuzzleGeneratedImageCandidate>,
) {
    let has_selected_candidate = draft.candidates.iter().any(|entry| entry.selected);
    // 再次生成图片是扩充候选池，不覆盖创作者已经看到或已经选择的候选图。
    // 若已有正式选择，新追加候选图保持未选中，避免同一草稿出现多个 selected。
    draft
        .candidates
        .extend(candidates.into_iter().map(|mut candidate| {
            if has_selected_candidate {
                candidate.selected = false;
            }
            candidate
        }));
}

fn list_published_puzzle_profiles(ctx: &TxContext) -> Result<Vec<PuzzleWorkProfile>, String> {
    ctx.db
        .puzzle_work_profile()
        .iter()
        .filter(|row| row.publication_status == PuzzlePublicationStatus::Published)
        .map(|row| build_puzzle_work_profile_from_row(&row))
        .collect()
}

fn refresh_next_profile_recommendation(
    ctx: &TxContext,
    run: &mut PuzzleRunSnapshot,
) -> Result<(), String> {
    let current_level = match run.current_level.as_ref() {
        Some(value) => value,
        None => {
            run.recommended_next_profile_id = None;
            return Ok(());
        }
    };
    let current_profile = build_puzzle_work_profile_from_row(
        &ctx.db
            .puzzle_work_profile()
            .profile_id()
            .find(&current_level.profile_id)
            .ok_or_else(|| "当前拼图作品不存在".to_string())?,
    )?;
    run.recommended_next_profile_id = select_next_profile(
        &current_profile,
        &run.played_profile_ids,
        &list_published_puzzle_profiles(ctx)?,
    )
    .map(|value| value.profile_id.clone());
    Ok(())
}

fn serialize_json<T: ::serde::Serialize>(value: &T) -> String {
    json_to_string(value).unwrap_or_else(|_| "{}".to_string())
}

fn deserialize_anchor_pack(value: &str) -> Result<PuzzleAnchorPack, String> {
    json_from_str(value).map_err(|error| format!("拼图 anchor_pack JSON 非法: {error}"))
}

fn deserialize_optional_draft(value: &Option<String>) -> Result<Option<PuzzleResultDraft>, String> {
    value
        .as_ref()
        .map(|raw| json_from_str(raw).map_err(|error| format!("拼图 draft JSON 非法: {error}")))
        .transpose()
}

fn deserialize_draft_required(value: &Option<String>) -> Result<PuzzleResultDraft, String> {
    deserialize_optional_draft(value)?.ok_or_else(|| "拼图 draft 尚未生成".to_string())
}

fn deserialize_theme_tags(value: &str) -> Result<Vec<String>, String> {
    json_from_str(value).map_err(|error| format!("拼图 theme_tags JSON 非法: {error}"))
}

fn deserialize_run(value: &str) -> Result<PuzzleRunSnapshot, String> {
    json_from_str(value).map_err(|error| format!("拼图 run snapshot JSON 非法: {error}"))
}

#[cfg(test)]
mod tests {
    use super::*;
    use module_puzzle::{
        build_generated_candidates, empty_anchor_pack, recommendation_score, tag_similarity_score,
    };

    #[test]
    fn puzzle_json_round_trip_keeps_snapshot_shape() {
        let snapshot = PuzzleRunSnapshot {
            run_id: "run-1".to_string(),
            entry_profile_id: "profile-1".to_string(),
            cleared_level_count: 0,
            current_level_index: 1,
            current_grid_size: 3,
            played_profile_ids: vec!["profile-1".to_string()],
            previous_level_tags: vec!["蒸汽城市".to_string()],
            current_level: None,
            recommended_next_profile_id: None,
        };
        let serialized = serialize_json(&snapshot);
        let parsed = deserialize_run(&serialized).expect("run json should parse");
        assert_eq!(parsed.run_id, "run-1");
    }

    #[test]
    fn puzzle_preview_is_publishable_with_complete_draft() {
        let anchor_pack = infer_anchor_pack("蒸汽城市雨夜猫咪", Some("蒸汽城市雨夜猫咪"));
        let draft = compile_result_draft(&anchor_pack, &[]);
        let candidates = build_generated_candidates("session-1", None, &draft, 2, 1_000_000)
            .expect("candidates should build");
        let draft = apply_selected_candidate(
            PuzzleResultDraft {
                candidates,
                ..draft
            },
            "session-1-candidate-1",
        )
        .expect("draft should select");
        let preview = build_result_preview(&draft, Some("作者"));
        assert!(preview.publish_ready);
    }

    #[test]
    fn puzzle_generated_images_are_appended_without_clearing_existing_candidates() {
        let anchor_pack = infer_anchor_pack("蒸汽城市雨夜猫咪", Some("蒸汽城市雨夜猫咪"));
        let mut draft = compile_result_draft(&anchor_pack, &[]);
        draft.candidates = vec![PuzzleGeneratedImageCandidate {
            candidate_id: "session-1-candidate-1".to_string(),
            image_src: "/generated-puzzle-assets/session-1/old/cover.png".to_string(),
            asset_id: "asset-old".to_string(),
            prompt: "旧提示词".to_string(),
            actual_prompt: Some("旧提示词".to_string()),
            source_type: "generated".to_string(),
            selected: true,
        }];

        append_generated_candidates(
            &mut draft,
            vec![PuzzleGeneratedImageCandidate {
                candidate_id: "session-1-candidate-2".to_string(),
                image_src: "/generated-puzzle-assets/session-1/new/cover.png".to_string(),
                asset_id: "asset-new".to_string(),
                prompt: "新提示词".to_string(),
                actual_prompt: Some("新提示词".to_string()),
                source_type: "generated".to_string(),
                selected: true,
            }],
        );

        assert_eq!(draft.candidates.len(), 2);
        assert_eq!(draft.candidates[0].candidate_id, "session-1-candidate-1");
        assert!(draft.candidates[0].selected);
        assert_eq!(draft.candidates[1].candidate_id, "session-1-candidate-2");
        assert!(!draft.candidates[1].selected);
    }

    #[test]
    fn puzzle_recommendation_score_prefers_same_author_weight() {
        let left = PuzzleWorkProfile {
            work_id: "work-a".to_string(),
            profile_id: "profile-a".to_string(),
            owner_user_id: "owner-a".to_string(),
            source_session_id: None,
            author_display_name: "作者".to_string(),
            level_name: "A".to_string(),
            summary: String::new(),
            theme_tags: vec!["雨夜".to_string(), "猫咪".to_string()],
            cover_image_src: Some("/a.png".to_string()),
            cover_asset_id: Some("asset-a".to_string()),
            publication_status: PuzzlePublicationStatus::Published,
            updated_at_micros: 1,
            published_at_micros: Some(1),
            play_count: 0,
            publish_ready: true,
            anchor_pack: empty_anchor_pack(),
        };
        let right = PuzzleWorkProfile {
            owner_user_id: "owner-a".to_string(),
            profile_id: "profile-b".to_string(),
            work_id: "work-b".to_string(),
            level_name: "B".to_string(),
            theme_tags: vec!["雨夜".to_string(), "蒸汽城市".to_string()],
            cover_image_src: Some("/b.png".to_string()),
            cover_asset_id: Some("asset-b".to_string()),
            publication_status: PuzzlePublicationStatus::Published,
            updated_at_micros: 2,
            published_at_micros: Some(2),
            play_count: 0,
            publish_ready: true,
            anchor_pack: empty_anchor_pack(),
            source_session_id: None,
            author_display_name: "作者".to_string(),
            summary: String::new(),
        };
        assert!(
            recommendation_score(&left, &right)
                > tag_similarity_score(&left.theme_tags, &right.theme_tags)
        );
    }
}