Merge remote-tracking branch 'origin/master' into style/game-play

# Conflicts:
#	docs/project-memory/shared-memory/pitfalls.md

docs/project-memory/shared-memory/pitfalls.md

@@ -2,6 +2,13 @@
 
 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。
 
+## 2026-09-30 Jenkins release 渠道环境污染 AGC 构建单测
+
+- **现象**：Jenkins `Genarrative-Agc-MacOS-Build` 的 release lane 在执行 `build-release.test.mjs` 时，`release stages Node before Tauri...` 用例报 `Cannot read properties of undefined (reading 'nsis')`。
+- **原因**：用例还断言 dev-only 的 `bundle.windows.nsis.installerHooks`，但 `resolveReleaseContext()` 默认读取进程环境；Jenkins 注入 `AGC_UPDATE_CHANNEL=release` 后，测试上下文变成 release。release 渠道只保留 Node 资源映射，没有 dev 的 NSIS hook，于是 `config.bundle.windows` 不存在。macOS 只是运行测试的宿主，测试实际覆盖的是 Windows target。
+- **处理**：凡是断言特定渠道配置的测试，必须通过 `resolveReleaseContext(args, { AGC_UPDATE_CHANNEL: 'dev' })` 或等价夹具显式固定渠道，不能继承 Jenkins release 环境。
+- **验证**：`AGC_UPDATE_CHANNEL=release node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs`。
+
 ## 2026-09-29 逐 delta 脱敏会吃掉段尾换行：DirectProject 汇报的 Markdown 表格整块失效
 
 - **现象**：AGC 项目对话里 agent 汇报正文渲染错位——段落并进同一行、序号项挤成一段、Markdown 表格整块不渲染（表头 `| 素材 | 用途 | 路径 |`、`|---|---|---|` 与数据行以纯文本连在同一行里）；同一段文本里的路径还会出现 `game<absolute-path>ame.js`、`assets<absolute-path>anvas-generated/...` 这种被切坏的占位符。重开项目读历史时同一段话渲染正常，很容易被当成渲染器偶发或模型写坏了 Markdown。
@@ -147,12 +154,12 @@
 - **处理**：契约期望同步包含现有 OSS HTTPS 项，保留完整白名单精确比较；不得删除业务所需权限或改成任意 URL 放行。更新下载与素材直传是不同调用链，变更能力配置时同步检查调用方和契约。
 - **验证**：运行 `npm run check:native-shells:contract` 与 `apps/ai-game-creator-shell/tests/assetDirectUpload.test.ts`；缓存完整性以实际 artifact 和导出日志为准，不能仅看上传 step 是否成功。
 
-## release 安装包文件名中的编码空格不能按控制字符拒绝
+## 旧版 release 安装包文件名中的编码空格不能按控制字符拒绝
 
 - **现象**：release 环境点击“下载客户端”只显示无法获取最新版本，`GET /api/client-downloads` 返回 `502 UPSTREAM_ERROR`；dev 环境正常。
