Merge remote-tracking branch 'origin/master' into feat/game-fork
Project CI / Backend tests (pull_request) Failing after 34s
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Successful in 7m27s
Project CI / Native shell tests (pull_request) Failing after 2m46s
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Successful in 5m58s
Project CI / AI game creator shell Rust crates (pull_request) Successful in 4m23s
Project CI / AI game creator shell web tests (pull_request) Failing after 45s
Project CI / Frontend tests (pull_request) Successful in 2m24s
Project CI / Repository checks (pull_request) Failing after 1m1s
Project CI / Backend tests (pull_request) Failing after 34s
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Successful in 7m27s
Project CI / Native shell tests (pull_request) Failing after 2m46s
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Successful in 5m58s
Project CI / AI game creator shell Rust crates (pull_request) Successful in 4m23s
Project CI / AI game creator shell web tests (pull_request) Failing after 45s
Project CI / Frontend tests (pull_request) Successful in 2m24s
Project CI / Repository checks (pull_request) Failing after 1m1s
# Conflicts: # apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs # apps/ai-game-creator-shell/src/components/game-distribution/GameDistributionPublishPanel.tsx # apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx # docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md # package.json # packages/shared/src/contracts/gameDistribution.ts # scripts/check-game-distribution-dto-parity.mjs # server-rs/crates/api-server/src/modules/game_distribution.rs # server-rs/crates/module-game-distribution/src/errors.rs # server-rs/crates/module-game-distribution/src/lib.rs # server-rs/crates/shared-contracts/src/game_distribution.rs # server-rs/crates/spacetime-client/src/active.rs # server-rs/crates/spacetime-client/src/active/mapper.rs # server-rs/crates/spacetime-client/src/active/mapper/game_distribution.rs # server-rs/crates/spacetime-client/src/game_distribution.rs # server-rs/crates/spacetime-client/src/module_bindings.rs # server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_snapshot_type.rs # server-rs/crates/spacetime-client/src/module_bindings/game_distribution_game_type.rs # server-rs/crates/spacetime-module/src/game_distribution.rs # server-rs/crates/spacetime-module/src/migration.rs # src/components/game-distribution/GameDetailPage.tsx # src/components/game-distribution/GameDistributionPages.test.tsx # src/components/game-distribution/GamePlayPage.tsx # src/components/platform-entry/PlatformEntryActiveFlowShell.tsx # src/services/gameDistributionClient.test.ts # src/services/gameDistributionClient.ts
This commit is contained in:
@@ -26,6 +26,7 @@
|
||||
- [后台游戏评价管理合同](./【玩法创作】平台入口与玩法链路-2026-05-15.md#后台游戏评价管理合同)：查找、分页、隐藏/恢复/删除、必填原因、统计与个人状态联动；已实现并通过本地验证，待用户验收，未部署。
|
||||
- [后台游戏评价管理里程碑](./project-memory/plans/【里程碑】后台游戏评价管理-2026-10-01.md)与[实施计划](./project-memory/plans/【实施计划】后台游戏评价管理-2026-10-01.md)：单里程碑范围、接口/schema 边界及验收要求；本地证据已回写主规范。
|
||||
- [游戏广场评分展示合同](./【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏广场评分展示合同)、[里程碑](./project-memory/plans/【里程碑】游戏广场评分展示-2026-10-01.md)与[实施计划](./project-memory/plans/【实施计划】游戏广场评分展示-2026-10-01.md)：已实现并通过本地定向验证，待用户验收，未部署；公开列表/详情携带真实摘要，卡片显示一位小数均分与人数，复用有效评价统计。
|
||||
- [游戏买断制泥点付费与播放鉴权合同](./【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏买断制泥点付费与播放鉴权合同)与[里程碑](./project-memory/plans/【里程碑】游戏买断制泥点付费与播放鉴权-2026-10-05.md)：已实现，本机真实栈 E2E 由人工验收脚本 `check:game-distribution-purchase-e2e` 覆盖（最近一次人工运行 76 PASS / 0 FAIL / 1 WARN），该脚本不在 CI 自动门禁内；待用户验收，未部署；作者可选买断制泥点付费，购买后永久可玩，后台审核可见价格且审核员不限次试用；网页与 AGC 两个发布入口一致支持定价并共用 `packages/shared` 组件 `PlatformGamePricingField`，AGC 定价的前端用例与 Rust 预填单测已覆盖，AGC 真实栈发布未覆盖。
|
||||
- [游戏游玩次数计数](./adr/【ADR】游戏游玩次数计数-2026-10-03.md)：点「开始游戏」前端上报一次游玩，api-server 纯内存聚合（5s flush、30min 去重、`IP+game` 限流、关停不强制 flush），批量 procedure 自增现有 `game_distribution_game.play_count`，不 bump `updated_at`。
|
||||
- [游戏共创与作品 Fork](./【技术方案】游戏共创与作品Fork-2026-10-03.md)：共创授权三态（只升不降）、作品级血缘与代际、成品包与工程源包两条改造路径、族谱树与溯源署名的产品设计与技术方案；同时作为该功能主规范，已评审通过，按 M1 逐里程碑实现。
|
||||
- [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)
|
||||
|
||||
@@ -0,0 +1,69 @@
|
||||
# 【里程碑】游戏买断制泥点付费与播放鉴权
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | implemented-awaiting-runtime-acceptance |
|
||||
| Date | 2026-10-05 |
|
||||
| Parent Spec | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`（「游戏买断制泥点付费与播放鉴权合同」章） |
|
||||
|
||||
## 目标
|
||||
|
||||
把游戏分发从“公开即免费可玩”扩展为“作者可选买断制泥点付费；其他用户购买后永久可玩；后台审核可见价格且审核员不限次试玩”。
|
||||
|
||||
## 范围
|
||||
|
||||
- 作者端定价：网页 `/games/publish` 与 AGC 发布面板在新建与更新模式选择“免费 / 买断制 N 泥点”；两入口共用 `packages/shared` 定价组件 `PlatformGamePricingField`，AGC 壳请求透传 `priceMudPoints`；给已上线作品发新版本时预填价格与模式，作者不改则价格不变。预填价口径：取该作品**最新版本的冻结价**（该版本可能是 `pending_review` / `rejected` 状态的版本，因此预填值可能尚未生效），仅当该冻结价缺失或为 0 时才回落作品行当前价，两条来源都取不到才按免费（0）。AGC 壳侧实现 `resolve_publication_prefill_price`（`apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:811`）；网页侧读版本详情 `detail.version.priceMudPoints ?? detail.game.priceMudPoints ?? 0`（`src/components/game-distribution/GamePublishPage.tsx:164`），后端 `version_detail_payload` 已把版本详情的 `game.priceMudPoints` 一并归一为同一冻结价口径（`server-rs/crates/api-server/src/modules/game_distribution.rs:3797`）。
|
||||
- 玩家端：公开详情展示价格与购买态、泥点购买、购买后游玩。
|
||||
- 付费游玩鉴权：未购买不得游玩，直连公开发行路径必须失败。
|
||||
- 泥点钱包扣费与 `game_purchase` 流水。
|
||||
- 后台审核详情与待审列表展示价格。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 创作者分成与结算、退款/撤销购买、促销/限时免费、订阅或游戏内购、价格运营审批流。
|
||||
- 评分/评论与付费的耦合、外部 OpenAPI。
|
||||
- 免费游戏现有链路的任何行为变化。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 现有游戏分发状态机、审核 CAS/幂等与版本冻结资料机制。
|
||||
- runtime profile 钱包的原子写与 `profile_wallet_ledger` 流水。
|
||||
- 现有发行网关 sandbox/CSP/Cookie 约束，以及后台待审版本预览会话（token 前缀承载相对资源）模式。
|
||||
- 主规范“游戏买断制泥点付费与播放鉴权合同”与本文档评审通过。评审前不写业务代码。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [x] 作者网页发布可选「免费」或「买断制 N 泥点」；负数/超上限/非整数被前后端同时拦截。证据：真实本地栈 E2E 价格 `1000001` → 400 且不落版本，`0` / `1000000` → 200；`cargo test -p module-game-distribution` 29 passed、`cargo test -p api-server game_distribution` 53 passed 覆盖定价校验，网页发布表单定价定向 Vitest 覆盖前端拦截。
|
||||
- [ ] AGC 发布面板与网页一致可选「免费 / 买断制 N 泥点」，非法值被前后端同时拦截；给已上线作品发新版本时按「最新版本冻结价优先、缺失或为 0 时才回落作品行当前价」预填价格与模式，作者不改则价格不变。
|
||||
- 已覆盖：AGC 发布面板定价定向 Vitest `apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx`（`:333` 默认免费提交 `priceMudPoints=0`；`:342` 买断制先本地校验：空值与 `1000001` 分别报「买断价必须是整数泥点」「买断价必须是 1 到 1000000 之间的整数泥点」且都不发发布请求，`120` 随版本提交 `priceMudPoints=120`；`:802` 历史响应没有回读价格时按免费预填；`:819` 更新模式预填线上买断价 240、作者不改仍按 240 提交）；AGC 壳请求层校验定向 Vitest `apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts`（`:180` 透传 `priceMudPoints=240`；`:197` `1000001` / `1.5` 在 native command 之前失败关闭）；预填口径 Rust 单测 `apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:1715`（`publication_prefill_price_prefers_latest_frozen_price_and_falls_back`：最新版本冻结价 300 优先于作品行 240、历史版本无冻结价回落 240、免费作品与缺字段按 0）；两入口共用 `packages/shared` 组件 `PlatformGamePricingField`。
|
||||
- **未覆盖，故本项保持未勾选**：AGC 真实栈「发布付费版本」未手点一次；真实本地栈 E2E 只覆盖网页发布入口的定价链路（`1000001` → 400 且不落版本、`0` / `1000000` → 200）。
|
||||
- [x] 后台审核详情展示该版本价格；无价格的历史版本按免费展示。证据：`cargo test -p api-server game_distribution` 53 passed（`private_version_payload` / `version_detail_payload` 输出 `priceMudPoints`，历史无价格版本按 0）；admin-web 审核价格展示定向 Vitest。
|
||||
- [x] 审核员不限次数试玩待审付费版本，不校验购买、不扣泥点。证据：真实本地栈 E2E 审核员两次试玩待审付费版本均 200、两次包内字节一致，作者与审核员余额/流水均不变。
|
||||
- [x] 未购买用户详情可见资料但无可播放入口；直连 `/games/<gameId>/` 返回 404。证据：真实本地栈 E2E 详情 `priceMudPoints=30` / `purchased=false` / `entryUrl=null`，发行网关与平台同源均 404，创建会话 403，未登录 401。
|
||||
- [x] 余额不足购买失败，余额、账单与购买记录都不变。证据：真实本地栈 E2E 返回 400 `INSUFFICIENT_MUD_POINTS`，余额与流水不变。
|
||||
- [x] 购买成功：余额减少 N、账单出现 `game_purchase` 流水、购买记录唯一、可反复游玩不再扣费。证据：真实本地栈 E2E 扣 30（120→90），`game_purchase` 流水与购买行各 1 条，重复进入不再扣费。
|
||||
- [x] 双击、并发与响应丢失重试只扣一次。证据：真实本地栈 E2E 同 key 重放、换 key 重复购买均不再扣费；两路不同 key 真并发返回 200/200、只有一个 `replayed=false`、余额只扣一次、购买记录 1 条。
|
||||
- [x] 作者本人与管理员免购买即可游玩付费作品且不扣费。证据：真实本地栈 E2E 作者（自购 400 `GAME_PURCHASE_OWNER_EXEMPT`、余额/流水不变、播放会话 200）与管理员（管理员令牌创建播放会话 200、入口 200）；管理员免购买经 play-session 管理员分支实现。
|
||||
- [x] 免费游戏的发布、详情、游玩与计数链路无行为变化。证据：真实本地栈 E2E 免费游戏详情保留入口、发行网关 200、匿名创建会话 200 且不签发令牌。
|
||||
|
||||
## 未覆盖边界（保持未勾选）
|
||||
|
||||
- [ ] 管理员安全下架后的播放会话失效：本轮未单独运行，与作者下架共用同一 404 关闭路径。
|
||||
- [ ] 多账号 / 多游戏混合并发购买：本轮只覆盖单游戏、单账号的两路真并发。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：Rust 定向测试（定价校验、购买幂等与并发、授权判定、状态机）、Vitest（发布表单定价、详情购买态、游玩页会话挂载、审核价格展示）、schema/绑定与编码门禁。
|
||||
- 运行时：真实本地栈跑通「发布付费游戏 → 后台审核可见价格并试玩 → 通过 → 未购买访问失败 → 购买 → 游玩 → 重复游玩不扣费」。
|
||||
- 边界：并发购买、余额不足、下架/封禁后播放会话失效、猜测 URL 直连、免费游戏回归。
|
||||
|
||||
## 验收证据摘要（真实栈 E2E）
|
||||
|
||||
- 验收命令：`npm run check:game-distribution-purchase-e2e`（等价于 `node scripts/check-game-distribution-purchase-e2e.mjs`，脚本入口见 `package.json:92`）。
|
||||
- 断言总数：该脚本内共 76 处 `check(...)` 调用；`check(name, ok, detail)`（脚本 `:86`）每条打印一行 `PASS` / `FAIL`，因此 76 即本轮断言总数。
|
||||
- 最近一次人工运行结论（2026-10-05，本机真实 SpacetimeDB / api-server / OSS）：**76 PASS / 0 FAIL / 1 WARN**（0 FAIL，进程退出码 0）。本节只记可复核的文本结论，不记耗时秒数。
|
||||
- 唯一 WARN：「管理员令牌购买」在现役登录链路下不可达 —— 后台管理员令牌在 `/api/*` 用户路由上先被 `require_bearer_auth` 判为无效登录态，走 401 前置，未进入 403 `GAME_PURCHASE_ADMIN_NOT_ALLOWED` 分支（该分支作为纵深防御保留）；管理员免购买由 play-session 管理员分支覆盖（脚本 `:1122`-`:1173`）。
|
||||
- WARN 语义：脚本的 `warn()`（`:91`）表示环境条件不满足而**跳过**的断言（例如未发现主站 Vite、`spacetime sql` 直查不可用），不是失败。
|
||||
- 脚本定位：**人工验收脚本，不在 CI 自动门禁内**（需真实 SpacetimeDB + api-server 与 `E2E_ADMIN_USER` / `E2E_ADMIN_PASSWORD` 环境变量），CI 绿不代表该链路已验证。
|
||||
- 交付状态：本里程碑结论最高到「本机真实栈验证通过，待用户验收，未部署」。
|
||||
@@ -1,5 +1,16 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-10-05 播放会话前缀在三处入口清空 Cookie，网关 403 纵深防御不变
|
||||
|
||||
- 背景：付费游戏的可玩入口是创建播放会话后拿到的 `/api/game-distribution/play-sessions/<token>/`（sandbox iframe 的 `src`，包内相对资源沿同一前缀解析）。该前缀落在 `/api/*` 上，边缘通用 `/api` location 必须转发 Cookie（`/api/auth/*` 需要 refresh cookie），而 `api-server` 播放网关对带可解析平台 refresh Cookie 的请求返回 403，导致真实浏览器里 iframe 与每个包内资源都 403、付费游戏实际不可玩。
|
||||
- 决策（边缘）：三份 nginx 模板（`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf`）在通用 `/api` location 之前内联 `location ^~ /api/game-distribution/play-sessions/`；代理头、`client_max_body_size 210m`、`limit_conn` / `limit_req`、超时与维护判断与通用 `/api` 保持一致，额外清空 Cookie。`^~` 必填（否则正则 location `~ ^/api(?:/|$)` 优先命中），且只匹配带尾斜杠的前缀。
|
||||
- 决策（dev）：`vite.config.ts` 在 `/api/game-distribution` 之前加同名前缀代理规则，`proxyReq.removeHeader('cookie')`。
|
||||
- 决策（网关）：`server-rs/crates/pingora-gateway` 新增 `RouteDecision::PlaySessionGateway`，与通用 `/api` 同口径（api 上游、api 限流分组、大小上限、维护闸），差别只在经新增的 `route_clears_cookie` 清空 Cookie（发行入口 `ReleaseGateway` 复用同一判定）。**不放宽** `api-server` 的 Cookie 拒绝。
|
||||
- 决策（边界）：前缀只认带尾斜杠的形式，创建会话的 `POST /api/game-distribution/play-sessions` 与 `POST /api/game-distribution/games/{gameId}/play-session` 继续走通用 `/api` 并保留 Cookie。
|
||||
- 门禁：矩阵新增 `play_sessions_gateway` 用例；`check:nginx-spa-routes` 新增「该前缀 location 存在、清空 Cookie、排在通用 `/api` 之前」断言，`check:pingora-route-parity` 新增「矩阵用例必须声明清 Cookie 且不得复用通用 `/api` location / Rust 播放会话分支必须排在通用 `/api` 之前」断言，`check:pingora-gateway-smoke` 新增真实网关下「该前缀清 Cookie、创建会话端点保留 Cookie」用例。
|
||||
- 影响面：`deploy/nginx/{genarrative.conf,genarrative-dev-http.conf,README.md}`、`deploy/container/nginx.conf`、`vite.config.ts`、`server-rs/crates/pingora-gateway/src/main.rs`、`deploy/pingora/nginx-route-parity.matrix.json`、`scripts/check-{nginx-spa-routes,pingora-route-parity,pingora-gateway-smoke}.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
- 关联：`docs/project-memory/shared-memory/pitfalls.md`「付费游戏播放会话前缀落在 `/api/*`」条。
|
||||
|
||||
## 2026-10-03 每日免费发放额为 0 时前端隐藏该池
|
||||
|
||||
- 背景：运营需要一个可逆的「不提供每日免费泥点」状态。不给它新增 `retired` 状态位或新字段，直接把后台配置 `daily_free_points_per_day` 配成 0，让「每日免费发放额」这个普通数值自己表达；前端据此隐藏每日免费相关入口。
|
||||
@@ -9,7 +20,6 @@
|
||||
- 影响范围：`packages/shared/src/utils/mudPoints.ts`、`PlatformMudPointWalletEntry`、`PlatformProfileRechargeModal`（池概览 3 列变 2 列、扣点顺序提示与泥点确认页文案随可见性切换）、`apps/admin-web/src/pages/AdminProfileWalletConfigPage.tsx`（每日免费允许填 0）、`server-rs/crates/module-runtime/{commands,errors,lib}.rs`；`daily_free_grant` / `daily_free_reset` 账本文案保留，历史流水不改写。
|
||||
- 验证：`cargo check -p module-runtime`、`cargo test -p module-runtime profile_wallet_config_allows_zero_daily_free_points`、`cargo fmt --check`、根 `npm run typecheck`、`npm run admin-web:typecheck`、共享层与 admin 定向 vitest 22/22、`npm run check:encoding`、`git diff --check` 通过。
|
||||
|
||||
|
||||
## 2026-10-05 创作者主页与关注粉丝的产品边界
|
||||
|
||||
- 产品已确认：桌面第四项“创作者主页”默认进入当前账号主页，“我的”移到第五项；他人的关注/粉丝列表公开可查看，自己或他人的两类列表均可点击用户进入其创作者主页。
|
||||
|
||||
@@ -2,6 +2,45 @@
|
||||
|
||||
这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
|
||||
|
||||
## 2026-10-05 PR #607 复核修复：档位点对齐/对比度、状态文案也走浮层、键盘去重、卸载 flush
|
||||
|
||||
- **档位圆点已删除（D1 的收口）**：这一轮把档位圆点**整体删除**（半透明备选方案未采用）。现在滑块只剩轨道 + 圆钮：轨道 6px 圆头、已选段 `--platform-accent` 由 `--strength-ratio` 驱动、**终点落在圆钮中心**（`calc(10px + ratio * (100% - 20px))`）、圆钮 20px 实心暖白（`--platform-panel-fill` + `--platform-subpanel-border` 1px 描边 + `color-mix` 柔影）；强度区横向内边距 `4px 6px 2px` → `4px 0 2px`（滑块铺满卡片内容宽度，填充段与圆钮两端与轨道两端贴齐）；相关 CSS（`space-between` 排布 / `z-index: 2` 抬层 / `.is-active{opacity:0}` / 点的 `color-mix` 底色 / 只为点对齐的 `padding: 0 7px`）与渲染标记一并删除。**判据**：`chatDialogFrameLayout.test.ts` 反向守卫（样式表里不再有 `.project-chat-composer-strength-stops` 规则、组件源码不再渲染该类名；滑块契约仍在：宽 100% / 高 26 / 圆钮 20×20、强度区左右内边距 0）+ `home.suite.ts` 首页菜单里查不到那组点。实测（447 视口，像素扫描）：轨道 90..324（宽 234 = 卡片内容宽），档位 0 时圆钮左缘 90.5（距轨道左端 0.5px）、档位 4 时圆钮右缘 322.3（距右端 1.8px，扫描行不在圆钮正中所以略窄），填充段终点落在**圆钮中心**（`calc(10px + ratio * (100% - 20px))`，被圆钮盖住），因此圆钮右侧不会露出橙色（终点曾写成 `20px + …` = 圆钮右缘，4× 设备像素下能看到一小截溢出）。**历史成因（只留一句，细节由 Git 追溯）**：圆点此前被 6px 轨道盖住、且与圆钮两端错位 ±12.2px，曾用「抬到轨道之上 + space-between 对齐 + 浅暖色」修过一轮，最终整体删除。
|
||||
- **状态文案（`role="status"`）也会顶高那一排（D2）**：`notice`（「模型列表已刷新」「正在刷新模型列表」「默认模型已停用」、推理档读取/保存失败）原先无条件渲染成控件里的 `role="status"`，`toast` 形态只接管了 `error`，于是 Direct 输入区仍会被一行状态文字顶成两行高。现行口径：浮层**收进组件内部**（`components/common/composerNotice.tsx` 的模块级单例 + toast 宿主），失败与状态分两条通道各自去重（同一条只弹一次、清空后可再弹），失败 `tone="error"`、状态 `tone="neutral"`；**任何宿主**的输入区子树里都不再有常驻 `role="alert"` / `role="status"` 行，宿主的 `errorPresentation` / `onUnavailable` / `onNotice` / `noticePresentation` 这套分支已删除。判据：`chat-composer.suite.ts`「routes model-list notices to the toast…」断言 Direct 输入区子树里 `[role='status']` 与 `[role='alert']` **都为 0**，且浮层在输入区之外。
|
||||
- **键盘长按每个事件都落盘（D5）**：range 的方向键在 Chromium 里每次重复都会补 `change`，旧行为 ~30 次/秒全量写盘（写链 + 持久化 + 回读）。现行口径：`selectEffort` 先比对「最近一次**落盘成功**的档位」（`persistedEffortRef`，挂载回读时就种上），相同则不写；连续调整只写**每个新档位**一次，钳位后的重复事件 0 次。实测（真实按键序列）：单击方向键 **1** 次落盘；长按 1.5s（34 个重复事件）**4** 次（`low/medium/high/max`，即每个新档位一次）；已在最高档继续长按 1.2s（28 个事件）**0** 次。
|
||||
- **拖动中途卸载会丢档位（D6）**：预览值只在 `change`/`keyup`/`pointerup`/`blur` 落盘，拖到一半被 Esc 关掉菜单或宿主卸载时不会提交。现行口径：卸载 cleanup 里 flush 一次（读 ref，不碰已卸载组件的 state）。实测：拖动到「中」未松手时落盘 0 次，`unmount()` 后恰好 **1** 次（`medium`）；单次拖动（按下 + 6 步横移 + 松手）全程 **1** 次（`high`），终值 = 松手位置。
|
||||
- **`forced-colors` 下焦点不可见（D4）**：高对比模式会丢弃 thumb 的 `box-shadow`，而焦点环正是画在 thumb 上的阴影。现行口径：加 `@media (forced-colors: active)` 回退 `outline: 2px solid Highlight; outline-offset: 2px`（系统色，不算新色值；只在 forced-colors 生效，亮色观感不变）。
|
||||
- **注释与实现必须同口径（D9）**：`.resource-reference-input` 的 `min-height: 0 / padding: 0` 原先写在文件末尾那条六类规则里靠**源码顺序**盖住前面的 `min-height: 56px / padding: 0 0 4px`，与「不依赖源码顺序」的注释矛盾。现行口径：几何（内边距 / 高度下界）写回 11520 行那条六类规则，末尾那条只留网格与行距，注释同步改成"不依赖源码先后"。
|
||||
- **深色主题下焦点环间隙不可靠（D3，仅记录不改代码）**：间隙色取 `--platform-input-fill`，深色主题该 token 只有 5% 不透明（`rgba(255,255,255,0.05)`），间隙会与焦点环颜色几乎一样。当前工作台根节点固定 `platform-theme--light`，走不到这条分支；将来真要启用深色主题，把间隙换成不透明 token 再验一次。
|
||||
|
||||
## 2026-10-05 模型菜单的观感是组件自带的共享样式面（首页同步复用）
|
||||
|
||||
- **现象**：工作台那颗 `ConversationModelSelect` 已经改成「强度区 + 模型列表」的卡片观感，但首页输入区右下角那颗（`className="home-input-model-select"`，同一个组件）还是**旧卡片**：161px 窄卡、10px 圆角、5px 内边距、32px 行高、旧灰投影。首页与工作台应当是同一套观感。
|
||||
- **成因**：#600 那轮把卡片 / 列表的新观感全挂在 `.game-workbench-chat .project-chat-surface.is-direct-codex .project-chat-composer.is-direct-codex …` 这条**宿主祖先链**上，于是只有工作台那一处命中；同一个组件换个宿主就退回基础规则。
|
||||
- **处理（现行口径）**：卡片 / 列表 / 行 / hover / 选中 pill / 细滚动条这套观感抬到**组件自带的共享样式面**——选择器只用组件类名（`.conversation-model-select .conversation-model-menu-shell`、`.conversation-model-select .conversation-model-menu`、`… .conversation-model-menu button…`），**不带任何宿主祖先链**；留在宿主作用域的只有工具栏几何（控制排的宽高与收缩、队列 chip、模型触发钮），**弹层锚点也是组件级**（`position: absolute; right: 0; bottom: calc(100% + 8px); z-index: 20`，见下方"后续"）。合并形态（有外壳）与独立形态（策划/画布直接渲染菜单）**同一套值**：卡 16px 圆角 / 12px 内边距 / 1px `--platform-line-soft` 描边 / `--platform-desktop-hover-shadow`；行 34px、圆角 9px、hover `--platform-nav-item-icon-fill`、选中 `--platform-warm-bg` + 600；独立形态的卡片自己就是滚动区（`max-height: 194 = 170 + 上下各 12`，与合并形态同高），外壳形态的列表 `max-height: 170`（5×34，不出现半行）。
|
||||
- **首页强度区（分两步收口）**：先只同步了卡片观感（当时首页那颗没有 effort 的 state / props，`view/home/index.tsx` 只传 `className` 与 `disabled`，直接加强度区等于新增一个首页从未暴露过的设置项）；随后按要求把强度区一并对齐，见下方"后续"。
|
||||
- **判据/取证**：`tests/appSurface/home.suite.ts`「首页模型菜单复用同一套共享样式面」——首页实例的 `.conversation-model-menu` 的祖先链里**没有** `.game-workbench-chat`，而只靠 `.conversation-model-select …` 就能解析出 16px 圆角 / 12px 内边距 / 34px 行，且菜单里确实有原生滑块（`input[type="range"]` 带 `aria-label="思维强度"`）；`tests/chatDialogFrameLayout.test.ts` 的外壳用例按新选择器集合更新（锚点与卡片观感都来自共享面，工作台作用域只剩工具栏几何）。真机实测（无头 Chromium，同一夹具同一裁剪框）：首页那颗 161×309 / 10px / 5px / 32px → **260×194 / 16px / 12px / 34px**（与工作台卡片逐项一致）；工作台那颗外壳 260×262.5、内层列表 234×170、行 34/9px **前后逐值不变**。
|
||||
- **边界**：策划面与画布也复用同一个组件 → 它们的菜单观感同样变成这张卡片（有意为之；窄面板下卡片最小宽度 260px，仍受 `calc(100vw - 24px)` 与各自锚点约束）。若某个宿主需要另一套尺寸，在**该宿主作用域**里覆盖，不要再把观感抄第二份。
|
||||
- **后续（同一批收口）**：强度区与外壳锚点也一并抬到共享面——`view/home/index.tsx` 给首页那颗传了**同一个** `ComposerReasoningEffortSelect`（`presentation="section"`，读写仍是组件自己的 `read_game_creator_app_config` / `select_game_creator_reasoning_effort`），首页因此与工作台逐项同形：外壳 260×262.5、强度区 234×60.5、列表 234×170、滑块 222×26（447 与 1200 两档实测一致；工作台回归后逐值不变）。抬升时必须删掉工作台作用域里两条**死重**规则（给旧独立「推理档」控件排版的 `display: inline-flex` 一族），否则它们会以更高特异性盖掉共享面的 `display: grid`，把强度区重新算宽 24px。
|
||||
- **滑块两点（最终收口）**：档位圆点先是改成派生浅暖色、直径收到 6px（= 轨道高度），随后**整体删除**（见上面 D1 条）。「进度条高度与滑块高度一致」保留两种解释对照：**变体 A 落地**（填充段 = 轨道高度 6px），**变体 B**（填充段做成 20px = 圆钮高度）只在夹具里渲染出图、未提交。
|
||||
|
||||
## 2026-10-05 给 `shared-contracts` 请求 DTO 加字段：`#[serde(default)]` 救不了 Rust 结构体字面量，AGC 壳编译失败会伪装成 `npm run dev:all` 起不来
|
||||
|
||||
- **现象**：`npm run dev:all` 的根栈五个服务与 AGC Vite 都就绪、终端也会打印启动汇总，但 AGC 窗口始终不出现；stdout 里夹着 `error[E0063]: missing field `price_mud_points`in initializer of`GameDistributionCreateVersionRequest``（`src\game_distribution_publish.rs:1356`）和 `error: could not compile `genarrative-ai-game-creator-shell` (bin ...) due to 1 previous error`。编译失败不会让 `tauri dev` 退出，dev:all 只会一直挂着（`waitForAgcFrontend` 的 660s 预算耗尽后才收束整棵树），容易被误判成端口占用或根栈没起来。
|
||||
- **根因**：变更在 `server-rs/crates/shared-contracts/src/game_distribution.rs` 给请求 DTO 末尾追加了 `#[serde(default)] pub price_mud_points: u64`。`serde(default)` 只影响**反序列化缺字段**，Rust **结构体字面量仍必须列全字段**。AGC 壳 `apps/ai-game-creator-shell/src-tauri` 是**独立 cargo workspace**（自带 `[workspace]`，只把 `shared-contracts` 当 path 依赖），`server-rs` 侧的 `cargo test -p ...` 六个 crate 全绿也覆盖不到它。
|
||||
- **处理（现行口径）**：改 `shared-contracts` 里**请求 DTO 字段**时，必须同一次编译 AGC 壳：先 `npm run agc:bundled-resources:prepare`（`build.rs` 只做只读校验，未准备资源会以「随包插件存在未声明文件」失败关闭），再 `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --features=cocos-editor-execute,unity-editor-execute,godot-editor-execute`（约 30s，feature 与 dev/release 对齐）；完整口径是 `npm run ai-game-creator-shell:check:rust`。定价字段的取值口径分两段：**历史口径**（2026-10-05 之前）AGC 发布面板没有买断制定价入口，构造版本请求时显式按免费提交 `price_mud_points: 0`，与升级前行为一致；**现行口径** AGC 发布面板已支持「免费 / 买断制」定价，请求按作者选择从载荷透传价格，`#[serde(default)]` 仅用于向后兼容不传该字段的旧客户端（按免费处理）。
|
||||
- **边界**：`cargo check` **不能省 feature 参数**——默认 feature 下 `build.rs` 会因为已 staging 的 godot/unity 插件 DLL「不在当前 feature 组合的声明清单里」而红，那是资源准备前置条件，不是本次代码的编译错误。门禁本身**已经存在**：CI `.gitea/workflows/project-ci.yml` 的 `AI game creator shell Rust lane 1/2`、`lane 2/2` 各顺序跑两片 `npm run check:native-shells:agc-rust-shard-N`（底层 `ai-game-creator-shell:check:rust:shell` → `cargo test --locked` 编出壳 bin），本地同序列是 `npm run check:native-shells`。漏拦的原因是本地验证只跑了 `server-rs` 侧 crate、没等 MR/CI 上的 AGC lane，不是缺门禁；因为 2466 条 bin 单测跑满很贵，**不要**把整条 lane 塞进常用本地命令，只在改动 shared-contracts 请求 DTO 时补上面的 `cargo check`。
|
||||
- **判据/取证**：E0063 原文（`logs/dev-all-feature.log`）；修复后 `tauri dev` watcher 重建输出 `Finished `dev` profile [unoptimized + debuginfo] target(s) in 38.16s` 并拉起 `target\debug\genarrative-ai-game-creator-shell.exe`；同一 feature 组合 `cargo check` 退出码 0；`.app/dev-stack.json` 记录的实际端口下 api-server `/healthz`、主站 `/`、admin-web `/admin/`、AGC marker `/__agc_dev_server.json` 均 200。
|
||||
- **关联**：`server-rs/crates/shared-contracts/src/game_distribution.rs`、`apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs`、`.gitea/workflows/project-ci.yml`、`scripts/check-native-shells.mjs`。
|
||||
|
||||
## 2026-10-05 付费游戏播放会话前缀落在 `/api/*`：边缘转发 Cookie 会让 iframe 与包内每个资源都 403
|
||||
|
||||
- **现象**：付费游戏在真实浏览器里打不开——播放会话 `src`（`/api/game-distribution/play-sessions/<token>/`）本身和包内每个相对资源（JS/CSS/图片/音频）全是 403，同一份包的免费游戏 `/games/<gameId>/` 正常。
|
||||
- **原因**：播放会话前缀落在 `/api/*` 上，而通用 `/api` location 必须转发 Cookie（`/api/auth/*` 依赖 refresh cookie）；`api-server` 播放网关对带**可解析平台 refresh Cookie** 的请求返回 403（与发行网关同族的纵深防御，本次不放宽），于是沙箱 iframe 的每个同前缀请求都带 Cookie、都被拒。dev 侧同样复现：`vite.config.ts` 原本只对 `/games/...` 清 Cookie，`/api/game-distribution` 规则会转发 Cookie。
|
||||
- **处理（现行口径）**：三份 nginx 模板（`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf`）在通用 `/api` location **之前**加 `location ^~ /api/game-distribution/play-sessions/`——`^~` 不能省，否则正则 location `~ ^/api(?:/|$)` 优先命中、Cookie 又被转发；代理头 / `client_max_body_size 210m` / `limit_conn` / `limit_req` / 超时 / 维护判断都与通用 `/api` 一致，只多一条 `proxy_set_header Cookie ""`。`vite.config.ts` 在 `/api/game-distribution` 之前加同名前缀规则（`proxyReq.removeHeader('cookie')`）。Pingora 侧对应 `RouteDecision::PlaySessionGateway`：路径原样走 api 上游，同样套 api 限流分组、大小上限与维护闸，差别只在新增的 `route_clears_cookie` 清空 Cookie（发行入口 `ReleaseGateway` 复用同一判定）。
|
||||
- **边界**：前缀**只匹配带尾斜杠**的形式——创建会话的 `POST /api/game-distribution/play-sessions`（以及 `POST /api/game-distribution/games/{gameId}/play-session`）需要账号凭证，必须继续走通用 `/api` 并保留 Cookie。网关的 403 拒绝保持不变，只在边缘/dev 保证请求不带 Cookie。
|
||||
- **门禁**：`npm run check:nginx-spa-routes` 对三份模板断言该 `^~` location 存在、块内清空 Cookie、代理头齐全且排在通用 `/api` location 之前（变异验证：删掉块内 `proxy_set_header Cookie "";` 立刻报「播放会话前缀 location 缺少代理片段」）；`npm run check:pingora-route-parity` 断言矩阵 `play_sessions_gateway` 用例声明清 Cookie 片段、不复用通用 `/api` location，且 Rust `classify_path` 的播放会话分支排在通用 `/api` 之前（变异验证：把矩阵片段换成通用 location、或在 Rust 里交换两个分支，各自单独判红）；`npm run check:pingora-gateway-smoke` 用真实网关二进制断言该前缀清 Cookie、创建会话端点保留 Cookie。三条都串在 `npm run lint` 链里，有自动调用方。
|
||||
- **关联**：`server-rs/crates/pingora-gateway/src/main.rs`、`deploy/pingora/nginx-route-parity.matrix.json`、`deploy/nginx/README.md`、`vite.config.ts`；另见本文件「主站 SPA allowlist 有三处真相源」条的「别踩」（发行入口不转发 Cookie 的同族规则）。
|
||||
|
||||
## 2026-10-05 自定义作者插槽应保留昵称降级语义
|
||||
|
||||
- 游戏公开投影里的「创作者」「未知作者」是角色占位词。作者昵称 hook 已将加载中和查询失败分别转成 null 与空串，宿主不能再用 `|| game.author.name` 把占位词补回。
|
||||
@@ -44,7 +83,7 @@
|
||||
|
||||
- **现象 / 风险**：改动 `preview.rs` 的注入逻辑（`inject_preview_fit_bridge` / `build_preview_response` / `PREVIEW_FIT_BRIDGE_TAG`）时，没有自动化门禁会告诉你「标签没注入」或「注入了两次」。两种失效都只在运行时才暴露：没注入等于整套运行画面点选静默失效（桥脚本的尺寸上报与点选都不执行，页面看起来完全正常）；注入两次会让桥的监听、尺寸上报与点选回调各注册一遍，页面同样看不出差别。
|
||||
- **现状**：`preview.rs` 的 `mod tests` 只有 4 个用例——`npm_preview_requires_build_and_prefers_bundled_assets`、`root_layout_serves_root_entry_and_keeps_legacy_paths_available`、`root_layout_does_not_expose_control_or_data_directories`、`legacy_layout_serves_root_ui_modules`；它们只断言预览路由的选取、状态行与页面自身文本，不涉及桥标签是否出现、出现几次，也不覆盖 `scan_preview_fit_bridge_html` 的「页面已带标签就不重复注入」分支（`inject_preview_fit_bridge` 里的 `if scan.has_bridge_script { return html.into_bytes(); }`）。
|
||||
- **结论（现行口径）**：这类「把常量原样返回 / 标签字符串存在」的转发型行为不固化成长用例（仓库口径：复制与源码文本断言不进测试）。改注入逻辑时按人工验证清单核对：① 响应 HTML 里 ``<script src="/__genarrative/local-preview-fit.js"></script>`` 出现在 `</body>` 前，且是经典脚本（不带 `type` / `nomodule`）；② 页面自身已带该标签时，响应里的标签数量不增加；③ `/__genarrative/local-preview-fit.js` 返回 200，且内容与 `resources/preview/local-preview-fit.js` 逐字节一致（`include_str!` 内嵌，可比 sha256）。
|
||||
- **结论（现行口径）**：这类「把常量原样返回 / 标签字符串存在」的转发型行为不固化成长用例（仓库口径：复制与源码文本断言不进测试）。改注入逻辑时按人工验证清单核对：① 响应 HTML 里 `<script src="/__genarrative/local-preview-fit.js"></script>` 出现在 `</body>` 前，且是经典脚本（不带 `type` / `nomodule`）；② 页面自身已带该标签时，响应里的标签数量不增加；③ `/__genarrative/local-preview-fit.js` 返回 200，且内容与 `resources/preview/local-preview-fit.js` 逐字节一致（`include_str!` 内嵌，可比 sha256）。
|
||||
- **关联**：`apps/ai-game-creator-shell/src-tauri/src/preview.rs`（`PREVIEW_FIT_BRIDGE_SCRIPT` / `PREVIEW_FIT_BRIDGE_TAG` / `inject_preview_fit_bridge`）、`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`。
|
||||
|
||||
## 2026-10-04 Phaser 4 `hitTestPointer` 的返回顺序不是叠放顺序
|
||||
@@ -71,6 +110,27 @@
|
||||
- **判据/取证**：Rust `cargo test … asset_generation_task` 27 条（含 `naming_task_stays_in_flight_across_ledger_reads_until_terminal`、`naming_task_update_requires_the_project_rename_permission`、`naming_task_update_rejects_a_record_from_another_project`、`naming_task_terminal_state_rejects_a_different_status_but_allows_the_same_one`、`ledger_with_an_unsupported_schema_version_fails_closed`、`ledger_without_a_schema_version_is_accepted_as_v1`）与 `conditional_project_rename_tests` 7 条（含超长名失败关闭）；前端 `homeProjectNamingAsync.test.tsx`（入队→running→终态的推进序列）、`projectNamingGenerationTaskRow.test.tsx`（行渲染）、appSurface 的「syncs the workbench title and recent project list with the AI name after creation」「recovers the naming row when the terminal event lands before the subscription is ready」「re-reads the naming ledger when the generation tasks panel opens」（后两条已做「改前红」验证：退回「先读后订阅 / 面板打开不补读」两条即红）。
|
||||
- **关联**：`apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`。
|
||||
|
||||
## 2026-10-04 输入区不放常驻状态行：那一排控件容不下第二行文字
|
||||
|
||||
- **现象**：AGC 工作台输入区里模型失败提示常驻一行红字，工具条上还浮着一个半透明的「模型 ⌄」压在 `@ + 默认 ⌄` 那一排上；口径是「完全没对齐」，改成 toast。
|
||||
- **成因**：`ConversationModelSelect` 的 `[role='alert']` 曾被从 `bottom: 36px` 浮层收回控件排内（`flex: 1 1 100%` 独占一行），整颗模型控件因此变成两行高；工具条是 `align-items: center` 的 flex 行、行高由最高项决定，于是触发钮被顶到行线上方、提示落到行线下方——**不是"某个元素绝对定位压过来"，是行内多了一行文字**。
|
||||
- **处理（现行口径）**：输入区**不留常驻状态行**，与输入区同一排的失败提示一律走浮层。`ConversationModelSelect` 新增 `errorPresentation: 'inline' | 'toast'`（默认 `inline`，首页 / 策划 / 画布原样不动），Direct 输入盒传 `'toast'`，由 `ComposerModelNoticeToast` 复用外壳同一枚 `PlatformRuntimeStatusToast`（bottom-center portal、6s 自动收起）；触发时机是失败消息**新出现**时一次（同条去重，清空后可再报），不做每次渲染都弹；不可用态照旧挡住发送，但不靠文字行表达。文案同步去掉误解性的「本地」前缀（`llmModelCatalog.ts` / `clientApi.ts` → 「模型服务不可用」）。
|
||||
- **判据/取证**：`tests/appSurface/chat-composer.suite.ts`——不可用时产出 toast，且输入区子树里既没有 `[role='alert']` 也没有旧文案；模型失败只报一次、清空后再出现才再报。
|
||||
- **关联**：`features/project-workspace/ConversationModelSelect.tsx`、`view/project-development/chat/components/DirectProjectComposer/{DirectProjectComposer.tsx,ComposerControls.tsx}`、`src/styles.css`。
|
||||
|
||||
## 2026-10-04 输入盒的强度选择并入模型菜单，底行只留一颗控件
|
||||
|
||||
- 目标口径：**减少底部空间占用** —— 底行只能有模型触发钮一颗控件。思维强度不再单独占位，而是作为**强度区嵌在模型菜单顶部**（标题「思维强度」+「当前：最高」+ 原生 `<input type="range" min=0 max=4 step=1>` + 5 个档位点），与模型列表共用同一张卡（`.conversation-model-menu-shell`，向上展开、贴触发钮右缘，里层 `.conversation-model-menu` 回到文档流只负责滚动）。
|
||||
- **滑块不能放进 `role="listbox"` 子树**：参数控件混进菜单角色会让读屏进菜单模式后读不到它，所以外壳是普通容器（强度区 + listbox 并列），只能靠 `strengthSection` 这个显式 prop 由宿主注入。
|
||||
- 档位枚举、默认值、持久化通道（读 `read_game_creator_app_config`、写 `select_game_creator_reasoning_effort`）与旧下拉**完全一致**；`ComposerReasoningEffortSelect` 的 `presentation` 默认 `'dropdown'`（策划输入盒继续用，零语义变化），Direct 用 `'section'`；`ConversationModelSelect` 不传 `strengthSection` 时渲染与改动前逐字一致（首页 / 策划 / 画布不受影响）。
|
||||
- 关掉旧的独立触发钮（底行元素 2 → 1）；浮层的开合、Esc 与点击外部关闭都由模型菜单既有行为负责，强度区不再自带浮层。
|
||||
- **取舍**：强度区随菜单挂载，打开时先显示「默认」再回读成落盘档位（一次 IPC 往返），测试里要 `waitFor`；换掉这一点需要把档位状态提到宿主，暂不做。
|
||||
- **判据/取证**：`tests/appSurface/chat-composer.suite.ts`（底行不再有第二颗控件、菜单里改档落同一条持久化通道、Esc/点外部关闭、滑块不在 listbox 内）+ `tests/chatDialogFrameLayout.test.ts`（外壳向上展开 / 强度区网格 / 底行高度不增）+ `tests/appSurface/design-agent.suite.ts`（策划菜单里没有滑块）。
|
||||
- **视觉口径**：卡片与滑块的观感照 Codex 参考图，颜色只取我们自己的暖色 token——卡片圆角 16px、内边距 12px、极淡描边（`--platform-line-soft`）+ 既有暖色投影 token `--platform-desktop-hover-shadow`、**不画横贯分隔线**（只靠留白）；强度区标题 `--platform-text-strong` 12/600、右侧当前档位 `--platform-text-soft` 11px；轨道 6px 圆头，已选段 `--platform-accent`、未选段 `--platform-subpanel-border`（进度由组件写进来的 `--strength-ratio` 驱动渐变 `calc(20px + var(--strength-ratio) * (100% - 20px))`），圆钮 20px **实心**（`--platform-panel-fill`，不用半透明 token，避免透出已选段变成"靶心"）+ `--platform-subpanel-border` 1px 描边 + 从 `--platform-accent` 派生的 `color-mix` 柔影；档位点 7px 绝对定位叠在轨道**之上**（`z-index: 2` > range 的 1）、当前档位那一点隐藏（见本文件顶部 2026-10-05 那条的对齐算式与实测）；模型列表行高 34px、行圆角 9px、hover `--platform-nav-item-icon-fill`、选中 `--platform-warm-bg` 轻量 pill + 右侧对勾；列表 `max-height: 170px`（=5×34，不出现半行），滚动条 6px 且平时透明、悬停卡片才显形。
|
||||
- **实测（无头 Chromium 夹具，447px / 900px）**：卡片 260×263（圆角 16 / 内边距 12）、强度区 234×61、滑块 222×26、档位点 7px 且中心与轨道中线重合（点 270 / 轨道 269）、列表行高 34、`max-height` 170（内容 315 → 滚动）、默认档进度 0%，按 `End` 到 100% 且文案变「当前：最高」；卡片右缘未溢出视口。
|
||||
|
||||
- **关联**：`features/project-workspace/ConversationModelSelect.tsx`、`view/project-development/chat/components/DirectProjectComposer/{DirectProjectComposer.tsx,ComposerControls.tsx}`、`src/styles.css`。
|
||||
|
||||
## 2026-10-03 后台异步回填被「进项目」覆盖：AI 项目名只在兜底名仍成立时改
|
||||
|
||||
- **现象**（Issue 599）：首页建项把 AI 命名改成「与建项并行、结果后台回填」后，偶尔工作台标题停在兜底名（`GameAgent 项目 <短 id>`），而磁盘 manifest 已经是 AI 名字。
|
||||
@@ -79,6 +139,15 @@
|
||||
- **判据/取证**：`npx vitest run apps/ai-game-creator-shell/tests/homeProjectNamingAsync.test.tsx` 的「keeps the AI name when the naming result lands before the project is entered」（去掉等待即复现兜底名覆盖）；appSurface 的「syncs the workbench title and recent project list with the AI name after creation」。
|
||||
- **边界**：条件改名的判据必须由宿主校验（项目 ID + 当前名称仍是兜底名），前端只转述 `expectedProjectId` / `expectedName`；用户已手动改名时宿主返回 `renamed: false`，回填整体跳过、绝不覆盖用户输入。
|
||||
- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`。
|
||||
|
||||
## 2026-10-03 AGC 输入区控件叠在一起：输入区内的操作排与状态提示不能用绝对定位
|
||||
|
||||
- **现象**：#600 截图里用户输入区域「元素堆叠」——空草稿时「AI 润色」按钮就压在输入内容区右下角（实测与编辑器相交 28×24px），模型控件的失败提示「本地模型服务不可用」直接画在第 3~4 行文字上（70×36px，长草稿时把整段文字盖住）；面板越窄越糟：280px 面板下推理档整颗压在「添加文件」上（28×28px），「插入素材引用」与推理档也相交（20×28px）。
|
||||
- **原因**：两条「靠绝对定位把控件挪出流」的旧写法叠在一起：① `.resource-reference-input-actions` 被写成 `position: absolute; right: 0; bottom: 0`，浮到编辑器右下角（同一份样式早前其实是网格第二行，见文件里 11893 行那条注释，被后写的绝对定位规则盖掉）；② `ConversationModelSelect` 的 `[role='alert'] / [role='status']` 是 `bottom: 36px` 的浮层，锚点就在输入盒正下方，提示必然落在文字上。另外 `.project-chat-composer-controls-right` 写死 `flex: 0 0 auto`，宽度不够时既不收缩也不换行，整组向右溢出输入盒（360px 面板下溢出 34px、280px 下 114px）。
|
||||
- **处理（现行口径）**：`.project-chat-composer.is-direct-codex` 是单列网格（`gap: 8px`）；**控件全部集中在唯一一行工具条**——左组 `@` / `+`，右组 模型 / 语音 / **「AI 润色 / 恢复原文」（紧贴发送左侧）** / 发送，六颗 `flex-wrap: nowrap` 平铺（润色钮由 `ResourceReferenceInput` 的 `actionsPortalTarget` portal 进右组发送钮之前的挂点，不再自成一行；它与发送钮同为圆角矩形按钮，相邻成组，DOM / Tab 顺序都是 模型 → 麦克风 → 润色 → 发送）；状态/提示层只在有内容时占行（空输入态第二行为 0 高、行间距为 0，状态自己带 6px 上间距）。窄宽度用 `min-width` 兜（控件排 252px / 外壳 278px）+ 横向溢出可见：**不换行、不堆叠、不重叠**，发送钮仍可点击（夹具 `elementFromPoint` 命中）。模型钮封顶 160px 且名字走省略号（收缩由它承担），左组是固定 28px 动作钮、`flex: 0 0 auto` 不参与收缩。**模型失败提示后来改成走浮层**（见本文件顶部 2026-10-04 / 2026-10-05 两条）：控件排里既不留常驻红字、也不留常驻状态文字——「控件排内独占一行」那次快照已退役，行高回到由模型触发钮决定。
|
||||
- **判据/取证**：`apps/ai-game-creator-shell/tests/chatDialogFrameLayout.test.ts` 用层叠求值钉住单行工具条（240 / 280 / 296 / 320 / 360 / 438 / 900 七个宽度下 `flex-wrap` 都是 `nowrap`、控件排 `min-width: 252px`、外壳 `min-width: 278px`）、输入盒最高高度算式（12 盒内上内边距 + 160 编辑器 + 0 输入区行距 + 0 状态行 + 0 输入区下内边距 + 8 输入盒与工具栏行距 + **30 工具栏行高（模型触发钮 30px 撑起来，发送/语音是 28px）** + 12 盒内下内边距 = **222**），以及组件源码里润色钮渲染在工具条挂点（`actionsPortalTarget={controlsActionsSlot}`、挂点在控件排之后）；`tests/appSurface/project-development.suite.ts` 钉住 composer 的 `gap: 8px`。真实渲染对照见 #600 PR：同一夹具在 495/438/360/296/280px 面板 × 空 / 长多行 / 队列+提示 四态下，改前 2~4 处相交（含文字被提示盖住），改后 0 处相交、0 处溢出。
|
||||
- **关联**：`apps/ai-game-creator-shell/src/styles.css`（文件末尾「输入区工具栏与状态提示」区块）、`docs/【功能说明】AGC聊天AI润色与发送前提醒-2026-09-10.md`。
|
||||
|
||||
## 2026-10-03 AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过
|
||||
|
||||
- **现象**：Windows 本机 `npm run check:generated-bindings`（`npm run lint` 链内，`scripts/check-repository-ci.sh` 的 Repository checks 也走它）在 `build.rs:167:29` panic：`插件随包资源校验失败：随包插件存在未声明文件：.../src-tauri/resources/plugins/agc-godot-editor/native/gdextension/bin/win-x64/agc_godot_editor.dll（目标 x86_64-pc-windows-msvc 与当前 feature 组合不允许；请先执行随包资源准备步骤）`；树上换成 `agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe` 时报同一类错。反向还有更隐蔽的形态：门禁 2 秒就 exit 0 说「通过」，但 tree 上其实带着编辑器产物。
|
||||
|
||||
@@ -532,6 +532,7 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
|
||||
| `/admin/*` | 先读取静态文件或目录 index，失败回退 `/admin/index.html`，HTML 默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
|
||||
| `/assets/*` | 从 Web 根目录精确读取静态文件；带 Vite 指纹的文件默认长期缓存，其它文件默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
|
||||
| `/api`、`/api/*` | 转发到 `api-server`，按配置执行 `Content-Length` 与流式 body 累计上限检查。 |
|
||||
| `/api/game-distribution/play-sessions/*` | 付费游戏播放会话入口，转发到 `api-server`；与 `/api/*` 同样限流、大小上限与维护判断，额外清空 `Cookie`（详见下节）。 |
|
||||
| `/v1/database/{db}/subscribe`、`/v1/identity*` | 转发到 SpacetimeDB，保留 WebSocket Upgrade 头。 |
|
||||
| `/__genarrative_pingora/healthz` | 仅在携带 `X-Genarrative-Pingora-Probe` 且匹配配置 token 时返回 shadow JSON，否则 404。 |
|
||||
| `/v1/*`、`/generated-*`、`/healthz*`、`/readyz*` | 返回 404，保持生产公网不暴露口径。 |
|
||||
@@ -545,6 +546,8 @@ SPA allowlist 里属于游戏分发入口的深链（游戏目录 / 详情 / 游
|
||||
|
||||
**平台同源发行入口**（`/games/game_<32 位十六进制 id>/…`）与 SPA allowlist 是两条不同的路由：Nginx 用 `location ~ "^/games/(?<game_id>game_[0-9a-f]{32})(?<game_path>/.*)?$"` 把它代理到 api-server 的发行网关（`proxy_set_header Cookie ""` + `proxy_pass .../api/game-distribution/releases/$game_id$game_path`），Pingora 侧对应 `RouteDecision::ReleaseGateway`：走 api 上游，但把上游路径重写成 `/api/game-distribution/releases/<gameId><asset 路径>`（与 Nginx 的 `proxy_pass` 同口径，原来的 query 不再拼接）、清空 `Cookie`，并按 Nginx 该 location 的语义既不进 SPA fallback、也不套用 `limit_conn` / `limit_req` 分组、不受维护闸拦截。只认小写、固定 32 位十六进制 id；`/games/detail` 这类 SPA 深链与 `/games/game/...` 这类形状不符的路径都不会被吞进发行网关。该口径由矩阵的 `games_release_gateway` 用例（含 `upstreamPath` 期望值）与 `cargo test -p pingora-gateway matches_nginx_route_parity_matrix` 固定。
|
||||
|
||||
**平台付费游戏播放会话入口**（`/api/game-distribution/play-sessions/<token>/…`，sandbox iframe 的 `src`，包内相对资源沿同一前缀解析）与通用 `/api` 路由只差一件事：转发时必须清空 `Cookie`。api-server 播放网关对带可解析平台 refresh Cookie 的请求返回 403（纵深防御，保留），Cookie 一旦被边缘转发，iframe 与包内每个相对资源都会 403，付费游戏实际不可玩（2026-10-05 就是这样暴露的）。因此 Nginx 三份模板都加 `location ^~ /api/game-distribution/play-sessions/`（`^~` 不能省，否则正则 location `~ ^/api(?:/|$)` 优先命中、Cookie 又被转发），代理头、`client_max_body_size`、`limit_conn` / `limit_req`、超时与维护判断都与通用 `/api` location 一致，只是多了 `proxy_set_header Cookie ""`；dev 侧 `vite.config.ts` 用同名前缀规则在通用 `/api/game-distribution` 之前清 Cookie。Pingora 侧对应 `RouteDecision::PlaySessionGateway`：路径原样走 api 上游、同样套用 api 限流分组、大小上限与维护闸，唯一差别是经 `route_clears_cookie` 清空 `Cookie`。前缀只匹配带尾斜杠的形式，创建会话的 `POST /api/game-distribution/play-sessions` 仍走通用 `/api` 并保留 Cookie。该口径由矩阵的 `play_sessions_gateway` 用例、`cargo test -p pingora-gateway matches_nginx_route_parity_matrix` 与 `npm run check:nginx-spa-routes` 里的播放会话 Cookie 隔离断言固定。
|
||||
|
||||
维护模式下，公网 API-like 路由返回 JSON `503`；公网 Web 静态路由先读取 `GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_PAGE_FILE` 指向的 release 外运行态公告，缺失时回退 `GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT/maintenance.html`，两者都不存在时返回纯文本 `503`。版本化默认页不得包含日期或具体时段，临时公告由 `maintenance-on.sh --page-file` 安装并在 `maintenance-off.sh` 时清理。IPv4 loopback / RFC1918 / link-local 和 IPv6 loopback / ULA / link-local 来源绕过整站维护闸，主站页面与静态资源、普通 API、后台页面与后台 API、SpacetimeDB 路由均按非维护状态继续处理；应用层登录、管理员鉴权和其它业务鉴权保持不变。Pingora 直连按 TCP peer 判定来源；仅当 peer 是 loopback 的同机 Nginx 时才接受 Nginx 强制覆盖的 `X-Real-IP`，绝不使用客户端可伪造的 `X-Forwarded-For` 做维护放行。该放行只绕过网关维护响应；若 `pause-after-stdb` 已停止 api-server，内网普通 API 和后台 API 仍不可用。
|
||||
代理失败时，API / SpacetimeDB 等代理路由返回统一 JSON 网关错误；本地静态路由仍保持对应 HTTP 错误状态。
|
||||
静态 `Range` 只支持单段 bytes range；多段 range 暂按完整文件返回，避免在正式替换前引入 multipart 响应面。`If-None-Match` / `If-Modified-Since` 优先于 `Range` 判定，命中时仍返回 `304`；`If-Range` 日期匹配时继续返回 `206`，日期旧于文件或弱 ETag 校验器时回完整 `200`；`206` / `304` / `416` 不做 gzip 压缩，避免 `Content-Range` 语义被响应体改写破坏。Gateway smoke 会用固定 `X-Request-Id` 对账静态 `304`、`405`、`206`、`416` 的 Pingora access log 行，确认本地响应状态也进入正式切换证据链。
|
||||
|
||||
@@ -500,10 +500,12 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
|
||||
- 公开素材：游戏行末尾追加可空 `cover_object_key` 与 `screenshots_json`（截图 `{assetId, objectKey}` 数组）；创建游戏时 `api-server` 就复核封面/截图素材存在且属于当前作者（不存在 400、他人素材 403），创建版本时按同一口径再次复核并派生对象键。 发布写入受灰度配置键 `game-distribution:publish` 约束：**灰度默认关闭**，未配置或 `enabled=false` 时写入口（创建游戏/版本、确认包、送审、审核通过激活）返回 503 `GAME_DISTRIBUTION_PUBLISH_DISABLED`，`enabled=true` 且白名单/比例/标签命中才放行，读取与安全下架保持可用；同一判据在 `GET /api/runtime/frontend-config` 以 `gameDistributionPublishEnabled` 下发给前端入口，匿名恒为 `false`。只有可见性为 `published` 且存在有效 `active_version_id` 的游戏，其封面/截图素材才在 `/api/assets/read-url` 上获得匿名读授权。
|
||||
- 复用规则：末尾可空列 `local_project_id` 保存发布方本地项目标识（AGC 的 `manifest.projectId`）。同一 `owner_user_id` 再次以相同 `local_project_id` 创建游戏时复用既有 `game_id` 并只新增版本，避免“更新”被实现成新建游戏；该字段只是复用提示，不构成所有权或路径凭证，也不能用于跨账号匹配。已软删除的游戏不参与复用：删除后重新发布同一本地项目应得到新的游戏身份。
|
||||
- 软删除：游戏行末尾追加可空 `deleted_at`（2026-10-01）。非空表示作者已删除该作品：`delete_game_distribution_game_and_return` 只写该时间戳并把公开投影下线（可见性回到 `unpublished`、撤销当前公开版本、递增 `publication_revision`），版本行、发行包与其冻结资料一律不改写。软删行不进入作者列表（`list_owner_game_distribution_games_and_return`）、公开目录（`list_public_game_distribution_games_and_return`）、公开详情（`get_public_game_distribution_game_and_return`）、发行网关素材授权（`game_distribution_asset_has_public_read_grant`）与审核队列；后台默认视图同样排除，只有显式 `status=deleted` 才会读到。作者侧版本回读对软删作品返回空（404），因此上传、确认与送审入口一并关闭。
|
||||
- 资料编辑：`update_game_distribution_game_metadata_and_return` 覆盖游戏行上的展示字段（标题/简介/详介/分类/标签/封面/截图/设备/输入模式/方向）并立即生效，要求 `expected_publication_revision` CAS；版本行与冻结资料不变，下一次审核通过仍会用新版本的冻结资料覆盖游戏行。
|
||||
- 资料编辑：`update_game_distribution_game_metadata_and_return` 覆盖游戏行上的展示字段（标题/简介/详介/分类/标签/封面/截图/设备/输入模式/方向）并立即生效，要求 `expected_publication_revision` CAS；版本行与冻结资料不变，下一次审核通过仍会用新版本的冻结资料覆盖游戏行。**资料编辑不得直接改公开价格**：调价必须走新版本审核。
|
||||
- 共创授权：游戏行末尾追加 `fork_authorization: String` 并设置 `#[default("forbidden")]`，取值 `forbidden` / `nonCommercial` / `full`（2026-10-04）。它表达作者对「这部作品能否被改编」的策略，与血缘正交：只能单向提升（`forbidden → nonCommercial → full`），降级与未知档位失败关闭；旧行按 `forbidden` 解释，旧客户端缺字段同样按禁止共创兜底。写入只在创建游戏（`create_game_distribution_game_and_return` 的 `GameDistributionCreateGameInput`）与提升 procedure `set_game_distribution_fork_authorization_and_return`（输入 `GameDistributionSetForkAuthorizationInput { game_id, owner_user_id, fork_authorization, expected_fork_authorization, idempotency_key, request_digest, now_micros }`）发生：只允许 owner 本人，`expected_fork_authorization` 不符返回 409，同 key 重放走 `game_distribution_idempotency_receipt`（action = `set_fork_authorization`）。`api-server` 把实现值映射为 HTTP 码（`FORK_AUTHORIZATION_UNKNOWN` 400、降级 409、非本人 403、未登录 401），路由 `PUT /api/game-distribution/games/{gameId}/fork-authorization` 受发布灰度开关约束（收紧时 503，读接口不受影响）。
|
||||
- 共创授权与软删除的交叉口径：已软删除的作品（`deleted_at` 非空）不再是可用的改编来源——`resolve_game_distribution_fork_declaration_tx` 先判 `deleted_at`，命中即按 `FORK_SOURCE_NOT_AVAILABLE` 失败（HTTP 409，与「未公开」同一错误码，不用错误码区分删除事实）；既有子作品与血缘行不受影响，父作品的删除不会连带下线子作品。衍生计数（`game_distribution_public_fork_count`）只统计 `deleted_at` 为空且 `visibility = published` 的子作品，作者删除子作品后父作品的「已被改编 N 次」随之下降。
|
||||
- 索引：`by_game_distribution_game_owner_user_id` 用于作者私有游戏列表；`game_id` 为主键。公开目录只返回 `visibility = published`、`deleted_at` 为空且存在有效 `active_version_id` 的投影。
|
||||
- 买断制定价（2026-10-05）：游戏行末尾追加 `price_mud_points: u64` 并设置 `#[default(0u64)]`；`0` 表示免费，上限 `1_000_000`（复用 `module-game-distribution::normalize_game_price_mud_points` 校验）。价格是版本冻结资料的一部分：作者在 `GameDistributionCreateVersionRequest.priceMudPoints` 提交，写入版本冻结 `metadata_json.priceMudPoints`，只有 `approve_game_distribution_version_and_return` 通过审核时才随资料整体生效到本行；未通过审核或资料编辑都不会改变当前公开价格。公开投影（`get_public_game_distribution_game_and_return` 等）在游戏快照上带出 `priceMudPoints`。
|
||||
- 索引：`by_game_distribution_game_owner_user_id` 用于作者私有游戏列表；`game_id` 为主键。公开目录只返回 `visibility = published`、`deleted_at` 为空且活动版本存在、状态为 `published`（有效 `active_version_id`）的投影。
|
||||
- 购买与播放鉴权 HTTP（2026-10-05）：`POST /api/game-distribution/games/{gameId}/purchase`（`require_bearer_auth` + 必填 `Idempotency-Key`，请求体 `{ expectedPriceMudPoints }`）经 facade 调 `purchase_game_distribution_game_and_return`，返回 `{ purchase, walletBalance, replayed }`；余额不足 400 `INSUFFICIENT_MUD_POINTS`、价格已变化 409、免费游戏 400、作者本人自购 400 `GAME_PURCHASE_OWNER_EXEMPT`（作者免购买，绝不扣费）、管理员令牌 403 `GAME_PURCHASE_ADMIN_NOT_ALLOWED`（购买只接受普通用户 bearer）、游戏不可见 404、缺幂等键 400、未登录 401。`POST /api/game-distribution/games/{gameId}/play-session` 对免费作品直接回既有公开入口 `/games/{gameId}/`；付费作品同时接受管理员令牌（按现有 admin 鉴权）与用户令牌，已购买 / 作者本人 / 管理员才签发绑定 `gameId + userId`、2 小时有效期的进程内会话，令牌为内存态，进程重启即失效。网关 `GET /api/game-distribution/play-sessions/{token}[/{assetPath}]` 不挂登录中间件、凭令牌读取当前公开版本包，能解析出平台刷新会话 Cookie 时 403，令牌过期 / 不存在、游戏下架 / 封禁或没有有效公开版本一律 404，全部 `no-store`。公开详情 `GET /api/game-distribution/games/{gameId}` 可选鉴权读取查看者：`purchased` 只反映真实购买记录，付费作品对未购买且非作者 / 非管理员把 `currentVersion.entryUrl` 置 `null`（资料与价格仍可见）；`GET /api/game-distribution/releases/{gameId}[/{assetPath}]` 在当前公开版本 `price_mud_points > 0` 时同样 404，付费作品只能经播放会话路径播放。
|
||||
- 游玩计数写入：`play_count` 只由批量 procedure `increment_game_distribution_game_play_counts_and_return`（输入 `GameDistributionPlayCountIncrementInput { increments: Vec<{ gameId, delta }> }`）累加。`api-server` 在内存里按 `identity + gameId` 做 30 分钟去重、按 `IP + gameId` 做固定窗口限流后，按 `GENARRATIVE_GAME_PLAY_COUNTER_FLUSH_INTERVAL_MS`（默认 5 秒）批量落库；事务内只对 `published` 且存在有效 `active_version_id` 的游戏 `saturating_add`，非公开静默跳过，且**不更新** `updated_at`。公开 HTTP 入口为 `POST /api/game-distribution/games/{gameId}/plays`，完整行为见玩法链路的「游玩计数（已实现）」。
|
||||
|
||||
### `game_distribution_lineage`
|
||||
@@ -579,7 +581,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
|
||||
- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
|
||||
- 用途：不可变发行版本与真实包确认事实。创建后冻结 `package_sha256`、字节数、文件数、根入口和版本号；后续只推进上传、校验、审核、公开、撤回状态，并记录私有对象键、文件清单、入口 URL、审核者和阶段时间。
|
||||
- 索引：`by_game_distribution_version_game_id`、`by_game_distribution_version_owner_user_id`。真实 ZIP 由 `api-server` 校验并写入私有 OSS 后，才通过 facade 确认 `uploaded`；表不保存 ZIP 正文。
|
||||
- 冻结资料：版本表末尾追加可空 `metadata_json`，保存创建版本时由 api-server 校验（标题/简介/分类/标签/设备/方向/必需封面/≤6 张截图）并从素材记录派生对象键后的资料快照；`approve_game_distribution_version_and_return` 通过审核时把该快照整体生效到游戏行，因此公开投影展示的始终是“已随版本审核通过”的资料，旧版本（无快照）保持原值。
|
||||
- 冻结资料：版本表末尾追加可空 `metadata_json`，保存创建版本时由 api-server 校验（标题/简介/分类/标签/设备/方向/必需封面/≤6 张截图/买断制价格 `priceMudPoints`）并从素材记录派生对象键后的资料快照；`approve_game_distribution_version_and_return` 通过审核时把该快照整体生效到游戏行，因此公开投影展示的始终是“已随版本审核通过”的资料与价格，旧版本（无快照）保持原值。**价格口径统一为「冻结资料缺 `priceMudPoints` 即免费（0）」**：待审列表、审核详情的版本价与审核通过后生效的游戏行价格都按 `0` 处理，不会回退到游戏行旧价。<code>parse_game_distribution_frozen_metadata</code> 会用 <code>normalize_game_price_mud_points</code> 校验价格上限，越界快照在审核时失败关闭。
|
||||
- 作者回读投影：版本回读（作者本人）与审核回读（管理员）在版本 payload 上追加 `frozenMetadata`（冻结快照原样 JSON，历史版本为 `null`）。只有公开投影会剥掉素材 ID，作者与管理员拿到 `coverAssetId` / `screenshots[].assetId`，因此作者续发时可以直接复用同一批封面与截图素材，不需要为了沿用封面重新上传一次；素材 ID 缺失（旧版本）时前端必须要求作者重新选择封面，不能用对象键反推素材身份。
|
||||
- 撤回与回读：`cancel_game_distribution_version_and_return` 只允许把未参与当前公开投影的版本推进到 `cancelled`，并要求 `expected_publication_revision` 与游戏公开修订号一致；`get_game_distribution_version_and_return` 供管理员按版本 ID 直读。客户端看到的 `recoveryAction` 由 `api-server` 按 `status` 派生，不落表。
|
||||
- 工程源包（M2b，2026-10-05）：版本行末尾追加三个可空/零默认列 `project_bundle_object_key: Option<String>`、`project_bundle_bytes: u64`（`0` = 未上传）、`project_bundle_sha256: Option<String>`，保存作者**可选**上传的工程源码包（与发行包并列的第二份私有资产）。三列由 `confirm_game_distribution_project_bundle_and_return` 一次性写入（`upload_project_bundle` 幂等动作），只在版本尚未公开（`awaiting_upload` / `upload_failed`）时接受；同一版本已确认工程包后换内容按冲突拒绝，同内容按幂等重放。作品授权非 `forbidden` 时，工程包与发行包走同一道取件鉴权与校验，**平台不设独立的「源码可见性」开关**——作者不传即退化产物级改编。对象键只在服务端使用（投影里只回 `projectBundleBytes` / `projectBundleSha256`），且键名与发行包不同（`.project.zip`），避免同 (作品, 版本) 的两份资产互相覆盖或串缓存。
|
||||
@@ -602,6 +604,16 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
|
||||
- 索引：owner、game、version 和 `by_game_distribution_receipt_scope` 组合索引；默认保留窗口由服务端清理策略控制。
|
||||
- 重放语义：写操作命中既有收据时，procedure 回传 `replayed = true` 并复用收据里的结果 ID，不重复创建游戏、版本或审核结论；同 key 不同请求摘要必须返回冲突。
|
||||
|
||||
### `game_distribution_purchase`
|
||||
|
||||
- Rust 结构体：`GameDistributionPurchase`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/game_distribution.rs`
|
||||
- 用途：游戏买断制购买记录。每账号每游戏最多一条：`purchase_id` 主键由 `game_id` 与 `user_id` 按长度前缀无歧义组合（`module-game-distribution::game_purchase_id`，前缀 `gdpurchase_`），并另建 `by_game_distribution_purchase_user_id` / `by_game_distribution_purchase_game_id` 两个 btree 索引供回读；`(user_id, game_id)` 唯一性由购买事务强制。
|
||||
- 字段：`purchase_id`（主键）、`game_id`、`user_id`、`price_mud_points`（成交价快照，之后调价不影响既有所有权）、`wallet_ledger_id`（对应 `profile_wallet_ledger` 流水）、`created_at`。表随迁移导出/导入。
|
||||
- 写入：只由 `purchase_game_distribution_game_and_return`（输入 `GameDistributionPurchaseInput { gameId, userId, expectedPriceMudPoints, idempotencyKey, requestDigest, nowMicros }`）在单一事务内写入：先校验游戏已公开且活动版本存在且 `status = published`（与公开投影同一口径）、作者本人自购直接失败关闭（`OwnerCannotPurchase`，返回 400，不扣费、不写购买行）、价格大于 0、`expectedPriceMudPoints` 与当前 `price_mud_points` CAS 一致，再走 runtime profile 钱包扣费路径（`RuntimeProfileWalletLedgerSourceType::GamePurchase`，流水 ID `game_purchase:{userId}:{gameId}`，`metadata_json` 记 `{"kind":"game_purchase","gameId":...}`），最后插入购买行。余额不足、账户冻结或存在退款欠款时失败关闭，不写购买行。
|
||||
- 幂等：复用 `game_distribution_idempotency_receipt`（`action = purchase`，`owner = 购买者`）；同 key 同摘要返回既有记录，同 key 不同摘要冲突；换 key 重复购买命中既有 `(user_id, game_id)` 时只补记收据、不再扣费并回传 `replayed = true`。结果类型 `GameDistributionPurchaseResult { ok, purchase, walletBalance, replayed, errorMessage }`。
|
||||
- 回读：只读 procedure `get_game_distribution_purchase_and_return`（输入 `GameDistributionPurchaseLookupInput { gameId, userId }`）返回购买快照与当前钱包余额，未购买时 `purchase` 为空。完整行为合同见玩法链路的「游戏买断制泥点付费与播放鉴权合同」。
|
||||
|
||||
### `llm_router_account`
|
||||
|
||||
- 当前 AGC Router 需求由 `llm_router_account` 表单独承载：API Key 核心字段、加密凭据、Router 账号元数据、生命周期与 provisioning 状态均在该表；不依赖 `external_api_key`。api-server 每次上游调用都读取权威 `llm_router_account` active/revoked 状态并即时解密当前密文，不做 TTL 凭据缓存，避免任意实例轮换或撤销后继续使用旧 Key。
|
||||
@@ -940,6 +952,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
|
||||
- Rust 结构体：`ProfileWalletLedger`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/runtime/active/profile.rs`
|
||||
- 说明：账号钱包流水表。`created_at` 表示钱包事务实际结算时间，列表先按当前余额反向校验 `balance_after - amount_delta` 的结算链，再以该时间倒序兜底，避免支付回调或退款重放延迟时出现余额顺序倒置；支付平台确认时间继续保存在充值订单 `paid_at`。`metadata_json` 为可选 JSON 对象字符串，旧行缺失时读取层按 `{}` 归一；外部生成扣费 / 退款写入 `externalGenerationJobId`，使退款记录可以追溯到对应 `external_generation_job`。
|
||||
- 来源类型（2026-10-05）：`RuntimeProfileWalletLedgerSourceType` 追加 `GamePurchase`（`game_purchase`），用于游戏买断制购买扣费；写入走通用入口 `apply_profile_wallet_signed_delta`，流水 ID 固定 `game_purchase:{userId}:{gameId}`（幂等重试不二次扣费），`metadata_json` 记 `{"kind":"game_purchase","gameId":...}`。扣费受人工冻结 / 退款欠款 / 可用余额校验约束，余额不足时失败关闭且不写购买行。**只追加枚举变体，未改本表结构。**
|
||||
- 实际变动为 0 的条目不进账单：写入侧只在余额真的变化时落账，每日免费 / 会员周期换期先按 `previous_balance - expired_points + granted_points`（饱和运算）算出实际变动，变动为 0 时只更新余额状态、不写本表；通用结算入口 `apply_profile_wallet_signed_delta` 在 `amount_delta == 0` 时同样不落账。读取侧 `list_profile_wallet_ledger_entries` 在结算链排序之后、截断 50 条上限之前剔除 `amount_delta == 0` 的存量行，因此历史遗留的 0 变动流水不会出现在 `GET /api/profile/wallet-ledger`，也不占用列表上限。该规则只影响展示与落账，不改变幂等 ledger、余额结算、消费投影和退款语义。
|
||||
|
||||
### `profile_wallet_consumption_total`
|
||||
|
||||
@@ -746,6 +746,7 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
|
||||
- 响应头与缓存：`X-Content-Type-Options`、CORP（`cross-origin`）、无凭据 CORS、HTML CSP、内容类型白名单与 `Cache-Control: public, max-age=60, must-revalidate` 都由发行网关设置，边缘不覆盖。换版与下架只改变后端公开投影，因此**最迟 60 秒**内新请求不再拿到旧版本；已经下载到浏览器的脚本无法远程抹除，撤销能力以"停止继续分发"为准。
|
||||
- 传输与条件请求（2026-10-05）：发行网关对文本类资源（HTML/JS/CSS/JSON/SVG/WASM，≥1 KiB）在客户端接受 `gzip` 时下发 `Content-Encoding: gzip` 并带 `Vary: Accept-Encoding`；图片、音频、视频等已是压缩格式的资源保持原样。同时下发强 `ETag`（按 `versionId + 资源路径` 摘要），命中 `If-None-Match` 时返回 `304`（无正文、保留 `Cache-Control` 与 `ETag`），所以 60 秒缓存窗口之后浏览器只需重验证而不是重下整包；`max-age` 与 `must-revalidate` 都不变，撤销窗口仍是 60 秒。后台试玩会话固定 `no-store`，不给 ETag。
|
||||
- 审核动作：管理员只提交审核结论与公开修订号，`entryUrl` 由 `api-server` 按 gameId 派生**同源路径** `/games/{gameId}/` 写入公开投影；dev / release / 预览环境口径完全一致，入口不再由部署侧配置，历史数据里的绝对 URL 继续兼容。
|
||||
- 付费游戏播放会话：付费游戏不走 `/games/<gameId>/`（未购买访问 404），可玩入口是创建播放会话后拿到的 `/api/game-distribution/play-sessions/<token>/`，它直接作为 iframe `src`，包内相对资源沿同一前缀解析。该前缀落在 `/api/*` 上，而通用 `/api` location 必须转发 Cookie（`/api/auth/*` 依赖 refresh cookie），Cookie 一到 `api-server` 播放网关就会命中它的 `403` 纵深防御，iframe 与包内每个资源都不可用。因此三份 nginx 模板在通用 `/api` location **之前**内联 `location ^~ /api/game-distribution/play-sessions/`（`^~` 不能省，否则正则 `~ ^/api(?:/|$)` 优先命中），代理头、`client_max_body_size 210m`、`limit_conn` / `limit_req`、超时与维护判断都与通用 `/api` 一致，只多一条 `proxy_set_header Cookie ""`；`vite.config.ts` 里排在 `/api/game-distribution` 之前的同名前缀规则做同一件事（`proxyReq.removeHeader('cookie')`）。网关的 Cookie 拒绝不放宽，只是让边缘/dev 转发时不带 Cookie。
|
||||
- 门禁：
|
||||
|
||||
```bash
|
||||
|
||||
@@ -64,7 +64,7 @@
|
||||
|
||||
交付“AGC 一键提交游戏 / 网页上传游戏 ZIP → 后端收取真实发行包 → 校验与人工审核 → 主站发现、详情、游客在线游玩 → 更新与下架”的完整闭环。验收必须使用真实上传、真实存储、真实审核状态和隔离发行域名；静态演示卡片、metadata-only 请求或前端本地发布状态不能作为完成证据。
|
||||
|
||||
首版支持可以离线运行的静态 Web 游戏：HTML、JavaScript、CSS、JSON 与图片、字体、音视频。AGC 首先支持现有 npm/Vite Web 工程；网页入口允许上传符合相同包合同的 ZIP，不以游戏引擎名称限制普通静态产物。Godot/Cocos 工程源码、原生可执行文件、Wasm、服务端进程、外部 API、多人联机、云存档和跨版本存档迁移不在首版内。本发行合同 Version 0.2 不包含用户评分与评论，其扩展范围见下文“网站游戏评分与评价合同”；关注扩展见下文“创作者主页与关注粉丝合同”提案，榜单、推荐算法、交易和创作者收入仍不在范围内。
|
||||
首版支持可以离线运行的静态 Web 游戏：HTML、JavaScript、CSS、JSON 与图片、字体、音视频。AGC 首先支持现有 npm/Vite Web 工程；网页入口允许上传符合相同包合同的 ZIP，不以游戏引擎名称限制普通静态产物。Godot/Cocos 工程源码、原生可执行文件、Wasm、服务端进程、外部 API、多人联机、云存档和跨版本存档迁移不在首版内。本发行合同 Version 0.2 不包含用户评分与评论，其扩展范围见下文“网站游戏评分与评价合同”；买断制泥点付费与付费游玩鉴权见下文“游戏买断制泥点付费与播放鉴权合同”；关注扩展见下文“创作者主页与关注粉丝合同”提案，榜单、推荐算法、交易、创作者收入与结算仍不在范围内。
|
||||
|
||||
### 入口与产品体验
|
||||
|
||||
@@ -122,9 +122,12 @@
|
||||
| 方法与路径 | 身份 | 行为 |
|
||||
| --- | --- | --- |
|
||||
| `GET /games` | 游客 | **已实现**：关键词与分类筛选，最多 48 项；仅公开可玩版本 |
|
||||
| `GET /games/{gameId}` | 游客 | **已实现**：当前公开资料与 `currentVersion.entryUrl`；不可见时 404 |
|
||||
| `GET /games/{gameId}` | 游客/登录 | **已实现**：当前公开资料、`priceMudPoints` 与查看者 `purchased`（匿名、坏令牌与读取失败按未购买，内容访问失败关闭）；付费作品对未购买且非作者/管理员的查看者把 `currentVersion.entryUrl` 置为 `null`，资料与价格仍可见；不可见时 404 |
|
||||
| `POST /games/{gameId}/plays` | 游客/登录 | **已实现**：上报一次「开始游戏」；可选 Bearer，非公开 404、超限 429，成功返回 `{recorded}`；只进 api-server 内存缓冲，失败不影响游玩 |
|
||||
| `GET /game-distribution/releases/{gameId}[/{assetPath}]` | 游客 | **已实现**：根路径等价于 `index.html`；发行网关只服务当前已公开版本包内文件，按扩展名白名单设内容类型，未知扩展名 404，带 Cookie 的请求 403；游玩页的入口来自详情投影的 `currentVersion.entryUrl` |
|
||||
| `POST /games/{gameId}/purchase` | 登录用户 | **已实现**：买断制购买，必填 `Idempotency-Key`，体 `{ expectedPriceMudPoints }`；扣费与购买记录同事务，重复购买幂等返回既有记录不再扣费；余额不足 400 `INSUFFICIENT_MUD_POINTS`、作者自购 400 `GAME_PURCHASE_OWNER_EXEMPT`、后台管理员令牌 403 `GAME_PURCHASE_ADMIN_NOT_ALLOWED`、价格已被新版本改变 409；免费游戏按 400 拒绝 |
|
||||
| `POST /games/{gameId}/play-session` | 游客/登录 | **已实现**：付费作品需登录，仅已购买、作者本人或后台管理员可签发，响应 `{ playUrl, expiresAt }`；免费作品不校验登录也不签发令牌，直接返回现有公开入口 `/games/{gameId}/`；未登录 401、不可见 404、未购买且非作者/管理员 403 |
|
||||
| `GET /game-distribution/releases/{gameId}[/{assetPath}]` | 游客 | **已实现**：根路径等价于 `index.html`；发行网关只服务当前已公开版本包内文件，按扩展名白名单设内容类型，未知扩展名 404，带 Cookie 的请求 403；当前公开版本 `price_mud_points > 0` 时统一 404（付费作品只经播放会话开放，不能靠猜测 `gameId` 绕过购买）；免费作品的游玩页入口来自详情投影的 `currentVersion.entryUrl` |
|
||||
| `GET /game-distribution/play-sessions/{token}[/{assetPath}]` | 凭播放令牌 | **已实现**：凭令牌读取当前公开版本包内文件，不读 Cookie（带可解析平台 refresh Cookie 的请求一律 403，边缘/dev 按该前缀清 Cookie），`no-store`；令牌不存在或过期、游戏下架/封禁、无有效公开版本一律 404 |
|
||||
| `GET /my-games` | 登录作者 | **已实现**：当前账号游戏、最近版本状态与驳回理由；owner 只从认证主体派生，单次最多 48 项 |
|
||||
| `GET /my-games/{gameId}` | 登录作者 | **已实现**：作者读自己名下单个游戏的详情，条目与 `GET /my-games` 同形（含全部版本私有状态、驳回理由与已公开版本的 `entryUrl`）。作者要能打开「审核中 / 被驳回 / 已下架 / 已撤回」的作品，公开详情只服务已公开投影，所以作者视角必须走这条 owner 作用域路由；游戏不存在或不属于当前主体都返回 404 |
|
||||
| `PATCH /my-games/{gameId}` | 登录作者 | **已实现**：作者编辑自己名下游戏的展示资料（标题/简介/详介/分类/标签/封面/截图/设备/输入模式/方向），立即生效并落 `tracking_event` 审计；要求 `Idempotency-Key` 与 `expectedPublicationRevision` CAS，随版本冻结的包摘要与资料快照不受影响，缺封面/截图归属不符仍按创建口径拒绝 |
|
||||
@@ -552,11 +555,121 @@
|
||||
- 管理员权限继续复用现有游戏审核权限映射，还是单独增加 `game-review-preview` 动作权限；第一里程碑默认复用现有审核权限，不扩大权限模型。
|
||||
- 预览 Token 的单次 HTML 读取与同包静态资源多次读取需要统一 TTL 和失效规则；第一里程碑使用短 TTL 的版本绑定会话。
|
||||
|
||||
## 游戏买断制泥点付费与播放鉴权合同
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | implemented（本地验证通过，待用户验收；未部署） |
|
||||
| Date | 2026-10-05 |
|
||||
| 适用边界 | 主站游戏分发（`/games`）的作者买断制定价、泥点购买、付费游玩鉴权与后台审核价格展示；不含创作者结算 |
|
||||
| 里程碑 | [游戏买断制泥点付费与播放鉴权](./project-memory/plans/【里程碑】游戏买断制泥点付费与播放鉴权-2026-10-05.md) |
|
||||
|
||||
### 目标
|
||||
|
||||
- 作者发布游戏时可选择“免费”或“买断制 N 泥点”；付费作品对其他用户在完成购买前不可游玩。
|
||||
- 买断制：购买一次永久拥有，重复进入不再扣费；换设备、重新登录或更新版本都不清除所有权。
|
||||
- 后台审核详情展示该版本价格；审核员试玩待审版本不受购买限制、不限次数、不扣泥点。
|
||||
|
||||
### 非目标
|
||||
|
||||
- 不做创作者分成与结算、退款与撤销购买、促销/限时免费、订阅或游戏内购、价格运营审批流。
|
||||
- 不扩展 `/api/external/v1` 及其 OpenAPI。
|
||||
- 不新建第二套账号、钱包或发行通道；泥点沿用 runtime profile 域。
|
||||
|
||||
### 入口与边界
|
||||
|
||||
- 作者入口：网页 `/games/publish`（新建与更新模式）与 AGC 发布面板；两个发布入口一致支持「付费方式：免费 / 买断制」与「买断价（泥点）」，共用同一份前端校验与服务端口径，非法值阻止提交。
|
||||
- 预填规则：给已上线作品发新版本时，面板按「最新版本冻结价优先、缺失或为 `0` 时回落作品行当前价、两条来源都取不到按免费（`0`）」预填价格与模式；作者不改则价格不变，避免审核通过后静默改价。
|
||||
- 玩家入口：`/games`、`/games/detail`、`/games/play`。
|
||||
- 审核入口：后台 `#game-distribution` 审核页（详情与待审列表）。
|
||||
- 正式状态来源：SpacetimeDB 的游戏价格、购买记录与钱包余额/流水；前端只负责表现与请求编排。
|
||||
|
||||
### 必须成立的行为
|
||||
|
||||
#### 定价与冻结
|
||||
|
||||
- 价格是版本冻结资料的一部分：作者提交新版本时携带价格，与封面/截图一样在审核通过时整体生效到游戏行；未通过审核的价格不改变当前公开价格。
|
||||
- 价格是整数泥点数，`0` 表示免费，取值域由服务端约束为 `0..=1_000_000`（上限于 2026-10-05 定稿）；免费与付费共用同一条发布与审核链路。
|
||||
- 展示资料编辑（`PATCH /my-games/{gameId}`）不得直接变更公开价格；调整价格必须走新版本审核。
|
||||
- 发布新版本必须预填并保持现有价格：预填取该作品**最新版本的冻结价**（该版本可能仍处于 `pending_review` / `rejected`，因此预填值未必已生效），仅当该冻结价缺失或为 `0` 时才回落作品行当前价，两条来源都取不到才按免费（`0`）；作者不改则价格不变，不允许因默认免费而静默改价。实现落点：AGC 壳 `resolve_publication_prefill_price`（`apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:811`）、网页 `src/components/game-distribution/GamePublishPage.tsx:164`（`detail.version.priceMudPoints ?? detail.game.priceMudPoints ?? 0`），后端 `version_detail_payload`（`server-rs/crates/api-server/src/modules/game_distribution.rs:3797`）已把版本详情的 `game.priceMudPoints` 归一为同一冻结价口径（历史无价格版本按 `0`，不回退游戏行旧价）。
|
||||
- 定价 UI 已抽取为 `packages/shared` 共享组件（`PlatformGamePricingField`），网页与 AGC 两个发布入口共用同一实现，不再保留两份。
|
||||
|
||||
#### 购买与所有权
|
||||
|
||||
- `price_mud_points = 0` 的游戏对所有人免费可玩，行为与现状一致。
|
||||
- 付费游戏对未购买用户：详情可见资料与价格，但不返回可播放入口。
|
||||
- 每账号每游戏最多一条购买记录；重复购买幂等返回既有记录且不再扣费。
|
||||
- 购扣泥点必须与购买记录写入处于同一原子事务：不允许“扣了没记录”或“记录了没扣”。
|
||||
- 余额不足时明确失败，不变更余额、不写购买记录。
|
||||
- 作者本人与管理员免购买即可游玩付费作品，且不扣费。
|
||||
|
||||
#### 播放鉴权
|
||||
|
||||
- 付费游戏的发行入口不经公开同源路径对外开放；未购买者直接访问 `/games/<gameId>/` 必须失败（404），不能靠猜测 `gameId` 绕过。
|
||||
- 允许游玩时由服务端签发绑定“`gameId` + 用户 + 短时效”的播放会话，游戏入口与包内资源经会话前缀读取；会话过期、游戏下架/封禁或目标版本失效后不可继续播放。
|
||||
- 播放会话沿用现有发行沙箱与网关约束：`sandbox="allow-scripts"` 不透明来源、拒绝真实平台 Cookie、CSP/MIME/`nosniff`/CORP 与运行期 storage 兼容层不变；会话响应按现有发行缓存口径（≤60s）或 `no-store`。
|
||||
- 免费游戏继续使用现有 `/games/<gameId>/` 公开入口，播放鉴权不得改变免费链路。
|
||||
- 游玩计数只在真正进入游戏后上报；未购买或被拒绝的访问不计数。
|
||||
|
||||
#### 后台审核
|
||||
|
||||
- 审核详情必须展示该版本价格（“免费”或“N 泥点”）；无价格的历史版本按免费口径展示。
|
||||
- 审核员试玩待审版本维持现有预览会话语义：不校验购买、不扣泥点、不限次数。
|
||||
- 审核通过后公开价格随版本生效；拒绝不影响当前公开价格。
|
||||
|
||||
#### 失败、重试与幂等
|
||||
|
||||
- 购买请求携带 `Idempotency-Key`：同 key 同请求返回原结果，同 key 不同请求返回冲突。
|
||||
- 并发或重复点击只产生一条购买记录、只扣一次。
|
||||
- 服务端不可用时购买失败关闭，不出现“未扣费却已解锁”或“已扣费却未解锁”的中间态。
|
||||
|
||||
#### 实现约束与已知风险
|
||||
|
||||
- 播放会话是 `api-server` 进程内短期会话，不持久化到 SpacetimeDB：多副本部署需要粘性路由，进程重启即全部失效，与既有后台待审预览会话同构。
|
||||
- 播放始终解析“当前公开版本”：作者发布并审核通过新版本后，旧会话继续玩到的是新版本包，与买断制永久所有权随 `gameId` 而非版本的口径一致。
|
||||
- 已知同类风险（本次只记录、不修）：后台待审预览入口 `/api/game-distribution/admin-previews/{token}/` 与播放会话同属 `/api` 前缀，`api-server` 预览网关同样对带可解析平台 refresh Cookie 的请求返回 403；本次只对播放会话前缀做了边缘/dev 清 Cookie 加固，预览前缀未加固。
|
||||
- `scripts/check-game-distribution-purchase-e2e.mjs`（`npm run check:game-distribution-purchase-e2e`）是人工验收脚本，需要 `E2E_ADMIN_USER` / `E2E_ADMIN_PASSWORD` 与真实 SpacetimeDB / api-server / OSS，不在 CI 自动门禁内；CI 绿不代表付费链路的运行时行为已验证，发布前必须人工运行并保留结果。
|
||||
- 上线前需用 `E2E_REQUIRE_PRIVATE_BUCKET=1` 复核生产桶不允许匿名直取发行包（既有要求，非本轮新增）。
|
||||
|
||||
### 契约与迁移
|
||||
|
||||
- SpacetimeDB：`game_distribution_game` 末尾追加 `price_mud_points: u64`（明确默认 0）；新增私有 `game_distribution_purchase`（`purchase_id` 主键，含 `game_id`、`user_id`、成交价快照、钱包流水 ID 与创建时间，`(user_id, game_id)` 唯一）；同步 `migration.rs`、后端表目录与生成绑定，并运行 `npm run check:spacetime-schema`。
|
||||
- 泥点流水新增来源类型 `game_purchase`（`RuntimeProfileWalletLedgerSourceType`，Rust 常量 `PROFILE_WALLET_LEDGER_SOURCE_TYPE_GAME_PURCHASE` 见 `server-rs/crates/shared-contracts/src/runtime.rs`），同步 Rust `shared-contracts`、`packages/shared`、前端与后台文案；接口侧来源文案由 `server-rs/crates/api-server/src/runtime_profile.rs` 的 `format_profile_wallet_ledger_source_type` 输出，后台落点为本轮已补齐的 `server-rs/crates/api-server/src/admin.rs`（流水来源映射 `wallet_ledger_source_type_to_string` 与后台统计消耗白名单），钱包消耗口径的 `game_purchase` 一并纳入 `server-rs/crates/spacetime-module/src/runtime/` 的 profile 消耗统计。
|
||||
- 游戏 DTO 增加 `priceMudPoints` 与购买态；新增购买与播放会话 DTO。免费游戏必须能忽略这些新字段而不改变行为。
|
||||
- AGC 版本请求携带 `priceMudPoints`（Rust DTO `GameDistributionCreateVersionRequest.price_mud_points`，`#[serde(default)]`）；字段仅用于向后兼容不传该字段的旧客户端（按免费处理），新客户端从发布面板透传作者选择的价格。
|
||||
- 不修改已有表字段的类型或顺序；新增字段一律末尾追加并带明确默认值。
|
||||
|
||||
### 验收标准与证据
|
||||
|
||||
| 条款 | 验收方式 | 证据 |
|
||||
| --- | --- | --- |
|
||||
| 定价 | 网页发布可选「免费/买断制」并拦截非法值，前后端口径一致 | 真实本地栈 E2E：价格 `1000001` → 400 且不落版本，`0` 与 `1000000` → 200；`cargo test -p module-game-distribution` 29 passed（`normalize_game_price_mud_points` 上限）、`cargo test -p api-server game_distribution` 53 passed（`validate_version_declaration` 定价校验）；网页发布表单定价定向 Vitest |
|
||||
| 定价（AGC 入口） | AGC 发布面板与网页一致可选「免费/买断制」并拦截非法值；给已上线作品发新版本时按「最新版本冻结价优先、缺失或为 0 时回落作品行当前价」预填价格与模式，作者不改则价格不变 | AGC 定价前端已覆盖：发布面板定价定向 Vitest `apps/ai-game-creator-shell/tests/gameDistributionPublishPanel.test.tsx:333/342/802/819`（默认免费提交 `0`；买断制空值与 `1000001` 本地拦截、`120` 随版本提交；历史响应无价格按免费预填；更新模式预填线上买断价 `240` 且作者不改仍按 `240` 提交），请求层定向 Vitest `apps/ai-game-creator-shell/tests/gameDistributionPublish.test.ts:180/197`（透传 `priceMudPoints=240`；`1000001` / `1.5` 在 native command 之前失败关闭）；预填口径 Rust 单测 `apps/ai-game-creator-shell/src-tauri/src/game_distribution_publish.rs:1715`。**未覆盖**：AGC 真实栈手点一次发布付费版本。定价 UI 与网页共用 `packages/shared` 共享组件 `PlatformGamePricingField` |
|
||||
| 后台可见 | 审核详情与待审列表显示该版本价格 | `cargo test -p api-server game_distribution` 53 passed（`private_version_payload` / `version_detail_payload` 输出 `priceMudPoints`，历史无价格版本按 0，不回退游戏行当前价）；admin-web 审核价格展示定向 Vitest |
|
||||
| 审核试玩 | 审核员不限次试玩待审付费版本，不校验购买、不扣泥点 | 真实本地栈 E2E：审核员两次试玩待审付费版本均 200、两次包内字节一致，作者与审核员余额/流水均不变 |
|
||||
| 购买 | 余额不足失败且不变更；成功扣 N、账单出现 `game_purchase` 流水、购买记录唯一 | 真实本地栈 E2E：余额不足 400 `INSUFFICIENT_MUD_POINTS` 且余额与流水不变；成功购买扣 30（120→90），`game_purchase` 流水与购买行各 1 条；同 key 重放与换 key 重复购买都不再扣费 |
|
||||
| 幂等 | 双击、并发、响应丢失重试只扣一次 | 真实本地栈 E2E：同 key 重放、换 key 重复购买均不再扣费；两路不同 key 真并发返回 200/200，只有一个 `replayed=false`，余额只扣一次、购买记录 1 条。多账号/多游戏混合并发未覆盖 |
|
||||
| 播放鉴权 | 未购买直连公开入口 404；购买后可反复游玩且不再扣费 | 真实本地栈 E2E：未购买时详情 `priceMudPoints=30` / `purchased=false` / `entryUrl=null`，直连发行网关与平台同源均 404，创建会话 403，未登录 401；购买后可玩且重复进入不再扣费；伪造令牌 404；直连带平台 Cookie 403、经 dev 代理（该前缀清 Cookie）200；作者下架后旧会话入口与资源均 404。管理员安全下架后的会话失效未单独跑（与作者下架共用同一 404 关闭路径） |
|
||||
| 免购买游玩 | 作者与管理员可游玩付费作品且不扣费 | 真实本地栈 E2E：作者免购买（详情 `purchased=false` 但有 `entryUrl`，自购 400 `GAME_PURCHASE_OWNER_EXEMPT` 且余额/流水不变，播放会话 200）；管理员免购买（管理员令牌创建播放会话 200、入口 200）。管理员免购买经 play-session 管理员分支实现；购买路由的 403 `GAME_PURCHASE_ADMIN_NOT_ALLOWED` 分支在当前产品形态不可达（管理员令牌在用户路由先被 `require_bearer_auth` 判 401），作为纵深防御保留并有单元测试 |
|
||||
| 免费回归 | 免费游戏发布/详情/游玩/计数无行为变化 | 真实本地栈 E2E：免费游戏详情保留入口、发行网关 200、匿名创建会话 200 且不签发令牌；`cargo test -p api-server game_distribution` 免费详情 `priceMudPoints=0` / `purchased=false` / 入口保持 |
|
||||
| 工程门禁 | schema/绑定、两端类型、定向测试、编码与 diff 检查通过 | `cargo test -p api-server game_distribution` 53 passed、`cargo test -p module-game-distribution` 29 passed、`cargo test -p spacetime-module game_distribution` 7 passed、`cargo test -p pingora-gateway` 42 passed；`check:game-distribution-dto-parity`、`check:pingora-route-parity`、`check:nginx-spa-routes`、`check:pingora-gateway-smoke`、`check:spacetime-schema`、`check:server-rs-ddd`、两端 typecheck 与定向 Vitest、`check:encoding`、`git diff --check` 全绿 |
|
||||
|
||||
上表运行时证据来自人工验收脚本 `scripts/check-game-distribution-purchase-e2e.mjs`（`npm run check:game-distribution-purchase-e2e`）：最近一次人工运行 **76 PASS / 0 FAIL / 1 WARN**，唯一 WARN 为「管理员令牌购买分支在现役登录链路下不可达（先被判 401）」。该脚本不在 CI 自动门禁内，CI 绿不代表该链路已验证；本表结论最高到“本机真实栈验证通过，待用户验收，未部署”。
|
||||
|
||||
### 已收口决策（2026-10-05）
|
||||
|
||||
1. 价格上限取值 `1_000_000`，与 `0` 一起构成唯一定价约束；作者调整公开价格必须走新版本提交与审核，不设独立价格运营审批流，已购买用户继续保有所有权、不再扣费。
|
||||
2. “免购买游玩”判定范围为作者本人与后台管理员：作者由游戏行的 `ownerUserId` 与当前登录主体比对；管理员必须携带后台管理员令牌，主站登录态与后台账号之间没有身份关联，普通登录不会被当作管理员。
|
||||
|
||||
本章当前没有待评审决策。
|
||||
|
||||
## 创作者主页与关注粉丝合同
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
|
||||
| Status | implemented（工程验证通过，用户已确认提交交付，未部署） |
|
||||
| Date | 2026-10-05 |
|
||||
| 范围 | 主站导航、公开创作者主页、游戏详情作者入口、关注关系与列表管理 |
|
||||
|
||||
Reference in New Issue
Block a user