完善页面细节3

pages/mall/admin/docs/UNI_APP_X_PAGE_FIX_GUIDE.md

@@ -1930,3 +1930,60 @@ const iconMap: Record<string, string> = {
 1. **标准化 Script 标签**：统一使用 `<script setup lang="uts">` 或 `<script lang="uts">`（配合 `defineComponent`）。
 2. **规范响应式声明**：避免在 `reactive` 上直接使用泛型（如 `reactive<T>(...)`），应使用类型断言 `reactive(...) as T`。
 3. **避免遗留的 Options API 写法**：尽量将旧的 `export default { data(), methods() }` 结构转换为 Composition API 模式，以获得最佳的 UTS 编译支持。
+
+### 原因二十三：AdminLayout 循环依赖导致 500 错误 (Circular Dependency)
+
+**问题描述：**
+在 H5 环境下，为某个子页面添加 `AdminLayout` 包裹后，Vite 或编译器报错 `500 Internal Server Error (ERR_ABORTED)`，且页面无法加载。
+
+**原因：**
+
+1. **依赖闭环**：`AdminLayout` 导入了侧边栏和路由逻辑，路由逻辑引用了 `adminComponentMap.uts`，而映射表又导入了所有子页面组件。
+2. **递归调用**：如果子页面组件再次导入 `AdminLayout` 试图自我包裹，就会形成死循环依赖，导致 Vite 开发服务器或编译后的模块加载失败。
+
+**解决方案：**
+
+1. **分层包裹架构**：所有注册在 `adminComponentMap.uts` 中的“子页面组件”**必须禁止** 导入和使用 `AdminLayout`。
+2. **统一入口提供布局**：由父级容器（如 `admin/index.uvue` 或顶层路由组件）负责一次性提供 `AdminLayout` 框架。
+
+### 原因二十四：标签切换/动态显显引起的高度抖动 (Layout Jitter)
+
+**问题描述：**
+使用 `v-if` 在不同配置标签间切换，或者动态显示/隐藏表单项时，外部卡片（Card）的尺寸会突然跳动，影响视觉稳定性。
+
+**解决方案：**
+
+1. **预设最小高度**：在 `config-card` 或 `config-body` 上显式设置 `min-height`（如 `550px` 或 `600px`），确保即使内容较少，容器高度也保持不变。
+2. **容器钳制**：确保 `min-height` 足够覆盖该页面中所有可能出现的最高配置项组合。
+
+### 原因二十五：边距一致性与像素级对齐 (Margin Consistency)
+
+**问题描述：**
+页面顶部标题、内容卡片、底部边距在不同页面不一致。例如：有些页面顶部紧贴 breadcrumb，有些页面底部多出大量空白，左右间距不统一。
+
+**解决方案：**
+
+1. **容器级 padding 置空**：子页面根组件（如 `.admin-page`）应设置 `padding: 0`，完全信任 `AdminLayout.uvue` 中 `.content-inner` 提供的 `20px` 标准边距 (`--admin-page-padding-desktop`)。
+2. **三段式间距 (20px 规则)**：
+   - **Header-to-Content Gap (20px)**: 顶部白色标题栏与下方内容卡片之间，统一定义 `margin-top: 20px`。
+   - **External Padding (20px)**: 由框架层 `.content-inner` 提供全局 20px 间距，确保页面四周留白均匀。
+3. **内容区域一致性**：所有装修类的预览组件（如 `.preview-column`）和管理卡片（如 `.manage-card`）应通过这种 20px 的分层间距保持视觉节奏一致。
+
+### 原因二十六：装修模块的“白色背景卡片”统一化 (Unified White Card Pattern)
+
+**问题描述：**
+装修（Decoration）和设计（Design）模块中，预览区（PhonePreview）和设置区（Settings）如果背景色参差不齐（灰白交替）或使用独立阴影的小卡片，会显得界面琐碎且不专业。
+
+**解决方案：**
+
+1. **大卡片容器化**：将左侧预览、中间预览、右侧配置等所有相关内容全部封装在一个 `.main-card` 或 `.card-container` 白色背景容器内，并使用统一阴影 (`0 2px 12px 0 rgba(0, 0, 0, 0.05)`)。
+2. **示例应用 - 主题风格 (theme-style.uvue)**：
+   - 移除原有的多个独立预览 Card，统一至一个大背景。
+   - 颜色选择项（ThemeItem）重构为带有 1px 细边框和特定圆角的微型容器。
+   - 预览手机（MockPhone）间距固定为 30px，并确保在容器内水平平铺。
+3. **避免深色背景块**：在配置表单内部，尽量避免使用深灰色（如 `#f6f8fb`）背景块，改用白色背景加浅灰色细边框 (`1px solid #f0f0f0`)，使整体视觉更加通透一致。
+4. **内部列间距对齐**：左边栏（MenuSide）、中预览（PhonePreview）、右配置（Settings）的内部 Padding 应维持在 30px-40px 左右，确保内容呼吸感一致。
+
+---
+
+这个指南现在涵盖了 uni-app-x 项目开发中最常见的 26 类问题，为后续开发提供了完整的故障排除和标准化指导。 🚀