文档：补充游玩计数契约与决策记录

- 玩法链路：路由表新增 POST /games/{gameId}/plays，并新增「游玩计数（已实现）」小节说明触发、落点、缓冲延迟、去重限流与写入语义
- 后端架构：game_distribution_game 节补 play_count 的批量 procedure 写入路径与参数
- decision-log：记录内存去重缓冲 + 批量 procedure 落库的决策、失败语义与影响范围

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

@@ -1,5 +1,16 @@
 # 决策记录
 
+## 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，进程被强杀最多丢一个窗口。
+- 身份与限流：登录用 `userId`、匿名用网页 `localStorage` 的 `clientId`（不可用时退化为会话内存值）、都拿不到回退 `IP + UA`；`identity + gameId` 30 分钟去重，`IP + gameId` 每分钟 60 次固定窗口限流。非公开/下架/封禁返回 404 且不计数；无效 Bearer 按匿名处理，绝不让计数阻断游玩。
+- 失败语义：只把 `SpacetimeClientError::Build`（未发出）放回重试；`Timeout` / `ConnectDropped` / `Procedure` 直接丢弃并记录丢失量——少计优于双计，本指标不做双计补偿，也不共享跨实例去重窗口。
+- 影响范围：`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 生成绑定不再经 prettier：ts-rs 原始输出即提交形态
 
 - 背景：`scripts/check-generated-bindings.mjs` 对 AGC 的 `chat/generated` / `services/generated` 在重生成后会就地跑一遍 `npx prettier --write` 再比较。这会直接改写生成文件，还把「Rust 声明真的变了」与「prettier 版本 / 配置造成的格式漂移」混在同一条告警里——本次报出的 `ThreadRequestKind.ts` / `TurnCompletedStatus.ts`「内容变化」无法复现为语义变化（已提交内容与当前 Rust 枚举一致），prettier 归一化把格式差异也报成了「与 Rust 声明不一致」；生成物被仓库格式化工具二次改写后，重跑 `cargo test export_bindings` 也不再幂等。

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -461,6 +461,7 @@ 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` 并只新增版本，避免“更新”被实现成新建游戏；该字段只是复用提示，不构成所有权或路径凭证，也不能用于跨账号匹配。
 - 索引：`by_game_distribution_game_owner_user_id` 用于作者私有游戏列表；`game_id` 为主键。公开目录只返回 `visibility = published` 且存在有效 `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`
 

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -119,6 +119,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 只从认证主体派生 |
 | `POST /games` | 登录作者 | **已实现**：幂等创建游戏身份，尚不公开；带 `localProjectId` 时同一作者复用既有 `gameId` |
@@ -136,6 +137,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 间隔。进程被强杀允许丢最后一个窗口，正常关停会在 outbox flush 超时内强制落库。
+- **去重与限流**：登录用 `userId`、匿名用网页持久的 `clientId`、都拿不到时回退 `IP + UA`；`identity + gameId` 30 分钟去重窗口，另按 `IP + gameId` 每分钟 60 次固定窗口限流（超限 429）。非公开/下架/封禁返回 404 且不计数。
+- **写入语义**：批量 procedure 在事务内只对 `published` 且存在有效公开版本的记录做 `saturating_add`，且**不更新** `updated_at`（避免重排作者列表）。该指标定位为展示用次数，不做交易级幂等、双计补偿或跨实例窗口共享。
+
 ### 发行路径、沙箱与网络能力
 
 - 发行入口是平台同源路径 `https://<平台域名>/games/<gameId>/`，边缘 nginx 把该前缀原样映射到 `api-server` 发行网关。运行隔离不依赖独立来源，而由 iframe `sandbox="allow-scripts"` 把游戏文档固定在不透明来源：游戏拿不到主站 Cookie、`localStorage`、`IndexedDB`、DOM 与 Service Worker，离开页面即随 iframe 卸载整套游戏代码。