# 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` 注释