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。

---

请求示例

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"
  }'

响应片段（示例）

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

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）