merge: branch 'huangzhenbao-admin' into comclib-analytics, keeping local RPC integration versions

pages/mall/admin/docs/RESPONSIVE_LAYOUT_GUIDE.md

@@ -0,0 +1,85 @@
+# 管理后台响应式布局实现指南
+
+本文档总结了商城管理后台从固定布局到响应式布局的改造过程及核心技术点。
+
+## 1. 核心目标
+
+- **多终端适配**：确保后台在桌面端（宽屏）、平板端（中等屏幕）和移动端（窄屏）均能良好展示。
+- **自动适配状态管理**：系统能自动感知屏幕宽度并调整侧边栏显隐逻辑。
+- **布局平滑过渡**：侧边栏的收起、拉出及内容区的重排应具有良好的动画效果。
+
+## 2. 状态管理 (Store) 扩展
+
+在 [adminNavStore.uts](layouts/admin/store/adminNavStore.uts) 中引入了响应式状态：
+
+- `windowWidth`: 实时存储当前窗口宽度。
+- `isMobile`: 计算属性，当宽度小于 768px 时判定为移动端。
+- `isMobileMenuOpen`: 控制移动端模式下侧边栏的展开状态。
+
+```typescript
+export const windowWidth = ref<number>(1024);
+export const isMobile = computed<boolean>(() => windowWidth.value < 768);
+export const isMobileMenuOpen = ref<boolean>(false);
+```
+
+## 3. 布局架构调整 (AdminLayout)
+
+[AdminLayout.uvue](layouts/admin/AdminLayout.uvue) 负责整体结构的响应式策略：
+
+### 3.1 监听并初始化
+
+在 `onMounted` 中初始化宽度并监听 `uni.onWindowResize`：
+
+```typescript
+onMounted(() => {
+  windowWidth.value = uni.getWindowInfo().windowWidth;
+  uni.onWindowResize((res) => {
+    windowWidth.value = res.size.windowWidth;
+  });
+});
+```
+
+### 3.2 侧边栏处理
+
+- **桌面端**：侧边栏常规展示，通过 `marginLeft` 为内容区腾出空间。
+- **移动端**：侧边栏通过 `position: absolute` 隐藏在屏幕外，通过 `translateX` 动画滑入。同时禁用二级侧边栏的常驻显示。
+
+### 3.3 移动端遮罩与切换
+
+- 引入 `mobile-mask` 遮罩层，点击遮罩自动关闭菜单。
+- [AdminHeader](layouts/admin/components/AdminHeader.uvue) 在移动端会显示 “☰” 切换按钮。
+
+## 4. 页面内容重排 (HomeIndex)
+
+[HomeIndex.uvue](layouts/admin/pages/HomeIndex.uvue) 利用 CSS 媒体查询实现内容区域的自适应：
+
+### 4.1 KPI 卡片流式布局
+
+使用 `flex-wrap: wrap` 配合 `min-width`：
+
+- **布局策略**：设置 `min-width: 250px` 作为安全边界，确保在 1200px 分辨率下依然能并排展示 4 个卡片。
+- **动态列数**：
+  - **宽屏 (>1200px)**: 4个卡片并排。
+  - **中屏 (768px - 1200px)**: 强制 2 个并排。
+  - **窄屏 (<768px)**: 1个卡片占满整行。
+- **高度控制**：统一固定为 `200px`。
+
+### 4.2 图表响应式
+
+- **垂直排列**：底部两个并排的图表在小屏下自动切换为垂直排列（`flex-direction: column`）。
+- **组件自适应**：图表组件内部利用父容器宽度自动伸缩。
+- **头部压缩**：移动端下，图表的配置项（如日期切换标签）由横向改为纵向，避免溢出。
+
+## 5. 组件化实践 (KpiMiniCard)
+
+统一使用了 [KpiMiniCard](pages/mall/admin/homePage/components/KpiMiniCard.uvue) 组件，确保：
+
+- 样式一致性。
+- 代码复用性。
+- 内部样式的可维护性。
+
+## 6. 使用建议
+
+- 后续开发新页面时，请优先使用 `stats-row` 和 `stat-card` 进行布局。
+- 对于复杂的表格页面，建议在移动端隐藏非核心列，或使用横向滚动条展示。
+- 所有的宽度判定建议遵循 768px 这一标准断点。