diff --git a/docs/README.md b/docs/README.md index a49333a9a..5857a7069 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,7 +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`。 +- [游戏游玩次数计数](./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 契约唯一机器可读来源。 diff --git a/docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md b/docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md index 949ad7ede..f38fe64fe 100644 --- a/docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md +++ b/docs/adr/【ADR】游戏游玩次数计数-2026-10-03.md @@ -43,8 +43,8 @@ ### 4. api-server 纯内存缓冲 + 周期 flush -- **纯内存，不落盘**：崩溃/被杀允许丢最后一个 flush 窗口；正常 SIGTERM/滚动重启必须在 - `finalize_shutdown` 内 force flush。 +- **纯内存，不落盘**：崩溃、被杀和正常 SIGTERM/滚动重启都允许丢最后一个 flush 窗口；进程退出不做 + force flush，关停路径不为计数等待网络（2026-10-04 修订，见「修订记录」）。 - **两张表**：增量表 `pending: HashMap`（5 秒级、flush 即清）与 30 分钟去重窗口表 `seen: HashMap`（30 分钟级、按 TTL 清理）。两者键不同、生命周期差 360 倍，不能合并： 合并会把 30 分钟窗口状态塞进 5 秒清空的表，或让 flush 需要按 gameId 重新聚合。 @@ -64,6 +64,9 @@ 丢量。理由是：超时后重试会在"其实已提交"时造成系统性双计，而丢弃只是偶发少计——对一个非交易展示指标， 后者更可接受（perf 优先于 correctness）。 +一次 flush 按 500 分块；任一分片失败即终止本次 flush 的后续分片，剩余增量直接丢弃（`Build` 只把当前分片 +放回）。连接不通时剩余分片只会重复同样的失败，逐个重试会把 worker 卡在多次连接超时上（2026-10-04 补充）。 + ### 7. 接口 `POST /api/game-distribution/games/{game_id}/plays`，公开端点（可选 bearer）： @@ -118,11 +121,18 @@ procedure 在 `spacetime-module`，facade + mapper 在 `spacetime-client`，缓 ## 落地与验收 - 实施边界：`spacetime-module` 新增批量自增 procedure 与 `SpacetimeType`；`spacetime-client` facade + - mapper；`api-server` 新增计数模块（增量 / 去重 / 限流 / flush worker / 关停 flush）、AppState 接线与公开 + 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 关停前最后一窗已落库；计数接口任何失败都 + 超限流 `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 任一分片失败即丢弃剩余分片。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 69733d294..5be14ea6c 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -1,12 +1,19 @@ # 决策记录 +## 2026-10-04 游戏游玩次数修订：关停不强制 flush、flush 失败丢弃剩余分片 + +- 变更：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`（上报先做内存限流预检再查公开可见性）。 + ## 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，进程被强杀最多丢一个窗口。 +- 缓冲与写入：`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` 直接丢弃并记录丢失量——少计优于双计，本指标不做双计补偿，也不共享跨实例去重窗口。 +- 失败语义：只把 `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` 通过。 diff --git a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md index d8e96fa7a..13c84302d 100644 --- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md +++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md @@ -141,9 +141,9 @@ - **触发点**：游玩页点击「开始游戏」时网页上报一次，不做 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`（避免重排作者列表）。该指标定位为展示用次数，不做交易级幂等、双计补偿或跨实例窗口共享。 +- **缓冲与延迟**：`api-server` 纯内存聚合（增量表 + 30 分钟去重表 + 限流表），flush 间隔由 `GENARRATIVE_GAME_PLAY_COUNTER_FLUSH_INTERVAL_MS` 配置（默认 5s），经批量 procedure 落库；读路径不叠加内存值，展示最多滞后一个 flush 间隔。崩溃、被杀和正常关停都允许丢最后一个未落库窗口，关停不做强制 flush。 +- **去重与限流**：登录用 `userId`、匿名用网页持久的 `clientId`、都拿不到时回退 `IP + UA`；`identity + gameId` 30 分钟去重窗口，另按 `IP + gameId` 每分钟 60 次固定窗口限流（超限 429）。公开上报端点先做内存限流预检，超限直接 429、不再查公开可见性；非公开/下架/封禁返回 404 且不计数。 +- **写入语义**：批量 procedure 在事务内只对 `published` 且存在有效公开版本的记录做 `saturating_add`，且**不更新** `updated_at`（避免重排作者列表）。该指标定位为展示用次数，不做交易级幂等、双计补偿或跨实例窗口共享。flush 按 500 分片，任一分片失败即终止本次 flush、剩余分片直接丢弃：`Build`（确定未发出）只把当前分片放回下一轮，其余错误连本批一起丢弃。 ### 发行路径、沙箱与网络能力