Merge remote-tracking branch 'origin/master' into codex/ddd

# Conflicts: # docs/technical/README.md # docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md # docs/technical/SPACETIMEDB_TABLE_CATALOG.md # scripts/generate-spacetime-bindings.mjs # server-rs/crates/api-server/src/app.rs # server-rs/crates/api-server/src/assets.rs # server-rs/crates/api-server/src/big_fish.rs # server-rs/crates/api-server/src/custom_world_ai.rs # server-rs/crates/api-server/src/llm.rs # server-rs/crates/api-server/src/main.rs # server-rs/crates/api-server/src/puzzle.rs # server-rs/crates/api-server/src/runtime_profile.rs # server-rs/crates/api-server/src/runtime_story/compat/ai.rs # server-rs/crates/api-server/src/runtime_story/compat/npc_actions.rs # server-rs/crates/api-server/src/runtime_story/compat/presentation.rs # server-rs/crates/api-server/src/runtime_story/compat/tests.rs # server-rs/crates/api-server/src/state.rs # server-rs/crates/module-auth/src/lib.rs # server-rs/crates/module-big-fish/src/lib.rs # server-rs/crates/module-custom-world/src/lib.rs # server-rs/crates/module-puzzle/src/lib.rs # server-rs/crates/module-runtime/src/lib.rs # server-rs/crates/spacetime-client/src/big_fish.rs # server-rs/crates/spacetime-client/src/lib.rs # server-rs/crates/spacetime-client/src/mapper.rs # server-rs/crates/spacetime-client/src/module_bindings/admin_disable_profile_redeem_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/admin_upsert_profile_redeem_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/advance_puzzle_next_level_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/append_ai_text_chunk_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/apply_chapter_progression_ledger_entry_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/attach_ai_result_reference_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/authorize_database_migration_operator_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/begin_story_session_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/big_fish_runtime_run_type.rs # server-rs/crates/spacetime-client/src/module_bindings/bind_asset_object_to_entity_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/cancel_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/clear_platform_browse_history_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/compile_big_fish_draft_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/compile_custom_world_published_profile_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/compile_puzzle_agent_draft_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/complete_ai_stage_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/complete_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/confirm_asset_object_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/consume_profile_wallet_points_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/continue_story_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_battle_state_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_big_fish_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_custom_world_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_profile_recharge_order_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_puzzle_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_big_fish_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_custom_world_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_puzzle_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_runtime_snapshot_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/drag_puzzle_piece_or_group_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/execute_custom_world_agent_action_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/export_auth_store_snapshot_from_tables_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/export_database_migration_to_file_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/fail_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/finalize_big_fish_agent_message_turn_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/finalize_custom_world_agent_message_turn_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/finalize_puzzle_agent_message_turn_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/generate_big_fish_asset_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_auth_store_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_battle_state_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_big_fish_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_chapter_progression_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_agent_card_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_agent_operation_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_gallery_detail_by_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_gallery_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_library_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_player_progression_or_default_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_dashboard_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_play_stats_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_recharge_center_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_referral_invite_center_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_gallery_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_run_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_work_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_runtime_inventory_state_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_runtime_setting_or_default_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_runtime_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_story_session_state_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/grant_player_progression_experience_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/import_auth_store_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/import_database_migration_from_file_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/import_database_migration_incremental_from_file_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_asset_history_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_big_fish_works_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_custom_world_gallery_entries_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_custom_world_profiles_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_custom_world_works_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_platform_browse_history_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_profile_save_archives_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_profile_wallet_ledger_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_puzzle_gallery_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_puzzle_works_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/mod.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_big_fish_game_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_custom_world_world_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_puzzle_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/record_big_fish_play_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/redeem_profile_referral_invite_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/redeem_profile_reward_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/refund_profile_wallet_points_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_combat_action_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_npc_battle_interaction_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_npc_interaction_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_npc_social_action_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_treasure_interaction_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resume_profile_save_archive_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/revoke_database_migration_operator_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/save_puzzle_generated_images_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/select_puzzle_cover_image_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/start_puzzle_run_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_big_fish_message_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_custom_world_agent_message_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_puzzle_agent_message_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_puzzle_leaderboard_entry_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/swap_puzzle_pieces_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/unpublish_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/update_puzzle_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_auth_store_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_chapter_progression_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_custom_world_agent_operation_progress_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_npc_state_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_platform_browse_history_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_runtime_setting_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_runtime_snapshot_and_return_procedure.rs # server-rs/crates/spacetime-module/src/auth/procedures.rs # server-rs/crates/spacetime-module/src/custom_world/mod.rs # server-rs/crates/spacetime-module/src/lib.rs # server-rs/crates/spacetime-module/src/migration.rs # server-rs/crates/spacetime-module/src/puzzle.rs # server-rs/crates/spacetime-module/src/runtime/profile.rs # src/components/platform-entry/PlatformEntryFlowShellImpl.tsx # src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx # src/services/aiService.ts # src/services/puzzle-runtime/puzzleRuntimeClient.ts
2026-05-02 03:35:59 +08:00
parent 9d9913095d fb6fb6e9f5
commit 8f4ca9abfa
513 changed files with 52813 additions and 6013 deletions
--- a/server-rs/crates/api-server/src/runtime_profile.rs
+++ b/server-rs/crates/api-server/src/runtime_profile.rs
@@ -5,31 +5,33 @@ use axum::{
    response::Response,
 };
 use module_runtime::{
-    PROFILE_RECHARGE_PAYMENT_CHANNEL_MOCK, RuntimeProfileMembershipBenefitRecord,
-    RuntimeProfileRechargeCenterRecord, RuntimeProfileRechargeOrderRecord,
-    RuntimeProfileRechargeProductRecord, RuntimeProfileRedeemCodeMode,
-    RuntimeProfileRedeemCodeRecord, RuntimeProfileRewardCodeRedeemRecord,
-    RuntimeProfileWalletLedgerSourceType, RuntimeReferralInviteCenterRecord,
-    RuntimeReferralRedeemRecord,
+    PROFILE_RECHARGE_PAYMENT_CHANNEL_MOCK, RuntimeProfileInviteCodeRecord,
+    RuntimeProfileMembershipBenefitRecord, RuntimeProfileRechargeCenterRecord,
+    RuntimeProfileRechargeOrderRecord, RuntimeProfileRechargeProductRecord,
+    RuntimeProfileRedeemCodeMode, RuntimeProfileRedeemCodeRecord,
+    RuntimeProfileRewardCodeRedeemRecord, RuntimeProfileWalletLedgerSourceType,
+    RuntimeReferralInviteCenterRecord,
 };
 use serde_json::{Value, json};
 use shared_contracts::runtime::{
-    AdminDisableProfileRedeemCodeRequest, AdminUpsertProfileRedeemCodeRequest,
-    CreateProfileRechargeOrderRequest, CreateProfileRechargeOrderResponse,
-    PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_CONSUME,
+    AdminDisableProfileRedeemCodeRequest, AdminUpsertProfileInviteCodeRequest,
+    AdminUpsertProfileRedeemCodeRequest, CreateProfileRechargeOrderRequest,
+    CreateProfileRechargeOrderResponse, PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_CONSUME,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_REFUND,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_INVITE_INVITEE_REWARD,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_INVITE_INVITER_REWARD,
+    PROFILE_WALLET_LEDGER_SOURCE_TYPE_NEW_USER_REGISTRATION_REWARD,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_POINTS_RECHARGE,
+    PROFILE_WALLET_LEDGER_SOURCE_TYPE_PUZZLE_AUTHOR_INCENTIVE_CLAIM,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_REDEEM_CODE_REWARD,
    PROFILE_WALLET_LEDGER_SOURCE_TYPE_SNAPSHOT_SYNC, ProfileDashboardSummaryResponse,
-    ProfileMembershipBenefitResponse, ProfileMembershipResponse, ProfilePlayStatsResponse,
-    ProfilePlayedWorkSummaryResponse, ProfileRechargeCenterResponse, ProfileRechargeOrderResponse,
-    ProfileRechargeProductResponse, ProfileRedeemCodeAdminResponse,
-    ProfileReferralInviteCenterResponse, ProfileWalletLedgerEntryResponse,
-    ProfileWalletLedgerResponse, RedeemProfileReferralInviteCodeRequest,
-    RedeemProfileReferralInviteCodeResponse, RedeemProfileRewardCodeRequest,
-    RedeemProfileRewardCodeResponse,
+    ProfileInviteCodeAdminResponse, ProfileMembershipBenefitResponse, ProfileMembershipResponse,
+    ProfilePlayStatsResponse, ProfilePlayedWorkSummaryResponse, ProfileRechargeCenterResponse,
+    ProfileRechargeOrderResponse, ProfileRechargeProductResponse, ProfileRedeemCodeAdminResponse,
+    ProfileReferralInviteCenterResponse, ProfileReferralInvitedUserResponse,
+    ProfileWalletLedgerEntryResponse, ProfileWalletLedgerResponse,
+    RedeemProfileReferralInviteCodeRequest, RedeemProfileReferralInviteCodeResponse,
+    RedeemProfileRewardCodeRequest, RedeemProfileRewardCodeResponse,
 };
 use spacetime_client::SpacetimeClientError;
 use time::OffsetDateTime;
