Merge remote-tracking branch 'origin/master' into feat/game-works-management

# Conflicts: # docs/project-memory/shared-memory/decision-log.md # docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md # server-rs/crates/api-server/src/modules/game_distribution.rs # server-rs/crates/spacetime-client/src/active.rs # server-rs/crates/spacetime-module/src/game_distribution.rs # src/components/game-distribution/GameDistributionPages.test.tsx
2026-10-04 15:00:23 +08:00
parent 3cca4fb99c 81cfbae207
commit 2f6df57ce2
46 changed files with 1806 additions and 130 deletions
@@ -24,6 +24,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)：已实现并通过本地定向验证，待用户验收，未部署；公开列表/详情携带真实摘要，卡片显示一位小数均分与人数，复用有效评价统计。
+- [游戏游玩次数计数](./adr/【ADR】游戏游玩次数计数-2026-10-03.md)：点「开始游戏」前端上报一次游玩，api-server 纯内存聚合（5s flush、30min 去重、`IP+game` 限流、关停不强制 flush），批量 procedure 自增现有 `game_distribution_game.play_count`，不 bump `updated_at`。
 - [外部 OpenAPI 与 API Key 接入方案](./【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md)
 - [外部 MCP 语义工具说明与参数设计](./technical/【技术方案】外部MCP语义工具说明与参数设计-2026-09-23.md)：15 个新增语义工具与全部原工具并存，复用现有 External API；包含工具说明、action、参数、幂等和兼容合同。
 - [External v1 OpenAPI](./openapi/genarrative-external-v1.openapi.json)：公开 HTTP 契约唯一机器可读来源。
