1

server-rs/crates/spacetime-module/src/big_fish/assets.rs

@@ -108,6 +108,7 @@ pub(crate) fn generate_big_fish_asset_tx(
             .map_err(|error| error.to_string())?,
         last_assistant_reply: Some(reply.clone()),
         publish_ready: coverage.publish_ready,
+        play_count: session.play_count,
         created_at: session.created_at,
         updated_at,
     };
@@ -164,6 +165,7 @@ pub(crate) fn publish_big_fish_game_tx(
             .map_err(|error| error.to_string())?,
         last_assistant_reply: Some("玩法已发布，可以进入测试运行态。".to_string()),
         publish_ready: true,
+        play_count: session.play_count,
         created_at: session.created_at,
         updated_at: published_at,
     };

server-rs/crates/spacetime-module/src/big_fish/session.rs

@@ -1,4 +1,7 @@
 use crate::big_fish::tables::{big_fish_agent_message, big_fish_creation_session};
+use crate::runtime::{
+    ProfilePlayedWorkUpsertInput, add_profile_observed_play_time, upsert_profile_played_work,
+};
 use crate::*;
 
 const INITIAL_BIG_FISH_CREATION_PROGRESS_PERCENT: u32 = 0;
@@ -93,6 +96,32 @@ pub fn delete_big_fish_work(
     }
 }
 
+#[spacetimedb::procedure]
+pub fn record_big_fish_play(
+    ctx: &mut ProcedureContext,
+    input: BigFishPlayRecordInput,
+) -> BigFishWorksProcedureResult {
+    match ctx.try_with_tx(|tx| record_big_fish_play_tx(tx, input.clone())) {
+        Ok(items) => match serde_json::to_string(&items) {
+            Ok(items_json) => BigFishWorksProcedureResult {
+                ok: true,
+                items_json: Some(items_json),
+                error_message: None,
+            },
+            Err(error) => BigFishWorksProcedureResult {
+                ok: false,
+                items_json: None,
+                error_message: Some(error.to_string()),
+            },
+        },
+        Err(message) => BigFishWorksProcedureResult {
+            ok: false,
+            items_json: None,
+            error_message: Some(message),
+        },
+    }
+}
+
 #[spacetimedb::procedure]
 pub fn submit_big_fish_message(
     ctx: &mut ProcedureContext,
@@ -194,6 +223,7 @@ pub(crate) fn create_big_fish_session_tx(
                 .map_err(|error| error.to_string())?,
             last_assistant_reply: Some(input.welcome_message_text.clone()),
             publish_ready: false,
+            play_count: 0,
             created_at,
             updated_at: created_at,
         });
@@ -383,6 +413,7 @@ pub(crate) fn submit_big_fish_message_tx(
         asset_coverage_json: session.asset_coverage_json.clone(),
         last_assistant_reply: session.last_assistant_reply.clone(),
         publish_ready: session.publish_ready,
+        play_count: session.play_count,
         created_at: session.created_at,
         updated_at: submitted_at,
     };
@@ -429,6 +460,7 @@ pub(crate) fn finalize_big_fish_agent_message_turn_tx(
             asset_coverage_json: session.asset_coverage_json.clone(),
             last_assistant_reply: session.last_assistant_reply.clone(),
             publish_ready: session.publish_ready,
+            play_count: session.play_count,
             created_at: session.created_at,
             updated_at,
         };
@@ -483,6 +515,7 @@ pub(crate) fn finalize_big_fish_agent_message_turn_tx(
         asset_coverage_json: session.asset_coverage_json.clone(),
         last_assistant_reply: Some(assistant_reply_text),
         publish_ready: session.publish_ready,
+        play_count: session.play_count,
         created_at: session.created_at,
         updated_at,
     };
@@ -536,6 +569,7 @@ pub(crate) fn compile_big_fish_draft_tx(
             .map_err(|error| error.to_string())?,
         last_assistant_reply: Some(reply.clone()),
         publish_ready: coverage.publish_ready,
+        play_count: session.play_count,
         created_at: session.created_at,
         updated_at: compiled_at,
     };
@@ -550,6 +584,92 @@ pub(crate) fn compile_big_fish_draft_tx(
     )
 }
 