@@ -109,6 +111,9 @@ fn format_profile_wallet_ledger_source_type(
        RuntimeProfileWalletLedgerSourceType::SnapshotSync => {
            PROFILE_WALLET_LEDGER_SOURCE_TYPE_SNAPSHOT_SYNC
        }
+        RuntimeProfileWalletLedgerSourceType::NewUserRegistrationReward => {
+            PROFILE_WALLET_LEDGER_SOURCE_TYPE_NEW_USER_REGISTRATION_REWARD
+        }
        RuntimeProfileWalletLedgerSourceType::InviteInviterReward => {
            PROFILE_WALLET_LEDGER_SOURCE_TYPE_INVITE_INVITER_REWARD
        }
@@ -127,6 +132,9 @@ fn format_profile_wallet_ledger_source_type(
        RuntimeProfileWalletLedgerSourceType::RedeemCodeReward => {
            PROFILE_WALLET_LEDGER_SOURCE_TYPE_REDEEM_CODE_REWARD
        }
+        RuntimeProfileWalletLedgerSourceType::PuzzleAuthorIncentiveClaim => {
+            PROFILE_WALLET_LEDGER_SOURCE_TYPE_PUZZLE_AUTHOR_INCENTIVE_CLAIM
+        }
    }
 }

@@ -330,6 +338,37 @@ pub async fn admin_disable_profile_redeem_code(
    ))
 }