@@ -0,0 +1,143 @@
+# 【ADR】游戏游玩次数计数
+
+状态：已接受（2026-10-03）
+
+## 背景
+
+网站游戏分发已经展示「X 次游玩」：目录卡片、详情、作者「我的游戏」与后台「游戏管理」都读
+`game_distribution_game.play_count`，契约里也有 `playCount`。但这条链路只读不写——游戏创建时置 `0`，
+之后没有任何自增、reducer 或 procedure；因此所有游戏恒显示 `0` 次游玩。
+
+主规范要求「不虚构评分、玩家数、排名和收藏状态」，里程碑与证据矩阵以「新游戏显示 0、目录数据来自真实
+接口」作为无假统计的证据，却从未定义「一次游玩如何累加」。相关现状：
+
+- **触发信号不存在**：游玩页 `/games/play` 先给封面与「开始游戏」，点击后才挂
+  `sandbox="allow-scripts"` 的 iframe；`startGame()` 纯本地状态，不发任何请求。AGC 客户端 12 类埋点白名单
+  不含「开始游玩」，主站路由埋点只有查看统计。
+- **发行网关不能承担计数**：`serve_release_entry` / `serve_release_asset` 只按 `gameId` 服务当前公开版本
+  文件；一次加载会打多个资源请求，且按设计禁带平台 Cookie、拿不到会话身份。
+- **平台没有匿名身份**：没有匿名访客 cookie，web 端没有 device/client id；`x-client-instance-id` 只在登录
+  链路采集。
+- **没有现成的服务端缓冲管线可复用**：AGC 埋点管线是客户端本地 15 分钟一批、服务端同步原子入库且明确
+  不做聚合；真正的「内存缓冲 + 周期 flush + 关停 flush」范式是主站路由埋点 `tracking_outbox`。
+- **部署与限流现状**：api-server 单实例；无 CSRF/Origin 中间件；应用层只有并发背压，按 IP 令牌桶在独立
+  的 `pingora-gateway`；现有缓存惯例是 std `OnceLock`/`LazyLock` + `Mutex`（无 `dashmap`/`moka`）。
+
+## 决策
+
+### 1. 触发点 = 游玩页点「开始游戏」
+
+以用户点击「开始游戏」后的前端上报作为一次游玩。理由：这是产品定义的启动动作，游客可用；`iframe load`
+只代表文档加载（规范已明确不能当业务状态），发行网关无法区分会话且会因资源请求重复。点击后即使 iframe
+超时/未真正载入也计一次（用户意图）。
+
+### 2. 落点 = 复用现有 `play_count`
+
+`game_distribution_game.play_count` 已经是 `u64`、已进公开/后台 DTO、已进四处 UI。只新增写入路径，不改
+字段语义、不新建计数表，避免双源。计数跟随游戏身份，不随发行版本。
+
+### 3. 范围 = 只做累计总次数
+
+不做日粒度 / 近 7 天热度、独立玩家数、榜单、推荐。`public_work_play_daily_stat` 属已退役自定义世界口径，
+不复活。
+
+### 4. api-server 纯内存缓冲 + 周期 flush
+
+- **纯内存，不落盘**：崩溃、被杀和正常 SIGTERM/滚动重启都允许丢最后一个 flush 窗口；进程退出不做
+  force flush，关停路径不为计数等待网络（2026-10-04 修订，见「修订记录」）。
+- **两张表**：增量表 `pending: HashMap<gameId, u64>`（5 秒级、flush 即清）与 30 分钟去重窗口表 `seen:
+  HashMap<identity + gameId, timestamp>`（30 分钟级、按 TTL 清理）。两者键不同、生命周期差 360 倍，不能合并：
+  合并会把 30 分钟窗口状态塞进 5 秒清空的表，或让 flush 需要按 gameId 重新聚合。
+- **限流表**：`rate: HashMap<ip + gameId, (windowStart, count)>` 固定窗口。
+- **并发**：请求路径只在短锁内做 HashMap 命中 + 自增；**flush 的网络调用移出锁外**。
+
+### 5. 写入形状 = 批量 procedure
+
+一次 flush 发一个 procedure，入参 `Vec<{gameId, delta}>`（按 500 分块），事务内逐条
+`play_count = play_count.saturating_add(delta)`；procedure 内**原子校验**游戏当前为 `published` 且
+`active_version_id` 存在，非公开跳过。**不 bump `updated_at`**：它只表示公开资料变更，且作者自有列表按它
+排序，bump 会让每次游玩重排作者列表。
+
+### 6. 失败语义 = 少计优于双计
+
+只重试确定未发出的 `Build`；`Timeout` / `ConnectDropped` 无法判断是否已提交，直接丢弃该批并 `warn!` 记录
+丢量。理由是：超时后重试会在"其实已提交"时造成系统性双计，而丢弃只是偶发少计——对一个非交易展示指标，
+后者更可接受（perf 优先于 correctness）。
+
+一次 flush 按 500 分块；任一分片失败即终止本次 flush 的后续分片，剩余增量直接丢弃（`Build` 只把当前分片
+放回）。连接不通时剩余分片只会重复同样的失败，逐个重试会把 worker 卡在多次连接超时上（2026-10-04 补充）。
+
+### 7. 接口
+
+`POST /api/game-distribution/games/{game_id}/plays`，公开端点（可选 bearer）：
+
+- 不挂 `require_bearer_auth`；用 `optional_access_token_from_headers` 拿可选 `userId`。
+- **不加 `Idempotency-Key`**（与其它游戏分发写路由惯例不同）：高频计数用不上幂等收据，30 分钟去重窗口就是
+  护栏。
+- 非公开 / 下架 / 封禁返回 `404` 且不计数；被限流返回 `429`；成功统一 `200 {recorded: bool}`。
+- 前端 fire-and-forget，**任何失败静默、绝不阻断游玩**；不做发行网关兜底计数。
+
+### 8. 身份与去重键
+
+登录用 `userId`；匿名用前端 `localStorage` 持久随机 `clientId`（随请求体带上）；两者都缺失时回退
+`IP + UA`。30 分钟窗口按 `identity + gameId`。不新造匿名 cookie、不依赖登录后才有的设备指纹。`IP`
+取 nginx 覆盖写入的 `X-Real-IP`（无 CDN 时即真实 TCP 对端），不取可伪造的 `X-Forwarded-For` 首段；
+限流键与微信支付下单的 `payer_client_ip` 同源（2026-10-04 补充）。
+
+### 9. 落位 = 纯持久化 / 读模型
+
+procedure 在 `spacetime-module`，facade + mapper 在 `spacetime-client`，缓冲 / worker / 端点在
+`api-server`；`module-game-distribution` 不动（自增不是领域规则，与既有「点赞计数」直接落持久化流程同构）。
+新增 procedure 不改表，schema guard 不触发，但必须 `npm run spacetime:generate` 重生成绑定并同步文档。
+
+### 10. 展示一致性 = 接受滞后
+
+读路径（目录 / 详情）继续只读 DB，不叠加内存 pending；接受「flush 间隔 + 写库」的 ≤10 秒滞后。
+
+## 影响与代价
+
+- 计数非实时，最多一个 flush 窗口的滞后；崩溃 / kill 丢最后一个窗口；模糊传输错误少计。
+- 匿名 `clientId` 可被清除 / 伪造，指标定位为展示用次数，仅靠限流兜底。
+- 单实例前提：去重 / 限流窗口不跨实例；将来多实例时各实例自行 flush（加法幂等），窗口不共享。
+- 不 bump `updated_at`，作者自有列表排序、公开修订 CAS 均不受影响。
+- 新增 procedure 只改 ABI（绑定），不改表 schema / `migration.rs`。
+
+## 备选方案与取舍
+
+1. **发行网关服务端计数**：一次加载多资源请求会重复、禁 Cookie 拿不到会话、无法去重。已否决。
+2. **复用 AGC 客户端埋点管线**：服务端同步入库且明确不做聚合，客户端 15 分钟批次，白名单不含游玩。已否决。
+3. **落盘 / outbox 保可靠**：无持久性需求（崩溃丢窗口已接受），引入磁盘与独立目录要求。已否决。
+4. **单张 map / 不做去重**：会重复计数；去重状态与增量生命周期不同。已否决。
+5. **每个游戏一次 procedure**：N 次 WebSocket 往返。已否决。
+6. **模糊失败重试**：超时已提交时系统性双计。已否决。
+7. **匿名 HttpOnly cookie / 纯 IP 去重**：前者要新造 cookie 与跨端 / 沙箱处理，后者在 NAT 下把多人并成一人。
+   已否决。
+
+## 明确不做
+
+- 日粒度 / 近 7 天 / 独立玩家数 / 榜单 / 推荐。
+- AGC 客户端界面埋点、外部 API / External OpenAPI 扩展。
+- 服务端网关兜底计数、CSRF token、应用层全局按 IP 限流（沿用既有限流与网关能力）。
+- 幂等收据表、双计补偿、跨实例窗口共享。
+
+## 落地与验收
+
+- 实施边界：`spacetime-module` 新增批量自增 procedure 与 `SpacetimeType`；`spacetime-client` facade +
+  mapper；`api-server` 新增计数模块（增量 / 去重 / 限流 / flush worker）、AppState 接线与公开
+  端点；前端 `gameDistributionClient` 增 `recordGamePlay` 并在 `startGame()` 触发。
+- 权威文档同步：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`（路由表与游戏分发合同节）、
+  `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`（`game_distribution_game` 的 procedure 与
+  写入口径）。
+- 验收判据：新游戏 `0` → 游客点一次 ≤10s 内显示 `1`；同身份 30 分钟内重复点击不增、不同身份各 `+1`；
+  超限流 `429` 且不写；下架 `404` 不计数但历史值保留；SIGTERM 关停允许丢最后一个未落库窗口；计数接口任何失败都
+  不影响游玩页；相关 Rust / 前端定向测试与 schema / DDD / 绑定 / DTO parity / 编码 / doc-index 门禁全绿。
+
+## 修订记录
+
+- 2026-10-03：初版。
+- 2026-10-04：关停不再强制 flush（原「正常 SIGTERM/滚动重启必须在 `finalize_shutdown` 内 force flush」
+  作废）。理由：关停时最后一个窗口丢失概率极低，而强制 flush 需要把 worker 生命周期接进关停顺序并为在途
+  网络写入等待；按"perf 与简单优先"取舍，直接放弃该窗口。同日明确 flush 任一分片失败即丢弃剩余分片。
+- 2026-10-04：客户端 IP 解析改为优先 nginx 覆盖写入的 `X-Real-IP`，`X-Forwarded-For` 只作回退且取最后
+  一段（nginx 用 `$proxy_add_x_forwarded_for` 追加的真实对端），不再信任可伪造的首段——公开上报端点原来
+  用它做匿名身份与限流键，可被伪造 IP 绕过并灌水。无 CDN 前置时 `X-Real-IP` 即真实客户端。
@@ -13,6 +13,24 @@
 - 影响范围：`packages/shared/src/contracts/gameCreationApp.ts`、`server-rs/crates/shared-contracts/src/game_creation_app.rs`、`apps/ai-game-creator-shell/src-tauri/src/{game_distribution_publish.rs,desktop.rs}`、`apps/ai-game-creator-shell/src/{services/gameDistributionPublish.ts,components/game-distribution/GameDistributionPublishPanel.tsx,App.tsx}`、`apps/ai-game-creator-shell/scripts/check-config.mjs`、`apps/ai-game-creator-shell/tests/**`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/project-memory/plans/`。
 - 验证方式：`npx vitest run …gameDistributionPublish*.test.*`、`npm run agc:typecheck`（含 `scripts/check-config.mjs`）、`cargo test -p shared-contracts`、`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml game_distribution_publish`、`npm run check:doc-index`、`npm run check:encoding`、`git diff --check`；真机：内部版本 4 条、线上最近提交 v6 的项目打开面板显示 v4 且只读，提交 `versionNumber: 4`。
 - 关联文档：[平台入口与玩法链路](../../【玩法创作】平台入口与玩法链路-2026-05-15.md)、[里程碑](【里程碑】AGC发布版本以工程内部版本为准-2026-10-03.md)。
+## 2026-10-04 游戏游玩次数修订：关停不强制 flush、flush 失败丢弃剩余分片、客户端 IP 只信 X-Real-IP
+
+- 变更：ADR `docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md` 修订——原「正常 SIGTERM/滚动重启必须在 `finalize_shutdown` 内 force flush」作废；崩溃、被杀、正常关停都允许丢最后一个未落库窗口，`api-server` 不再注册关停 flush。
+- 新增：一次 flush 按 500 分片，任一分片失败即终止本次 flush，剩余分片直接丢弃（`Build` 只把当前分片放回下一轮），避免连接不通时每个分片各等一次连接超时把 worker 卡住。
+- 理由：关停丢一个窗口概率极低，强制 flush 要为在途网络写入等待、并把 worker 生命周期接进关停顺序；按 perf 与简单优先取舍。
+- 受影响实现：`game_play_counter_worker.rs`（删 `flush_game_play_counter_for_shutdown`、失败即 break）、`main.rs`（`finalize_shutdown` 去掉计数 flush）、`game_play_counter.rs`（`take_pending` 仅测试使用）、`modules/game_distribution.rs`（上报先做内存限流预检再查公开可见性）。
+- 安全修正：`request_context::client_ip_from_headers` 改为优先 nginx 覆盖写入的 `X-Real-IP`，`X-Forwarded-For` 只作回退且取最后一段（nginx 用 `$proxy_add_x_forwarded_for` 追加的真实对端），不再信任可伪造的首段；公开上报端点的匿名身份/限流键与微信支付下单的 `payer_client_ip` 同时受益。无 CDN 前置时 `X-Real-IP` 即真实客户端。
+
+## 2026-10-03 游戏游玩次数：api-server 内存去重缓冲 + 批量 procedure 落 play_count
+
+- 背景：`game_distribution_game.play_count` 早已存在且随公开投影展示，但没有任何写入口；浏览列表、详情或发行网关加载都不能算「游玩」。需要一个不拖慢进入游戏、崩溃时最多少计一个窗口的上报链路。完整决策与备选方案见 ADR `docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md`。
+- 触发与落点：游玩页点击「开始游戏」时网页 fire-and-forget 上报 `POST /api/game-distribution/games/{gameId}/plays`；不建新表，累加既有 `play_count`。
+- 缓冲与写入：`api-server` 纯内存聚合，`GENARRATIVE_GAME_PLAY_COUNTER_FLUSH_INTERVAL_MS`（默认 5s）到点批量调用新 procedure `increment_game_distribution_game_play_counts_and_return`（输入 `Vec<{gameId, delta}>`）；事务内只对 `published` 且有有效 `active_version_id` 的记录 `saturating_add`，且不更新 `updated_at`（避免重排作者列表）。读路径不叠加内存值，展示最多滞后一个 flush 间隔。~~正常关停强制 flush~~（2026-10-04 修订：关停不再强制 flush，见上条）。
+- 身份与限流：登录用 `userId`、匿名用网页 `localStorage` 的 `clientId`（不可用时退化为会话内存值）、都拿不到回退 `IP + UA`；`identity + gameId` 30 分钟去重，`IP + gameId` 每分钟 60 次固定窗口限流。非公开/下架/封禁返回 404 且不计数；无效 Bearer 按匿名处理，绝不让计数阻断游玩。
+- 失败语义：只把 `SpacetimeClientError::Build`（未发出）放回重试；`Timeout` / `ConnectDropped` / `Procedure` 直接丢弃并记录丢失量——少计优于双计，本指标不做双计补偿，也不共享跨实例去重窗口。一次 flush 按 500 分片，任一分片失败即终止本次 flush，剩余分片直接丢弃（2026-10-04 补充）。
+- 影响范围：`spacetime-module/game_distribution.rs`（输入类型 + procedure + tx）、`spacetime-client` facade 与生成绑定、`api-server` 新增 `game_play_counter.rs` / `game_play_counter_worker.rs` 及 config/state/main/handler、前端 `gamePlayClientId.ts` / `gameDistributionClient.ts` / `GamePlayPage.tsx`、`.eslintrc.cjs` 白名单。
+- 权威文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 的 `game_distribution_game` 节，以及 `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` 的「游玩计数（已实现）」节。
+- 验证：`cargo check -p api-server` 与 `cargo test -p api-server game_play_counter`（9 passed）通过；前端定向 vitest（点击上报断言 + clientId 稳定性）与 `eslint --max-warnings 0` 通过；`npm run check:server-rs-ddd`、`npm run check:generated-bindings`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。

 ## 2026-10-03 AGC 画布引用统一走「活跃聊天输入区」注册表（Issue 602）

@@ -3,6 +3,7 @@
 ## 范围

 - 后台管理默认入口为 `#dashboard`，原服务 / 数据库状态页保留为 `#overview`，导航展示名为“服务总览”。
+- 桌面端后台侧边栏按“工作台 / 数据与监控 / 运营配置 / 充值与支付 / AGC 管理 / 内容运营 / 账号权限”分组，默认只展开当前路由所在组。分组标题可独立折叠；每次切换路由（包括同组内跳转和浏览器 hash 导航）自动展开目标组，折叠动作不切换页面。只展示当前账号有权访问的页签，空组不渲染，组内数量只统计可访问页签。折叠状态仅保留在当前页面会话；分组不改变路由 hash、页签权限或移动端底栏的平铺顺序。
 - Dashboard 由 `GET /admin/api/dashboard` 提供统一 BFF 投影，前端只展示后端返回的 `range`、`metrics`、`charts`、`operations` 和 `warnings`。
 - 不新增持久化统计表或字段；profile / tracking 私有事实由仅 runtime service identity 可调用的 `get_admin_dashboard_stats_and_return` procedure 在同一事务快照内聚合，再经 `spacetime-client` facade 返回 api-server；素材与钱包继续复用原有查询。api-server 不再通过固定 `LIMIT` 拉取原始访问明细后自行拼装精确指标；该权威聚合失败时整个 Dashboard 请求失败，不用 0 伪装未知值。
 - 当前 profile / tracking 表没有覆盖这些跨 scope、跨日期统计的现成索引，因此 procedure 为保证精确性仍需遍历相关事实；上线后需监控调用耗时，数据规模继续增长时再以日期前缀索引或持久化日聚合事实替换，不能重新引入固定行数截断。
@@ -487,6 +487,7 @@ Responses 的终态载荷既是工具调用的恢复源，也是正文的恢复
 - 软删除：游戏行末尾追加可空 `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；版本行与冻结资料不变，下一次审核通过仍会用新版本的冻结资料覆盖游戏行。
 - 索引：`by_game_distribution_game_owner_user_id` 用于作者私有游戏列表；`game_id` 为主键。公开目录只返回 `visibility = published`、`deleted_at` 为空且存在有效 `active_version_id` 的投影。
+- 游玩计数写入：`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_review`

@@ -123,6 +123,7 @@
 | --- | --- | --- |
 | `GET /games` | 游客 | **已实现**：关键词与分类筛选，最多 48 项；仅公开可玩版本 |
 | `GET /games/{gameId}` | 游客 | **已实现**：当前公开资料与 `currentVersion.entryUrl`；不可见时 404 |
+| `POST /games/{gameId}/plays` | 游客/登录 | **已实现**：上报一次「开始游戏」；可选 Bearer，非公开 404、超限 429，成功返回 `{recorded}`；只进 api-server 内存缓冲，失败不影响游玩 |
 | `GET /game-distribution/releases/{gameId}[/{assetPath}]` | 游客 | **已实现**：根路径等价于 `index.html`；发行网关只服务当前已公开版本包内文件，按扩展名白名单设内容类型，未知扩展名 404，带 Cookie 的请求 403；游玩页的入口来自详情投影的 `currentVersion.entryUrl` |
 | `GET /my-games` | 登录作者 | **已实现**：当前账号游戏、最近版本状态与驳回理由；owner 只从认证主体派生，单次最多 48 项 |
 | `GET /my-games/{gameId}` | 登录作者 | **已实现**：作者读自己名下单个游戏的详情，条目与 `GET /my-games` 同形（含全部版本私有状态、驳回理由与已公开版本的 `entryUrl`）。作者要能打开「审核中 / 被驳回 / 已下架 / 已撤回」的作品，公开详情只服务已公开投影，所以作者视角必须走这条 owner 作用域路由；游戏不存在或不属于当前主体都返回 404 |
@@ -144,6 +145,14 @@

 领域规则进入 `module-*`，游戏/版本/审核/操作账本和事务进入 `spacetime-module`，访问统一通过 `spacetime-client`，HTTP 与上传编排进入 `api-server`，对象存储副作用复用 `platform-*`，跨端 DTO 同步 Rust `shared-contracts` 与 `packages/shared`。新业务必须使用当前正式表与契约，不得以未挂载源码或非正式私有快照作为公开事实；实际表字段、索引、受信服务身份及迁移清单在持久化里程碑评审时冻结。已有表若确需加字段，只能末尾追加并给明确默认值；删除/改名/重排/改类型必须另行确认迁移计划。

+### 游玩计数（已实现）
+
+- **触发点**：游玩页点击「开始游戏」时网页上报一次，不做 iframe load、不在发行网关计数、不设停留阈值；点击后即使 iframe 超时也计一次。计数失败静默，绝不阻断进入游戏。
+- **落点**：复用 `game_distribution_game.play_count` 累计次数，随目录、详情、作者「我的游戏」与后台游戏管理投影读取，不另建计数表。
+- **缓冲与延迟**：`api-server` 纯内存聚合（增量表 + 30 分钟去重表 + 限流表），flush 间隔由 `GENARRATIVE_GAME_PLAY_COUNTER_FLUSH_INTERVAL_MS` 配置（默认 5s），经批量 procedure 落库；读路径不叠加内存值，展示最多滞后一个 flush 间隔。崩溃、被杀和正常关停都允许丢最后一个未落库窗口，关停不做强制 flush。
+- **去重与限流**：登录用 `userId`、匿名用网页持久的 `clientId`、都拿不到时回退 `IP + UA`（`IP` 取 nginx 覆盖写入的 `X-Real-IP`，不取可伪造的 `X-Forwarded-For` 首段）；`identity + gameId` 30 分钟去重窗口，另按 `IP + gameId` 每分钟 60 次固定窗口限流（超限 429）。公开上报端点先做内存限流预检，超限直接 429、不再查公开可见性；非公开/下架/封禁返回 404 且不计数。
+- **写入语义**：批量 procedure 在事务内只对 `published` 且存在有效公开版本的记录做 `saturating_add`，且**不更新** `updated_at`（避免重排作者列表）。该指标定位为展示用次数，不做交易级幂等、双计补偿或跨实例窗口共享。flush 按 500 分片，任一分片失败即终止本次 flush、剩余分片直接丢弃：`Build`（确定未发出）只把当前分片放回下一轮，其余错误连本批一起丢弃。
+
 ### 发行路径、沙箱与网络能力

 - 发行入口是平台同源路径 `https://<平台域名>/games/<gameId>/`，边缘 nginx 把该前缀原样映射到 `api-server` 发行网关。运行隔离不依赖独立来源，而由 iframe `sandbox="allow-scripts"` 把游戏文档固定在不透明来源：游戏拿不到主站 Cookie、`localStorage`、`IndexedDB`、DOM 与 Service Worker，离开页面即随 iframe 卸载整套游戏代码。