feat: add puzzle onboarding and match3d entry updates

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

@@ -85,11 +85,12 @@ use crate::{
     puzzle::{
         advance_puzzle_next_level, claim_puzzle_work_point_incentive, create_puzzle_agent_session,
         delete_puzzle_work, drag_puzzle_piece_or_group, execute_puzzle_agent_action,
-        get_puzzle_agent_session, get_puzzle_gallery_detail, get_puzzle_run,
-        get_puzzle_work_detail, get_puzzle_works, list_puzzle_gallery, put_puzzle_work,
-        record_puzzle_gallery_like, remix_puzzle_gallery_work, start_puzzle_run,
-        stream_puzzle_agent_message, submit_puzzle_agent_message, submit_puzzle_leaderboard,
-        swap_puzzle_pieces, update_puzzle_run_pause, use_puzzle_runtime_prop,
+        generate_puzzle_onboarding_work, get_puzzle_agent_session, get_puzzle_gallery_detail,
+        get_puzzle_run, get_puzzle_work_detail, get_puzzle_works, list_puzzle_gallery,
+        put_puzzle_work, record_puzzle_gallery_like, remix_puzzle_gallery_work,
+        save_puzzle_onboarding_work, start_puzzle_run, stream_puzzle_agent_message,
+        submit_puzzle_agent_message, submit_puzzle_leaderboard, swap_puzzle_pieces,
+        update_puzzle_run_pause, use_puzzle_runtime_prop,
     },
     refresh_session::refresh_session,
     request_context::{attach_request_context, resolve_request_id},
@@ -1003,6 +1004,19 @@ pub fn build_router(state: AppState) -> Router {
                     require_bearer_auth,
                 )),
         )