+pub async fn admin_upsert_profile_invite_code(
+    State(state): State<AppState>,
+    Extension(request_context): Extension<RequestContext>,
+    Extension(admin): Extension<AuthenticatedAdmin>,
+    Json(payload): Json<AdminUpsertProfileInviteCodeRequest>,
+) -> Result<Json<Value>, Response> {
+    let metadata_json = normalize_admin_invite_code_metadata(payload.metadata)
+        .map_err(|error| runtime_profile_error_response(&request_context, error))?;
+    let updated_at_micros = OffsetDateTime::now_utc().unix_timestamp_nanos() / 1_000;
+    let record = state
+        .spacetime_client()
+        .admin_upsert_profile_invite_code(
+            admin.session().username.clone(),
+            payload.invite_code,
+            metadata_json,
+            updated_at_micros as i64,
+        )
+        .await
+        .map_err(|error| {
+            runtime_profile_error_response(
+                &request_context,
+                map_runtime_profile_client_error(error),
+            )
+        })?;
+
+    Ok(json_success_body(
+        Some(&request_context),
+        build_profile_invite_code_admin_response(record),
+    ))
+}
+
 pub async fn get_profile_play_stats(
    State(state): State<AppState>,
    Extension(request_context): Extension<RequestContext>,
@@ -479,6 +518,16 @@ fn build_profile_referral_invite_center_response(
        today_inviter_reward_count: record.today_inviter_reward_count,
        today_inviter_reward_remaining: record.today_inviter_reward_remaining,
        reward_points: record.reward_points,
+        invited_users: record
+            .invited_users
+            .into_iter()
+            .map(|user| ProfileReferralInvitedUserResponse {
+                user_id: user.user_id,
+                display_name: user.display_name,
+                avatar_url: user.avatar_url,
+                bound_at: user.bound_at,
+            })
+            .collect(),
        has_redeemed_code: record.has_redeemed_code,
        bound_inviter_user_id: record.bound_inviter_user_id,
        bound_at: record.bound_at,
@@ -487,7 +536,7 @@ fn build_profile_referral_invite_center_response(
 }

 fn build_redeem_profile_referral_invite_code_response(
-    record: RuntimeReferralRedeemRecord,
+    record: module_runtime::RuntimeReferralRedeemRecord,
 ) -> RedeemProfileReferralInviteCodeResponse {
    RedeemProfileReferralInviteCodeResponse {
        center: build_profile_referral_invite_center_response(record.center),
@@ -515,6 +564,30 @@ fn build_redeem_profile_reward_code_response(
    }
 }

+fn normalize_admin_invite_code_metadata(metadata: Option<Value>) -> Result<String, AppError> {
+    let metadata = match metadata {
+        Some(Value::Null) | None => json!({}),
+        Some(value) if value.is_object() => value,
+        Some(_) => {
+            return Err(AppError::from_status(StatusCode::BAD_REQUEST)
+                .with_message("邀请码 metadata 必须是 JSON 对象")
+                .with_details(json!({ "field": "metadata" })));
+        }
+    };
+    let metadata_json = serde_json::to_string(&metadata).map_err(|error| {
+        AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_message(format!("邀请码 metadata 序列化失败：{error}"))
+            .with_details(json!({ "field": "metadata" }))
+    })?;
+    if metadata_json.len() > 4096 {
+        return Err(AppError::from_status(StatusCode::BAD_REQUEST)
+            .with_message("邀请码 metadata 不能超过 4096 bytes")
+            .with_details(json!({ "field": "metadata" })));
+    }
+
+    Ok(metadata_json)
+}
+
 fn parse_profile_redeem_code_mode(raw: &str) -> Result<RuntimeProfileRedeemCodeMode, String> {
    match raw.trim().to_ascii_lowercase().as_str() {
        "public" => Ok(RuntimeProfileRedeemCodeMode::Public),
@@ -524,6 +597,20 @@ fn parse_profile_redeem_code_mode(raw: &str) -> Result<RuntimeProfileRedeemCodeM
    }
 }

+fn build_profile_invite_code_admin_response(
+    record: RuntimeProfileInviteCodeRecord,
+) -> ProfileInviteCodeAdminResponse {
+    let metadata =
+        serde_json::from_str::<Value>(&record.metadata_json).unwrap_or_else(|_| json!({}));
+    ProfileInviteCodeAdminResponse {
+        user_id: record.user_id,
+        invite_code: record.invite_code,
+        metadata,
+        created_at: record.created_at,
+        updated_at: record.updated_at,
+    }
+}
+
 fn build_profile_redeem_code_admin_response(
    record: RuntimeProfileRedeemCodeRecord,
 ) -> ProfileRedeemCodeAdminResponse {
@@ -545,18 +632,31 @@ fn build_profile_redeem_code_admin_response(
 mod tests {
    use module_runtime::RuntimeProfileWalletLedgerSourceType;

-    use super::format_profile_wallet_ledger_source_type;
+    use super::{format_profile_wallet_ledger_source_type, normalize_admin_invite_code_metadata};

    use axum::{
        body::Body,
        http::{Request, StatusCode},
    };
+    use http_body_util::BodyExt;
+    use platform_auth::{
+        AccessTokenClaims, AccessTokenClaimsInput, AuthProvider, BindingStatus, sign_access_token,
+    };
+    use serde_json::Value;
+    use std::time::Duration;
+    use time::OffsetDateTime;
    use tower::ServiceExt;

    use crate::{app::build_router, config::AppConfig, state::AppState};

    #[test]
-    fn profile_wallet_ledger_source_type_formats_asset_operation_values() {
+    fn profile_wallet_ledger_source_type_formats_backend_values() {
+        assert_eq!(
+            format_profile_wallet_ledger_source_type(
+                RuntimeProfileWalletLedgerSourceType::NewUserRegistrationReward
+            ),
+            shared_contracts::runtime::PROFILE_WALLET_LEDGER_SOURCE_TYPE_NEW_USER_REGISTRATION_REWARD
+        );
        assert_eq!(
            format_profile_wallet_ledger_source_type(
                RuntimeProfileWalletLedgerSourceType::AssetOperationConsume
@@ -569,6 +669,12 @@ mod tests {
            ),
            shared_contracts::runtime::PROFILE_WALLET_LEDGER_SOURCE_TYPE_ASSET_OPERATION_REFUND
        );
+        assert_eq!(
+            format_profile_wallet_ledger_source_type(
+                RuntimeProfileWalletLedgerSourceType::PuzzleAuthorIncentiveClaim
+            ),
+            shared_contracts::runtime::PROFILE_WALLET_LEDGER_SOURCE_TYPE_PUZZLE_AUTHOR_INCENTIVE_CLAIM
+        );
    }

    #[tokio::test]
@@ -699,6 +805,60 @@ mod tests {
        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
    }

+    #[tokio::test]
+    async fn profile_referral_redeem_code_calls_spacetime_for_authenticated_user() {
+        let state = seed_authenticated_state().await;
+        let token = issue_access_token(&state);
+        let app = build_router(state);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/profile/referrals/redeem-code")
+                    .header("authorization", format!("Bearer {token}"))
+                    .header("content-type", "application/json")
+                    .body(Body::from(r#"{"inviteCode":"SY12345678"}"#))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::BAD_GATEWAY);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("body should collect")
+            .to_bytes();
+        let payload: Value =
+            serde_json::from_slice(&body).expect("response body should be valid json");
+        assert_eq!(
+            payload["error"]["details"]["provider"],
+            Value::String("spacetimedb".to_string())
+        );
+    }
+
+    #[test]
+    fn admin_invite_code_metadata_accepts_only_json_object() {
+        assert_eq!(
+            normalize_admin_invite_code_metadata(None).expect("empty metadata should default"),
+            "{}"
+        );
+        assert_eq!(
+            normalize_admin_invite_code_metadata(Some(serde_json::json!({
+                "channel": "spring",
+                "source": "banner"
+            })))
+            .expect("object metadata should serialize"),
+            r#"{"channel":"spring","source":"banner"}"#
+        );
+
+        let error = normalize_admin_invite_code_metadata(Some(serde_json::json!("spring")))
+            .expect_err("non-object metadata should reject");
+        assert_eq!(error.message(), "邀请码 metadata 必须是 JSON 对象");
+    }
+
    #[tokio::test]
    async fn runtime_profile_legacy_routes_are_not_mounted() {
        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
@@ -731,4 +891,40 @@ mod tests {
            assert_eq!(response.status(), StatusCode::NOT_FOUND, "{uri}");
        }
    }
+
+    async fn seed_authenticated_state() -> AppState {
+        let state = AppState::new(fast_spacetime_timeout_config()).expect("state should build");
+        state
+            .seed_test_phone_user_with_password("13800138104", "secret123")
+            .await
+            .id;
+        state
+    }
+
+    fn fast_spacetime_timeout_config() -> AppConfig {
+        AppConfig {
+            spacetime_procedure_timeout: Duration::from_secs(1),
+            ..AppConfig::default()
+        }
+    }
+
+    fn issue_access_token(state: &AppState) -> String {
+        let claims = AccessTokenClaims::from_input(
+            AccessTokenClaimsInput {
+                user_id: "user_00000001".to_string(),
+                session_id: "sess_runtime_profile".to_string(),
+                provider: AuthProvider::Password,
+                roles: vec!["user".to_string()],
+                token_version: 2,
+                phone_verified: true,
+                binding_status: BindingStatus::Active,
+                display_name: Some("资料页用户".to_string()),
+            },
+            state.auth_jwt_config(),
+            OffsetDateTime::now_utc(),
+        )
+        .expect("claims should build");
+
+        sign_access_token(&claims, state.auth_jwt_config()).expect("token should sign")
+    }
 }