Merge pull request #1 from codex/profile-redeem-code

profile redeem code and dev password registration
2026-04-28 14:49:15 +08:00
parent 3cdbf36859 1d319ba916
commit 3c5ba97775
32 changed files with 1836 additions and 281 deletions
--- a/docs/technical/PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md
+++ b/docs/technical/PASSWORD_ENTRY_FLOW_DESIGN_2026-04-21.md
@@ -1,6 +1,8 @@
 # 密码登录入口历史落地设计

 > 2026-04-25 更新：当前产品策略已调整为“不开放密码注册”。新用户必须通过手机号验证码注册/登录，密码登录只面向已经登录后设置过密码的手机号账号。`POST /api/auth/entry` 只接受 `phone + password`，不支持邮箱、用户名或叙世号登录，也不承担自动建号能力。本文原有“密码自动建号”内容仅作为历史背景保留，当前落地以本更新和 [PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md](./PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md) 为准。
+>
+> 2026-04-28 更新：为开发期本地/测试服联调新增服务端环境变量 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED`，默认 `false`。仅当该变量显式为 `true` 时，`POST /api/auth/entry` 可对未知手机号用本次密码直接创建账号并登录；默认关闭时仍严格保持未知手机号返回 `401` 的生产语义。该开关不得用于生产环境，也不新增任何前端规则说明文案。

 日期：`2026-04-21`

@@ -166,6 +168,13 @@
 2. 不创建账号。
 3. 不写 `password_hash`。

+开发期例外：
+
+1. 当 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true` 时，未知手机号会创建手机号账号。
+2. 新账号立即写入本次密码的 `password_hash`，并将 `password_login_enabled` 置为 `true`。
+3. 成功响应沿用密码登录响应体，`created` 只保留在领域结果中，不额外暴露到当前 HTTP contract。
+4. 手机号格式和密码长度校验仍完全沿用正式密码入口规则。
+
 ### 8.2 未设置密码

 当账号存在但 `password_login_enabled = false` 时：
@@ -233,6 +242,8 @@
 4. 邮箱、用户名或叙世号作为密码登录标识返回 `400`。
 5. 登录成功时返回 access token。
 6. 登录成功时写回 refresh cookie。
+7. `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED` 默认关闭时行为不变。
+8. 开关开启时，未知手机号可通过 `/api/auth/entry` 创建账号并登录；同手机号后续用相同密码登录复用同一用户，错误密码仍返回 `401`。

 ## 13. 完成定义

