# 变更提案: admin-frontend-dashboard-trend-count-toggle

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

---

## 1. 需求

### 背景
当前 `admin-frontend` 仪表盘的“收入趋势”模块仅支持按金额查看趋势线。用户希望在不破坏现有 Apple 风格页面结构的前提下，补充“按数量”视角，让管理员在同一图表区域中切换查看订单数量走势。

### 目标
- 在 `admin-frontend/src/views/dashboard/DashboardView.vue` 的趋势面板中新增“金额 / 数量”切换。
- 切换到“数量”后，图表 Y 轴、摘要卡片与最近记录同步以订单数量为主展示。
- 保持 `apple/DESIGN.md` 的 Apple 风格约束：纯色分区、单一强调蓝、克制交互和低装饰噪音。

### 约束条件
```yaml
范围约束: 仅调整 admin-frontend 仪表盘趋势模块及其图表工具逻辑
视觉约束: 延续 Apple 风格，不引入双图、双线、多色复杂图例
技术约束: 不新增图表库，继续复用现有 SVG 图表实现
业务约束: 不修改后端接口，前端基于现有趋势返回字段实现切换
```

### 验收标准
- [ ] 趋势面板新增“按金额 / 按数量”切换，默认保持“按金额”。
- [ ] 切换到“按数量”时，图表线条、Y 轴标签、摘要卡片和最近记录与数量口径一致。
- [ ] 视觉样式仍符合 `apple/DESIGN.md`，新增交互保持克制、清晰、可访问。
- [ ] `admin-frontend` 构建通过，产物成功输出到 `public/assets/admin`。

---

## 2. 方案

### 技术方案
1. 在 `src/utils/dashboard.ts` 中把趋势图构建逻辑参数化，支持金额/数量两种指标，并根据口径生成对应的 Y 轴标签格式。
2. 在 `src/views/dashboard/DashboardView.vue` 中新增趋势显示模式状态、切换按钮和摘要视图模型。
3. 保持现有 `getOrderTrend` 接口调用方式，直接复用响应中的 `paid_total`、`paid_count`、`commission_total`、`commission_count` 等字段完成数量视图。

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

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 数量视图摘要语义不清 | 中 | 采用“成交订单 / 佣金订单 / 日均成交”三段式摘要，并保留金额作为辅助信息 |
| 图表参数化后影响原金额模式 | 中 | 默认金额模式不变，并通过构建验证确保类型与模板连接正确 |
| 子模块产物状态与根仓状态不同步 | 中 | 构建后同时检查根仓与 `public/assets/admin` 子模块状态 |

---

## 3. 成果设计

### 设计方向
- **美学基调**: 延续当前 Apple 风格的浅灰内容面板 + 单一蓝色交互重点。
- **交互模式**: 在现有时间筛选旁新增一组低干扰 segmented pills，用于切换“按金额 / 按数量”。
- **记忆点**: 同一张克制的趋势图，在不增加视觉负担的情况下完成经营口径切换。

### 视觉要素
- **配色**: 继续使用 `#0071e3` 作为唯一强调色；背景和卡片保持 `#ffffff / #f5f5f7 / #fbfbfd` 层次。
- **排版**: 不新增标题层级，切换器作为次级控制区，与时间范围筛选并列。
- **状态**: 激活态用浅蓝底 + 浅蓝边框，未激活态保持白底细边框。

### 实施结果
- 已在趋势面板头部增加独立的“按金额 / 按数量”切换分组。
- 已将趋势图 SVG 构建逻辑扩展为双口径模式，数量模式下自动切换 Y 轴标签为“笔”。
- 已将摘要卡片和最近记录改为跟随当前口径同步展示。

---

## 4. 技术决策

### admin-frontend-dashboard-trend-count-toggle#D001: 采用单图切换而不是双图/双线
**日期**: 2026-04-23
**状态**: ✅采纳
**背景**: 用户在确认环节明确选择“金额 / 数量切换”方案。
**决策**: 在同一趋势图区域中，通过切换按钮切换图表口径和摘要信息。
**理由**: 该方案最符合 Apple 风格的克制表达，同时不会显著增加页面密度。

### admin-frontend-dashboard-trend-count-toggle#D002: 数量模式复用现有接口字段，不新增后端联调
**日期**: 2026-04-23
**状态**: ✅采纳
**背景**: 现有趋势接口已返回 `paid_count` 和 `commission_count` 等字段。
**决策**: 前端直接基于现有响应切换图表指标和摘要视图。
**理由**: 可以在最小范围内完成需求，避免扩展后端接口或引入新请求。