+        .route(
+            "/api/runtime/puzzle/onboarding/generate",
+            post(generate_puzzle_onboarding_work).layer(DefaultBodyLimit::max(
+                PUZZLE_REFERENCE_IMAGE_BODY_LIMIT_BYTES,
+            )),
+        )
+        .route(
+            "/api/runtime/puzzle/onboarding/save",
+            post(save_puzzle_onboarding_work).route_layer(middleware::from_fn_with_state(
+                state.clone(),
+                require_bearer_auth,
+            )),
+        )
         .route(
             "/api/runtime/puzzle/works",
             get(get_puzzle_works).route_layer(middleware::from_fn_with_state(

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

@@ -72,12 +72,33 @@ mod work_author;
 
 use shared_logging::init_tracing;
 use tokio::net::TcpListener;
+use tokio::runtime::Builder as TokioRuntimeBuilder;
 use tracing::info;
 
 use crate::{app::build_router, config::AppConfig, state::AppState};
 
-#[tokio::main]
-async fn main() -> Result<(), std::io::Error> {
+const API_SERVER_STARTUP_STACK_SIZE_BYTES: usize = 32 * 1024 * 1024;
+
+fn main() -> Result<(), std::io::Error> {
+    // Windows 本地调试下 Axum 路由树和启动恢复链较重，显式放大启动线程栈，避免 debug 构建在进入监听前栈溢出。
+    std::thread::Builder::new()
+        .name("api-server-bootstrap".to_string())
+        .stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
+        .spawn(run_api_server_with_runtime)?
+        .join()
+        .map_err(|_| std::io::Error::other("api-server 启动线程异常退出"))?
+}
+
+fn run_api_server_with_runtime() -> Result<(), std::io::Error> {
+    TokioRuntimeBuilder::new_multi_thread()
+        .enable_all()
+        .thread_name("api-server-worker")
+        .thread_stack_size(API_SERVER_STARTUP_STACK_SIZE_BYTES)
+        .build()?
+        .block_on(run_api_server())
+}
+
+async fn run_api_server() -> Result<(), std::io::Error> {
     // 运行本地开发与联调时，优先从仓库根目录加载本地变量，避免手工逐项导出 OSS / APIMart 配置。
     let _ = dotenvy::from_filename(".env");
     let _ = dotenvy::from_filename(".env.local");

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

@@ -45,7 +45,8 @@ use shared_contracts::{
         UsePuzzleRuntimePropRequest,
     },
     puzzle_works::{
-        PutPuzzleWorkRequest, PuzzleWorkDetailResponse, PuzzleWorkMutationResponse,
+        PutPuzzleWorkRequest, PuzzleOnboardingGenerateRequest, PuzzleOnboardingGenerateResponse,
+        PuzzleOnboardingSaveRequest, PuzzleWorkDetailResponse, PuzzleWorkMutationResponse,
         PuzzleWorkProfileResponse, PuzzleWorkSummaryResponse, PuzzleWorksResponse,
     },
 };
@@ -157,6 +158,222 @@ pub async fn create_puzzle_agent_session(
     ))
 }
 
+pub async fn generate_puzzle_onboarding_work(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    payload: Result<Json<PuzzleOnboardingGenerateRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_AGENT_API_BASE_PROVIDER,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let prompt_text = payload.prompt_text.trim().to_string();
+    ensure_non_empty(
+        &request_context,
+        PUZZLE_AGENT_API_BASE_PROVIDER,
+        &prompt_text,
+        "promptText",
+    )?;
+
+    let now = current_utc_micros();
+    let session_id = build_prefixed_uuid_id("puzzle-onboarding-");
+    let level_name = generate_puzzle_first_level_name(&state, prompt_text.as_str()).await;
+    let tags = generate_puzzle_work_tags(&state, level_name.as_str(), prompt_text.as_str()).await;
+    let candidates = generate_puzzle_image_candidates(
+        &state,
+        "onboarding-guest",
+        session_id.as_str(),
+        level_name.as_str(),
+        prompt_text.as_str(),
+        None,
+        Some(PUZZLE_IMAGE_MODEL_GPT_IMAGE_2),
+        1,
+        0,
+    )
+    .await
+    .map_err(|error| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_AGENT_API_BASE_PROVIDER,
+            map_puzzle_generation_endpoint_error(error),
+        )
+    })?;
+    let selected = candidates.first().cloned().ok_or_else(|| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_AGENT_API_BASE_PROVIDER,
+            AppError::from_status(StatusCode::BAD_GATEWAY).with_details(json!({
+                "provider": PUZZLE_AGENT_API_BASE_PROVIDER,
+                "message": "新手引导拼图图片生成结果为空",
+            })),
+        )
+    })?;
+    let level = PuzzleDraftLevelRecord {
+        level_id: "onboarding-level-1".to_string(),
+        level_name: level_name.clone(),
+        picture_description: prompt_text.clone(),
+        candidates,
+        selected_candidate_id: Some(selected.candidate_id.clone()),
+        cover_image_src: Some(selected.image_src.clone()),
+        cover_asset_id: Some(selected.asset_id.clone()),
+        generation_status: "ready".to_string(),
+    };
+    let anchor_pack = map_puzzle_domain_anchor_pack(module_puzzle::build_form_anchor_pack(
+        level_name.as_str(),
+        level.picture_description.as_str(),
+    ));
+    let item = PuzzleWorkProfileRecord {
+        work_id: format!("onboarding-work-{now}"),
+        profile_id: format!("onboarding-profile-{now}"),
+        owner_user_id: "onboarding-guest".to_string(),
+        source_session_id: None,
+        author_display_name: "百梦主".to_string(),
+        work_title: level_name.clone(),
+        work_description: prompt_text.clone(),
+        level_name,
+        summary: prompt_text,
+        theme_tags: tags,
+        cover_image_src: level.cover_image_src.clone(),
+        cover_asset_id: level.cover_asset_id.clone(),
+        publication_status: "draft".to_string(),
+        updated_at: format_timestamp_micros(now),
+        published_at: None,
+        play_count: 0,
+        remix_count: 0,
+        like_count: 0,
+        recent_play_count_7d: 0,
+        point_incentive_total_half_points: 0,
+        point_incentive_claimed_points: 0,
+        anchor_pack,
+        publish_ready: true,
+        levels: vec![level.clone()],
+    };
+
+    Ok(json_success_body(
+        Some(&request_context),
+        PuzzleOnboardingGenerateResponse {
+            item: map_puzzle_work_profile_response(&state, item.clone()).summary,
+            level: map_puzzle_draft_level_response(level),
+        },
+    ))
+}
+
+pub async fn save_puzzle_onboarding_work(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    payload: Result<Json<PuzzleOnboardingSaveRequest>, JsonRejection>,
+) -> Result<Json<Value>, Response> {
+    let Json(payload) = payload.map_err(|error| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_WORKS_PROVIDER,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": PUZZLE_WORKS_PROVIDER,
+                "message": error.body_text(),
+            })),
+        )
+    })?;
+
+    let prompt_text = payload.prompt_text.trim().to_string();
+    ensure_non_empty(
+        &request_context,
+        PUZZLE_WORKS_PROVIDER,
+        &prompt_text,
+        "promptText",
+    )?;
+
+    let first_level = payload.item.levels.first().cloned().ok_or_else(|| {
+        puzzle_error_response(
+            &request_context,
+            PUZZLE_WORKS_PROVIDER,
+            AppError::from_status(StatusCode::BAD_REQUEST).with_details(json!({
+                "provider": PUZZLE_WORKS_PROVIDER,
+                "message": "新手引导拼图缺少可保存关卡",
+            })),
+        )
+    })?;
+    let levels_json = serialize_puzzle_levels_response(&request_context, &payload.item.levels)?;
+    let work_title = payload.item.work_title.trim();
+    let work_title = if work_title.is_empty() {
+        first_level.level_name.clone()
+    } else {
+        work_title.to_string()
+    };
+    let work_description = payload.item.work_description.trim();
+    let work_description = if work_description.is_empty() {
+        prompt_text.clone()
+    } else {
+        work_description.to_string()
+    };
+    let summary = payload.item.summary.trim();
+    let summary = if summary.is_empty() {
+        first_level.picture_description.clone()
+    } else {
+        summary.to_string()
+    };
+    let now = current_utc_micros();
+    let owner_user_id = authenticated.claims().user_id().to_string();
+    let session_id = build_prefixed_uuid_id("puzzle-session-");
+    state
+        .spacetime_client()
+        .create_puzzle_agent_session(PuzzleAgentSessionCreateRecordInput {
+            session_id: session_id.clone(),
+            owner_user_id: owner_user_id.clone(),
+            seed_text: prompt_text.clone(),
+            welcome_message_id: build_prefixed_uuid_id("puzzle-message-"),
+            welcome_message_text: build_puzzle_welcome_text(&prompt_text),
+            created_at_micros: now,
+        })
+        .await
+        .map_err(|error| {
+            puzzle_error_response(
+                &request_context,
+                PUZZLE_WORKS_PROVIDER,
+                map_puzzle_client_error(error),
+            )
+        })?;
+
+    let (_, profile_id) = build_stable_puzzle_work_ids(session_id.as_str());
+    let item = state
+        .spacetime_client()
+        .update_puzzle_work(PuzzleWorkUpsertRecordInput {
+            profile_id,
+            owner_user_id,
+            work_title,
+            work_description,
+            level_name: first_level.level_name,
+            summary,
+            theme_tags: payload.item.theme_tags,
+            cover_image_src: first_level.cover_image_src,
+            cover_asset_id: first_level.cover_asset_id,
+            levels_json: Some(levels_json),
+            updated_at_micros: now,
+        })
+        .await
+        .map_err(|error| {
+            puzzle_error_response(
+                &request_context,
+                PUZZLE_WORKS_PROVIDER,
+                map_puzzle_client_error(error),
+            )
+        })?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        PuzzleWorkMutationResponse {
+            item: map_puzzle_work_profile_response(&state, item),
+        },
+    ))
+}
+
 pub async fn get_puzzle_agent_session(
     State(state): State<AppState>,
     AxumPath(session_id): AxumPath<String>,

server-rs/crates/shared-contracts/src/puzzle_works.rs

@@ -127,3 +127,23 @@ pub struct PuzzleWorkDetailResponse {
 pub struct PuzzleWorkMutationResponse {
     pub item: PuzzleWorkProfileResponse,
 }
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleOnboardingGenerateRequest {
+    pub prompt_text: String,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleOnboardingGenerateResponse {
+    pub item: PuzzleWorkSummaryResponse,
+    pub level: PuzzleDraftLevelResponse,
+}
+
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq)]
+#[serde(rename_all = "camelCase")]
+pub struct PuzzleOnboardingSaveRequest {
+    pub prompt_text: String,
+    pub item: PuzzleWorkSummaryResponse,
+}