# Dashboard 统计接口对接说明

> 适用范围：美国版 Web 管理端 Dashboard 首页统计
>
> 接口实现：`IDashboardAppService.GetOverviewAsync` / `DashboardAppService.GetOverviewAsync`

---

## 1. 接口信息

- **方法**：`GET`
- **路径**：`/api/app/dashboard/overview`
- **鉴权**：需要登录（Bearer Token）
- **请求参数**：无

---

## 2. 返回结构（顶层）

```json
{
  "labelsPrintedToday": {},
  "activeTemplates": {},
  "activeUsers": {},
  "locations": {},
  "people": {},
  "products": {},
  "weeklyPrintVolume": [],
  "byCategory": [],
  "byCategoryTotal": 0,
  "recentLabels": [],
  "generatedAt": "2026-04-22T10:00:00+08:00",

  "metricCards": [],
  "categoryDistribution": [],
  "categoryDistributionTotal": 0
}
```

说明：
- `labelsPrintedToday/activeTemplates/...`、`byCategory/byCategoryTotal` 是**前端直观命名**（推荐使用）。
- `metricCards`、`categoryDistribution`、`categoryDistributionTotal` 为**兼容字段**（与旧版返回一致）。
- `recentLabels`：**Recent Labels** 区块数据，全门店按打印时间倒序取最新 **10** 条（`fl_label_print_task`）。

---

## 3. 字段说明

### 3.1 指标卡片对象（`DashboardMetricCardDto`）

用于以下字段：
- `labelsPrintedToday`
- `activeTemplates`
- `activeUsers`
- `locations`
- `people`
- `products`
- `metricCards[]`（同结构）

| 字段 | 类型 | 说明 |
|---|---|---|
| `key` | string | 指标标识（如 `labelsPrintedToday`） |
| `title` | string | 指标标题 |
| `value` | int | 当前值 |
| `previousValue` | int | 对比周期值 |
| `changeValue` | int | 增减值（`value - previousValue`） |
| `changeRate` | decimal | 增减比例（百分比，保留 2 位） |

---

### 3.2 周趋势（`weeklyPrintVolume`）

| 字段 | 类型 | 说明 |
|---|---|---|
| `date` | string | 日期，格式 `yyyy-MM-dd` |
| `value` | int | 当天打印量 |

---

### 3.3 分类分布（`byCategory`）

`byCategory` 与 `categoryDistribution` 结构一致。

| 字段 | 类型 | 说明 |
|---|---|---|
| `categoryId` | string | 分类 Id（`fl_label_category.Id`） |
| `categoryName` | string | 分类名称 |
| `count` | int | 该分类下标签数量 |
| `ratio` | decimal | 占比（百分比，保留 2 位） |

---

### 3.4 最近打印标签（`recentLabels`）

数组元素类型：`DashboardRecentLabelItemDto`，按 **`PrintedAt`（`PrintedAt` 为空则用 `CreationTime`）倒序**，最多 **10** 条。

| 字段 | 类型 | 说明 |
|---|---|---|
| `taskId` | string | 打印任务 Id（`fl_label_print_task.Id`） |
| `labelCode` | string | 标签编码（界面 Serial，如 `1-251201`） |
| `displayName` | string | 展示标题：优先 **产品名**，否则 **标签名** |
| `printedByUserId` | string \| null | 打印人用户 Id（`CreatedBy`） |
| `printedByName` | string | 打印人展示名（`User.Name` 或 `UserName`） |
| `printedAt` | string (datetime) | 打印时间（ISO 8601） |
| `status` | string | `active` 或 `expired`：从 `PrintInputJson` 解析 `expiryDate` / `expiry` / `expirationDate`，与**当天日期**比较；无保质期或解析失败视为 `active` |
| `labelTypeBadge` | string | 模板尺寸短文案（如 `2"x2"`），用于左侧圆标 |

前端可用 `printedAt` 自行格式化为「10 mins ago」等相对时间。

---

## 4. 返回示例

