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

补充广场卡片评分、公开投影和兼容失败行为合同
新增单里程碑验收标准及实施计划
同步文档索引和共享决策记录

docs/README.md

@@ -23,6 +23,7 @@
 - [网站游戏评分与评价里程碑](./project-memory/plans/【里程碑】网站游戏评分与评价-2026-09-30.md)：唯一评价、编辑预填、4000 字符、公共分页与平均分/人数的验收边界与本地证据。
 - [后台游戏评价管理合同](./【玩法创作】平台入口与玩法链路-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)：方案已确认，待实现；公开列表/详情携带真实摘要，卡片显示一位小数均分与人数，复用有效评价统计。
 - [外部 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 契约唯一机器可读来源。

docs/project-memory/plans/【实施计划】游戏广场评分展示-2026-10-01.md

@@ -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、浏览器和部署均待执行。文档检查结果只证明文档完整性，不证明功能已实现。

docs/project-memory/plans/【里程碑】游戏广场评分展示-2026-10-01.md

@@ -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、浏览器及生产部署尚未执行。既有评价与后台管理证据不能作为本里程碑已通过的证据。

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

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

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

@@ -2,7 +2,7 @@
 
 > 更新时间：`2026-10-01`
 >
-> 本文描述现役主站平台壳、图片画布编辑器和游戏分发合同；拟新增能力在各节单独标明状态。网站游戏评分与评价、后台游戏评价管理已实现并通过本地验证，待用户验收，未部署。当前实现以路由树、shared-contracts 和 SpacetimeDB module / bindings 为准。
+> 本文描述现役主站平台壳、图片画布编辑器和游戏分发合同；拟新增能力在各节单独标明状态。网站游戏评分与评价、后台游戏评价管理已实现并通过本地验证，待用户验收，未部署；游戏广场评分展示方案已确认，待实现。当前实现以路由树、shared-contracts 和 SpacetimeDB module / bindings 为准。
 
 ## 现役平台入口
 
@@ -197,7 +197,7 @@
 - 用户已确认加入详情页平均分和评分人数：无人评分显示“暂无评分”，空评论计入评分人数，修改不增加人数，当前规模先由后端读取评价记录计算。
 - 本方案采用以下评审默认值：评分只接受整数；每页默认 20 条；按首次提交时间倒序；取消首次填写清空草稿，取消编辑恢复原评价；评价跟随游戏身份，不随发行版本更新清空。
 - 登录用户均可评价，包括游戏作者；不增加必须先游玩、消费或具有发布权限的条件。评价权限不复用 `game-distribution:publish` 发布灰度。
-- 本次不增加 AGC 客户端评价界面、独立评价页面、游戏目录评分展示、评论回复/点赞/图片/Markdown、评价删除、评价审核或推荐排行；不新建通用评论框架、评分缓存或独立统计任务。
+- 基础评价功能不包含 AGC 客户端评价界面、独立评价页面、游戏目录评分展示、评论回复/点赞/图片/Markdown、评价删除、评价审核或推荐排行；后台管理与广场评分展示分别由下方独立合同扩展，不新建通用评论框架、评分缓存或独立统计任务。
 
 ### 评分、评论与统计口径
 
@@ -262,7 +262,7 @@
 - 对同一条评价的并发修改采用后提交成功的事务覆盖，避免为该低风险编辑引入新版本锁或操作账本；重复提交相同内容返回已有记录，不变更人数和创建时间，也不制造修改时间。
 - 公共作者资料由现有账号公开投影取得，不能由评论请求伪造昵称或头像；私有表不直接对浏览器订阅公开。日志不记录评论正文、Token 或私有账号字段。
 - 新增表，不删除、改名、重排或修改现有游戏/版本字段；同步迁移登记、表目录、生成绑定与 schema 检查。现有评价数据不存在，无需旧数据回填；已有游戏无评价时自然返回空列表与“暂无评分”。
-- 旧客户端和现有游戏目录、详情 DTO 不需要增加必填字段；评分摘要由新增评价接口提供。本次不扩展 `/api/external/v1`，不改外部 OpenAPI。
+- 基础评价功能由新增评价接口提供评分摘要，不要求旧客户端或原游戏目录、详情 DTO 增加必填字段；广场评分展示对公开游戏投影的增量约束见下方独立合同。本次不扩展 `/api/external/v1`，不改外部 OpenAPI。
 - 规则与校验进入 `module-game-distribution`，表与事务进入 `spacetime-module`，读取经 `spacetime-client` facade，HTTP/鉴权进入现有 `api-server` 分发路由，DTO 同步 `shared-contracts` / `packages/shared`；网站只持有展示和编辑草稿。
 
 ### HTTP 与 DTO
@@ -404,3 +404,56 @@
 回归脚本精简后，在现有本机隔离服务上以新 fixture 复跑：网站 40 项、后台 51 项 HTTP 检查通过，后台 `prepare` / `check` 不再依赖旧库验收产物。网站交互 11 项、评价领域 5 项、Spacetime module 编译、网站类型检查及定向格式/静态检查通过。此轮未重新发布 module 或重跑旧库迁移、浏览器验收；HTTP 结果用于验证脚本回归流程，新的内部读取简化由编译和源码条件对照验证。
 
 未验证：生产部署、真实移动设备/系统输入法、无关全量测试和真实游戏包游玩。永久删除由真实 HTTP 验证，浏览器仅验证提示与取消；网络失败草稿由交互自动化验证，未在浏览器断网复现。用户验收尚未完成，计划和里程碑保留；不据此宣称已上线。
+
+## 游戏广场评分展示合同
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | accepted（用户确认方案，待实现；未部署） |
+| Date | 2026-10-01 |
+| 入口 | 网站 `/games` 游戏广场卡片 |
+| 交付目标 | 游客与登录用户在游戏卡片查看真实平均分和评分人数，统计与详情评价及后台管理口径一致 |
+| 里程碑 | [游戏广场评分展示](./project-memory/plans/【里程碑】游戏广场评分展示-2026-10-01.md) |
+
+### 范围与展示规则
+
+- 在广场卡片简介下方、分类和作者信息上方增加评分摘要，保留标题、游玩次数、封面、卡片点击、现有排序及筛选。移动端摘要允许换行，长标题和较大人数不能撑宽卡片。
+- 有评分时显示如 `8.2/10 · 26 人评分`，均分固定一位小数；不把 10 分制转换成 5 星制。无人评分时显示“暂无评分”。
+- 摘要来自列表响应，不为每张卡片请求公共评价页或个人评价；详情仍由现有评价读取/保存结果驱动，保存后可即时更新详情摘要。
+- 广场返回时重新读取列表，保留既有筛选与滚动位置；用户改分或管理员隐藏、恢复、删除后的下一次成功读取反映新统计。不增加推送、轮询或后台管理通知。
+- 本增量只覆盖网站公开评分摘要，不增加评分排序、排行、推荐、评论预览、卡片评分输入、AGC 评价或作者管理页评分展示。
+
+### 统计、可见性与失败行为
+
+- 统计沿用已有有效评价口径：只计算未隐藏的评价，包含空评论、当前用户和作者的评价；每账号每游戏最多计一次，编辑不增加人数，新发行版本不清空评价。
+- 游戏列表仍只返回满足现有公开可见性与有效公开版本规则的游戏；评分不放宽下架、封禁或版本可见性。游戏资料和摘要在同一次数据库读取事务内形成一致快照。
+- 无有效评价时严格返回 `averageScore=null`、`ratingCount=0`；全部评价被隐藏或删除后同样返回该空态。均分由后端对该游戏全部有效评价计算，不由前端分页或累计推导。
+- 列表读取失败沿用整页错误与重新加载入口，不能用虚构零分或“暂无评分”代替失败。兼容期响应缺少评分摘要时，卡片显示“评分暂不可用”，保留游戏资料和打开详情能力；只有明确的 `null/0` 摘要表示无人评分。
+- 公共摘要只包含均分与人数，不返回评论正文、管理原因、管理员身份或个人评价状态；游客读取不要求登录或发布权限。
+
+### API、兼容与数据边界
+
+| 方法与路径 | 增量响应合同 |
+| --- | --- |
+| `GET /api/game-distribution/games` | `data.games[]` 每项保证增加 `ratingSummary:{averageScore:number|null,ratingCount:number}`，原字段和 envelope 保留 |
+| `GET /api/game-distribution/games/{gameId}` | 与列表共用公开投影，保证返回同形状 `ratingSummary`；详情评价接口仍提供提交/刷新时的权威摘要 |
+
+- 公开列表和详情使用 `Cache-Control: no-store`，避免浏览器或代理复用过期摘要；既有评价接口的 no-store 行为保留。
+- 共用游戏 DTO 中 `ratingSummary` 为可选字段，以允许作者侧响应和旧响应省略；当前公开列表/详情必须返回对象。字段缺失与 `averageScore=null,ratingCount=0` 具有不同含义，旧客户端可忽略新增字段。
+- 同步 Rust/TypeScript 共享 DTO、数据库 procedure 返回类型、后端 facade/mapper、生成绑定和响应字段契约检查。摘要在读取时计算，不增加持久化统计表、字段、缓存、回填或重算任务。
+- 公开投影返回类型变化需要数据库 module 与后端绑定配套更新；先验证配套后端/module，再更新网站。现有持久化表及评价数据不变，无破坏性迁移。
+- 不扩展 `/api/external/v1`，不改变外部 OpenAPI、后台管理接口或评价写入语义。
+
+### 验收与当前证据
+
+| 条款 | 验收方式 | 当前证据 |
+| --- | --- | --- |
+| 正常与空态 | 游客卡片显示一位小数/人数；无评价、全部隐藏/删除显示“暂无评分”；缺字段显示“评分暂不可用” | 待实现验证 |
+| 统计一致 | 同一稳定数据集的公开列表、公开详情和评价接口均分/人数一致；多游戏统计不串联，空评论计人数 | 待实现验证 |
+| 修改与管理 | 改分人数不变；隐藏、恢复、删除后下一次读取正确变化；详情返回广场读取最新值 | 待实现验证 |
+| 可见性与故障 | 下架/封禁游戏不进入列表；匿名可读；列表失败不伪装为零评价；私有管理信息不泄漏 | 待实现验证 |
+| 请求与页面 | 列表一次取得全部卡片摘要；筛选/返回滚动行为保留，桌面及 375px 移动布局可操作 | 待实现验证 |
+| 工程与兼容 | DTO/绑定/schema、定向 Rust/Vitest/typecheck、编码/文档索引/diff 检查与隔离环境 API/browser smoke | 待实现验证 |
+
+用户已确认方案，并要求先写文档与提交。本次只交付主规范、单里程碑和实施计划，工程实现、自动化行为测试、真实数据库/API、浏览器与生产部署均未执行；此前基础评价及后台管理证据不能替代本增量验收。