--- a/docs/technical/PROFILE_REDEEM_CODE_IMPLEMENTATION_2026-04-28.md
+++ b/docs/technical/PROFILE_REDEEM_CODE_IMPLEMENTATION_2026-04-28.md
@@ -0,0 +1,131 @@
+# 资料兑换码模块落地设计
+
+## 1. 目标
+
+本轮在现有“我的”资料与钱包 projection 上新增兑换码能力。用户兑换成功后直接增加叙世币余额，写入 `profile_wallet_ledger`，并同步刷新 `profile_dashboard_state.wallet_balance`。
+
+管理侧本轮只提供后端 API，不新增管理后台页面。私有兑换码创建时支持内部 `userId` 与公开叙世号两类输入，后端创建阶段统一解析成内部 `userId` 存储。
+
+## 2. 兑换码类型
+
+`RuntimeProfileRedeemCodeMode` 固定为三种：
+
+| 类型 | 规则 |
+| --- | --- |
+| `Public` | 任意用户可兑换，`max_uses` 按用户独立计算。 |
+| `Unique` | 任意用户可兑换，`max_uses` 全局共用。 |
+| `Private` | 仅 `allowed_user_ids` 中的用户可兑换，`max_uses` 全局共用。 |
+
+兑换码入库前必须 `trim + uppercase`。空兑换码、奖励为 0、次数为 0 均拒绝。
+
+## 3. 表结构
+
+### 3.1 `profile_redeem_code`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `code` | `String` | 主键，标准化后的兑换码。 |
+| `mode` | `RuntimeProfileRedeemCodeMode` | 兑换码模式。 |
+| `reward_points` | `u64` | 单次到账叙世币。 |
+| `max_uses` | `u32` | 公共码为单用户上限，唯一码/私有码为全局上限。 |
+| `global_used_count` | `u32` | 全局已使用次数。公共码也记录总使用次数，但不参与公共码上限判断。 |
+| `enabled` | `bool` | 是否启用。 |
+| `allowed_user_ids` | `Vec<String>` | 私有码允许用户；公共/唯一码存空数组。 |
+| `created_by` | `String` | 管理员用户 ID。 |
+| `created_at` | `Timestamp` | 创建时间。 |
+| `updated_at` | `Timestamp` | 更新时间。 |
+
+### 3.2 `profile_redeem_code_usage`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `usage_id` | `String` | 主键，格式 `redeem:{code}:{user_id}:{micros}:{sequence}`。 |
+| `code` | `String` | 兑换码。 |
+| `user_id` | `String` | 兑换用户。 |
+| `amount_granted` | `u64` | 到账叙世币。 |
+| `created_at` | `Timestamp` | 兑换时间。 |
+
+索引：`code`、`user_id`、`(code, user_id)`。
+
+## 4. SpacetimeDB 过程
+
+### 4.1 用户兑换
+
+`redeem_profile_reward_code(input: RuntimeProfileRewardCodeRedeemInput) -> RuntimeProfileRewardCodeRedeemProcedureResult`
+
+流程：
+
+1. 标准化 code。
+2. 校验兑换码存在、启用、奖励大于 0。
+3. 按模式校验使用范围与次数。
+4. 同一事务内写入 `profile_redeem_code_usage`、增加钱包余额、写入 `profile_wallet_ledger`，最后更新 `profile_redeem_code.global_used_count`。
+5. 返回 `walletBalance`、`amountGranted` 与本次 `ledgerEntry`。
+
+### 4.2 管理创建/更新
+
+`admin_upsert_profile_redeem_code(input: RuntimeProfileRedeemCodeAdminUpsertInput) -> RuntimeProfileRedeemCodeAdminProcedureResult`
+
+私有码必须至少解析出一个内部用户 ID。公共码与唯一码忽略 allowed 列表并存空数组。
+
+### 4.3 管理停用
+
+`admin_disable_profile_redeem_code(input: RuntimeProfileRedeemCodeAdminDisableInput) -> RuntimeProfileRedeemCodeAdminProcedureResult`
+
+只更新 `enabled=false` 与 `updated_at`，不存在时返回“兑换码不存在”。
+
+## 5. Axum API
+
+用户接口：
+
+- `POST /api/profile/redeem-codes/redeem`
+- `POST /api/runtime/profile/redeem-codes/redeem`
+
+请求：`{ "code": "WELCOME2026" }`
+
+成功返回：
+
+```json
+{
+  "walletBalance": 130,
+  "amountGranted": 100,
+  "ledgerEntry": {
+    "id": "redeem:WELCOME2026:user:1777392000000000:0",
+    "amountDelta": 100,
+    "balanceAfter": 130,
+    "sourceType": "redeem_code_reward",
+    "createdAt": "2026-04-28T00:00:00Z"
+  }
+}
+```
+
+管理员接口：
+
+- `POST /admin/api/profile/redeem-codes`
+- `POST /admin/api/profile/redeem-codes/disable`
+
+管理员接口复用现有 `require_admin_auth`。
+
+## 6. 错误文案
+
+| 场景 | message |
+| --- | --- |
+| 空 code | `兑换码不能为空` |
+| 不存在 | `兑换码不存在` |
+| 停用 | `兑换码已停用` |
+| 奖励为 0 | `兑换码奖励无效` |
+| 次数耗尽 | `兑换次数已用完` |
+| 私有码账号不匹配 | `该兑换码不适用于当前账号` |
+| 私有码无允许用户 | `私有兑换码必须指定可兑换用户` |
+
+## 7. 前端交互
+
+“我的”页头像右侧入口由 `会员充值` 改为 `兑换码`。点击打开独立模态窗口，窗口内只保留输入框、兑换按钮和后端返回提示，不展示兑换规则说明。
+
+成功后展示 `已到账 X 叙世币`，并刷新 profile dashboard。失败后直接展示后端 `message`。
+
+## 8. 测试矩阵
+
+- Rust/module-runtime：覆盖公共码、唯一码、私有码、失败场景、流水来源和余额累加。
+- Axum：覆盖用户鉴权、管理员鉴权、runtime error 到 400 的映射和兼容路径。
+- 前端：覆盖入口替换、独立 modal、成功刷新余额和失败展示后端 message。
+- 验证命令：`cargo test`、目标前端测试、`npm run api-server:maincloud`、`npm run check:encoding`。
--- a/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
+++ b/docs/technical/SPACETIMEDB_TABLE_CATALOG.md
@@ -23,7 +23,7 @@ spacetime sql <db> "SELECT * FROM custom_world_gallery_entry"
 | 领域 | 表 |
 | --- | --- |
 | 认证 | `auth_store_snapshot`, `user_account`, `auth_identity`, `refresh_session` |
