diff --git a/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md b/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md
index 8185305d..9ab84092 100644
--- a/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md
+++ b/pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md
@@ -185,6 +185,27 @@
   2. 布局由主入口统一提供，子页面只需编写内容区的 `<view>`。
   3. **例外**: 仅当某个页面是独立存在的（例如登录页、引导页），且需要独立布局时，才允许自行包装。
 
+#### **原因二十四：ECharts 图表不显示与容器高度塌陷 (Grid/Flex 嵌套陷阱)**
+
+- **现象**: 页面加载后饼图/折线图区域空白，且高度为 0，或仅显示为一条细线；Grid 布局中左右卡片高度不一致（左高右低或反之）。
+- **原因**:
+  1. **Grid 子项默认行为**: CSS Grid 的直接子项 (`.gender-col`) 默认是 `display: block`。若其内部卡片 (`.gender-card`) 设置了 `height: 100%`，在某些浏览器或特定嵌套层级下，如果父级没有显式高度（仅由兄弟元素撑开），`100%` 无法正确计算，导致高度塌陷。
+  2. **Canvas 依赖**: ECharts 的 Canvas 依赖父容器的实际像素高度。如果初始化时父容器高度为 0（因 Flex 压缩或加载时序），Canvas 就会渲染成 0x0。
+  3. **Margin 干扰**: 左侧卡片 (`AnalyticsUserMapTable`) 原本带有 `margin-bottom: 16px`。在 Grid 布局(`align-items: stretch` 默认)中，Grid Cell 的高度包含了这个 Margin。这导致左侧卡片的 _可见背景区域_ 比右侧卡片 _矮_ 了 16px（因为 Margin 是透明的），视觉上顶部对齐但底部不对齐。
+- **解决方案**:
+  1. **Grid 子项 Flex 化**:
+     ```css
+     .map-col,
+     .gender-col {
+       min-width: 0;
+       display: flex; /* 关键：启用 Flex 上下文 */
+       flex-direction: column; /* 确保子元素垂直填充 */
+     }
+     ```
+     这样 Grid Cell 变为 Flex Container，其子元素 (`.gender-card`) 的 `height: 100%` 或 `flex: 1` 就能正确基于 Grid Cell 的最终高度进行计算。
+  2. **移除组件级 Margin**: Grid 布局应使用 `gap` 属性控制间距，组件自身 (`.user-map-card`) 不应自带外部 Margin，否则会破坏等高计算。
+  3. **强制 Canvas 填充**: 图表组件容器需设置 `width: 100% !important; height: 100% !important;` 且 `position: absolute` (配合父级 relative) 或 `flex: 1`，确保填满 Flex 空间。
+
 ## 🛠️ 完整修复流程
 
 ```