# 变更提案: 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 都需保持可用