+pub(crate) fn record_big_fish_play_tx(
+    ctx: &ReducerContext,
+    input: BigFishPlayRecordInput,
+) -> Result<Vec<BigFishWorkSummarySnapshot>, String> {
+    validate_play_record_input(&input).map_err(|error| error.to_string())?;
+    let session = ctx
+        .db
+        .big_fish_creation_session()
+        .session_id()
+        .find(&input.session_id)
+        .filter(|row| row.stage == BigFishCreationStage::Published)
+        .ok_or_else(|| "big_fish 已发布作品不存在".to_string())?;
+    let played_at = Timestamp::from_micros_since_unix_epoch(input.played_at_micros);
+    let draft = session
+        .draft_json
+        .as_deref()
+        .map(deserialize_draft)
+        .transpose()
+        .map_err(|error| format!("big_fish.draft_json 非法: {error}"))?;
+    let title = draft
+        .as_ref()
+        .map(|value| value.title.trim().to_string())
+        .filter(|value| !value.is_empty())
+        .unwrap_or_else(|| "大鱼吃小鱼".to_string());
+    let subtitle = draft
+        .as_ref()
+        .and_then(|value| {
+            let subtitle = value.subtitle.trim();
+            if subtitle.is_empty() {
+                let core_fun = value.core_fun.trim();
+                (!core_fun.is_empty()).then(|| core_fun.to_string())
+            } else {
+                Some(subtitle.to_string())
+            }
+        })
+        .unwrap_or_default();
+    let world_key = format!("big-fish:{}", session.session_id);
+
+    upsert_profile_played_work(
+        ctx,
+        ProfilePlayedWorkUpsertInput {
+            user_id: input.user_id.clone(),
+            world_key: world_key.clone(),
+            owner_user_id: Some(session.owner_user_id.clone()),
+            profile_id: Some(session.session_id.clone()),
+            world_type: Some("BIG_FISH".to_string()),
+            world_title: title,
+            world_subtitle: subtitle,
+            played_at_micros: input.played_at_micros,
+        },
+    )?;
+    add_profile_observed_play_time(
+        ctx,
+        &input.user_id,
+        &world_key,
+        input.elapsed_ms,
+        input.played_at_micros,
+    )?;
+    let next_session = BigFishCreationSession {
+        session_id: session.session_id.clone(),
+        owner_user_id: session.owner_user_id.clone(),
+        seed_text: session.seed_text.clone(),
+        current_turn: session.current_turn,
+        progress_percent: session.progress_percent,
+        stage: session.stage,
+        anchor_pack_json: session.anchor_pack_json.clone(),
+        draft_json: session.draft_json.clone(),
+        asset_coverage_json: session.asset_coverage_json.clone(),
+        last_assistant_reply: session.last_assistant_reply.clone(),
+        publish_ready: session.publish_ready,
+        // 中文注释：正式进入已发布作品时同时累加作品播放数，用户侧去重由 profile_played_world 保证。
+        play_count: session.play_count.saturating_add(1),
+        created_at: session.created_at,
+        updated_at: played_at,
+    };
+    replace_big_fish_session(ctx, &session, next_session);
+
+    list_big_fish_works_tx(
+        ctx,
+        BigFishWorksListInput {
+            owner_user_id: String::new(),
+            published_only: true,
+        },
+    )
+}
+
 pub(crate) fn build_big_fish_session_snapshot(
     ctx: &ReducerContext,
     row: &BigFishCreationSession,
@@ -663,6 +783,7 @@ pub(crate) fn build_big_fish_work_summary(
         level_main_image_ready_count: coverage.level_main_image_ready_count,
         level_motion_ready_count: coverage.level_motion_ready_count,
         background_ready: coverage.background_ready,
+        play_count: row.play_count,
     })
 }
 
@@ -699,6 +820,7 @@ mod tests {
             asset_coverage_json: "{}".to_string(),
             last_assistant_reply: Some("欢迎来到大鱼吃小鱼共创。".to_string()),
             publish_ready: false,
+            play_count: 0,
             created_at: Timestamp::from_micros_since_unix_epoch(1),
             updated_at: Timestamp::from_micros_since_unix_epoch(1),
         }

server-rs/crates/spacetime-module/src/big_fish/tables.rs

@@ -17,6 +17,7 @@ pub struct BigFishCreationSession {
     pub(crate) asset_coverage_json: String,
     pub(crate) last_assistant_reply: Option<String>,
     pub(crate) publish_ready: bool,
+    pub(crate) play_count: u32,
     pub(crate) created_at: Timestamp,
     pub(crate) updated_at: Timestamp,
 }

