14afbc16
 李曜臣
2026-6-22
|
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
31
32
33
34
35
36
37
38
39
40
41
42
43
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
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
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
|
# 6-16 代码优化
本文档说明 **2026-06-16** 对美国版 Web 管理端 **`GET /api/app/dashboard/overview`** 中 **Recent Labels** 区块 **Label ID** 展示规则的同步改造。
测试环境：`http://flus-test.3ffoodsafety.com`
---
## 背景
Dashboard「Recent Labels」列表原先 `recentLabels[].labelCode` 返回 **`fl_label.LabelCode`**（或标签业务编码），与业务要求的 **Label ID** 含义不一致。
业务规则（与 App preview、Print Log、报表一致）：
**Label ID = 某门店在某个自然日内，每次打印任务按时间递增的序号**
| 示例 | 含义 |
|------|------|
| `20260513-1` | 该门店 2026-05-13 当日第 1 次打印 |
| `20260513-2` | 同日第 2 次 |
| `20260514-1` | 次日重新从 1 计数 |
格式：`{yyyyMMdd}-{n}`（`n` 从 1 递增；按 **`PrintedAt ?? CreationTime`** 所在自然日、同一 **`locationId`** 统计）。
> **注意**：`labelCode` 字段名保持不变（前端 Recent Labels 已绑定该字段展示 Label ID），**语义**由「标签编码」改为「门店当日打印序号」。不是 `fl_label.Id`，也不是 `fl_label.LabelCode`。
---
## 接口说明
| 项目 | 内容 |
|------|------|
| 方法 | `GET` |
| 路径 | `/api/app/dashboard/overview` |
| 鉴权 | Bearer Token（Web 管理端登录 Token） |
| 入参 | 无 |
### 出参变更（`DashboardOverviewOutputDto.recentLabels[]`）
| 字段 | 变更前 | 变更后 |
|------|--------|--------|
| **`labelCode`** | `fl_label.LabelCode`（标签业务编码） | 该打印任务在所属门店、打印日内的序号 **`yyyyMMdd-n`** |
`recentLabels` 其余字段（`taskId`、`displayName`、`printedByName`、`printedAt`、`status`、`labelTypeBadge`）不变。
Overview 其它区块（指标卡片、周趋势、分类分布等）不受影响。
### `labelCode`（Label ID）计算规则
与 **`POST /api/app/us-app-labeling/preview`**、**`GET /api/app/reports/print-log-list`** 共用 Helper：**`ReportsPrintLogDailyLabelIdHelper.ResolveDailyLabelIdsAsync`**。
1. 取打印任务 **`PrintedAt ?? CreationTime`** 的日期部分 `yyyyMMdd`。
2. 在同一 **`locationId`**、同一自然日内，按 `PrintedAt ?? CreationTime` 升序、`Id` 升序对所有任务排序。
3. 第 `i` 条任务的 Label ID = **`{yyyyMMdd}-{i}`**（`i` 从 1 开始）。
4. Recent Labels 取权限范围内**最新 10 条**打印任务；每条任务的 `labelCode` 为其在**所属门店当日序列**中的序号（非全平台统一编号）。
多门店场景：不同门店各自从 `-1` 计数；同一 Dashboard 列表可混合展示多个门店的记录，每条记录的 `labelCode` 仅对应该任务的 `locationId` + 打印日。
---
## 请求示例
```bash
curl -X GET "http://flus-test.3ffoodsafety.com/api/app/dashboard/overview" \
-H "Authorization: Bearer {token}"
```
### 响应片段（`recentLabels` 示例）
```json
{
"recentLabels": [
{
"taskId": "1234567890123456789",
"labelCode": "20260604-3",
"displayName": "Organic Milk 1L",
"printedByName": "Alice",
"printedAt": "2026-06-04T14:22:00",
"status": "active",
"labelTypeBadge": "2\"x2\""
},
{
"taskId": "1234567890123456788",
"labelCode": "20260604-2",
"displayName": "Whole Wheat Bread",
"printedByName": "Bob",
"printedAt": "2026-06-04T11:05:00",
"status": "expired",
"labelTypeBadge": "4\"x2\""
}
],
"generatedAt": "2026-06-04T15:00:00"
}
```
若某任务无法解析门店或打印时间，则 `labelCode` 为 **`无`**。
---
## 涉及代码
| 文件 | 说明 |
|------|------|
| `Services/DashboardAppService.cs` | `GetOverviewAsync`：`recentLabels` 查询增加 `LocationId`，调用 `ResolveDailyLabelIdsAsync` 填充 `labelCode` |
| `Dtos/Dashboard/DashboardRecentLabelItemDto.cs` | `LabelCode` XML 注释更新为当日序号语义 |
| `IServices/IDashboardAppService.cs` | 接口 `remarks` 补充 `recentLabels[].labelCode` 规则说明 |
| `Helpers/ReportsPrintLogDailyLabelIdHelper.cs` | 共用（与 6-11 preview / 6-2 print-log 一致） |
---
## 验证步骤
1. 登录 Web 管理端，获取 Bearer Token。
2. 选定门店，确认某自然日已有 N 条 `fl_label_print_task`（可用 print-log 或 SQL 核对）。
3. 调用 **`GET /api/app/dashboard/overview`**，`recentLabels` 中对应任务的 **`labelCode`** 应与 print-log 列表中同一 `taskId` 的 Label ID 一致。
4. 跨日打印：次日首条应为 `{新日期}-1`。
5. 多门店：两门店同日各打印 1 次，两条记录的 `labelCode` 末尾序号均可为 `-1`（各自门店独立计数）。
### SQL 抽查
```sql
SELECT Id, LocationId, PrintedAt, CreationTime,
IFNULL(PrintedAt, CreationTime) AS EffectiveTime
FROM fl_label_print_task
WHERE LocationId = '{locationId}'
AND IFNULL(PrintedAt, CreationTime) >= '{yyyy-MM-dd}'
AND IFNULL(PrintedAt, CreationTime) < DATE_ADD('{yyyy-MM-dd}', INTERVAL 1 DAY)
ORDER BY EffectiveTime, Id;
```
按行号 `1..N` 对应 `labelCode` 的 `-n` 部分；日期部分为 `yyyyMMdd`。
---
## 关联文档
- Label ID 通用规则与 preview：`项目相关文档/6-11代码优化.md`
- App print-log Label ID：`项目相关文档/6-2代码优化.md`
- Dashboard 数据范围（管理员 / 门店绑定）：`DashboardScopeHelper` 及接口 `IDashboardAppService` 注释
|
