Merge remote-tracking branch 'origin/master' into fix/test-concurrent-problem

# Conflicts: # docs/project-memory/shared-memory/pitfalls.md
2026-10-01 19:50:10 +08:00
parent 348d20bf55 b60aea4e71
commit 6cfc69abf5
90 changed files with 9031 additions and 98 deletions
@@ -1,5 +1,38 @@
 # 决策记录

+## 2026-10-01 游戏广场评分展示边界
+
+- 用户确认广场卡片增加一位小数的 10 分制平均分与评分人数，无有效评价显示“暂无评分”；保留现有排序、筛选、卡片打开详情及返回上下文。
+- 公开游戏列表和详情共用投影，随现有请求返回 ratingSummary；复用后端有效评价统计并排除隐藏记录，不逐卡请求评价，不增加统计表、缓存或重算任务。
+- 共用 DTO 可选字段兼容作者及旧响应，当前公开列表/详情保证返回；缺字段显示“评分暂不可用”，不能伪装为无人评分。读取与后台管理后的下一次刷新一致，不增加推送/轮询。
+- 本增量不改变持久化表或评价写入，仅同步读取投影、DTO 与生成绑定；不扩展评分排序、推荐、AGC 或外部 API。
+- 用户要求测试保持简单：仅补卡片正常/零评价/缺摘要及公开摘要契约断言，复用已有统计/管理/目录测试和少量隔离数据 smoke；不新增专用 E2E、分页 fixture 或逐层重复测试。
+- 权威入口：[游戏广场评分展示合同](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#游戏广场评分展示合同)。已完成工程实现及本地定向验证，待用户验收，未部署；持久化表未变，公开 procedure 返回类型与后端绑定需配套发布。
+
+## 2026-10-01 后台游戏评价管理规则
+
+- 用户确认新增管理员隐藏/删除评价，后台不能修改分数或正文；隐藏整条评价并从公共列表、平均分、人数和公共分页总数排除，恢复后重新参与。个人区域固定提示“已被管理员隐藏”，用户仍可编辑但不能自动恢复公开。
+- 隐藏和删除必须填写原因，恢复不要求；原因仅后台展示。删除物理移除，不能恢复，用户可重新评价，唯一规则继续成立。
+- 当前方案范围为游戏名称选择/ID定位、评价用户 ID、评论关键词、状态四类组合筛选，以及分页、详情、单条操作和持久操作记录。不增加批量、导出、举报、自动审核或评分/时间范围筛选。
+- 实现边界：评价表末尾追加默认 false 的 is_hidden；新增私有管理记录，事务保存操作人/原因/时间，以创建时间区分删除后重建记录，同 key 重试不得再次操作新评价。不增加统计缓存；用户编辑保持隐藏状态，管理操作不改变用户内容时间。
+- 状态：用户确认按方案实施；后台与网站联动已实现并通过本地存量升级、真实 HTTP 和浏览器验证，证据见主规范。待用户验收，未部署。产生隐藏记录后不得直接回退到未过滤隐藏状态的旧后端。
+- 权威入口：[后台游戏评价管理合同](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#后台游戏评价管理合同)；活动[里程碑](../plans/【里程碑】后台游戏评价管理-2026-10-01.md)与[实施计划](../plans/【实施计划】后台游戏评价管理-2026-10-01.md)。
+
+## 2026-09-30 网站游戏评价范围与状态边界
+
+- 已确认需求：网站游戏详情支持每账号每游戏唯一一条 1–10 分评分和可空的评论（最多 4000 字符），可修改自己的评价；个人区默认展示已有评价并提供编辑预填，公共列表分页且不排除自己。
+- 已确认扩展：详情显示真实平均分与评分人数，空评论计人数，修改不增加人数；当前先由后端评价记录计算，不增加统计缓存。
+- 状态：用户已确认按最新方案实现；整数评分、默认每页 20 条、创建时间排序、取消行为与游戏维度保留作为现行合同。网站与后端实现已落地，本地验收证据见主规范；用户验收与生产发布单独确认。原发行 Version 0.2 的排除项不再被解释为永久禁止新增用户评价。
+- 实现边界：新增私有 `game_distribution_review` 表和三条评价 API，游戏/账号组合主键保证唯一；可见性与写入同事务，分页与均分来自一致快照，作者资料读时关联账号。网站用游戏/账号上下文隔离草稿，以读取序号隔离旧成功、错误和加载结束，保存期间冻结输入。
+- 权威入口：[平台入口与玩法链路](../../【玩法创作】平台入口与玩法链路-2026-05-15.md#网站游戏评分与评价合同)；执行验收使用[独立里程碑](../plans/【里程碑】网站游戏评分与评价-2026-09-30.md)，不得把既有发行或本次文档检查当作评价功能上线证据。
+
+## 2026-10-01 生产 Nginx 以模板为唯一来源：host-only 块独立成 snippet、退役路由不做显式 404
+
+- 背景：线上主站 `genarrative.conf` 长期手工维护，`profile` 未进 SPA allowlist 导致 `/profile` 刷新 404，`client_max_body_size` 也停在 `64m`；同时线上存在 4 处仓库模板没有的 host-only 块（画廊读取限流、`/finance-forecast/`、`/medical-science/`、`/home/` 官网首页入口），直接用 `Genarrative-Server-Provision` 覆盖会静默删除它们。
+- 决策：生产 vhost 以 `deploy/nginx/genarrative.conf` 为唯一来源；生产机专属路径收进 `deploy/nginx/snippets/genarrative-host-extras.conf`，由主模板 include、由 Server-Provision 安装，新增平台路由仍必须在主模板内声明并同步 `deploy/pingora/nginx-route-parity.matrix.json` 与 Pingora 网关。snippet 内的 location 有意不在矩阵覆盖范围，Pingora 接公网 443 前必须单独确认这些路径的处理方式。
+- 边界：退役路由（`/match3d`、`/puzzle`、`/runtime/*`、`/gallery/*/detail`、`/works/detail`、`/worlds/detail`、`/bark-battle` 等）不再进 SPA allowlist，也不配置显式 404，统一落 `location /` 的 `error_page 404 /404.html`。`/home/` 是 2026-08-11 官网拆分前的历史入口，是否退役需与官网侧一起决定。
+- 验证方式：`node scripts/check-nginx-spa-routes.mjs`、`node scripts/check-pingora-route-parity.mjs`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`、`bash -n scripts/jenkins-server-provision.sh`；线上改后按生效配置烟测 `/profile`、模板 12 条 SPA 路由、`/admin/`、`/home/`、`/finance-forecast/`、`/medical-science/`、画廊 API 与 `/games/game_<id>/…` 发行网关。
+
 ## 2026-10-01 DirectProject 审批拒绝原因留痕

 - 决策：宿主拒绝 app-server 的审批 / 交互请求时，原因必须落 AppData `RUST` 日志。稳定键 `agent.direct_codex.approval.denied`，字段为 `thread_id` / `method` / `reason` / `distinct_reasons`；未绑定宿主执行器时另记 `agent.direct_codex.interaction.no_adapter`（`method` / `outcome`，`outcome` 区分 `decline` / `empty-permissions` / `unsupported-method`）；回包未送达另记 `agent.direct_codex.approval.response_delivery_failed`，`cause` 区分 `response-write-failed` 与 `turn-bind-mismatch`。
@@ -2,6 +2,13 @@

 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。

+## 2026-10-01 线上 Nginx 手工维护漂移：`/profile` 刷新 404、发行包请求体仍限 64m
+
+- **现象**：登录后刷新 `https://www.genarrative.world/profile` 直接 404，返回 Nginx 默认 404 页（162 字节）；应用内点击进入正常。`curl` 复现：`/`、`/project`、`/creation`、`/components`、`/design-system`、`/games*`、`/editor/canvas` 全部 200 且正文与 `/` 同一份 SPA 外壳，只有 `/profile`（含 `/PROFILE`、`/profile/`）404。
+- **原因**：刷新是真实 HTTP 请求，命中线上 `/etc/nginx/conf.d/genarrative.conf` 的 SPA allowlist；线上白名单是手工维护的（留档 `genarrative.conf.bak-sparoutes-20260923T153751Z`），`profile` 从未加入，该深链落回 `location /` 的 `try_files $uri $uri/ =404`。仓库三份模板当时都写了 `profile`，而 `npm run check:nginx-spa-routes` 只校验仓库模板，查不出线上漂移。同一份线上文件还把 `client_max_body_size` 停在 `64m`（模板 210m，会让 200 MiB 发行包上传 413），并保有 4 处模板没有的 host-only 块（画廊读取限流 location、`/finance-forecast/`、`/medical-science/`、`/home/` 官网首页入口），所以直接拿模板整文件覆盖会删掉这些线上能力。
+- **处理**：线上只收敛 SPA allowlist（12 条，含 `/profile`）并补 `error_page 404 /404.html`；host-only 块收进 `deploy/nginx/snippets/genarrative-host-extras.conf`，由主模板 include、由 `Genarrative-Server-Provision` 安装。退役路由不进白名单，也不需要显式 404 配置，落 `location /` 即得品牌 404（非 HTML 客户端保持纯 404）。
+- **判据/取证**：改前 `grep -c profile /etc/nginx/conf.d/genarrative.conf` 为 0；改后 `curl -s -o /dev/null -w '%{http_code}' https://www.genarrative.world/profile` 为 200（正文 sha 与 `/` 一致），`sudo nginx -T | grep -c 'editor/canvas|profile|project'` 为 1，`match3d` 计数为 0。
+- **长期口径**：任何 SPA/路由白名单改动都要同时核对**生效配置**（`sudo nginx -T`）与仓库模板；线上主站 vhost 只由模板 + `genarrative-host-extras.conf` 生成，不再手工追加路由。snippet 内的 location 不在 Pingora 路由矩阵覆盖范围，Pingora 接公网 443 前要单独确认这些 host-only 路径。
 ## 2026-09-30 构建期 staging 撞上不装 npm 依赖的 Linux 门禁：AGC 壳 Rust lane 全红

 - **现象**：`Project CI` 的 AGC 壳 Rust 三条 lane（`npm run check:native-shells:agc-rust-shard-*`）在 `fb130d184` 之后全部失败，日志只有 `error: failed to run custom build command for genarrative-ai-game-creator-shell` 与 `thread 'main' panicked at build.rs:65:28: Claude Agent SDK 缺失；请先执行 npm ci`（run 3083 / job 17521 实测，1 分钟即失败）。
@@ -6200,3 +6207,16 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理（现行口径）**：`src/tests/mod.rs` 新增 `MOCK_PROVIDER_REQUEST_TIMEOUT`（30 秒）作为「等一条 mock provider 请求到达」的唯一预算，`wait_for_captured_mock_request` 与 `sessions.rs` 里 7 处 `recv_timeout` 统一引用它；负向断言（确认「不会有下一个请求」的 200ms 窗口）保持不动。请求到达即返回，成功路径零成本，真断链仍会失败，只是失败得更晚。
 - **验证**：`cargo test --bin genarrative-ai-game-creator-shell tests::sessions:: -- --test-threads=1` 44 passed；`node apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs --shards=4 --shard-index=4` 787 tests ok in 88.7s（正是原先失败的那一片）。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/tests/sessions.rs`、`apps/ai-game-creator-shell/src-tauri/src/tests/mod.rs`。
+
+## 2026-10-01 AGC 官方 Claude 模型缺少账号令牌会被误报为通道断开
+
+- **现象**：模型目录把回合路由到 `cc`，本地 `game-creator.config.json` 的 `llm.apiKey` 为空时，Claude Agent SDK 返回失败终态；界面只显示“执行通道未能建立或已断开”。
+- **根因**：Claude sidecar 只从 `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` 或本地 `llm.apiKey` 读取认证，没有复用已登录的 AGC 平台会话；同时失败终态解析丢弃了上游错误摘要。
+- **处理**：官方模型且未启用自定义目录时，将当前平台会话令牌仅注入 sidecar 子进程环境；保留最多 512 字符的 Claude 终态错误摘要，继续由统一诊断层脱敏，避免凭据落盘。
+## 2026-10-01 AGC 首页把 Web 预检错误与 Tauri IPC 错误合并，造成无法诊断的生成阻拦
+
+- **现象**：用户在首页点击「做游戏」后看到「Web 游戏环境预检未通过，请检查 Node/npm 或浏览器」，但同一安装包的 `--environment-check` 可能已经返回 `status=ready`；首页仍会阻止自动命名、建项和首次生成。
+- **根因**：`homeWebPreflight.ts` 原先对 `preflight_web_game_creation` 的所有异常统一抛出 `HOME_WEB_PREFLIGHT_FAILURE`，调用方 `useHomeProjectCreation.ts` 的两层 `catch` 又再次覆盖原始错误。于是宿主真实预检码、Tauri IPC 断连、命令未注册和 WebView `Failed to fetch` 都显示成 Node/npm/浏览器故障。
+- **处理**：保留预检失败关闭语义，但提取 Rust 返回的安全错误码；对无错误码的 Tauri 调用故障显示独立 IPC 提示，并仅对这类瞬态调用失败重试一次。首页调用方必须透传该安全提示，不能重新覆盖为通用文案。
+- **验证**：`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx` 覆盖 ready、具体宿主错误码、IPC 失败、无错误码 blocked 和 planning 绕过；同一 Windows 安装包 CLI 实测 Node `v22.22.2`、npm `10.9.7`、Edge desktop/mobile PNG 均通过。
+- **关联**：`apps/ai-game-creator-shell/src/features/app-shell/homeWebPreflight.ts`、`apps/ai-game-creator-shell/src/features/app-shell/useHomeProjectCreation.ts`、`apps/ai-game-creator-shell/tests/homeWebPreflight.test.tsx`、`apps/ai-game-creator-shell/src-tauri/src/environment_check/web_creation.rs`。