王明 / Food-Labeling-Management-Platform

Blame view

项目相关文档/Dashboard统计接口对接说明.md 7.13 KB
Edit Raw Normal View History Permalink
3b307558   李曜臣   统计接口实现 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
 
  # 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,
4d328ec2   李曜臣   平台端报表reports,仪表盘D... 
31
 
    "recentLabels": [],
3b307558   李曜臣   统计接口实现 
32
33
34
35
36
37
38
39
40
41
42
 
    "generatedAt": "2026-04-22T10:00:00+08:00",
  
    "metricCards": [],
    "categoryDistribution": [],
    "categoryDistributionTotal": 0
  }
  ```
  
  说明：
  - `labelsPrintedToday/activeTemplates/...`、`byCategory/byCategoryTotal` 是**前端直观命名**（推荐使用）。
  - `metricCards`、`categoryDistribution`、`categoryDistributionTotal` 为**兼容字段**（与旧版返回一致）。
4d328ec2   李曜臣   平台端报表reports,仪表盘D... 
43
 
  - `recentLabels`：**Recent Labels** 区块数据，全门店按打印时间倒序取最新 **10** 条（`fl_label_print_task`）。
3b307558   李曜臣   统计接口实现 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
  
  ---
  
  ## 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 位） |
  
  ---
4d328ec2   李曜臣   平台端报表reports,仪表盘D... 
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
  ### 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」等相对时间。
  
  ---
3b307558   李曜臣   统计接口实现 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 
  ## 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,
4d328ec2   李曜臣   平台端报表reports,仪表盘D... 
179
180
181
182
183
184
185
186
187
188
189
190
 
    "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\""
      }
    ],
3b307558   李曜臣   统计接口实现 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
    "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`