1

docs/technical/PROFILE_NEW_USER_WALLET_REWARD_2026-05-01.md

@@ -0,0 +1,34 @@
+# 新用户注册默认光点落地说明
+
+## 目标
+
+每个新注册用户默认获得 `10` 个光点。赠送必须由后端统一落账，前端只展示余额和流水，不在本地补发或推算。
+
+## 落账规则
+
+1. 默认赠送数量固定为 `10`，由 `module-runtime` 暴露常量，避免不同 crate 散落数字。
+2. 钱包余额继续使用 `profile_dashboard_state.wallet_balance`，流水继续使用 `profile_wallet_ledger`。
+3. 新增流水来源 `new_user_registration_reward`，用于区分注册赠送、邀请奖励、充值和兑换码。
+4. 注册赠送的流水 ID 固定为 `new-user-registration:{user_id}`，SpacetimeDB procedure 内做幂等保护，重复调用不重复加钱。
+5. 手机号注册、开发密码自动注册、微信新用户绑定手机号后激活，都必须调用同一个注册赠送入口。
+6. 微信 callback 阶段只会生成待绑定手机号的临时账号，不在该阶段赠送；只有绑定新手机号并激活该微信账号时才赠送。若绑定到已有手机号账号，则不补发注册赠送。
+7. 注册赠送和邀请码奖励可以叠加。先发注册赠送，再处理邀请码奖励时，新用户最终余额为 `10 + 邀请奖励`。
+
+## 存档同步约束
+
+`runtime_snapshot.game_state.playerCurrency` 是运行态内的旧货币字段，不允许覆盖已经存在真实钱包业务流水的账户余额。只要用户已有非 `snapshot_sync` 的钱包流水，后续存档同步只能累计游玩时长和玩过世界，不再用 `playerCurrency` 回写 `wallet_balance`。
+
+这样可以避免新用户注册赠送的 `10` 个光点，在首次保存 `playerCurrency = 0` 的运行态快照时被覆盖成 `0`。
+
+## 影响文件
+
+1. `server-rs/crates/module-runtime/src/lib.rs`
+2. `server-rs/crates/spacetime-module/src/runtime/profile.rs`
+3. `server-rs/crates/spacetime-client/src/runtime.rs`
+4. `server-rs/crates/api-server/src/phone_auth.rs`
+5. `server-rs/crates/api-server/src/password_entry.rs`
+6. `server-rs/crates/api-server/src/wechat_auth.rs`
+7. `server-rs/crates/shared-contracts/src/runtime.rs`
+8. `packages/shared/src/contracts/runtime.ts`
+9. `src/components/rpg-entry/RpgEntryHomeView.tsx`
+