# 6-11 代码优化

本文档说明 **2026-06-11** 对美国版 App **`POST /api/app/us-app-labeling/preview`** 出参 **`labelId`** 的格式调整。

---

## 背景

预览页「Label ID」原先返回 **`fl_label.Id`**（GUID，如 `3a2192be-7b8f-e3e8-db9c-3a5e627b9222`），与业务要求不符。

业务规则：**Label ID = 某门店当日每次打印任务的递增序号**，与 Print Log、管理端报表一致：

| 示例 | 含义 |
|------|------|
| `20260513-1` | 该门店 2026-05-13 当日第 1 次打印 |
| `20260513-2` | 同日第 2 次 |
| `20260514-1` | 次日重新从 1 计数 |

格式：`{yyyyMMdd}-{n}`（`n` 从 1 递增，按 `PrintedAt ?? CreationTime` 所在自然日、同一 `locationId` 统计）。

测试环境：`http://flus-test.3ffoodsafety.com`

---

## 接口说明

| 项目 | 内容 |
|------|------|
| 方法 | `POST` |
| 路径 | `/api/app/us-app-labeling/preview` |
| 鉴权 | Bearer Token |

### 入参（Body：`UsAppLabelPreviewInputVo`）

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `locationId` | string | 是 | 门店 Id（`location.Id`） |
| `labelCode` | string | 是 | 标签编码（`fl_label.LabelCode`） |
| `productId` | string | 否 | 预览产品 Id |
| `baseTime` | DateTime | 否 | 基准时间；影响模板内日期/时间控件，也用于确定「哪一天的序号」；未传则用服务端当前时间 |
| `printInputJson` | object | 否 | 打印时输入项 |

### 出参（`UsAppLabelPreviewDto`）变更

| 字段 | 变更前 | 变更后 |
|------|--------|--------|
| **`labelId`** | `fl_label.Id`（GUID） | 门店当日**下一个**打印序号 `yyyyMMdd-n` |

其余字段（`locationId`、`labelCode`、`template`、`labelLastEdited` 等）不变。

### `labelId` 计算规则

1. 取 **`baseTime ?? 当前服务器时间`** 的日期部分 `yyyyMMdd`。
2. 统计该 **`locationId`** 在当日内已有打印任务数（`fl_label_print_task`，时间取 `PrintedAt ?? CreationTime`）。
3. **`labelId = {yyyyMMdd}-{已有任务数 + 1}`**（预览不落库，表示「若此刻点击 Print 将获得的序号」）。
4. 与 **`POST /api/app/us-app-labeling/get-print-log-list`**、管理端 **`GET /api/app/reports/print-log-list`** 使用同一 Helper：`ReportsPrintLogDailyLabelIdHelper`。

> **注意**：`labelId` 不是 `fl_label.LabelCode`，也不是 `fl_label.Id`。标签主键如需内部关联，请使用打印任务创建后的 `taskId` 或 print-log 中的 `labelEntityId`。

---

## 请求示例

```bash
curl -X POST "http://flus-test.3ffoodsafety.com/api/app/us-app-labeling/preview" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "550e8400-e29b-41d4-a716-446655440000",
    "labelCode": "LBL0001",
    "productId": "PROD001",
    "baseTime": "2026-05-13T09:00:00"
  }'
```

### 响应片段（示例）

```json
{
  "labelId": "20260513-3",
  "locationId": "550e8400-e29b-41d4-a716-446655440000",
  "labelCode": "LBL0001",
  "labelLastEdited": "2026-06-01T08:30:09",
  "template": { }
}
```

若该门店在 `2026-05-13` 已有 2 条打印记录，预览返回 `20260513-3`；当日首条预览为 `20260513-1`。

---

## 涉及代码

| 文件 | 说明 |
|------|------|
| `Helpers/ReportsPrintLogDailyLabelIdHelper.cs` | 新增 `ResolveNextDailyLabelIdAsync`（预览取下一序号） |
| `Services/UsAppLabelingAppService.cs` | `PreviewAsync` 出参 `LabelId` 改用当日序号 |
| `Dtos/UsAppLabeling/UsAppLabelPreviewDto.cs` | `labelId` XML 注释 |
| `IServices/IUsAppLabelingAppService.cs` | 接口注释 |

---

## 验证步骤

1. 选定门店，确认当日已有 N 条 `fl_label_print_task`（可用 print-log 列表核对）。
2. 调用 **preview**，`labelId` 应为 `{今日yyyyMMdd}-{N+1}`。
3. 执行 **print** 创建新任务后，print-log 中该任务 `labelId` 与预览时一致（同一时刻连续预览+打印）。
4. 修改 `baseTime` 为历史日期，序号应按该日任务数计算，而非「今天」。

### SQL 抽查

```sql
SELECT Id, LocationId, PrintedAt, CreationTime
FROM fl_label_print_task
WHERE LocationId = '{locationId}'
  AND IFNULL(PrintedAt, CreationTime) >= CURDATE()
  AND IFNULL(PrintedAt, CreationTime) < DATE_ADD(CURDATE(), INTERVAL 1 DAY)
ORDER BY IFNULL(PrintedAt, CreationTime), Id;
```

当日行数 + 1 应与 preview 返回的 `-n` 部分一致。

---

## 关联文档

- 同序号规则：`项目相关文档/6-2代码优化.md` → **App `get-print-log-list` 的 Label ID**
- App 预览页读取字段：`labelId` / `LabelId`（`preview.vue`）