Merge remote-tracking branch 'origin/master' into fix/acl-elevation-single-flight

2026-09-23 20:13:56 +08:00
parent d94ee96836 1b05a1d05e
commit f056c8a325
19 changed files with 510 additions and 35 deletions
@@ -9277,3 +9277,22 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 影响面：`apps/ai-game-creator-shell/src/view/project-development/chat/{conversation/directThreadChat.ts,controller/useDirectThreadChatSubscription.ts,controller/useDirectProjectChatController.ts}` 与 `apps/ai-game-creator-shell/tests/{directThreadChat.test.ts,appSurface/chat-composer.suite.ts}`。
 - 验证：reducer 新增 2 条用例（兜底收口后同名 `turn.started` 不复活且真终态仍能补上结束时间；身份不同的回合不动），appSurface 新增 `stops claiming the turn is running when a failed send left turn.started open`；变异验证：拿掉 controller 里的兜底收口调用后该用例变红（界面仍显示「陶泥儿正在处理」），恢复即绿。
 - 边界（未做）：根因仍在宿主侧——要在进程内保证开闭配对，应由 Rust 在回合函数退出（含 panic / 任务中止）时补一条终态事件（drop 守卫）；本次只做到前端不再跟着说谎。另：兜底收口的回合没有终态时间，仍会落进「`finished` 但拿不到终态时间」那个已知缺口（终态文案要不要藏，见 `DirectProjectTurn.tsx` 与 `DirectChatTurnState` 注释里的 A 项）。