-- **原因**：release 渠道产品名为“陶泥儿 Release”，NSIS 首装包名因此包含空格，OSS `latest.json` 中的 URL 使用 `%20`。`validate_download_url` 的百分号解码校验把 `0x20` 当成控制字符拒绝，Windows 清单被判非法；release macOS 清单当时又未发布，聚合后两端都无下载项并返回 502。
-- **处理（现行口径）**：清单 URL 校验允许百分号编码的空格，继续拒绝其它控制字符、`/`、`\`、DEL、非法编码和跨目录文件名；不得通过改写真实产物名绕过校验。
-- **验证**：`platform-oss` 用 `陶泥儿%20Release_0.1.110_x64-setup.exe` 做清单解析回归；线上修复后接口应返回 release Windows 下载项，macOS 未发布时进入 `unavailablePlatforms`。
+- **原因（历史）**：旧版 release 渠道产品名带英文渠道后缀，NSIS 首装包名因此包含空格，OSS `latest.json` 中的 URL 使用 `%20`。`validate_download_url` 的百分号解码校验把 `0x20` 当成控制字符拒绝，Windows 清单被判非法；release macOS 清单当时又未发布，聚合后两端都无下载项并返回 502。
+- **处理（现行口径）**：release 渠道现复用正式产品名 `陶泥儿`，不再生成带 `Release` 文本的包名；清单 URL 校验仍允许合法的百分号编码空格，以兼容自定义渠道产品名，同时继续拒绝其它控制字符、`/`、`\`、DEL、非法编码和跨目录文件名。
+- **验证**：`platform-oss` 继续覆盖带编码空格的自定义渠道文件名，并用 `陶泥儿_0.1.110_x64-setup.exe` 做 release 清单解析回归；线上接口应返回 release Windows 下载项，macOS 未发布时进入 `unavailablePlatforms`。
 - **关联**：`server-rs/crates/platform-oss/src/client_downloads.rs`、`apps/ai-game-creator-shell/scripts/build-release.mjs`、`docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`。
 
 ## 客户端图标素材描述不能先包装再截断
@@ -166,7 +173,7 @@
 
 - **现象**：在一台已经装了某个渠道 AGC 客户端的设备上安装另一个渠道的安装包，装完后旧客户端直接消失（安装目录被覆盖、卸载项被接管），更新端点、平台服务器与本地登录态一起换成新渠道的；两个渠道的客户端无法共存。
 - **原因**：渠道此前只烘焙了 `plugins.updater.endpoints` 与 `VITE_AGC_PLATFORM_CHANNEL`（`apps/ai-game-creator-shell/scripts/build-release.mjs` 的 `createChannelConfig`），`productName` / `identifier` 用的是渠道无关的基线值。Tauri 的 Windows 安装目录与卸载项由 `productName` 决定，WebView2 数据目录与客户端数据目录由 `identifier` 决定，于是所有渠道落到 `%LOCALAPPDATA%\陶泥儿`、`HKCU\...\Uninstall\陶泥儿` 与 `%APPDATA%\world.genarrative.ai-game-creator`。
-- **处理（现行口径）**：渠道进入安装身份，默认渠道保持基线身份不变，其它渠道派生 `<产品名> <渠道显示名>` 与 `<基线>.<渠道>`；身份与端点在同一次构建期 `--config` 注入。见决策记录 2026-09-21 条目。
+- **处理（现行口径）**：渠道进入安装身份，`dev` 保持既有开发版身份，`release` 复用正式产品名但保持独立 identifier，自定义渠道派生 `<产品名> <渠道显示名>` 与 `<基线>.<渠道>`；身份与端点在同一次构建期 `--config` 注入。见决策记录 2026-09-21 与 2026-09-30 条目。
 - **核对方式**：装完任渠道的包后看 `HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\<产品名>` 的 `InstallLocation`、`%APPDATA%\<identifier>` 与主程序窗口标题是否按渠道分开；同名安装目录或同名数据目录说明身份没有生效。
 - **易错点**：只改安装包文件名或快捷方式名而不改 `identifier`，两个渠道仍会抢同一份 Agent Runner / 项目锁与登录态；反过来把渠道后缀加在默认渠道上，既有安装的升级链会断（客户端认不出旧安装）。相似前缀目录（如 `world.genarrative.ai-game-creator-backup`）不得进入提权 ACL 的 managed 范围。
 - **关联**：`apps/ai-game-creator-shell/scripts/channel-identity.mjs`、`build-release.mjs`、`build-macos-ci.mjs`、`src-tauri/src/config.rs`。
@@ -6133,3 +6140,12 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **处理**：覆盖规则带上同样的祖先作用域，`overflow: hidden` 用两个选择器（单类名 + `.platform-desktop-shell--workbench .platform-tab-panel.platform-tab-panel--game-play`）一起写，既压得过 workbench 规则也不依赖文件顺序。
 - **判据**：真实 Chromium（dev 栈 390x844 / 360x640 / 844x390 横屏矮视口）实测 `overflowY=hidden`、面板与整页横竖都不溢出，同时广场舞台仍是 `overflowY=auto` 且内容可滚（689px）。同类问题排查姿势：改 `.platform-tab-panel` 或任何 workbench 内元素的样式，先在浏览器里读 `getComputedStyle`，别只看类名/源码顺序。
 - **关联**：`src/index.css`（`.platform-tab-panel--game-play` 与 `.platform-desktop-shell--workbench .platform-tab-panel`）、`scripts/check-game-distribution-web-e2e.mjs`、`src/components/game-distribution/gameDistribution.css`。
+
+## 2026-09-24 移动端固定底部菜单会压住「内联」弹窗：`z-index` 高也点不到
+
+- **现象**：手机端主站从头像入口上传头像，裁剪弹窗的「取消 / 上传」被底部「游戏 / 我的」菜单盖住，点按钮命中底部菜单；弹窗遮罩、面板本身都正常渲染，只有底部一条区域失去交互。
+- **原因**：`.platform-desktop-shell--workbench .platform-desktop-layout` 带 `position: relative; z-index: 1`，**自成一个 stacking context**。底部主菜单（`.platform-mobile-bottom-dock`，`z-index: 60`）是 layout 的兄弟节点，而弹窗用 `portal={false}` 内联渲染在 layout 内部——弹窗自己的 `z-[80]` 只在 layout 的局部层叠里比较，整体被限制在 `z-index: 1` 之上、`z-index: 60` 之下。**在祖先 stacking context 内抬高子元素 `z-index` 无效，必须让弹窗跳出该 context**。
+- **处理（现行口径）**：独立弹窗一律走 `UnifiedModal` 默认的页面级 portal（挂 `document.body`），不要用 `portal={false}` 内联渲染。目前只剩 `PlatformStatusDialog` 保留内联（运行态内嵌遮罩，且它渲染位置本就在 layout 之外）。
+- **同时**：主站顶栏（`platform-desktop-topbar`）在窄屏必须保持单行——加 `flex-wrap` 后新增一个动作入口就会让品牌折到第二行；窄屏降级靠 `< 640px` 图标化下载入口、`< 480px` 只留品牌 IP 标识。
+- **验证**：真机尺寸下用 `document.elementFromPoint(按钮中心)` 断言命中的是按钮自身而不是底部菜单（`overlay.parentElement === document.body`）；顶栏断点矩阵（320–768）断言单行且无横向溢出。
+- **关联**：`src/components/common/SquareImageCropModal.tsx`、`src/components/platform-entry/PlatformProfileModalShell.tsx`、`src/components/platform-entry/PlatformEntryActiveFlowShell.tsx`、`src/index.css`。