server-rs/crates/spacetime-module/src/migration.rs

@@ -109,6 +109,8 @@ macro_rules! migration_tables {
             user_browse_history,
             profile_dashboard_state,
             profile_wallet_ledger,
+            profile_redeem_code,
+            profile_redeem_code_usage,
             profile_invite_code,
             profile_referral_relation,
             profile_played_world,
@@ -659,6 +661,19 @@ where
     Ok(wrapped.0)
 }
 
+fn normalize_migration_row(table_name: &str, value: &serde_json::Value) -> serde_json::Value {
+    let mut next_value = value.clone();
+    if table_name == "big_fish_creation_session" {
+        if let Some(object) = next_value.as_object_mut() {
+            // 中文注释：旧迁移包没有公开游玩次数字段，导入时按新建作品默认 0 兼容。
+            object
+                .entry("play_count".to_string())
+                .or_insert_with(|| serde_json::Value::from(0));
+        }
+    }
+    next_value
+}
+
 fn insert_migration_table_rows(
     ctx: &ReducerContext,
     table: &MigrationTable,
@@ -672,7 +687,8 @@ fn insert_migration_table_rows(
                         let mut imported = 0u64;
                         let mut skipped = 0u64;
                         for value in &table.rows {
-                            let row = row_from_json(value)
+                            let normalized_value = normalize_migration_row(stringify!($table), value);
+                            let row = row_from_json(&normalized_value)
                                 .map_err(|error| format!("{}: {error}", stringify!($table)))?;
                             let insert_result = ctx.db
                                 .$table()

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

@@ -1,3 +1,6 @@
+use crate::runtime::{
+    ProfilePlayedWorkUpsertInput, add_profile_observed_play_time, upsert_profile_played_work,
+};
 use module_puzzle::{
     PUZZLE_MAX_TAG_COUNT, PuzzleAgentMessageFinalizeInput, PuzzleAgentMessageKind,
     PuzzleAgentMessageRole, PuzzleAgentMessageSnapshot, PuzzleAgentSessionCreateInput,
@@ -1072,6 +1075,12 @@ fn start_puzzle_run_tx(
     .map(|value| value.profile_id.clone());
 
     increment_puzzle_profile_play_count(ctx, &entry_profile_row, input.started_at_micros);
+    upsert_puzzle_profile_played_work(
+        ctx,
+        &input.owner_user_id,
+        &entry_profile_row,
+        input.started_at_micros,
+    )?;
     insert_puzzle_runtime_run(ctx, &run, &input.owner_user_id, input.started_at_micros)?;
     Ok(run)
 }
@@ -1179,6 +1188,12 @@ fn advance_puzzle_next_level_tx(
         .find(&next_profile.profile_id)
     {
         increment_puzzle_profile_play_count(ctx, &next_profile_row, input.advanced_at_micros);
+        upsert_puzzle_profile_played_work(
+            ctx,
+            &input.owner_user_id,
+            &next_profile_row,
+            input.advanced_at_micros,
+        )?;
     }
     replace_puzzle_runtime_run(ctx, &row, &next_run, input.advanced_at_micros);
     Ok(next_run)
@@ -1219,6 +1234,13 @@ fn submit_puzzle_leaderboard_entry_tx(
         &input.run_id,
         input.submitted_at_micros,
     );
+    add_profile_observed_play_time(
+        ctx,
+        &input.owner_user_id,
+        &format!("puzzle:{}", input.profile_id),
+        input.elapsed_ms.max(1_000),
+        input.submitted_at_micros,
+    )?;
 
     let leaderboard_entries = list_puzzle_leaderboard_entries(
         ctx,
@@ -1607,6 +1629,28 @@ fn increment_puzzle_profile_play_count(
     );
 }
 
+fn upsert_puzzle_profile_played_work(
+    ctx: &TxContext,
+    user_id: &str,
+    row: &PuzzleWorkProfileRow,
+    played_at_micros: i64,
+) -> Result<(), String> {
+    // 拼图正式游玩以作品 profile_id 作为公开作品号，用户侧明细按 world_key 去重。
+    upsert_profile_played_work(
+        ctx,
+        ProfilePlayedWorkUpsertInput {
+            user_id: user_id.to_string(),
+            world_key: format!("puzzle:{}", row.profile_id),
+            owner_user_id: Some(row.owner_user_id.clone()),
+            profile_id: Some(row.profile_id.clone()),
+            world_type: Some("PUZZLE".to_string()),
+            world_title: row.level_name.clone(),
+            world_subtitle: row.summary.clone(),
+            played_at_micros,
+        },
+    )
+}
+
 fn replace_generated_candidate(
     draft: &mut PuzzleResultDraft,
     candidates: Vec<PuzzleGeneratedImageCandidate>,

server-rs/crates/spacetime-module/src/runtime/profile.rs

@@ -28,6 +28,39 @@ pub struct ProfileWalletLedger {
     pub(crate) created_at: Timestamp,
 }
 
+#[spacetimedb::table(accessor = profile_redeem_code)]
+pub struct ProfileRedeemCode {
+    #[primary_key]
+    pub(crate) code: String,
+    pub(crate) mode: RuntimeProfileRedeemCodeMode,
+    pub(crate) reward_points: u64,
+    pub(crate) max_uses: u32,
+    pub(crate) global_used_count: u32,
+    pub(crate) enabled: bool,
+    pub(crate) allowed_user_ids: Vec<String>,
+    pub(crate) created_by: String,
+    pub(crate) created_at: Timestamp,
+    pub(crate) updated_at: Timestamp,
+}
+
+#[spacetimedb::table(
+    accessor = profile_redeem_code_usage,
+    index(accessor = by_profile_redeem_code_usage_code, btree(columns = [code])),
+    index(accessor = by_profile_redeem_code_usage_user_id, btree(columns = [user_id])),
+    index(
+        accessor = by_profile_redeem_code_usage_code_user_id,
+        btree(columns = [code, user_id])
+    )
+)]
+pub struct ProfileRedeemCodeUsage {
+    #[primary_key]
+    pub(crate) usage_id: String,
+    pub(crate) code: String,
+    pub(crate) user_id: String,
+    pub(crate) amount_granted: u64,
+    pub(crate) created_at: Timestamp,
+}
+
 #[spacetimedb::table(accessor = profile_invite_code)]
 pub struct ProfileInviteCode {
     #[primary_key]
@@ -83,6 +116,17 @@ pub struct ProfilePlayedWorld {
     pub(crate) last_observed_play_time_ms: u64,
 }
 
+pub(crate) struct ProfilePlayedWorkUpsertInput {
+    pub(crate) user_id: String,
+    pub(crate) world_key: String,
+    pub(crate) owner_user_id: Option<String>,
+    pub(crate) profile_id: Option<String>,
+    pub(crate) world_type: Option<String>,
+    pub(crate) world_title: String,
+    pub(crate) world_subtitle: String,
+    pub(crate) played_at_micros: i64,
+}
+
 #[spacetimedb::table(accessor = profile_membership)]
 pub struct ProfileMembership {
     #[primary_key]
@@ -248,7 +292,7 @@ pub fn consume_profile_wallet_points_and_return(
         apply_profile_wallet_adjustment(
             tx,
             input.clone(),
-            RuntimeProfileWalletLedgerSourceType::AssetGenerationConsume,
+            RuntimeProfileWalletLedgerSourceType::AssetOperationConsume,
             true,
         )
     }) {
@@ -275,7 +319,7 @@ pub fn refund_profile_wallet_points_and_return(
         apply_profile_wallet_adjustment(
             tx,
             input.clone(),
-            RuntimeProfileWalletLedgerSourceType::AssetGenerationRefund,
+            RuntimeProfileWalletLedgerSourceType::AssetOperationRefund,
             false,
         )
     }) {
@@ -396,6 +440,64 @@ pub fn redeem_profile_referral_invite_code(
     }
 }
 
+// 兑换码奖励、usage 与钱包流水必须在同一事务内落库，避免到账和计次分离。
+#[spacetimedb::procedure]
+pub fn redeem_profile_reward_code(
+    ctx: &mut ProcedureContext,
+    input: RuntimeProfileRewardCodeRedeemInput,
+) -> RuntimeProfileRewardCodeRedeemProcedureResult {
+    match ctx.try_with_tx(|tx| redeem_profile_reward_code_record(tx, input.clone())) {
+        Ok(record) => RuntimeProfileRewardCodeRedeemProcedureResult {
+            ok: true,
+            record: Some(record),
+            error_message: None,
+        },
+        Err(message) => RuntimeProfileRewardCodeRedeemProcedureResult {
+            ok: false,
+            record: None,
+            error_message: Some(message),
+        },
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn admin_upsert_profile_redeem_code(
+    ctx: &mut ProcedureContext,
+    input: RuntimeProfileRedeemCodeAdminUpsertInput,
+) -> RuntimeProfileRedeemCodeAdminProcedureResult {
+    match ctx.try_with_tx(|tx| admin_upsert_profile_redeem_code_record(tx, input.clone())) {
+        Ok(record) => RuntimeProfileRedeemCodeAdminProcedureResult {
+            ok: true,
+            record: Some(record),
+            error_message: None,
+        },
+        Err(message) => RuntimeProfileRedeemCodeAdminProcedureResult {
+            ok: false,
+            record: None,
+            error_message: Some(message),
+        },
+    }
+}
+
+#[spacetimedb::procedure]
+pub fn admin_disable_profile_redeem_code(
+    ctx: &mut ProcedureContext,
+    input: RuntimeProfileRedeemCodeAdminDisableInput,
+) -> RuntimeProfileRedeemCodeAdminProcedureResult {
+    match ctx.try_with_tx(|tx| admin_disable_profile_redeem_code_record(tx, input.clone())) {
+        Ok(record) => RuntimeProfileRedeemCodeAdminProcedureResult {
+            ok: true,
+            record: Some(record),
+            error_message: None,
+        },
+        Err(message) => RuntimeProfileRedeemCodeAdminProcedureResult {
+            ok: false,
+            record: None,
+            error_message: Some(message),
+        },
+    }
+}
+
 pub(crate) fn list_profile_save_archive_rows(
     ctx: &ReducerContext,
     input: RuntimeProfileSaveArchiveListInput,
@@ -498,6 +600,172 @@ pub(crate) fn sync_profile_projections_from_snapshot(
     Ok(())
 }
 
+pub(crate) fn upsert_profile_played_work(
+    ctx: &ReducerContext,
+    input: ProfilePlayedWorkUpsertInput,
+) -> Result<(), String> {
+    let user_id = input.user_id.trim();
+    let world_key = input.world_key.trim();
+    if user_id.is_empty() {
+        return Err("profile_played_world.user_id 不能为空".to_string());
+    }
+    if world_key.is_empty() {
+        return Err("profile_played_world.world_key 不能为空".to_string());
+    }
+
+    let played_at = Timestamp::from_micros_since_unix_epoch(input.played_at_micros);
+    let played_world_id = format!("{user_id}:{world_key}");
+    let existing = ctx
+        .db
+        .profile_played_world()
+        .played_world_id()
+        .find(&played_world_id);
+
+    if let Some(existing) = existing {
+        ctx.db
+            .profile_played_world()
+            .played_world_id()
+            .delete(&existing.played_world_id);
+        ctx.db.profile_played_world().insert(ProfilePlayedWorld {
+            played_world_id,
+            user_id: user_id.to_string(),
+            world_key: world_key.to_string(),
+            owner_user_id: input.owner_user_id,
+            profile_id: input.profile_id,
+            world_type: input.world_type,
+            world_title: input.world_title,
+            world_subtitle: input.world_subtitle,
+            first_played_at: existing.first_played_at,
+            last_played_at: played_at,
+            last_observed_play_time_ms: existing.last_observed_play_time_ms,
+        });
+    } else {
+        ctx.db.profile_played_world().insert(ProfilePlayedWorld {
+            played_world_id,
+            user_id: user_id.to_string(),
+            world_key: world_key.to_string(),
+            owner_user_id: input.owner_user_id,
+            profile_id: input.profile_id,
+            world_type: input.world_type,
+            world_title: input.world_title,
+            world_subtitle: input.world_subtitle,
+            first_played_at: played_at,
+            last_played_at: played_at,
+            last_observed_play_time_ms: 0,
+        });
+    }
+
+    ensure_profile_dashboard_state(ctx, user_id, played_at);
+    Ok(())
+}
+
+pub(crate) fn add_profile_observed_play_time(
+    ctx: &ReducerContext,
+    user_id: &str,
+    world_key: &str,
+    elapsed_ms: u64,
+    observed_at_micros: i64,
+) -> Result<(), String> {
+    let user_id = user_id.trim();
+    let world_key = world_key.trim();
+    if user_id.is_empty() || world_key.is_empty() || elapsed_ms == 0 {
+        return Ok(());
+    }
+
+    let observed_at = Timestamp::from_micros_since_unix_epoch(observed_at_micros);
+    let played_world_id = format!("{user_id}:{world_key}");
+    if let Some(existing) = ctx
+        .db
+        .profile_played_world()
+        .played_world_id()
+        .find(&played_world_id)
+    {
+        ctx.db
+            .profile_played_world()
+            .played_world_id()
+            .delete(&existing.played_world_id);
+        ctx.db.profile_played_world().insert(ProfilePlayedWorld {
+            played_world_id,
+            user_id: existing.user_id,
+            world_key: existing.world_key,
+            owner_user_id: existing.owner_user_id,
+            profile_id: existing.profile_id,
+            world_type: existing.world_type,
+            world_title: existing.world_title,
+            world_subtitle: existing.world_subtitle,
+            first_played_at: existing.first_played_at,
+            last_played_at: observed_at,
+            last_observed_play_time_ms: existing
+                .last_observed_play_time_ms
+                .saturating_add(elapsed_ms),
+        });
+    }
+
+    add_profile_dashboard_play_time(ctx, user_id, elapsed_ms, observed_at);
+    Ok(())
+}
+
+fn ensure_profile_dashboard_state(ctx: &ReducerContext, user_id: &str, updated_at: Timestamp) {
+    if ctx
+        .db
+        .profile_dashboard_state()
+        .user_id()
+        .find(&user_id.to_string())
+        .is_some()
+    {
+        return;
+    }
+
+    ctx.db
+        .profile_dashboard_state()
+        .insert(ProfileDashboardState {
+            user_id: user_id.to_string(),
+            wallet_balance: 0,
+            total_play_time_ms: 0,
+            created_at: updated_at,
+            updated_at,
+        });
+}
+
+fn add_profile_dashboard_play_time(
+    ctx: &ReducerContext,
+    user_id: &str,
+    elapsed_ms: u64,
+    updated_at: Timestamp,
+) {
+    let current = ctx
+        .db
+        .profile_dashboard_state()
+        .user_id()
+        .find(&user_id.to_string());
+
+    if let Some(existing) = current {
+        ctx.db
+            .profile_dashboard_state()
+            .user_id()
+            .delete(&existing.user_id);
+        ctx.db
+            .profile_dashboard_state()
+            .insert(ProfileDashboardState {
+                user_id: user_id.to_string(),
+                wallet_balance: existing.wallet_balance,
+                total_play_time_ms: existing.total_play_time_ms.saturating_add(elapsed_ms),
+                created_at: existing.created_at,
+                updated_at,
+            });
+    } else {
+        ctx.db
+            .profile_dashboard_state()
+            .insert(ProfileDashboardState {
+                user_id: user_id.to_string(),
+                wallet_balance: 0,
+                total_play_time_ms: elapsed_ms,
+                created_at: updated_at,
+                updated_at,
+            });
+    }
+}
+
 fn sync_profile_dashboard_from_snapshot(
     ctx: &ReducerContext,
     snapshot: &RuntimeSnapshot,
@@ -1194,6 +1462,185 @@ fn redeem_profile_referral_invite_code_record(
     })
 }
 
+fn redeem_profile_reward_code_record(
+    ctx: &ReducerContext,
+    input: RuntimeProfileRewardCodeRedeemInput,
+) -> Result<RuntimeProfileRewardCodeRedeemSnapshot, String> {
+    let validated_input = build_runtime_profile_reward_code_redeem_input(
+        input.user_id,
+        input.code,
+        input.redeemed_at_micros,
+    )
+    .map_err(|error| error.to_string())?;
+    let redeemed_at = Timestamp::from_micros_since_unix_epoch(validated_input.redeemed_at_micros);
+    let user_id = validated_input.user_id;
+    let code = validated_input.code;
+    let redeem_code = ctx
+        .db
+        .profile_redeem_code()
+        .code()
+        .find(&code)
+        .ok_or_else(|| "兑换码不存在".to_string())?;
+
+    if !redeem_code.enabled {
+        return Err("兑换码已停用".to_string());
+    }
+    if redeem_code.reward_points == 0 {
+        return Err("兑换码奖励无效".to_string());
+    }
+
+    let user_used_count = count_profile_redeem_code_user_usage(ctx, &code, &user_id);
+    match redeem_code.mode {
+        RuntimeProfileRedeemCodeMode::Public if user_used_count >= redeem_code.max_uses => {
+            return Err("兑换次数已用完".to_string());
+        }
+        RuntimeProfileRedeemCodeMode::Unique
+            if redeem_code.global_used_count >= redeem_code.max_uses =>
+        {
+            return Err("兑换次数已用完".to_string());
+        }
+        RuntimeProfileRedeemCodeMode::Private => {
+            if !redeem_code
+                .allowed_user_ids
+                .iter()
+                .any(|item| item == &user_id)
+            {
+                return Err("该兑换码不适用于当前账号".to_string());
+            }
+            if redeem_code.global_used_count >= redeem_code.max_uses {
+                return Err("兑换次数已用完".to_string());
+            }
+        }
+        _ => {}
+    }
+
+    let usage_id = build_profile_redeem_code_usage_id(
+        ctx,
+        &code,
+        &user_id,
+        validated_input.redeemed_at_micros,
+    );
+    let wallet_ledger_id = format!("{}:ledger", usage_id);
+    let wallet_balance = apply_profile_wallet_delta(
+        ctx,
+        &user_id,
+        redeem_code.reward_points,
+        RuntimeProfileWalletLedgerSourceType::RedeemCodeReward,
+        &wallet_ledger_id,
+        redeemed_at,
+    )?;
+
+    ctx.db
+        .profile_redeem_code_usage()
+        .insert(ProfileRedeemCodeUsage {
+            usage_id,
+            code: code.clone(),
+            user_id,
+            amount_granted: redeem_code.reward_points,
+            created_at: redeemed_at,
+        });
+
+    let next_code = ProfileRedeemCode {
+        global_used_count: redeem_code.global_used_count.saturating_add(1),
+        updated_at: redeemed_at,
+        ..redeem_code
+    };
+    ctx.db.profile_redeem_code().code().delete(&code);
+    ctx.db.profile_redeem_code().insert(next_code);
+
+    let ledger_entry = ctx
+        .db
+        .profile_wallet_ledger()
+        .wallet_ledger_id()
+        .find(&wallet_ledger_id)
+        .ok_or_else(|| "兑换码钱包流水写入失败".to_string())?;
+
+    Ok(RuntimeProfileRewardCodeRedeemSnapshot {
+        wallet_balance,
+        amount_granted: ledger_entry.amount_delta.max(0) as u64,
+        ledger_entry: build_profile_wallet_ledger_snapshot_from_row(&ledger_entry),
+    })
+}
+
+fn admin_upsert_profile_redeem_code_record(
+    ctx: &ReducerContext,
+    input: RuntimeProfileRedeemCodeAdminUpsertInput,
+) -> Result<RuntimeProfileRedeemCodeSnapshot, String> {
+    let validated_input = build_runtime_profile_redeem_code_admin_upsert_input(
+        input.admin_user_id,
+        input.code,
+        input.mode,
+        input.reward_points,
+        input.max_uses,
+        input.enabled,
+        input.allowed_user_ids,
+        input.allowed_public_user_codes,
+        input.updated_at_micros,
+    )
+    .map_err(|error| error.to_string())?;
+    let updated_at = Timestamp::from_micros_since_unix_epoch(validated_input.updated_at_micros);
+    let allowed_user_ids = resolve_profile_redeem_code_allowed_user_ids(ctx, &validated_input)?;
+    let existing = ctx
+        .db
+        .profile_redeem_code()
+        .code()
+        .find(&validated_input.code);
+    let created_at = existing
+        .as_ref()
+        .map(|row| row.created_at)
+        .unwrap_or(updated_at);
+    let global_used_count = existing
+        .as_ref()
+        .map(|row| row.global_used_count)
+        .unwrap_or(0);
+
+    if let Some(existing) = existing {
+        ctx.db.profile_redeem_code().code().delete(&existing.code);
+    }
+
+    let row = ProfileRedeemCode {
+        code: validated_input.code,
+        mode: validated_input.mode,
+        reward_points: validated_input.reward_points,
+        max_uses: validated_input.max_uses,
+        global_used_count,
+        enabled: validated_input.enabled,
+        allowed_user_ids,
+        created_by: validated_input.admin_user_id,
+        created_at,
+        updated_at,
+    };
+    let inserted = ctx.db.profile_redeem_code().insert(row);
+    Ok(build_profile_redeem_code_snapshot_from_row(&inserted))
+}
+
+fn admin_disable_profile_redeem_code_record(
+    ctx: &ReducerContext,
+    input: RuntimeProfileRedeemCodeAdminDisableInput,
+) -> Result<RuntimeProfileRedeemCodeSnapshot, String> {
+    let validated_input = build_runtime_profile_redeem_code_admin_disable_input(
+        input.admin_user_id,
+        input.code,
+        input.updated_at_micros,
+    )
+    .map_err(|error| error.to_string())?;
+    let updated_at = Timestamp::from_micros_since_unix_epoch(validated_input.updated_at_micros);
+    let existing = ctx
+        .db
+        .profile_redeem_code()
+        .code()
+        .find(&validated_input.code)
+        .ok_or_else(|| "兑换码不存在".to_string())?;
+
+    ctx.db.profile_redeem_code().code().delete(&existing.code);
+    let inserted = ctx.db.profile_redeem_code().insert(ProfileRedeemCode {
+        enabled: false,
+        updated_at,
+        ..existing
+    });
+    Ok(build_profile_redeem_code_snapshot_from_row(&inserted))
+}
+
 fn build_profile_referral_invite_center_snapshot(
     ctx: &ReducerContext,
     user_id: &str,
@@ -1579,6 +2026,74 @@ fn latest_profile_recharge_order(
     orders.into_iter().next()
 }
 
+fn count_profile_redeem_code_user_usage(ctx: &ReducerContext, code: &str, user_id: &str) -> u32 {
+    ctx.db
+        .profile_redeem_code_usage()
+        .by_profile_redeem_code_usage_code_user_id()
+        .filter((code, user_id))
+        .count() as u32
+}
+
+fn build_profile_redeem_code_usage_id(
+    ctx: &ReducerContext,
+    code: &str,
+    user_id: &str,
+    redeemed_at_micros: i64,
+) -> String {
+    let sequence = count_profile_redeem_code_user_usage(ctx, code, user_id);
+    format!(
+        "redeem:{}:{}:{}:{}",
+        code, user_id, redeemed_at_micros, sequence
+    )
+}
+
+fn resolve_profile_redeem_code_allowed_user_ids(
+    ctx: &ReducerContext,
+    input: &RuntimeProfileRedeemCodeAdminUpsertInput,
+) -> Result<Vec<String>, String> {
+    if input.mode != RuntimeProfileRedeemCodeMode::Private {
+        return Ok(Vec::new());
+    }
+
+    let mut allowed_user_ids = input.allowed_user_ids.clone();
+    for public_user_code in &input.allowed_public_user_codes {
+        if let Some(account) = ctx
+            .db
+            .user_account()
+            .by_user_account_public_code()
+            .filter(public_user_code)
+            .next()
+        {
+            allowed_user_ids.push(account.user_id);
+        }
+    }
+    allowed_user_ids.sort();
+    allowed_user_ids.dedup();
+
+    if allowed_user_ids.is_empty() {
+        return Err("私有兑换码必须指定可兑换用户".to_string());
+    }
+
+    Ok(allowed_user_ids)
+}
+
+fn build_profile_redeem_code_snapshot_from_row(
+    row: &ProfileRedeemCode,
+) -> RuntimeProfileRedeemCodeSnapshot {
+    RuntimeProfileRedeemCodeSnapshot {
+        code: row.code.clone(),
+        mode: row.mode,
+        reward_points: row.reward_points,
+        max_uses: row.max_uses,
+        global_used_count: row.global_used_count,
+        enabled: row.enabled,
+        allowed_user_ids: row.allowed_user_ids.clone(),
+        created_by: row.created_by.clone(),
+        created_at_micros: row.created_at.to_micros_since_unix_epoch(),
+        updated_at_micros: row.updated_at.to_micros_since_unix_epoch(),
+    }
+}
+
 fn build_profile_wallet_ledger_snapshot_from_row(
     row: &ProfileWalletLedger,
 ) -> RuntimeProfileWalletLedgerEntrySnapshot {