+
+## 2026-09-23 后台 Dashboard「消耗泥点」改为对冲退还后的净消耗
+
+- 背景：Dashboard 的「消耗泥点数」只累计负向消费流水，生成失败退还、精选审核返还和 LLM Router 正向冲正都不参与抵扣，运营看到的「总消耗」明显高于用户实际花费（用户现场反馈）。
+- 决策：`GET /admin/api/dashboard` 的 `consumedMudPoints` 改为净消耗。先按北京时间业务日累计 `asset_operation_consume` / `llm_router_consume` 的负向流水绝对值，再用同期 `asset_operation_refund` 正向流水和 `llm_router_consume` 正向冲正流水按日抵扣：先抵当日消耗，不足再回溯抵扣最近仍有净额的业务日，抵扣不完的退还丢弃。因此每日净额非负，区间合计严格等于「消耗 − 退还」。新增 `refundedMudPoints` 与「退还泥点」趋势图，前台「消耗泥点数」卡旁并列「退还泥点数」卡，毛消耗可由「消耗 + 退还」核出，不把退还金额藏进净额。
+- 边界（本次不改）：用户详情「历史花费」（`profile_wallet_consumption_total` 投影与手动对账）维持既有「退款不冲减」决策，仍只累计负向消费流水；若要改成净额，必须单独走投影语义 + 对账口径变更，不能顺手改这一处。充值退款追回、余额重置、赠送和 hold 继续不计入消耗。
+- 影响范围：`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/AdminDashboardPage.tsx`、对应用例与 `docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md`。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server dashboard_consumption`（新增 4 条净额用例全绿）；`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server admin`（136 passed / 0 failed / 1 ignored）；`npm run admin-web:typecheck`；`npx vitest run apps/admin-web/src`（218 passed）；`npm run check:encoding`、`git diff --check`。
+
+## 2026-09-23 后台充值订单实付口径、发放泥点列、用户累计充值与兑换码单位
+
+- 背景：充值管理列表与用户详情把订单金额当实付展示，未支付订单也显示非 0 实付；发放泥点挤在「金额 / 泥点」一格或商品列小字里；用户详情看不到该用户累计充值额度；兑换码页的奖励数字没有单位，运营无法判断是元还是泥点。
+- 决策（实付只有支付过的订单才有）：`AdminRechargeOrderEntryPayload` 新增 `paidAmountCents`，由 api-server 按订单 `paid_at` 是否存在判定——存在才等于订单金额，未支付 / 已关闭 / 已过期固定为 0。后台前端实付列显示 `未支付`（并附订单金额小字），退款面板「订单实付」读同一字段；订单金额 `amountCents` 不再被当作实付。
+- 决策（发放泥点独立成列）：充值管理列表的表头由「金额 / 泥点」拆成「实付」与「发放泥点」两列，用户详情充值订单表同样新增「发放泥点」列，商品列只保留商品名；未支付订单发放为 0 泥点，与实付口径一致。
+- 决策（累计充值由后端算）：用户详情新增 `cumulativeRechargedCents`，api-server 按 `user_id` 读取 `profile_recharge_order`、只累加 `paid_at` 存在的订单金额（退款不回减），单次读取上限 500 行；读取失败或命中上限返回 `null`，前端显示「读取失败」，不用用户详情最多 20 条订单在 BFF 或前端近似重算。此次只新增 BFF 字段，未改 SpacetimeDB 表结构与 procedure。
+- 决策（兑换码奖励是泥点）：兑换码 `rewardPoints` 是奖励泥点（兑换成功按 `redeem_code_reward` 流水进钱包），后台输入标签改为「奖励泥点」、列表列头与单元格都带「泥点」单位。
+- 影响范围：`server-rs/crates/api-server/src/{admin.rs,admin_recharge.rs}`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/api/adminApiTypes.ts`、`apps/admin-web/src/pages/{AdminRechargeOrderPage.tsx,AdminRedeemCodePage.tsx}`、`apps/admin-web/src/components/AdminUserDetailDialog.tsx`、对应三个用例文件与后端架构数据契约文档。
+- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml --bin api-server cumulative_recharge`（2 条新用例）与 `cargo check -p api-server`；`npm run admin-web:typecheck`；`npx vitest run apps/admin-web/src`（220 passed），其中三个定向文件 33 passed（新增「未支付订单不显示实付金额，发放泥点单独成列」与「累计充值读取不到时展示未知，不用订单列表近似」）。
+- 边界（未验证）：未连真实生产库核对历史订单的累计充值数值，也未跑真实栈 API smoke。
@@ -5947,3 +5947,11 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **现象**：模板清单里的封面 URL 失效（或离线）时，卡片封面上出现浏览器的破碎图片图标，比没有封面更难看。
 - **处理**：`TemplateCard` 的 `img` 加 `onError` 直接把自身 `visibility` 设为 `hidden`（不进 state，卡片是 memo 的纯展示组件），留下封面容器本身的中性底色；单测用 `fireEvent.error(cover)` 钉住。
 - **关联**：`apps/ai-game-creator-shell/src/view/template-library/TemplateCard.tsx`、`apps/ai-game-creator-shell/tests/templateLibraryView.test.tsx`。
+
+## 2026-09-23 渠道 `--config` 只写窗口标题，打包产物系统标题栏回来了且登录请求被 ACL 拒绝
+
+- **现象**：dev 渠道 0.1.129 安装包启动后，窗口顶部同时出现系统标题栏（浅蓝条 + 原生最小化/最大化/关闭）与前端自绘 `WindowChrome`；窗口缩到 816x639（约 800x600 客户区）；登录页常驻「无法连接登录服务，请确认配套后端或 API 代理已启动后重试」。应用日志同一秒出现 `startup.window-title.failed: 缺少 client 主窗口`，而 `https://dev.genarrative.world` 在浏览器/curl 下可正常响应。
+- **原因**：`ebb288a6a`（2026-09-23 18:49）为统一渠道产品名，在渠道配置里加了 `app: { windows: [{ title: productName }] }`。Tauri 的 `--config` 合并是 JSON Merge Patch（`tauri-utils/build.rs` 用 `json_patch::merge`）：对象递归合并、**数组整体替换**。基线窗口数组被整条换掉后，`label` 回落到默认 `main`（不是 `client`）、`decorations` 回落到 `true`、尺寸回落到 800x600。三条症状同源：① `decorations: true` → 系统标题栏；② 尺寸回落 → 816x639；③ label 不再是 `client` → `capabilities/main.json`（`windows: ["client"]`，承载 `http:default` 与平台 API scope、dialog/opener/updater/剪贴板权限）整条不命中，前端 `fetchClientHttp` 走 `@tauri-apps/plugin-http` 时被 ACL 拒绝并抛错，登录状态检查就报成"连不上服务器"。判断关键：**这类"连不上服务"是权限拒绝，不是网络故障——先看窗口 label 与 capability 的 `windows` 是否还对得上，别去查后端与代理**。
+- **处理（现行口径）**：`createChannelConfig()` 从基线 `src-tauri/tauri.conf.json` 读完整 client 窗口对象后展开、只覆盖 `title`（`readBaseClientWindow()`），渠道配置不得再出现"只写 `title`"的窗口对象。新增守卫：`build-release.test.mjs` 用同语义的 merge patch 复现 Tauri 合并并断言 `label=client` / `decorations=false` / 1280x800 / min 1280x720 且承载 `http:default` 的 capability 必须包含该 label；`check-config.mjs` 增补基线 `decorations !== false` 失败关闭。
+- **验证**：`node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs scripts/cargo-features.test.mjs scripts/release-oss.test.mjs scripts/prepare-macos-codex.test.mjs`（60/60）、`node apps/ai-game-creator-shell/scripts/check-config.mjs` 通过；`createChannelConfig('dev', …)` 实测输出含 `label: client` 与 `decorations: false`。修复后的安装包尚未重新构建与安装，真机观感与登录链未复核。
+- **关联**：`apps/ai-game-creator-shell/scripts/build-release.mjs`、`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、`apps/ai-game-creator-shell/scripts/check-config.mjs`、`apps/ai-game-creator-shell/src-tauri/capabilities/main.json`、`docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。
@@ -22,7 +22,8 @@
 ## 指标口径

 - 生产素材数：`editor_project_resource` 中 `source_type = 'generated'` 的资源，按 `created_at` 映射到北京时间业务日。
