Refine play type integration flow and docs

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

@@ -40,6 +40,15 @@ pub async fn password_entry(
         state.password_entry_service().execute(input).await
     }
     .map_err(map_password_entry_error)?;
+    let session_client = resolve_session_client_context(&headers);
+    let signed_session = create_password_auth_session(&state, &result.user, &session_client)?;
+    state
+        .sync_auth_store_snapshot_to_spacetime()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
+                .with_message(format!("同步认证快照失败：{error}"))
+        })?;
     if result.created {
         crate::registration_reward::grant_new_user_registration_wallet_reward(
             &state,
@@ -48,8 +57,6 @@ pub async fn password_entry(
         )
         .await;
     }
-    let session_client = resolve_session_client_context(&headers);
-    let signed_session = create_password_auth_session(&state, &result.user, &session_client)?;
     record_daily_login_tracking_event_after_auth_success(
         &state,
         &request_context,
@@ -57,13 +64,6 @@ pub async fn password_entry(
         AuthLoginMethod::Password,
     )
     .await;
-    state
-        .sync_auth_store_snapshot_to_spacetime()
-        .await
-        .map_err(|error| {
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
-                .with_message(format!("同步认证快照失败：{error}"))
-        })?;
 
     let mut headers = HeaderMap::new();
     attach_set_cookie_header(

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

@@ -100,13 +100,6 @@ pub async fn reset_password(
         &session_client,
         module_auth::AuthLoginMethod::Password,
     )?;
-    record_daily_login_tracking_event_after_auth_success(
-        &state,
-        &request_context,
-        &result.user.id,
-        module_auth::AuthLoginMethod::Password,
-    )
-    .await;
     state
         .sync_auth_store_snapshot_to_spacetime()
         .await
@@ -114,6 +107,13 @@ pub async fn reset_password(
             AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
                 .with_message(format!("同步认证快照失败：{error}"))
         })?;
+    record_daily_login_tracking_event_after_auth_success(
+        &state,
+        &request_context,
+        &result.user.id,
+        module_auth::AuthLoginMethod::Password,
+    )
+    .await;
 
     let mut headers = HeaderMap::new();
     attach_set_cookie_header(

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

@@ -151,6 +151,20 @@ pub async fn phone_login(
         }
     };
     let created = result.created;
+    let session_client = resolve_session_client_context(&headers);
+    let signed_session = create_auth_session(
+        &state,
+        &result.user,
+        &session_client,
+        AuthLoginMethod::Phone,
+    )?;
+    state
+        .sync_auth_store_snapshot_to_spacetime()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
+                .with_message(format!("同步认证快照失败：{error}"))
+        })?;
     if created {
         crate::registration_reward::grant_new_user_registration_wallet_reward(
             &state,
@@ -170,13 +184,6 @@ pub async fn phone_login(
     } else {
         None
     };
-    let session_client = resolve_session_client_context(&headers);
-    let signed_session = create_auth_session(
-        &state,
-        &result.user,
-        &session_client,
-        AuthLoginMethod::Phone,
-    )?;
     record_daily_login_tracking_event_after_auth_success(
         &state,
         &request_context,
@@ -184,13 +191,6 @@ pub async fn phone_login(
         AuthLoginMethod::Phone,
     )
     .await;
-    state
-        .sync_auth_store_snapshot_to_spacetime()
-        .await
-        .map_err(|error| {
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
-                .with_message(format!("同步认证快照失败：{error}"))
-        })?;
 
     let mut headers = HeaderMap::new();
     attach_set_cookie_header(

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

@@ -2,8 +2,8 @@ use super::*;
 
 pub(crate) fn build_puzzle_form_seed_text(payload: &CreatePuzzleAgentSessionRequest) -> String {
     build_puzzle_form_seed_prompt(PuzzleFormSeedPromptParts {
-        title: None,
-        work_description: None,
+        title: payload.work_title.as_deref(),
+        work_description: payload.work_description.as_deref(),
         picture_description: payload
             .picture_description
             .as_deref()
@@ -32,8 +32,8 @@ pub(crate) async fn save_puzzle_form_payload_before_compile(
     now: i64,
 ) -> Result<String, Response> {
     let seed_text = build_puzzle_form_seed_text_from_parts(
-        None,
-        None,
+        payload.work_title.as_deref(),
+        payload.work_description.as_deref(),
         payload
             .picture_description
             .as_deref()

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

@@ -725,8 +725,8 @@ pub async fn execute_puzzle_agent_action(
         }
         "save_puzzle_form_draft" => {
             let seed_text = build_puzzle_form_seed_text_from_parts(
-                None,
-                None,
+                payload.work_title.as_deref(),
+                payload.work_description.as_deref(),
                 payload
                     .picture_description
                     .as_deref()

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

@@ -384,6 +384,28 @@ fn puzzle_compile_error_preserves_vector_engine_unavailable_status() {
     assert_eq!(response.status(), StatusCode::SERVICE_UNAVAILABLE);
 }
 
+#[test]
+fn puzzle_form_seed_text_includes_work_metadata() {
+    let payload = CreatePuzzleAgentSessionRequest {
+        seed_text: Some("旧 seed 会被画面描述兜底覆盖。".to_string()),
+        work_title: Some("雨夜猫街".to_string()),
+        work_description: Some("123".to_string()),
+        picture_description: Some("一只猫在雨夜灯牌下回头。".to_string()),
+        reference_image_src: None,
+        reference_image_srcs: Vec::new(),
+        reference_image_asset_object_id: None,
+        reference_image_asset_object_ids: Vec::new(),
+        image_model: None,
+        ai_redraw: Some(true),
+    };
+
+    let seed_text = build_puzzle_form_seed_text(&payload);
+
+    assert!(seed_text.contains("作品名称：雨夜猫街"));
+    assert!(seed_text.contains("作品描述：123"));
+    assert!(seed_text.contains("画面描述：一只猫在雨夜灯牌下回头。"));
+}
+
 #[tokio::test]
 async fn puzzle_compile_error_normalizes_legacy_apimart_image_message() {
     let error = map_puzzle_compile_error(SpacetimeClientError::Runtime(

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

@@ -56,13 +56,6 @@ pub async fn refresh_session(
         Some(&rotated.session.issued_by_provider),
         Some(&rotated.session.client_info),
     )?;
-    record_daily_login_tracking_event_after_auth_success(
-        &state,
-        &request_context,
-        &rotated.user.id,
-        rotated.session.issued_by_provider.clone(),
-    )
-    .await;
     state
         .sync_auth_store_snapshot_to_spacetime()
         .await
@@ -70,6 +63,13 @@ pub async fn refresh_session(
             AppError::from_status(axum::http::StatusCode::INTERNAL_SERVER_ERROR)
                 .with_message(format!("同步认证快照失败：{error}"))
         })?;
+    record_daily_login_tracking_event_after_auth_success(
+        &state,
+        &request_context,
+        &rotated.user.id,
+        rotated.session.issued_by_provider.clone(),
+    )
+    .await;
 
     let mut headers = HeaderMap::new();
     attach_set_cookie_header(

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

@@ -591,7 +591,7 @@ impl AppState {
         )
         .map_err(|_| SpacetimeClientError::Runtime("认证快照更新时间超出 i64 范围".to_string()))?;
         // 当前进程内 auth_store 是认证请求的即时工作集；SpacetimeDB 正式认证表用于跨进程恢复。
-        // 远端数据库挂起或网络异常时，只降级后续恢复能力，不能让已成功的登录/刷新/退出回滚为失败。
+        // 认证变更必须在返回客户端前写入 SpacetimeDB，避免只在本进程内成功、重启后丢失账号或会话。
         #[cfg(not(test))]
         if let Err(error) = self
             .spacetime_client
@@ -600,9 +600,9 @@ impl AppState {
         {
             warn!(
                 error = %error,
-                "认证快照导入 SpacetimeDB 正式表失败，当前认证流程继续"
+                "认证快照导入 SpacetimeDB 正式表失败，当前认证流程中止"
             );
-            return Ok(());
+            return Err(error);
         }
         #[cfg(not(test))]
         Ok(())

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

@@ -145,13 +145,6 @@ pub async fn handle_wechat_callback(
                 &session_client,
                 AuthLoginMethod::Wechat,
             )?;
-            record_daily_login_tracking_event_after_auth_success(
-                &state,
-                &request_context,
-                &result.user.id,
-                AuthLoginMethod::Wechat,
-            )
-            .await;
             state
                 .sync_auth_store_snapshot_to_spacetime()
                 .await
@@ -159,6 +152,13 @@ pub async fn handle_wechat_callback(
                     AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
                         .with_message(format!("同步认证快照失败：{error}"))
                 })?;
+            record_daily_login_tracking_event_after_auth_success(
+                &state,
+                &request_context,
+                &result.user.id,
+                AuthLoginMethod::Wechat,
+            )
+            .await;
             let mut response = Redirect::to(&build_auth_result_redirect_url(
                 &redirect_path,
                 &[
@@ -241,6 +241,20 @@ pub async fn bind_wechat_phone(
             .await
             .map_err(map_wechat_bind_phone_error)?
     };
+    let session_client = resolve_session_client_context(&headers);
+    let signed_session = create_auth_session(
+        &state,
+        &result.user,
+        &session_client,
+        AuthLoginMethod::Wechat,
+    )?;
+    state
+        .sync_auth_store_snapshot_to_spacetime()
+        .await
+        .map_err(|error| {
+            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
+                .with_message(format!("同步认证快照失败：{error}"))
+        })?;
     if result.activated_new_user {
         crate::registration_reward::grant_new_user_registration_wallet_reward(
             &state,
@@ -249,13 +263,6 @@ pub async fn bind_wechat_phone(
         )
         .await;
     }
-    let session_client = resolve_session_client_context(&headers);
-    let signed_session = create_auth_session(
-        &state,
-        &result.user,
-        &session_client,
-        AuthLoginMethod::Wechat,
-    )?;
     record_daily_login_tracking_event_after_auth_success(
         &state,
         &request_context,
@@ -263,13 +270,6 @@ pub async fn bind_wechat_phone(
         AuthLoginMethod::Wechat,
     )
     .await;
-    state
-        .sync_auth_store_snapshot_to_spacetime()
-        .await
-        .map_err(|error| {
-            AppError::from_status(StatusCode::INTERNAL_SERVER_ERROR)
-                .with_message(format!("同步认证快照失败：{error}"))
-        })?;
 
     let mut response_headers = HeaderMap::new();
     attach_set_cookie_header(