Files

T

yinjianm e393b11b61 feat(admin-frontend): 完成节点与礼品卡管理工作台

补齐节点管理真实新增、编辑与排序流程，接入权限组与路由组
维护页，并支持 11 种协议的动态配置表单

开放礼品卡管理入口，交付模板、兑换码、使用记录与统计四页签
工作台，接入 gift-card 相关后台接口

将知识库、权限组与路由管理从占位页升级为真实页面，并修复侧边栏
低高度裁切问题

修复仪表盘 24h 流量排行涨跌始终为 0 的问题，改为对比昨天整日统
计并补充单元测试

2026-04-24 21:58:16 +08:00

5.4 KiB

Raw Permalink Blame History

变更提案: admin-frontend-sidebar-height-overflow

元信息

类型: 缺陷修复
方案类型: implementation
优先级: P1
状态: 已确认
创建: 2026-04-24

1. 需求

背景

admin-frontend 新增系统管理与订阅管理分组后，左侧导航项明显增多。当前 AdminLayout.vue 的侧边栏仍采用“Logo + ElMenu 直接铺满”的结构，而 body 又被全局设置为 overflow: hidden。在用户截图所示的小窗口高度下，底部菜单会被直接裁切，导致“礼品卡管理”“系统管理”“支付配置”等入口无法完整访问。

目标

修复管理端侧边栏在低视口高度下显示不全的问题。
按用户已确认的方案，保留顶部 Logo/品牌区固定，仅让菜单区独立纵向滚动。
保持现有 Apple 风格后台的导航层级、折叠行为和移动端体验不回退。

约束条件

范围约束: 仅处理 admin 侧边栏在低高度下的可访问性与滚动行为，不扩展菜单信息架构
技术约束: 继续使用 Vue3 + TypeScript + Element Plus，不新增依赖
兼容性约束: 需兼容桌面展开态、折叠态以及现有移动端 fixed aside 行为
视觉约束: 延续 apple/DESIGN.md 与 .helloagents/DESIGN.md 的纯白侧栏 + 单一蓝色激活态体系

验收标准

在窗口高度不足时，侧边栏底部菜单项仍可通过纵向滚动访问完整。
顶部 Logo/品牌区保持固定，不跟随菜单滚动一起消失。
折叠态与移动端侧边栏不出现新的遮挡、抖动或布局错位。
admin-frontend 执行 npm run build 通过。

2. 方案

技术方案

在 AdminLayout.vue 中把侧边栏拆成“固定头部品牌区 + 独立滚动的菜单容器”两层结构，而不是直接让 ElMenu 占满整个 ElAside。
为侧边栏与菜单滚动容器补齐 min-height: 0、overflow-y: auto、底部留白和滚动条细节，解决 flex 子项在固定高度容器中无法正确收缩的问题。
保持现有 ElMenu、ElSubMenu 和折叠逻辑不变，确保这次修复是针对根因的最小改动，而不是重写导航实现。

影响范围

涉及模块:
  - 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 都需保持可用

5.4 KiB Raw Permalink Blame History