yinjianm
e393b11b61
补齐节点管理真实新增、编辑与排序流程，接入权限组与路由组 维护页，并支持 11 种协议的动态配置表单 开放礼品卡管理入口，交付模板、兑换码、使用记录与统计四页签 工作台，接入 gift-card 相关后台接口 将知识库、权限组与路由管理从占位页升级为真实页面，并修复侧边栏 低高度裁切问题 修复仪表盘 24h 流量排行涨跌始终为 0 的问题，改为对比昨天整日统 计并补充单元测试
109 lines
5.4 KiB
Markdown
109 lines
5.4 KiB
Markdown
# 变更提案: admin-frontend-sidebar-height-overflow
|
|
|
|
## 元信息
|
|
```yaml
|
|
类型: 缺陷修复
|
|
方案类型: implementation
|
|
优先级: P1
|
|
状态: 已确认
|
|
创建: 2026-04-24
|
|
```
|
|
|
|
---
|
|
|
|
## 1. 需求
|
|
|
|
### 背景
|
|
`admin-frontend` 新增系统管理与订阅管理分组后，左侧导航项明显增多。当前 `AdminLayout.vue` 的侧边栏仍采用“Logo + ElMenu 直接铺满”的结构，而 `body` 又被全局设置为 `overflow: hidden`。在用户截图所示的小窗口高度下，底部菜单会被直接裁切，导致“礼品卡管理”“系统管理”“支付配置”等入口无法完整访问。
|
|
|
|
### 目标
|
|
- 修复管理端侧边栏在低视口高度下显示不全的问题。
|
|
- 按用户已确认的方案，保留顶部 Logo/品牌区固定，仅让菜单区独立纵向滚动。
|
|
- 保持现有 Apple 风格后台的导航层级、折叠行为和移动端体验不回退。
|
|
|
|
### 约束条件
|
|
```yaml
|
|
范围约束: 仅处理 admin 侧边栏在低高度下的可访问性与滚动行为，不扩展菜单信息架构
|
|
技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增依赖
|
|
兼容性约束: 需兼容桌面展开态、折叠态以及现有移动端 fixed aside 行为
|
|
视觉约束: 延续 apple/DESIGN.md 与 .helloagents/DESIGN.md 的纯白侧栏 + 单一蓝色激活态体系
|
|
```
|
|
|
|
### 验收标准
|
|
- [ ] 在窗口高度不足时，侧边栏底部菜单项仍可通过纵向滚动访问完整。
|
|
- [ ] 顶部 Logo/品牌区保持固定，不跟随菜单滚动一起消失。
|
|
- [ ] 折叠态与移动端侧边栏不出现新的遮挡、抖动或布局错位。
|
|
- [ ] `admin-frontend` 执行 `npm run build` 通过。
|
|
|
|
---
|
|
|
|
## 2. 方案
|
|
|
|
### 技术方案
|
|
1. 在 `AdminLayout.vue` 中把侧边栏拆成“固定头部品牌区 + 独立滚动的菜单容器”两层结构，而不是直接让 `ElMenu` 占满整个 `ElAside`。
|
|
2. 为侧边栏与菜单滚动容器补齐 `min-height: 0`、`overflow-y: auto`、底部留白和滚动条细节，解决 flex 子项在固定高度容器中无法正确收缩的问题。
|
|
3. 保持现有 `ElMenu`、`ElSubMenu` 和折叠逻辑不变，确保这次修复是针对根因的最小改动，而不是重写导航实现。
|
|
|
|
### 影响范围
|
|
```yaml
|
|
涉及模块:
|
|
- admin-frontend: 更新主布局侧边栏结构与样式，修复低高度下菜单裁切
|
|
- .helloagents/modules/admin-frontend.md: 记录侧边栏低高度滚动规则
|
|
预计变更文件: 3
|
|
```
|
|
|
|
### 风险评估
|
|
| 风险 | 等级 | 应对 |
|
|
|------|------|------|
|
|
| Element Plus 菜单在滚动容器中出现高度塌陷或双滚动条 | 中 | 采用独立滚动容器并显式补齐 `min-height: 0` 与内边距，避免只在 `ElMenu` 上追加单点样式 |
|
|
| 移动端 fixed aside 与桌面侧栏样式相互影响 | 中 | 仅在当前侧边栏作用域内增加滚动容器样式，保留现有移动端定位策略 |
|
|
| 构建会刷新 `public/assets/admin` 构建产物 | 低 | 本轮仅完成本地构建验证，不自动代做子模块发布 |
|
|
|
|
---
|
|
|
|
## 3. 核心场景
|
|
|
|
### 场景: 低高度窗口中的侧边栏导航
|
|
**模块**: admin-frontend
|
|
**条件**: 浏览器窗口高度不足以同时容纳品牌区与全部菜单项
|
|
**行为**: 用户在左侧导航区域滚动菜单
|
|
**结果**: 顶部品牌区固定可见，菜单项可完整访问，激活态与分组结构保持正常
|
|
|
|
---
|
|
|
|
## 4. 技术决策
|
|
|
|
### admin-frontend-sidebar-height-overflow#D001: 侧边栏采用“固定品牌区 + 独立滚动菜单区”
|
|
**日期**: 2026-04-24
|
|
**状态**: ✅采纳
|
|
**背景**: 用户明确选择“顶部 Logo/品牌区固定，仅菜单区域独立纵向滚动”的处理方式。
|
|
**选项分析**:
|
|
| 选项 | 优点 | 缺点 |
|
|
|------|------|------|
|
|
| A: 固定品牌区，菜单区独立滚动 | 保留品牌识别和导航定位，改动集中、体验最稳定 | 需要微调侧栏结构和滚动容器样式 |
|
|
| B: 整个侧边栏整体滚动 | 实现简单 | 品牌区会被滚出视口，低高度下辨识度更差 |
|
|
| C: 低高度自动折叠成图标栏 | 可压缩空间 | 会改变现有导航行为，且不是用户选定方案 |
|
|
**决策**: 选择方案 A
|
|
**理由**: 最符合用户已确认交互，也与当前 Apple 风格后台“固定品牌区 + 稳定导航层级”的设计基线一致。
|
|
**影响**: 影响 `AdminLayout.vue` 侧边栏结构与样式，不涉及 API、路由或业务数据流。
|
|
|
|
---
|
|
|
|
## 5. 成果设计
|
|
|
|
### 设计方向
|
|
- **美学基调**: 克制运营后台 —— 保留纯白侧栏、细边框、轻阴影和单一蓝色激活态，让修复更像“增强可用性”而非“换一套皮肤”
|
|
- **记忆点**: 窗口再矮，顶部品牌区依旧稳定悬停，菜单像独立轨道一样顺滑滚动
|
|
- **参考**: 现有 `apple/DESIGN.md` 与 `.helloagents/DESIGN.md` 的 Apple 风格后台规范
|
|
|
|
### 视觉要素
|
|
- **配色**: 保持现有 `#ffffff` 侧栏底色、`#0071e3` 激活色和中性文字层级，不引入新强调色
|
|
- **字体**: 延续全局系统字体栈 `--xboard-font-sans`，不新增字体
|
|
- **布局**: 侧栏继续分为顶部品牌区与下方菜单区，但改为明确的上下分层，菜单区获得独立滚动上下文
|
|
- **动效**: 保留当前宽度折叠过渡；滚动本身不增加额外装饰动画
|
|
- **氛围**: 维持轻薄、低噪音的 Apple 化后台质感，仅补齐滚动可达性
|
|
|
|
### 技术约束
|
|
- **可访问性**: 键盘聚焦与当前菜单激活态不可被滚动修复破坏
|
|
- **响应式**: 桌面低高度、桌面折叠态和移动端 fixed aside 都需保持可用
|