From f58f51052c0ecde2f1fc9eba8874f37ac10a9c56 Mon Sep 17 00:00:00 2001
From: Suzumiya <suzmii@qq.com>
Date: Mon, 5 Oct 2026 17:15:07 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E6=AD=A3=20pitfalls=20=E9=87=8C?=
 =?UTF-8?q?=E7=9A=84=E5=AE=9E=E6=B5=8B=E6=95=B0=E5=AD=97=EF=BC=9Agzip=20?=
 =?UTF-8?q?=E5=90=8E=20phaser.min.js=20=E4=B8=BA=20353,336=20B=EF=BC=8C?=
 =?UTF-8?q?=E5=B9=B6=E8=AE=B0=E5=BD=95=E4=B8=A4=E4=BE=A7=E7=94=BB=E9=9D=A2?=
 =?UTF-8?q?=E8=80=97=E6=97=B6=E5=AF=B9=E7=85=A7?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/project-memory/shared-memory/pitfalls.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 95905d797..3a4882178 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -6413,5 +6413,5 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/` 
 - **根因**：① 网页游玩页的加载态只有一行小字盖在 `#17131b` 近黑壳上，没有封面/进度/阶段文案，`ready` 判定又只看 iframe `onLoad`（文档加载完成 ≠ 游戏可玩）；② 后台试玩只有 `<iframe class="admin-game-review-preview">`，没有加载态、没有超时、没有失败处理，会话过期或资源 404 会永远停在空白；③ 发行网关把 ZIP 解压后的原文直出，`phaser.min.js` 1,375,976 B 原样下发（`Content-Encoding: none`），也没有 ETag —— 4 Mbps 下光这一个文件就 ~2.7 s，且 60 秒 `max-age` 过后浏览器只能重下整包。
 - **处理（现行口径）**：新增共享组件 `PlatformGameLoadingSurface`（`packages/shared`，封面/标题 + 动效进度 + 按时长推进的阶段文案 + 慢加载提示），网页游玩页与后台试玩共用；两端的加载上限统一为 `PLATFORM_GAME_LOADING_TIMEOUT_MS`（20 秒），后台超时后给出「重新创建试玩会话」。发行网关对文本类资源（HTML/JS/CSS/JSON/SVG/WASM，≥1 KiB、客户端接受 gzip）下发 `Content-Encoding: gzip` + `Vary: Accept-Encoding`，并下发按 `versionId + 资源路径` 摘要的强 ETag，命中 `If-None-Match` 返回 304（无正文）。
 - **边界**：镜像/音频/视频等已是压缩格式的资源不压；后台试玩会话仍是 `no-store` 且不给 ETag；`max-age=60, must-revalidate` 与撤销窗口不变（换版/下架仍最迟 60 秒对新请求生效，304 只是在窗口之后省掉重下）。边缘 gzip/Brotli 与本层不冲突：两边都以「响应已带 `Content-Encoding` 就跳过」收口；但 Pingora 网关在自身压缩关闭时会**移除** `accept-encoding`（`normalize_accept_encoding_for_gateway_compression`），那种部署形态下源站压缩不会生效，属于网关侧口径。
-- **验证**：`cargo test -p api-server --bin api-server -- game_distribution`（新增 ETag 作用域、`If-None-Match` 列表/弱校验命中、`gzip;q=0` 拒绝、文本压缩与二进制/小文件不压、304 无正文等用例）；`npx vitest run packages/shared/src/components/PlatformGameLoadingSurface.test.tsx`、`src/components/game-distribution/GameDistributionPages.test.tsx`、`apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx`；真实栈复跑探针后发行网关 `phaser.min.js` 由 1,376 KB 降到约 330 KB，用户端/后台端改后同链路对照见 PR。
+- **验证**：`cargo test -p api-server --bin api-server -- game_distribution`（新增 ETag 作用域、`If-None-Match` 列表/弱校验命中、`gzip;q=0` 拒绝、文本压缩与二进制/小文件不压、304 无正文、`*` 对包内缺失路径仍 404 等用例）；`npx vitest run packages/shared/src/components/PlatformGameLoadingSurface.test.tsx`、`src/components/game-distribution/GameDistributionPages.test.tsx`、`apps/admin-web/src/pages/AdminGameDistributionReviewPage.test.tsx`；`npm run check:game-distribution-ops-rollback-e2e` 47 项通过（含压缩/Vary/ETag/304/不接受 gzip 四条新断言）。真实栈同链路复跑：`phaser.min.js` 1,375,976 B → 353,336 B（gzip，4 Mbps 下 2724 ms → 774 ms），用户端游戏画面 3298 ms → 1543 ms、后台试玩 4587 ms → 2694 ms。
 - **关联**：`packages/shared/src/components/PlatformGameLoadingSurface.tsx`、`src/components/game-distribution/GamePlayPage.tsx`、`apps/admin-web/src/pages/AdminGameDistributionReviewPage.tsx`、`server-rs/crates/api-server/src/modules/game_distribution.rs`、`deploy/nginx/README.md`。