Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

docs/technical/ASSET_GENERATION_POINTS_CONSUMPTION_2026-04-27.md

@@ -0,0 +1,64 @@
+# 资产生成叙世币消耗接入方案
+
+## 背景
+
+当前叙世币钱包余额、充值流水与邀请奖励已经收口到 `server-rs/crates/spacetime-module/src/runtime/profile.rs`。资产图片生成由 Axum API 调用外部模型并写入 OSS，SpacetimeDB reducer/procedure 不能直接执行外部网络生成，因此扣费需要拆成两层：
+
+- SpacetimeDB 负责钱包余额和流水的原子变更。
+- Axum 负责在发起外部生成前扣费，并在生成或持久化失败时补偿退款。
+
+## 首期范围
+
+首期接入带 Bearer 身份、能明确归属真实用户的资产生成与发布入口：
+
+- `POST /api/custom-world/scene-image`
+- `POST /api/custom-world/cover-image`
+- `POST /api/runtime/custom-world/cover-image`
+- `POST /api/runtime/custom-world-library/{profile_id}/publish`
+- 自定义世界 Agent 动作 `publish_world`
+- Big Fish Agent 正式图片生成动作 `big_fish_generate_level_main_image`、`big_fish_generate_level_motion`、`big_fish_generate_stage_background`
+- Big Fish Agent 动作 `big_fish_publish_game`
+- Puzzle Agent 图片生成动作 `compile_puzzle_draft`、`generate_puzzle_images`
+- Puzzle Agent 动作 `publish_puzzle_work`
+
+暂不接入以下入口：
+
+- 旧资产工坊角色主形象/动作生成接口：当前仍使用 `asset-tool` 作为兼容归属，无法确认真实用户。
+- 手动上传封面：不调用外部生成模型，不消耗叙世币。
+- 自定义世界草稿自动补图链路：属于后台补全流程，避免一次用户操作触发多笔不可预期扣费。
+- 文本实体、NPC 生成：本次需求聚焦资产生成，首期只覆盖图片资产。
+
+## 计费规则
+
+- 每次图片资产生成请求消耗 `1` 枚叙世币。
+- 每次作品发布请求消耗 `1` 枚叙世币；余额不足时禁止发布。
+- 在调用外部图片生成前预扣，余额不足时直接返回业务错误，不调用外部模型。
+- 发布请求在写入发布状态前预扣，余额不足时直接返回业务错误，不调用发布 mutation。
+- 如果图片生成、远程下载、OSS 写入、资产记录确认或发布 mutation 失败，Axum 自动发起同额退款。
+- 如果退款失败，原始错误仍返回给调用方，同时服务端日志记录退款失败，便于后续人工核对。
+
+## 钱包流水
+
+新增两个流水来源类型，首期同时覆盖“资产生成”和“资产发布”这两类资产操作：
+
+- `asset_generation_consume`：资产生成预扣，`amount_delta = -1`。
+- `asset_generation_refund`：资产生成失败退款，`amount_delta = +1`。
+
+`wallet_ledger_id` 由 Axum 传入，格式：
+
+- 扣费：`asset_generation_consume:{user_id}:{asset_kind}:{asset_id}`
+- 退款：`asset_generation_refund:{user_id}:{asset_kind}:{asset_id}`
+
+SpacetimeDB procedure 对 `ledger_id` 做幂等保护：如果同一个流水 ID 已存在，则直接返回当前钱包快照，不重复变更余额。
+
+## 工程落点
+
+- `module-runtime`：新增钱包调整输入、钱包调整结果、流水来源枚举。
+- `spacetime-module`：新增 `consume_profile_wallet_points_and_return` 与 `refund_profile_wallet_points_and_return` procedure，并扩展钱包变更 helper 支持负数。
+- `spacetime-client`：新增对应调用方法和绑定类型。
+- `api-server`：在自定义世界图片生成与发布入口前扣费，错误分支退款。
+- `shared-contracts`：新增 API 流水来源常量，保证“我的-钱包流水”输出使用稳定契约字符串。
+
+## 非目标
+
+本次不做分档价格、不做会员免扣、不做前端计费展示改造，也不迁移旧 `server-node` 逻辑。旧资产工坊角色主形象/动作生成与发布接口仍需要先补齐 Bearer 身份归属后再纳入扣费范围。

docs/technical/MY_TAB_REFERRAL_AND_COMMUNITY_IMPLEMENTATION_2026-04-25.md

@@ -19,6 +19,7 @@
 - 奖励流水继续复用 `profile_wallet_ledger`，新增来源类型：
   - `invite_inviter_reward`
   - `invite_invitee_reward`
+- API 返回钱包流水时，`sourceType` 必须复用 `server-rs/crates/shared-contracts/src/runtime.rs` 中的常量，避免 SpacetimeDB 枚举映射和前端合同字符串漂移。
 
 ## SpacetimeDB 表设计
 

docs/technical/PUBLIC_WORK_CODE_MOBILE_SHARE_ENTRY_FIX_2026-04-25.md

@@ -14,6 +14,17 @@
 6. 作品详情返回必须恢复打开详情前的平台来源 Tab；从分类进入回分类，从首页进入回首页，从创作中心进入回创作中心。
 7. 所有入口保持轻量 UI，不写规则说明文案，不改变发布、下架、进入游戏的后端语义。
 
+## 作品分享路由补充
+
+1. 公开作品入口路由统一使用当前作品页面路径加 `work=作品号`：RPG 为 `/worlds/detail?work=CW-00000001`，拼图为 `/gallery/puzzle/detail?work=PZ-00000001`，大鱼玩法为 `/runtime/big-fish?work=BF-00000001`。
+2. 从公开广场、最近浏览、创作中心打开已发布作品详情或玩法时，若当前作品有公开作品号，地址栏必须同步追加 `work=作品号`；没有作品号的草稿详情仍保持无查询参数路径。
+3. 首次进入主应用时若 URL 带 `work` 查询参数，平台入口自动复用现有公开编号搜索逻辑打开对应作品详情，不新增独立详情系统。
+4. 详情页必须保留“复制作品号”和“分享作品”两个独立动作：
+   - 复制作品号只复制 `CW / PZ / BF` 编号。
+   - 分享作品复制一段邀请好友来玩的中文文本，文本内必须包含作品名、作品号和带 `work` 查询参数的完整网址。
+5. 分享复制使用现有剪切板兼容工具，Clipboard API 权限失败时走降级复制，并在按钮内短暂反馈 `已复制` 或 `复制失败`。
+6. UI 中只保留按钮级短文案，不写规则说明，不在详情页新增大段分享说明。
+
 ## 验收
 
 1. 399px 竖屏首页能直接看到并使用搜索入口。
@@ -23,3 +34,5 @@
 5. 桌面右侧趋势列表只显示排序和作品类型，不再显示 `1777110165.990127Z` 这类原始时间字符串，也不直接显示作品号。
 6. 在内嵌浏览器 Clipboard API 拒绝写入时，详情页与创作中心作品号复制仍能通过降级路径完成，并显示 `已复制` 或 `复制失败`。
 7. 打开拼图详情后点击返回，不再固定跳到创作中心，而是回到打开详情前的平台 Tab。
+8. 打开 `/?work=CW-00000001`、`/worlds/detail?work=CW-00000001`、`/gallery/puzzle/detail?work=PZ-00000001` 或 `/runtime/big-fish?work=BF-00000001` 后能自动进入对应公开作品详情或玩法。
+9. 点击详情页“分享作品”后，剪切板内容包含邀请文本、作品号和当前站点下带 `work=作品号` 的完整网址。