merge: branch 'huangzhenbao-admin' into comclib-analytics, keeping local RPC integration versions
This commit is contained in:
comlibmb
@@ -11,6 +11,114 @@
|
||||
- **解决方案**: 确保替换操作覆盖文件的完整生命周期，或者在发现 500 错误时检查文件末尾是否有残留的旧标签。
|
||||
- **预防**: 优先使用 `create_file` 或子代理重写整个文件，而非局部替换复杂的 SFC 结构。
|
||||
|
||||
#### **原因十二：KPI 统计网格响应式不一致 (用户体验红线)**
|
||||
|
||||
- **现象**: 某些宽度下出现一行 3 个卡片，导致视觉不平衡或数据展示拥挤。
|
||||
- **原因**: 使用了 `repeat(auto-fit/auto-fill, ...)` 或基于 `min-width` 的 flex 自动布局。
|
||||
- **解决方案**:
|
||||
1. 使用全局统一类 `.kpi-grid`。
|
||||
2. 严禁使用 `auto-fit/auto-fill`。
|
||||
3. 必须显式使用视图断点拦截：
|
||||
- `>= 1200px`: 固定 4 列 (`grid-template-columns: repeat(4, minmax(0, 1fr))`)。
|
||||
- `768px - 1199px`: 固定 2 列 (`grid-template-columns: repeat(2, minmax(0, 1fr))`)。
|
||||
- `< 768px`: 固定 1 列 (`grid-template-columns: repeat(1, minmax(0, 1fr))`)。
|
||||
4. 使用 `minmax(0, 1fr)` 配分子项 `min-width: 0` 确保在任何容器宽度下网格不被撑爆。
|
||||
- **强制规则**: 任何页面都不允许出现一行 3 个卡片的情况。
|
||||
|
||||
#### **原因十三：侧边栏响应式断点与 Overlay 冲突 (严重体验红线)**
|
||||
|
||||
- **现象**: 在 770px~1005px 宽度下，侧边栏遮挡内容，或内容区没有正确让出空间。
|
||||
- **原因**:
|
||||
1. 断点逻辑不统一：`main` 布局计算与组件显隐逻辑使用了不同的宽度阈值。
|
||||
2. 动画不匹配：内容区 `margin-left` 动画时长与侧栏 `transform` 时长不一致。
|
||||
3. 状态残留：跨断点时没有强制重置 Overlay 状态。
|
||||
- **1:1 复刻 CRMEB 解决方案**:
|
||||
1. **明确三段断点策略**:
|
||||
- **Desktop (>=1200px)**: `aside=dock`, `subSider=dock` (如果开启)。`mainLeft = 270px`。
|
||||
- **Tablet (768px-1199px)**: `aside=dock`, `subSider=overlay` (带 mask)。`mainLeft = 70px`。
|
||||
- **Mobile (<768px)**: `aside=overlay`, `subSider=overlay`。`mainLeft = 0px`。
|
||||
2. **统一状态机**: 使用 `layoutMode` (desktop/tablet/mobile) 驱动所有组件渲染，而非散乱的媒体查询。
|
||||
3. **计算属性驱动布局**: `mainLeft` 必须严格根据 `layoutMode` 和 `subSider` 的 Dock/Overlay 属性动态计算。
|
||||
4. **跨断点清理**: 在 `onWindowResize` 监听到模式切换时，立即强制关闭所有 Overlay (mask=false)，防止残影遮挡。
|
||||
5. **指针事件隔离**: 隐藏态侧栏必须显式设置 `pointer-events: none` 和 `visibility: hidden`。
|
||||
|
||||
#### **原因十四：KPI 统计概况列数不一致 (CRMEB 像素级规范)**
|
||||
|
||||
- **现象**: 统计概况在大屏下显示 4 列或 5 列，导致无法一行平铺 6 个核心指标。
|
||||
- **解决方案 (6-2-1 规则)**:
|
||||
1. 使用全局类 `.kpi-grid-6` 实现专用的统计概况布局。
|
||||
2. **强制断点**:
|
||||
- `> 1200px`: 固定 6 列 (`repeat(6, minmax(0, 1fr))`)。
|
||||
- `768px - 1199.98px`: 固定 2 列。
|
||||
- `< 768px`: 固定 1 列。
|
||||
3. **侧栏联动**: 当 `viewport < 768px` 时，布局容器必须切换到移动端模式（主侧栏变为 Overlay，mainLeft 归零），确保 1 列布局拥有最大水平空间。
|
||||
|
||||
#### **原因十五：ECharts 图表响应式裁切与视觉偏位**
|
||||
|
||||
- **现象**: 窗口缩小时饼图被砍掉一半，或在大屏下视觉不居中、底部不对齐。
|
||||
- **原因**:
|
||||
1. 使用了固定高度（如 `height: 521px`）而没有弹性容器。
|
||||
2. ECharts 的 `center` 和 `radius` 使用了静态百分比或固定像素，无法适配极端宽高比。
|
||||
3. 仅依赖 `window.resize` 而没有监听“容器级”尺寸变化（如侧边栏折叠导致的局部宽度变化）。
|
||||
- **解决方案**:
|
||||
1. **容器加固**: 移除根组件固定高度，改用 `min-height`；卡片内容区设置 `overflow: visible` 防止裁切。
|
||||
2. **像素级算法**: 禁止在 `option` 中直接硬编码 `['50%', '60%']`，应计算：`outerRadius = min(w, h) * 0.38`，`centerY = legendSpace + (h - legendSpace) / 2`。
|
||||
3. **双重自适应**:
|
||||
- **底层**: 使用 `ResizeObserver` 监听容器级 DOM 变化。
|
||||
- **上层**: 监听 `store` 中的侧边栏状态，在动画结束后强制触发 `refreshSize()`。
|
||||
4. **文字同步**: 中间文字（total-value）必须通过 `computed` 样式与饼图中心点像素级同步。
|
||||
5. **架构建议**: 在 UTS 环境下，涉及 ECharts 等需要向 RenderJS 传递复杂 Object 的组件，**优先使用 Options API**。Options API 在处理 `toPlainObject` 转换及 Prop 传递时具备更稳定的兼容性，可避免 `script setup` 下可能出现的对象元数据干扰。
|
||||
|
||||
#### **原因十六：ECharts 响应式失效与百分比布局规范**
|
||||
|
||||
- **现象**: 侧边栏折叠时图表不缩小导致溢出，或在不同宽高比下圆环变形/裁切。
|
||||
- **原因**:
|
||||
1. 使用了固定的像素值定义 `radius` 和 `center`。
|
||||
2. 容器高度依赖父级 `flex` 且未设置 `min-height`，导致某些极端高度下被折叠。
|
||||
3. 缺乏对动画中间态的捕获。
|
||||
- **强制解决方案 (Web/uni-app-x)**:
|
||||
1. **百分比优先**: `radius` 必须使用百分比（如 `['55%', '75%']`），`center` 必须使用百分比。
|
||||
2. **高度钳制**: 容器使用 `height: clamp(...)` 或固定高度（如 `520px`）+ `min-height`。
|
||||
3. **全链路 Resize**:
|
||||
- `ResizeObserver` 监听 DOM 容器变化。
|
||||
- `transitionend` 监听侧边栏动画结束。
|
||||
- `watch` 监听全局布局状态（`layoutMode` / `collapsed`）。
|
||||
4. **裁切隔离**: 所有祖先容器、`ec-wrap`、`ec-canvas` 必须显式设置 `overflow: visible !important`。
|
||||
|
||||
#### **原因十七：ECharts 画布溢出与容器约束 (Containing Block 丢失)**
|
||||
|
||||
- **现象**: `ec-canvas` (uni-view) 拥有极大的 `width/height` (如 948px) 且 `position: absolute`，但脱离了父级卡片，溢出到整个页面，且图表内容消失。
|
||||
- **原因**:
|
||||
1. **层叠上下文丢失**: `ec-canvas` 的父组件或 `EChartsView` 根节点未设置 `position: relative`，导致 absolute 元素相对于 `body` 定位。
|
||||
2. **尺寸初始化瓶颈**: 在父容器高度为 0 (如 `flex` 自动压缩) 或动画中间态初始化 ECharts，导致内部 `canvas` 宽高计算错误。
|
||||
- **强制解决方案**:
|
||||
1. **修正 Containing Block (Step 1)**:
|
||||
- 容器(`chart-wrap`)必须显式设置 `position: relative !important`。
|
||||
- 使用 `:deep()` 强制约束子组件：`.ec-wrap { position: relative; } .ec-canvas { position: absolute; inset: 0; width: 100% !important; height: 100% !important; }`。
|
||||
2. **确定性高度策略 (Step 2)**:
|
||||
- 图表容器禁止高度塌陷。使用 `height: clamp(min, preferred, max)` 或固定高度。
|
||||
- 示例：`height: clamp(280px, 40vh, 450px); min-height: 280px;`。
|
||||
3. **Resize 闭环链路 (Step 3)**:
|
||||
- 禁止使用 `setTimeout` 盲猜。
|
||||
- 必须使用 `ResizeObserver` 监听 `chart-wrap` 尺寸变化。
|
||||
- 必须监听 `sidebar` 的 `transitionend` 事件，确保侧边栏动画结束后的布局稳定。
|
||||
- 统一使用 `requestAnimationFrame(() => chart.resize())` 确保在下一次重绘前完成布局对齐。
|
||||
4. **百分比布局 (Step 4)**:
|
||||
- `series.pie` 的 `radius` 和 `center` 必须使用百分比形式，杜绝 px 导致的自适应失败。
|
||||
|
||||
#### **原因十八：CRMEB 响应式断点与图表重构规范 (1:1 复刻)**
|
||||
|
||||
- **现象**: 在 1200px 断点切换时布局生硬，图表在单列模式下比例过小或中心偏移。
|
||||
- **解决方案**:
|
||||
1. **Grid 布局容器**: 容器页面必须使用 CSS Grid 定义 `grid-template-columns: 2fr 1fr` (>=1200) 和 `1fr` (<1200)，避免 flex 宽度计算误差。
|
||||
2. **外部图例隔离**: 为保证 ECharts 渲染空间的确定性，禁止使用内置 `legend`。改为 `flex-direction: row` 的外部 `legend-col`，确保左上角图例与右侧饼图互不干扰。
|
||||
3. **确定性中心同步**:
|
||||
- ECharts `center` 设置为 `['50%', '50%']`。
|
||||
- 中心文字组件使用绝对定位 `top:50%; left:50%; transform:translate(-50%,-50%)` 实现物理像素级对齐。
|
||||
4. **两档响应式高度**:
|
||||
- `chart-col` 在桌面端 (>=1200) 使用中等高度 (约 320-360px)。
|
||||
- 在移动端/窄屏 (<1200) 自动扩展为大高度 (约 500-600px)，以匹配全宽展示的视觉张力。
|
||||
|
||||
## 🛠️ 完整修复流程
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user