- 消耗泥点数：`profile_wallet_ledger` 中 `source_type = asset_operation_consume` 且 `amount_delta < 0` 的流水绝对值，按 `created_at` 映射到北京时间业务日。
+- 消耗泥点数（净消耗）：`profile_wallet_ledger` 中 `source_type` 为 `asset_operation_consume` / `llm_router_consume` 且 `amount_delta < 0` 的流水绝对值，按 `created_at` 映射到北京时间业务日后，再按日对冲同期退还泥点——先抵当日消耗，不足再回溯抵扣最近仍有净额的业务日，抵扣不完的退还丢弃，因此每日净额非负，区间合计严格等于「消耗 − 退还」。充值退款追回、余额重置、赠送和 hold 都不计入。
+- 退还泥点数：`source_type = asset_operation_refund` 的正向流水（生成失败退还、精选审核返还）与 `llm_router_consume` 的正向冲正流水，按 `created_at` 映射到北京时间业务日。它只对冲本看板的消耗口径，不改变用户详情「历史花费」按既有决策的退款不冲减口径。
 - 总注册用户：`profile_dashboard_state` 行数。
 - 新增用户数：`profile_dashboard_state` 中 `created_at` 落在当前筛选时间窗内的账号数，按北京时间业务日归属，支持本日 / 本周 / 本月快捷日期范围。
 - 新增用户付费率：分母为当前筛选时间窗内的新增用户，分子为这些用户中截至本次查询时已至少完成一次真实支付的去重人数。真实支付以 `profile_recharge_order.paid_at` 存在且不晚于本次查询时刻为准；只创建订单或未支付订单不计，已退款订单仍表示曾经发生过付费转化，因此保留在分子。返回付费人数、新增用户数和四舍五入后的基点率；分母为 0 时 DTO 返回 0，前端百分比显示 `-`。
@@ -33,6 +34,7 @@
 - 留存活跃：用户在注册日恰好 `D+1` / `D+7` 的 `tracking_daily_stat` 中存在上述有效 user scope 行；同一用户同日多个事件只计一次，不按“1 / 7 天内累计回访”计算。筛选范围约束注册 cohort，观察日允许晚于筛选结束日。
 - 留存成熟条件：目标观察日必须早于当前北京时间业务日；观察日为今天时因当天尚未完整结束而排除。D1、D7 的可观察人数通常不同，分别返回 `eligibleUsers`、`retainedUsers` 与 `rateBasisPoints = round(retainedUsers * 10000 / eligibleUsers)`；分母为 0 时 DTO 返回 0，前端百分比显示 `-`。汇总率按总人数加权，不平均每日百分比。
 - 运营汇总页签：复用同一时间窗，展示运营指标卡、素材类型分布和访问模块分布。
+- 趋势图：`消耗泥点` 图展示按日对冲之后的净额，区间合计与「消耗泥点数」指标一致；`退还泥点` 图展示同期退还金额，毛消耗可由「消耗 + 退还」核出，避免把退还金额藏进净额里。

 ## 前后端文件

@@ -136,7 +136,8 @@
 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
 - 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
