extract recharge logic

docs/project-memory/shared-memory/decision-log.md

@@ -4813,3 +4813,10 @@
 - 就绪边界：HTTP `/readyz` 同时验证调用池握手和缓存读连接；required subscription 失败必须不就绪。非 HTTP worker / controller 不创建缓存读连接，继续使用 1 条调用连接和各自的队列窄订阅。
 - 运维口径：`GENARRATIVE_SPACETIME_POOL_SIZE=8` 表示 8 条调用连接，HTTP 基础拓扑另加 1 条缓存读连接；外部生成和充值过期监听的独立窄订阅不计入该值。读模型行缓存从 8 份降为 1 份，但 SDK 空 table metadata、8 条调用 socket 和 runner 仍存在，不承诺总 RSS 等比例降为八分之一。
 - 验证方式：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`；发布后在 8 个调用槽暖机后对比 api-server cgroup memory / PSS，并确认 `/readyz` 与代表性 gallery、公开详情、创作入口和用户标签读取正常。
+
+## 2026-07-17 主站与 AI 游戏创作客户端复用微信 Native 充值生命周期
+
+- 背景：主站个人中心已具备微信 Native 二维码确认重试和 SSE 自动到账监听，AI 游戏创作客户端又在大型 `App.tsx` 中维护一套简化充值状态，关闭、迟到响应和终态语义容易继续分叉。
+- 决策：`packages/shared` 的充值组件目录新增宿主无关的 `useWechatNativeRechargeController`，通过注入确认、监听和余额快照回调统一管理二维码校验、手动确认重试、SSE 监听、终态映射和 lifecycle 隔离。主站只把 Native 分支委托给共享 controller，H5、JSAPI、小程序、登录恢复、任务和邀请码仍留在原 controller；AI 游戏创作客户端通过本地 `useRechargeController` 托管弹窗加载与固定 `wechat_native` 下单，`App.tsx` 只负责视图接线。
+- 余额边界：AI 游戏创作客户端的 `useWalletStore.mudPointBalance` 仍是唯一余额真相；充值响应只把后端完整快照写入 store，支付成功后触发完整刷新，不在客户端本地推算或增减泥点。
+- 验证方式：共享 hook Vitest、AI 游戏创作客户端充值与 Wallet Store 定向测试、主站充值渠道定向测试、两个 TypeScript 边界、`npm run check:encoding` 和 `git diff --check`。

docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md

@@ -88,7 +88,7 @@ V1.18 开发窗口把模式扩展为 `执行 / 聊天 / 目标`，Goal 创建和
 
 以下能力清单保留 Runtime V1 的演进记录；其中“App 进程内 tokio task”“跨进程同项目写入不作为支持目标”和“恢复到当前 App 进程”的旧描述均已由 V1.1 替代。当前边界是 App / CLI 只落账并唤醒同一发布二进制的独立 Runner，append-only JSONL 使用进程内锁加 OS 文件锁，恢复继续由 Runner 接管同一 run / session。
 
-客户端泥点余额统一由 `apps/ai-game-creator-shell/src/stores/useWalletStore.ts` Zustand store 持有，唯一余额真相是 `mudPointBalance`。`ProfileDashboardSummary.walletBalance` 不作为余额来源；所有可能改变余额的动作统一调用 `onWalletBalanceMayHaveChanged()` 从 recharge-center 完整刷新，不在客户端本地增减余额。账单请求、充值产品内容、下单 / 支付确认和弹窗状态留在使用它们的组件，侧栏账户菜单直接订阅该 store，不通过布局 props 传递余额。
+客户端泥点余额统一由 `apps/ai-game-creator-shell/src/stores/useWalletStore.ts` Zustand store 持有，唯一余额真相是 `mudPointBalance`。`ProfileDashboardSummary.walletBalance` 不作为余额来源；充值中心、下单和支付确认返回的后端余额快照统一写入该 store，支付成功后再调用 `onWalletBalanceMayHaveChanged()` 完整刷新，不在客户端本地增减余额。账单请求状态留在使用它的组件；充值弹窗加载与下单状态收口到客户端 `useRechargeController`，微信 Native 二维码、确认重试、SSE 到账监听和迟到响应隔离复用 `packages/shared` 的 `useWechatNativeRechargeController`。侧栏账户菜单直接订阅钱包 store，不通过布局 props 传递余额。
 
 Agent Runtime 负责：
 
@@ -530,7 +530,7 @@ game-project/
 - 聊天输入 `/publish` 只使用主窗口当前已加载的 manifest、最近 run trace、预览状态、资产来源和最近命令摘要，在聊天里生成发布准备清单，列出原型通过状态、预览、任务、资产、音频、包装说明和试玩包导出状态，并提供 `/run`、`/trace`、`/agent-resume ` 或 `/export` 草稿；该命令不调用 Tauri 读写、不启动或打开预览、不读取文件、不新增普通用户面板，真正导出仍由用户发送 `/export` 并走确认流。
 - 开发窗口可从 Agent 状态列表进入单个专业 Agent 对话并管理其 Session；正式用户项目开发页只读展示专业 Agent 协作状态，不提供单 Agent 对话入口、Session 控件或工具台。
 - v1 普通用户登录后直接进入单窗口客户端首页；同一窗口中切换首页、项目组、指南 / 反馈和项目开发页。项目组页管理最近项目、打开项目、新建项目和显示目录；打开项目只切换到项目开发页，不调用 `open_game_creator_workspace_window` 打开第二窗口。旧 Tauri 窗口 command 只保留兼容，不进入用户主流程。
-- 2026-07-16 补充，2026-07-17 扩展：普通用户窗口顶部账户资产统一复用 `PlatformMudPointWalletEntry`；首屏余额来自 `/api/profile/dashboard`，展开时按需读取 `/api/profile/recharge-center` 中的泥点拆分。顶部资产“充值”与侧栏账户菜单“充值泥点”共用 `PlatformProfileRechargeModal`，桌面壳固定使用 `wechat_native` 下单并在弹窗内完成扫码与到账确认，成功后同步刷新顶部余额和泥点拆分。“使用详情”统一打开 `packages/shared` 中的 `PlatformProfileWalletLedgerModal`，由各宿主分别维护打开、加载、失败重试状态并读取 `/api/profile/wallet-ledger`，共享组件只承接账单来源文案、金额与日期展示及 loading / empty / error 视图，不发请求、不持有账户事实。AI 游戏创作壳的 Tailwind 入口必须显式扫描 `packages/shared/src/components`，避免共享组件的 utility 样式在构建时被遗漏。
+- 2026-07-16 补充，2026-07-17 扩展：普通用户窗口顶部账户资产统一复用 `PlatformMudPointWalletEntry`；余额统一来自 `/api/profile/recharge-center` 的 `mudPointBalance`，不再把 `/api/profile/dashboard` 的兼容总额作为客户端余额真相。顶部资产“充值”与侧栏账户菜单“充值泥点”共用 `PlatformProfileRechargeModal`，桌面壳固定使用 `wechat_native` 下单并在弹窗内完成扫码与到账确认；客户端充值 controller 与主站共同复用共享 Native 支付 controller，统一处理二维码校验、手动确认重试、SSE 自动到账监听和关闭后的迟到响应，成功后同步刷新顶部余额和泥点拆分。“使用详情”统一打开 `packages/shared` 中的 `PlatformProfileWalletLedgerModal`，由各宿主分别维护打开、加载、失败重试状态并读取 `/api/profile/wallet-ledger`，共享组件只承接账单来源文案、金额与日期展示及 loading / empty / error 视图，不发请求、不持有账户事实。AI 游戏创作壳的 Tailwind 入口必须显式扫描 `packages/shared/src/components`，避免共享组件的 utility 样式在构建时被遗漏。
 - 主窗口可通过系统文件管理器显示当前项目目录，也可在聊天输入 `/open-project` 走同一只读打开动作；该操作只打开本地目录，不初始化项目、不写项目文件、不切换工作区。主窗口头部显示最近 `.agent/run.latest.json` 的 run 状态摘要和当前项目预览状态，并通过“刷新状态”重新读取同一 trace，不新增状态数据库。
 - 首页、项目组页和项目开发页共用单窗口壳的全局运行时配置弹窗，读写 Tauri 应用配置目录中的 `game-creator.config.json`；正式 Supervisor 项目页缺配置时只显示错误，不自动打开该弹窗。API Key 仍不进入本地项目、trace、manifest 或聊天记录。
 - 首页发送和项目组新建都通过 Tauri 原生目录选择器选择项目路径；用户取消目录选择时不覆盖已有输入或草稿。