王明 / Food-Labeling-Management-Platform

Dashboard统计接口对接说明.md 7.13 KB

Dashboard 统计接口对接说明

适用范围：美国版 Web 管理端 Dashboard 首页统计

接口实现：IDashboardAppService.GetOverviewAsync / DashboardAppService.GetOverviewAsync

1. 接口信息

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

2. 返回结构（顶层）

{
  "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
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. 返回示例

{
  "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