# 变更提案: admin-frontend-rank-limit-scroll

## 元信息
```yaml
类型: 功能增强
方案类型: implementation
优先级: P1
状态: 已完成
创建: 2026-04-23
```

---

## 1. 需求

### 背景
当前 `admin-frontend` 仪表盘中的“节点流量排行”和“用户流量排行”都固定只显示前 6 条，列表区域也会随着内容高度自然撑开。用户希望在不破坏现有 Apple 风格基线的前提下，让两个排行面板都支持 `10 个 / 20 个` 显示切换，并将排行内容放进可滚动的展示区域，避免页面被长列表拉得过高。

### 目标
- 在 `admin-frontend/src/views/dashboard/DashboardView.vue` 的两个流量排行面板中新增 `10 个 / 20 个` 显示数量切换。
- 让节点排行和用户排行都支持独立控制显示数量，并在列表较长时使用固定高度滚动区域承载内容。
- 延续 `apple/DESIGN.md` 的 Apple 风格：纯色分区、单一蓝色强调、低装饰噪音、清晰可访问的按钮状态。

### 约束条件
```yaml
范围约束: 仅调整 admin-frontend 仪表盘排行面板的交互和样式，不改后端接口
视觉约束: 保持 Apple 风格，不引入表格化重组件或高密度控制栏
技术约束: 继续复用现有 Vue3 + TypeScript + Element Plus + 原生样式体系
工作树约束: 保留当前未提交的趋势图口径切换改动，在其基础上完成本轮排行增强
```

### 验收标准
- [ ] “节点流量排行”和“用户流量排行”均提供 `10 个 / 20 个` 数量切换。
- [ ] 切换后列表展示条数与选择一致，且面板内容区域保持可滚动，不因为长列表破坏整体布局。
- [ ] 新增交互仍符合 `apple/DESIGN.md` 的视觉基线，并具备可见焦点与明确激活态。
- [ ] `admin-frontend` 构建通过，根仓与 `public/assets/admin` 子模块状态可见。

---

## 2. 方案

### 技术方案
1. 在 `DashboardView.vue` 中新增节点排行和用户排行各自的显示条数状态，并通过计算属性统一产出当前应渲染的列表。
2. 在排行面板头部保留现有时间范围筛选，同时补充轻量级 segmented pills 作为 `10 / 20` 显示数量切换控件。
3. 为排行列表增加固定高度滚动容器、轻量滚动条样式和面板内边距节奏，让 20 条模式下仍维持 Apple 风格的整洁感。

### 影响范围
```yaml
涉及模块:
  - admin-frontend/src/views/dashboard/DashboardView.vue
  - public/assets/admin (构建产物输出)
预计变更文件: 1-3
```

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 排行面板头部控件过多导致拥挤 | 中 | 把时间筛选与数量筛选分成两组，保持同一视觉语言但明确主次 |
| 滚动容器高度不合适影响信息密度 | 中 | 采用按 10/20 模式自适应的最大高度，同时在移动端回退为更紧凑布局 |
| 当前工作树已有趋势图增强改动 | 中 | 在现有未提交改动上增量实现，并通过构建验证确认两项增强可同时成立 |

---

## 3. 成果设计

### 设计方向
- **美学基调**: 延续当前 Apple 风格浅色信息面板，让排行区域像可浏览的信息胶囊，而不是后台表格。
- **交互模式**: 时间范围和显示数量都使用 pill 按钮；数量按钮作为次级控制，保持克制但清晰。
- **记忆点**: 同一个排行面板中，长列表被收进柔和滚动视窗，滚动时仍保持整洁的白底与单一蓝色强调。

### 视觉要素
- **配色**: 沿用 `#0071e3` 作为唯一强调色，滚动容器背景继续使用 `#fbfbfd` / `#ffffff` 层次。
- **排版**: 面板头部分成信息区与控件区，控件区按分组排列；列表内部继续保留名称、流量值、蓝色进度条和涨跌百分比。
- **状态**: 激活态为浅蓝底 + 浅蓝边框；滚动条使用低对比灰蓝色，避免视觉噪音。

---

## 4. 技术决策

### admin-frontend-rank-limit-scroll#D001: 两个排行面板独立控制显示数量
**日期**: 2026-04-23
**状态**: ✅采纳
**背景**: 节点排行和用户排行虽然共享时间范围，但使用场景不同，用户可能需要分别查看不同数量。
**决策**: 节点排行与用户排行分别维护自己的 `10 / 20` 数量切换状态。
**理由**: 这样不会把两个排行耦合成单一控制，也更贴合面板级交互。

### admin-frontend-rank-limit-scroll#D002: 使用固定高度滚动容器而不是整页自然拉伸
**日期**: 2026-04-23
**状态**: ✅采纳
**背景**: 20 条排行如果完全展开，会让 dashboard 纵向长度显著增加，破坏当前首页节奏。
**决策**: 在排行面板内引入滚动容器，并按 10/20 模式设置不同的最大高度。
**理由**: 能在保留更多信息的同时维持 Apple 风格的页面节奏和阅读效率。