-| 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `profile_played_world`, `profile_save_archive` |
+| 运行时档案 | `runtime_setting`, `runtime_snapshot`, `user_browse_history`, `profile_dashboard_state`, `profile_wallet_ledger`, `profile_redeem_code`, `profile_redeem_code_usage`, `profile_played_world`, `profile_save_archive` |
 | RPG 运行时 | `story_session`, `story_event`, `npc_state`, `inventory_slot`, `battle_state`, `treasure_record`, `quest_record`, `quest_log`, `player_progression`, `chapter_progression` |
 | 世界创作 | `custom_world_profile`, `custom_world_session`, `custom_world_agent_session`, `custom_world_agent_message`, `custom_world_agent_operation`, `custom_world_draft_card`, `custom_world_gallery_entry` |
 | 拼图 | `puzzle_agent_session`, `puzzle_agent_message`, `puzzle_work_profile`, `puzzle_runtime_run` |
@@ -133,6 +133,27 @@ SELECT * FROM profile_wallet_ledger WHERE user_id = '<user_id>';
 SELECT * FROM profile_wallet_ledger WHERE user_id = '<user_id>' ORDER BY created_at DESC;
 ```

+### `profile_redeem_code`
+
+- 作用：运营发放的叙世币兑换码，支持公共码、唯一码和私有码。
+- 结构：`code PK: String`, `mode: RuntimeProfileRedeemCodeMode`, `reward_points: u64`, `max_uses: u32`, `global_used_count: u32`, `enabled: bool`, `allowed_user_ids: Vec<String>`, `created_by: String`, `created_at: Timestamp`, `updated_at: Timestamp`。
+- 索引：主键 `code`。
+
+```sql
+SELECT * FROM profile_redeem_code WHERE code = '<CODE>';
+```
+
+### `profile_redeem_code_usage`
+
+- 作用：记录每一次兑换行为，为公共码用户维度计次、唯一/私有码全局计次提供依据。
+- 结构：`usage_id PK: String`, `code: String`, `user_id: String`, `amount_granted: u64`, `created_at: Timestamp`。
+- 索引：`code`, `user_id`, `(code, user_id)`。
+
+```sql
+SELECT * FROM profile_redeem_code_usage WHERE code = '<CODE>';
+SELECT * FROM profile_redeem_code_usage WHERE user_id = '<user_id>';
+```
+
 ### `profile_played_world`

 - 作用：记录用户玩过的世界及最后游玩时间，用于个人页历史和继续游戏入口。