文档：明确游戏广场评分展示方案

补充广场卡片评分、公开投影和兼容失败行为合同新增单里程碑验收标准及实施计划同步文档索引和共享决策记录
2026-10-01 08:03:56 +00:00
parent 824768615a
commit fd39ed507b
5 changed files with 172 additions and 3 deletions
@@ -0,0 +1,50 @@
+# 【实施计划】游戏广场评分展示
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | [游戏广场评分展示](./【里程碑】游戏广场评分展示-2026-10-01.md) |
+| Status | ready（用户确认方案，待开始工程实现；本次仅提交文档） |
+| Date | 2026-10-01 |
+| Owner | Codex |
+
+## 修改边界
+
+- 主规范：[游戏广场评分展示合同](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏广场评分展示合同)；仅实施本里程碑。
+- 数据读取：`server-rs/crates/spacetime-module/src/game_distribution.rs` 的公开快照、列表/详情读取及 procedure 返回类型；复用已有评分 helper。现有持久化表、索引、评价写入与 migration 登记不变。
+- 后端：`spacetime-client/src/active/mapper/game_distribution.rs` 公开 record 和 mapper、`shared-contracts/src/game_distribution.rs`、`api-server/src/modules/game_distribution.rs` 公开响应与 no-store；通过既有 facade，不新增数据库访问通道。
+- 前端：`packages/shared/src/contracts/gameDistribution.ts`、共享评分文本组件及导出，网站 `GameGalleryPage.tsx`、`GameReviews.tsx` 和对应 CSS/定向测试；API client 只按必要调整类型，不新增逐卡读取。
+- 契约检查：`scripts/check-game-distribution-dto-parity.mjs`、生成绑定及既有评分/后台管理 E2E 脚本中相关断言。
+- 文档：主规范、本文、里程碑、文档索引及稳定决策。后台 UI、AGC、外部 OpenAPI、发行包链路不在修改范围。
+
+## 实现顺序
+
+1. 扩展 `GameDistributionPublicGameSnapshot` 返回类型，追加 `average_score:Option<f64>` 与 `rating_count:u64`；复用 `game_distribution_user_rating_summary` 及领域 `visible_review_summary` 的隐藏过滤、一位小数和空态。列表先核对公开可见性与有效版本、按原规则排序并限量，再只为返回项构建含摘要的快照；不能让无效版本占用限量名额。详情共用该公开快照。
+2. 同步生成绑定与公开 record/mapper，将摘要映射为既有 `GameDistributionRatingSummaryRecord`。浮点数进入公开快照/record 后，移除其及引用结果类型中不适用的 `Eq`，保留 `PartialEq`；record 嵌入摘要时按现有序列化用途补齐必要 derives。
+3. Rust/TS 共用游戏 DTO 追加可选 `ratingSummary`，Rust 允许旧字段缺失；公开 `public_game_payload` 必须输出摘要对象，复用既有摘要转换。同步列表/详情 no-store、DTO parity 的公开构建器 `mustEmit` 和必要嵌套约束；作者 `game_payload` 可省略摘要，不造零值。
+4. 将纯评分文本展示抽到 `packages/shared`，只接收摘要数据，复用一位小数及人数表现。现有 `GameRatingSummary` 保留详情评价的加载/错误/重试职责，已加载文本使用共享组件；广场卡片使用列表摘要，无额外评价请求，缺字段显示“评分暂不可用”。卡片简介下增摘要行，采用现有视觉变量并允许移动换行。
+5. 更新定向测试及现有 E2E 断言：零评价、有评分、空评论、多游戏、全部隐藏、恢复、删除及改分；稳定数据集比对列表/详情/评价接口。验证返回广场重新挂载读取、原筛选/滚动恢复和旧响应隔离，不引入全局同步状态。
+6. 执行定向工程检查与隔离运行时/browser smoke，按主规范回写证据和限制，交付用户验收；验收通过后融合持久结论并清理临时计划。
+
+## 验证命令与操作
+
+- `cargo test --manifest-path server-rs/Cargo.toml --locked -p module-game-distribution reviews`
+- `cargo test --manifest-path server-rs/Cargo.toml --locked -p shared-contracts game_distribution`
+- `cargo test --manifest-path server-rs/Cargo.toml --locked -p api-server game_distribution`
+- `cargo check --manifest-path server-rs/Cargo.toml --locked -p spacetime-module -p spacetime-client`
+- `npm run spacetime:generate`、`npm run check:generated-bindings`、`npm run check:spacetime-schema`、`npm run check:game-distribution-dto-parity`
+- `npm run test -- src/components/game-distribution/GameDistributionPages.test.tsx src/components/game-distribution/GameReviews.test.tsx src/services/gameDistributionClient.test.ts`，追加新共享展示组件的定向测试。
+- `npm run typecheck`，对受影响代码运行仓库现有格式/静态检查。
+- `npm run check:doc-index`、`npm run check:encoding`、`git diff --check`。
+- 按现有 dev 脚本启动显式隔离数据库和 `npm run dev:api-server`，读取 `.app/dev-stack.json` 核对目标/端口，检查 `/healthz`；用既有 ratings 与 moderation E2E 流程验证新增列表/详情断言，不访问生产或清空数据。
+- 真实浏览器桌面与 375px 移动视口验证有/无评分、长标题与人数、列表错误/重试、详情改分后返回、筛选及滚动恢复。记录请求，确认卡片摘要随列表返回。
+
+## 风险与回滚点
+
+- 公开 procedure 返回类型属于配套运行时合同；module、生成绑定和后端先在隔离环境一起验证，再按现有运维流程发布，网站随后更新。无需持久化迁移或数据回填，不能用删除数据处理类型不匹配。
+- 评分聚合仅作用于返回项，并使用既有按游戏索引；保留有效版本过滤与排序，避免额外扫描全部匹配游戏的评价。当前规模不增加缓存、统计表或预计算任务。
+- 缺字段只表示不可用，不能默认成 `null/0`；详情评价状态继续由现有读取/保存驱动，避免公开投影摘要覆盖提交后的最新值。
+- 回滚网站展示可保留新增公开字段；回滚 module/后端必须恢复互相匹配的绑定，并继续过滤隐藏评价。不得退回不识别管理隐藏状态的基础评价旧实现。
+
+## 未验证
+
+本次仅落地方案文档，工程实现、行为测试、绑定生成、真实数据库/API、浏览器和部署均待执行。文档检查结果只证明文档完整性，不证明功能已实现。
@@ -0,0 +1,57 @@
+# 【里程碑】游戏广场评分展示
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | accepted（用户确认方案，待实现；未部署） |
+| Date | 2026-10-01 |
+| Parent Spec | [游戏广场评分展示合同](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏广场评分展示合同) Version 1.0 |
+
+## 目标
+
+在网站游戏广场交付真实评分摘要展示，保持与详情评价及后台隐藏/恢复/删除后的统计一致，并保留原有目录交互。
+
+## 范围
+
+- 游客与登录用户均可在卡片查看 10 分制一位小数均分和评分人数，无有效评价显示“暂无评分”。
+- 公开列表和详情返回同形状摘要，统计来自后端全部有效评价，与公开游戏资料采用一致读取快照。
+- 空评论计人数，编辑不增加人数；隐藏/删除不计入，恢复重新参与，新版本保留评分。
+- 列表一次取得摘要，详情返回广场重新读取，并保留既有筛选与滚动位置。
+- 缺少摘要与无人评分明确区分，列表故障沿用重试；桌面和移动卡片均可正常展示和操作。
+- 共享契约、生成绑定和配套运行时验证，不改变持久化表或既有数据。
+
+## 不在范围内
+
+- 卡片输入评分、评论预览、评分排序、排行、推荐、AGC 或作者管理页评分展示。
+- 统计持久化/缓存/重算任务、推送/轮询、评价写入和管理规则变更、外部 API。
+- 原网站评价与后台管理的用户验收、生产部署或游戏发行包验收。
+
+## 依赖与前置条件
+
+- 用户已确认方案，本次授权先编写并提交文档；本里程碑尚未开始工程实现。
+- 当前基础评价、后台管理与有效评价统计已实现并通过本地验证，其用户验收和生产发布状态独立。
+- 现有公开游戏目录、详情、平台认证、数据库服务身份与后端访问链路可用。
+- 有隔离测试游戏和评价账号，可验证多游戏统计、管理状态变化及真实桌面/移动视口。
+
+## 验收标准
+
+- [ ] 游客和登录用户均显示真实 `8.2/10 · 26 人评分` 形状，均分固定一位小数。
+- [ ] 无评价及全部隐藏/删除为 `null/0` 和“暂无评分”，缺摘要为“评分暂不可用”，不显示虚构分数。
+- [ ] 公开列表、公开详情、评价接口在稳定数据集上的统计一致；多游戏不串数据，统计覆盖全部有效评价而非当前评价页。
+- [ ] 空评论计人数，改分只改均分，改文字不改均分；隐藏/恢复/删除后下一次读取正确变化。
+- [ ] 下架/封禁或没有有效公开版本的游戏不进入目录；摘要不泄漏评论、管理原因、管理员或个人状态。
+- [ ] 广场不逐卡请求评价；列表失败显示原错误/重试，旧响应不覆盖新筛选结果。
+- [ ] 详情修改评分后返回广场读取最新值；筛选、封面、卡片点击和滚动恢复行为保留。
+- [ ] 桌面和 375px 移动视口下长标题、大人数及评分换行不溢出、不阻挡操作。
+- [ ] 新公开响应保证带摘要，作者/旧响应可省略；DTO/绑定/schema 与定向检查通过，持久化数据保持。
+- [ ] 真实隔离数据库/API和浏览器证据对照主规范记录，缺失验证如实标明。
+
+## 证据要求
+
+- 自动化：公开投影映射/响应、共享契约新旧形状、卡片正常/空态/缺摘要，以及原目录和详情交互回归。
+- 运行时：多游戏和超过一页评价的数据集，公开列表/详情/评价接口对照；改分、隐藏/恢复/删除后的读取及浏览器返回广场。
+- 边界：全部隐藏、零评价、不可公开游戏、匿名读取、缺摘要/列表失败、迟到响应及移动布局。
+
+## 未验证
+
+当前仅确认并记录方案；工程实现、行为测试、数据库/API、浏览器及生产部署尚未执行。既有评价与后台管理证据不能作为本里程碑已通过的证据。
@@ -1,5 +1,13 @@
 # 决策记录

