Merge pull request '修复移动端顶栏折行与头像裁剪弹窗被底部主菜单遮挡' (#515) from fix/mobile-style into master

Reviewed-on: #515

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

@@ -9157,3 +9157,11 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 本地假数据补齐：`scripts/admin-web-fake-api.mjs` 新增 `agc-models`、`game-distribution/games`、`profile/recharge-products`、`profile/redeem-codes`、`profile/tasks`、`agc/tracking-events` 夹具，并对 `profile/recharge-orders` 按 `AdminRechargeOrderEntryPayload` 的真实字段补齐（缺字段会让页面抛 `Cannot read properties of undefined`——后台没有 error boundary，整页会白屏）。**已知缺口**：充值管理页仍缺一处夹具字段（页面读 `undefined.find`），本轮没能出图；该页自身 21 条单测通过、类型检查通过，仅缺截图。
 - 排序验证：共享组件新增用例覆盖「正序 / 倒序 / 取消 + aria-sort + 行序」；现场实测邀请码列表按「创建」排序：正序 `EXPIRED-CODE, BETA-CREATOR, TAONIER-VIP-2026`、倒序翻回 `TAONIER…, BETA…, EXPIRED…`，`th[aria-sort]` 依次为 `ascending` / `descending`。
 - 边界（未完成）：未跑生产后台构建与真实后台接口联调（截图用假数据）；`apps/admin-web` 目前没有 error boundary，任何接口形状不符仍会把整页渲染清空（本次只加固了 `AdminAgcTrackingPage` 一处，其余页面同类写法未逐个排查）；`AdminAgcTemplatesPage` 的列表面板是本次新增的外壳（原页面没有面板），视觉上多了白底卡片。
+
+## 2026-09-24 移动端主站顶栏收成单行、个人中心弹窗统一走页面级 portal
+
+- 背景：移动端主站（`PlatformEntryActiveFlowShell` 工作台壳层）顶栏在 `e3682fd06` 加入「下载客户端」后，`flex-wrap` 让品牌与下载/泥点/账户入口折成两行；同一壳层里 `.platform-desktop-layout` 带 `z-index: 1` 形成 stacking context，把 `portal={false}` 的弹窗封在这个 context 内，低于 `z-index: 60` 的固定底部主菜单——头像裁剪弹窗的「取消 / 上传」正好被「游戏 / 我的」压住点不到。
+- 决策（顶栏）：顶栏在所有断点都保持单行（`flex-nowrap`），窄屏靠两个降级点让位：`< 640px` 下载入口收起为 44×44 图标按钮（保留 `aria-label="下载客户端"`），`< 480px` 顶栏品牌只留 IP 标识（`platform-desktop-topbar__brand` 内隐藏 `platform-brand-logo__copy`）。品牌字标、下载文案的完整形态在 `>= 640px` / `>= 480px` 恢复，桌面端外观不变。
+- 决策（弹窗层级）：个人中心的独立弹窗（`SquareImageCropModal`、`PlatformProfileModalShell` 两个壳层）改回 `UnifiedModal` 默认的页面级 portal（挂到 `document.body`），不再用 `portal={false}` 内联渲染；层级由现有 `z-[80]` 决定，仍在鉴权 / 法务 / 预览等 `z-[110]` 以上弹窗之下。`PlatformStatusDialog` 保持内联（承载运行态内嵌遮罩，不在本次范围）。
+- 影响范围：`src/components/platform-entry/PlatformEntryActiveFlowShell.tsx`、`src/components/creation-home/ClientDownloadEntry.tsx`、`src/components/common/SquareImageCropModal.tsx`、`src/components/platform-entry/PlatformProfileModalShell.tsx`、`src/index.css`。
+- 验证：本地 Vite + Chromium 真机尺寸复核（320/360/375/390/414/480/639/640/768/1024）：顶栏在 320–768 全部单行、右侧留白 16px；弹窗内「上传 / 保存」`elementFromPoint` 命中自身而非底部菜单，overlay 父节点为 `BODY`。定向 Vitest（`ClientDownloadEntry`、`PlatformProfileModalShell`、`PlatformActiveProfileView`、`PlatformEntryActiveFlowShell`、`UnifiedModalPortalTheme`）与 `prettier --check`、`eslint`、`tsc`、`check:encoding` 通过。

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

@@ -6100,3 +6100,12 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 
 - **做法**：`npm run check:agc-direct-execution-fixture -- --agc-exe "<已安装渠道包的主程序绝对路径>" --cases completed`。夹具在临时项目和 loopback Provider 上跑 CLI 执行链路，可直接核对已安装包的随包 Codex。
 - **判读**：若报 `Codex app-server JSON-RPC 失败`，sidecar 已启动并返回协议错误，应先检查请求体及已安装包的源码版本；若根本无法启动，再查安装目录 `coding-agent/win-x64/manifest.json` 的组件哈希、`codex-package.json` 的版本和缺失组件。夹具模式中的 `remote_control disabled reason=provider-proxy-auth` 是预期诊断行。
+
+## 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`。

src/components/common/SquareImageCropModal.tsx

@@ -319,7 +319,6 @@ export function SquareImageCropModal({
       closeLabel={labels.close}
       closeVariant="profileCompact"
       closeIcon="×"
-      portal={false}
       zIndexClassName="z-[80]"
       panelClassName="platform-remap-surface max-w-sm rounded-[1.4rem]"
       headerClassName="border-white/10 px-5 py-4"

src/components/creation-home/ClientDownloadEntry.tsx

@@ -75,14 +75,16 @@ export function ClientDownloadEntry() {
         tone="secondary"
         size="sm"
         shape="pill"
-        className="min-h-11 shrink-0 whitespace-nowrap"
+        aria-label="下载客户端"
+        title="下载客户端"
+        className="min-h-11 shrink-0 gap-0 whitespace-nowrap max-sm:h-11 max-sm:w-11 max-sm:px-0 sm:gap-2 sm:px-4"
         onClick={() => {
           setState({ status: 'loading' });
           setOpen(true);
         }}
       >
-        <Download className="h-4 w-4" aria-hidden="true" />
-        下载客户端
+        <Download className="h-4 w-4 shrink-0" aria-hidden="true" />
+        <span className="hidden sm:inline">下载客户端</span>
       </PlatformActionButton>
       <UnifiedModal
         open={open}

src/components/platform-entry/PlatformEntryActiveFlowShell.tsx

@@ -618,8 +618,8 @@ export function PlatformEntryFlowShellImpl({
             </aside>
 
             <div className="platform-desktop-main flex min-w-0 flex-1 flex-col">
-              <header className="platform-desktop-topbar flex min-h-16 shrink-0 flex-wrap items-center justify-between gap-1 gap-y-2 px-4 py-2 sm:flex-nowrap sm:gap-3 sm:px-6 sm:py-0">
-                <div className="min-w-0 shrink-0 lg:hidden">
+              <header className="platform-desktop-topbar flex min-h-16 shrink-0 flex-nowrap items-center justify-between gap-1 px-4 py-2 sm:gap-3 sm:px-6 sm:py-0">
+                <div className="platform-desktop-topbar__brand min-w-0 shrink-0 lg:hidden">
                   <ActivePlatformBrand />
                 </div>
                 <div className="platform-desktop-topbar__brand-search hidden min-w-0 flex-1 items-center lg:flex">
@@ -662,7 +662,7 @@ export function PlatformEntryFlowShellImpl({
                   </form>
                 </div>
 
-                <div className="platform-desktop-topbar__actions flex max-w-full shrink-0 flex-wrap items-center gap-1 sm:flex-nowrap sm:gap-2 lg:gap-3">
+                <div className="platform-desktop-topbar__actions flex min-w-0 shrink-0 items-center gap-1 sm:gap-2 lg:gap-3">
                   <ClientDownloadEntry />
                   {isAuthenticated ? (
                     <PlatformMudPointWalletEntry

src/components/platform-entry/PlatformProfileModalShell.tsx

@@ -84,7 +84,6 @@ export function PlatformProfileModalShell({
       showCloseButton={showCloseButton}
       closeOnBackdrop={false}
       closeOnEscape={false}
-      portal={false}
       size={size}
       zIndexClassName={zIndexClassName}
       overlayClassName={PROFILE_MODAL_OVERLAY_CLASS}
@@ -128,7 +127,6 @@ export function PlatformProfileSecondaryModalShell({
       showCloseButton={false}
       closeOnBackdrop={false}
       closeOnEscape={false}
-      portal={false}
       size={size}
       zIndexClassName={zIndexClassName}
       overlayClassName={

src/index.css

@@ -12612,6 +12612,22 @@ button.image-canvas-editor__reference-chip:disabled {
     min-width: 0;
     padding-inline: 0.12rem;
   }
+
+  .platform-desktop-shell--workbench
+    .platform-desktop-topbar
+    .platform-desktop-topbar__actions {
+    gap: 0.38rem !important;
+  }
+}
+
+/* 窄屏顶栏必须保持单行：品牌只保留 IP 标识，字标让位给下载、泥点与账户入口。 */
+@media (max-width: 479px) {
+  .platform-desktop-shell--workbench
+    .platform-desktop-topbar
+    .platform-desktop-topbar__brand
+    .platform-brand-logo__copy {
+    display: none;
+  }
 }
 
 .platform-desktop-shell--workbench .platform-desktop-rail {