```json
{
  "labelsPrintedToday": {
    "key": "labelsPrintedToday",
    "title": "Labels Printed Today",
    "value": 342,
    "previousValue": 305,
    "changeValue": 37,
    "changeRate": 12.13
  },
  "activeTemplates": {
    "key": "activeTemplates",
    "title": "Active Templates",
    "value": 24,
    "previousValue": 22,
    "changeValue": 2,
    "changeRate": 9.09
  },
  "activeUsers": {
    "key": "activeUsers",
    "title": "Active Users",
    "value": 8,
    "previousValue": 7,
    "changeValue": 1,
    "changeRate": 14.29
  },
  "locations": {
    "key": "locations",
    "title": "Locations",
    "value": 12,
    "previousValue": 11,
    "changeValue": 1,
    "changeRate": 9.09
  },
  "people": {
    "key": "people",
    "title": "People",
    "value": 48,
    "previousValue": 45,
    "changeValue": 3,
    "changeRate": 6.67
  },
  "products": {
    "key": "products",
    "title": "Products",
    "value": 156,
    "previousValue": 156,
    "changeValue": 0,
    "changeRate": 0
  },
  "weeklyPrintVolume": [
    { "date": "2026-04-16", "value": 142 },
    { "date": "2026-04-17", "value": 226 },
    { "date": "2026-04-18", "value": 185 },
    { "date": "2026-04-19", "value": 261 },
    { "date": "2026-04-20", "value": 192 },
    { "date": "2026-04-21", "value": 121 },
    { "date": "2026-04-22", "value": 342 }
  ],
  "byCategory": [
    { "categoryId": "CAT001", "categoryName": "Breakfast", "count": 420, "ratio": 42.00 },
    { "categoryId": "CAT002", "categoryName": "Lunch", "count": 350, "ratio": 35.00 },
    { "categoryId": "CAT003", "categoryName": "Dinner", "count": 230, "ratio": 23.00 }
  ],
  "byCategoryTotal": 1000,
  "recentLabels": [
    {
      "taskId": "…",
      "labelCode": "1-251201",
      "displayName": "Chicken Breast",
      "printedByUserId": "…",
      "printedByName": "Alice J.",
      "printedAt": "2026-04-22T09:50:00+08:00",
      "status": "active",
      "labelTypeBadge": "2\"x2\""
    }
  ],
  "generatedAt": "2026-04-22T10:00:00+08:00",
  "metricCards": [],
  "categoryDistribution": [],
  "categoryDistributionTotal": 1000
}
```

---

## 5. 统计口径说明

### 5.1 Labels Printed Today
- 当前值：`fl_label_print_task` 在“今日 00:00~次日 00:00”的记录数。
- 对比值：昨日同口径记录数。

### 5.2 Active Templates
- 当前值：`fl_label_template` 中 `IsDeleted = false AND State = true` 数量。
- 对比值：同口径且 `CreationTime < 最近7天起始日` 的数量。

### 5.3 Active Users
- 当前值：`User` 表中 `IsDeleted = false AND State = true` 数量。
- 对比值：同口径且 `CreationTime < 最近7天起始日` 的数量。

### 5.4 Locations
- 当前值：`location` 表中 `IsDeleted = false` 数量。
- 对比值：同口径且 `CreationTime < 最近7天起始日` 的数量。

### 5.5 People
- 当前值：`User` 表中 `IsDeleted = false` 数量。
- 对比值：同口径且 `CreationTime < 最近7天起始日` 的数量。

### 5.6 Products
- 当前值：`fl_product` 表中 `IsDeleted = false` 数量。
- 对比值：当前版本由于 `FlProductDbEntity` 未映射 `CreationTime`，临时按同口径总量返回（即变化可能为 0）。

### 5.7 Weekly Print Volume
- 统计最近 7 天（含今天）每天 `fl_label_print_task` 数量。
- 无数据日期补 0。

### 5.8 By Category
- 基于启用且未删除的 `fl_label_category` 作为分类集合。
- 统计 `fl_label` 中未删除且 `LabelCategoryId` 命中的数量。
- 占比按 `count / byCategoryTotal * 100` 计算，保留 2 位。

---

## 6. 前端接入建议

- 新页面优先使用：
  - 指标：`labelsPrintedToday`、`activeTemplates`、`activeUsers`、`locations`、`people`、`products`
  - 图表：`weeklyPrintVolume`
  - 环图：`byCategory` + `byCategoryTotal`
- 旧逻辑仍可使用兼容字段：
  - `metricCards`
  - `categoryDistribution`
  - `categoryDistributionTotal`