+## 2026-10-01 游戏广场评分展示边界
+
+- 用户确认广场卡片增加一位小数的 10 分制平均分与评分人数，无有效评价显示“暂无评分”；保留现有排序、筛选、卡片打开详情及返回上下文。
+- 公开游戏列表和详情共用投影，随现有请求返回 ratingSummary；复用后端有效评价统计并排除隐藏记录，不逐卡请求评价，不增加统计表、缓存或重算任务。
+- 共用 DTO 可选字段兼容作者及旧响应，当前公开列表/详情保证返回；缺字段显示“评分暂不可用”，不能伪装为无人评分。读取与后台管理后的下一次刷新一致，不增加推送/轮询。
+- 本增量不改变持久化表或评价写入，仅同步读取投影、DTO 与生成绑定；不扩展评分排序、推荐、AGC 或外部 API。
+- 权威入口：[游戏广场评分展示合同](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏广场评分展示合同)。当前先交付文档，工程实现和验收待完成。
+
 ## 2026-10-01 后台游戏评价管理规则

 - 用户确认新增管理员隐藏/删除评价，后台不能修改分数或正文；隐藏整条评价并从公共列表、平均分、人数和公共分页总数排除，恢复后重新参与。个人区域固定提示“已被管理员隐藏”，用户仍可编辑但不能自动恢复公开。