- 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier` 与 updater 端点：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
+- 渠道 `--config` 在 Tauri 构建前最后合并，同时注入 `productName`、`identifier`、updater 端点与窗口标题：安装身份与更新端点必须来自同一个渠道，不能各自回读默认值。macOS 发布入口构建 `*.app`、updater 归档与 DMG 前先按发布渠道解析产品名，产物名一律派生而不写死。
+- 渠道配置走 Tauri 的 JSON Merge Patch 语义：对象递归合并，**数组整体替换**。因此 `app.windows` 必须按基线 `tauri.conf.json` 的完整 client 窗口对象下发、只覆盖 `title`（脚本从基线读取后展开）；任何"只写 `{ title }`"的写法都会让 `label` / `decorations` / 尺寸回落成 Tauri 默认值（`label=main`、`decorations=true`、800x600），表现为打包产物重新出现系统标题栏，并按 label 连带失效承载平台 HTTP 权限等 capability。守卫用例：`build-release.test.mjs` 的渠道配置合并用例与 `check-config.mjs` 的 `decorations` 门禁。
 - 定时调度分别判断服务端与客户端 scope：dev 小时调度在提交含 AGC 相关路径时发布对应渠道，纯文档或流水线自身的提交仍只跑 Full Build；release 每日调度在服务端相关路径变化时发布正式 Full Build，在 AGC 相关路径变化时发布 release 客户端，并在同一调度内等待、汇总各 lane 结果，失败 lane 下一轮补发。判定失败或勾选强制触发时按"需要发布"处理。
 - 更新摘要不再自动生成：发布脚本不读取提交记录生成 `notes`；只有 `AGC_UPDATE_RELEASE_NOTES` 非空时，才把显式手动文案写入渠道清单和旧协议清单的 `releaseNotes`。未设置时清单不携带更新说明，归档文件 `release-notes.txt` 记录“本次没有可用的更新摘要”。
 - 清单里的 `commit` 是非标准字段：更新插件忽略未知字段；发布脚本只为线上排障保留源码 revision，不驱动更新摘要。
@@ -176,7 +176,7 @@ npm run check:server-rs-ddd
 22. 后台主动退款只支持 `wechat_mp`、`wechat_jsapi`、`wechat_h5`、`wechat_native` 普通 V3 泥点订单。`api-server` 必须先按正式支付渠道和商品类型拦截不支持的订单，再做微信支付订单查单预检，然后调用 SpacetimeDB procedure 原子创建退款 hold；只有 hold 成功才允许调用微信退款。`wechat_mp_virtual`、历史非正式渠道值、会员、未支付、对账未完成、退款已满额、人工冻结、退款欠账或永久泥点不足必须在调用普通 V3 provider 前 fail-closed。
 23. `profile_recharge_refund_hold` 以稳定 `out_refund_no` 为主键，保存订单、用户、本次退款金额、占用永久泥点、管理员、原因和 `active / settled / released` 状态。重试只有在订单、`out_refund_no`、退款金额、管理员和归一化原因全部与原 hold 一致时才可复用，任一不一致都按幂等内容冲突 fail-closed，不能用新原因调用微信后保留旧审计。部分退款的 hold 在累计应追回增量之外额外保留 1 泥点并发舍入缓冲，全额退款不加缓冲；活动 hold 不改变钱包总额，但普通钱包消费必须预留全部活动 hold；成功退款 observation 扣款并结算匹配 hold，关闭退款释放 hold，外部退款追回不得消耗其他活动 hold。
 24. 退款欠账继续以 `profile_recharge_order_refund_settlement.unrecovered_points` 为唯一真相；不新增平行 debt 累计。`profile_wallet_manual_restriction` 只保存人工冻结，普通消费同时检查人工冻结与退款欠账。后续永久泥点到账后继续偿还欠账，每日免费与会员周期泥点不参与；解除人工冻结不得清除退款欠账限制。
-25. 管理员充值订单、用户详情、历史花费手动对账、退款预检/执行、应急退款号登记、退款人工复核和钱包冻结接口只留在 `api-server` 管理员鉴权路由。用户详情中的历史花费泥点数读取 `profile_wallet_consumption_total` 投影；已有投影时，每次 `asset_operation_consume` 负向流水落账在同一事务内按主键 O(1) 原子累加，退款不回减，充值退款追回、余额重置、赠送和 hold 均不计入。首次上线必须在停止业务写入的维护窗口内，由 owner 调用 `POST /admin/api/profile/users/initialize-consumption-projections`，一次扫描全部权威钱包流水，为每个已有钱包流水的用户初始化存量投影；接口成功后才能恢复流量。维护遗漏或新用户缺行时，首次消费按该用户索引一次性重建（当前消费流水已经在同一事务中，不能重复加本次金额）；钱包详情首次读取也保留同一按用户兜底。`POST /admin/api/profile/users/reconcile-consumption` 是显式手动对账入口：owner 始终可用，member 必须单独持有 `profile-wallet-consumption-reconcile` 操作权限，任何一级 Tab 都不自动附带；用户详情只在后端返回 `canReconcileConsumption=true` 时展示按钮。操作经二次确认后扫描该用户全部权威钱包流水、比较并校准投影，同时记录管理员和对账时间。退款人工复核 BFF 必须从管理员会话写入操作人，要求非空原因，返回微信退款交易号、订单总额以及获批错误码等正式审计字段，并调用 runtime service identity 受限 procedure；后台确认面板必须展示这些后端事实，前端不得自行改 settlement、钱包冻结或消费累计。外部微信副作用由 `platform-wechat` 执行，退款/hold/钱包事务留在 `spacetime-module`，后台前端只展示 BFF 返回的正式状态。
+25. 管理员充值订单、用户详情、历史花费手动对账、退款预检/执行、应急退款号登记、退款人工复核和钱包冻结接口只留在 `api-server` 管理员鉴权路由。用户详情中的历史花费泥点数读取 `profile_wallet_consumption_total` 投影；已有投影时，每次 `asset_operation_consume` 负向流水落账在同一事务内按主键 O(1) 原子累加，退款不回减，充值退款追回、余额重置、赠送和 hold 均不计入。首次上线必须在停止业务写入的维护窗口内，由 owner 调用 `POST /admin/api/profile/users/initialize-consumption-projections`，一次扫描全部权威钱包流水，为每个已有钱包流水的用户初始化存量投影；接口成功后才能恢复流量。维护遗漏或新用户缺行时，首次消费按该用户索引一次性重建（当前消费流水已经在同一事务中，不能重复加本次金额）；钱包详情首次读取也保留同一按用户兜底。`POST /admin/api/profile/users/reconcile-consumption` 是显式手动对账入口：owner 始终可用，member 必须单独持有 `profile-wallet-consumption-reconcile` 操作权限，任何一级 Tab 都不自动附带；用户详情只在后端返回 `canReconcileConsumption=true` 时展示按钮。操作经二次确认后扫描该用户全部权威钱包流水、比较并校准投影，同时记录管理员和对账时间。退款人工复核 BFF 必须从管理员会话写入操作人，要求非空原因，返回微信退款交易号、订单总额以及获批错误码等正式审计字段，并调用 runtime service identity 受限 procedure；后台确认面板必须展示这些后端事实，前端不得自行改 settlement、钱包冻结或消费累计。外部微信副作用由 `platform-wechat` 执行，退款/hold/钱包事务留在 `spacetime-module`，后台前端只展示 BFF 返回的正式状态。充值订单实付金额（`paidAmountCents`）同样由后端判定：只有 `paid_at` 存在的订单才有实付，未支付、已关闭、已过期订单固定为 `0`，后台前端不得拿订单金额（`amountCents`）顶替实付；订单发放泥点（`pointsDelta`）必须与实付分开成列展示。用户详情的累计充值金额（`cumulativeRechargedCents`）由 api-server 按 `user_id` 受控读取 `profile_recharge_order`、只累加 `paid_at` 存在的订单 `amount_cents`（退款不回减）得出；读取失败或命中单次读取上限时返回 `null`，前端按未知展示，不得用用户详情最多 20 条订单在 BFF 或前端近似重算。

 ## 用户钱包与编辑器生成扣费契约

@@ -767,7 +767,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - Rust 结构体：`ProfileRedeemCode`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
 - 生效时间：复用邀请码时间窗口语义，`starts_at` / `expires_at` 均可为空；两者同时存在时必须满足 `starts_at < expires_at`。开始时刻计入有效区间，截止时刻不计入有效区间。用户兑换时以后端接收的 `redeemed_at_micros` 判定：未到开始时间拒绝为“兑换码未生效”，到达或超过截止时间拒绝为“兑换码已过期”。
- 后台契约：`AdminUpsertProfileRedeemCodeRequest` 通过可空 `startsAt` / `expiresAt` 接收 RFC3339 时间，列表与保存响应同步返回这两个字段；后台页只负责输入、回填和显示，真正兑换判定留在后端事务路径。
+- 后台契约：`AdminUpsertProfileRedeemCodeRequest` 通过可空 `startsAt` / `expiresAt` 接收 RFC3339 时间，列表与保存响应同步返回这两个字段；后台页只负责输入、回填和显示，真正兑换判定留在后端事务路径。`reward_points` 是奖励泥点（兑换成功后按 `redeem_code_reward` 流水进入泥点钱包），不是金额；后台奖励输入与列表必须带泥点单位。

 ### `profile_redeem_code_usage`