报表 Reports 接口对接说明（Print Log / Label Report）

适用范围：美国版 Web「Reports」— Print Log 列表与导出、Label Report 统计与导出、重打
实现：IReportsAppService / ReportsAppService；重打复用 IUsAppLabelingAppService.ReprintAsync（已支持 admin 跳过创建人校验）
路由前缀：/api/app

---

0. 角色与数据范围（必读）

• 判断依据：CurrentUser.Roles 中是否存在忽略大小写等于 admin 的角色码（与 JWT 中角色码一致，参见 AuthSessionAppService / ReportsRoleHelper）。
• admin：不按 CreatedBy 过滤，可查看/统计全部 fl_label_print_task（仍受 Partner/Group/Location/日期/关键字筛选）。
• 非 admin：所有列表与统计仅包含 CreatedBy == 当前用户 Id 的打印任务。
• 重打：非 admin 仅能重打本人任务；admin 可重打任意用户任务，但仍须 locationId 与历史任务一致（与 App 重打规则一致）。

---

1. Partner / Group / Location 筛选说明

• locationId：若传则只查该门店（location.Id 字符串）。
• partnerId（fl_partner.Id）：按合作伙伴名称与 location.Partner 文本全等（trim 后）匹配，得到门店集合再过滤任务。
• groupId（fl_group.Id）：按组织的 GroupName + 父级 PartnerName 与门店的 GroupName + Partner 文本全等匹配门店。
• 若 Partner/Group 在库中不存在，返回空列表/空统计（不报错）。
• 未传 Partner/Group/Location 时：不按门店集合预过滤（仅日期、关键字、用户范围生效）。

---

2. Print Log — 分页查询

• 方法：GET
• 路径：/api/app/reports/print-log-list（以 Swagger 为准；ABP 约定多为 get-print-log-list 映射到该路径）

2.1 查询参数（ReportsPrintLogGetListInputVo）

参数	类型	说明
skipCount	int	页码，从 1 起
maxResultCount	int	每页条数
sorting	string	可选：PrintedAt asc / PrintedAt desc（默认倒序）
partnerId	string	可选
groupId	string	可选
locationId	string	可选
startDate	date	可选；默认与结束日组成约 30 天窗口
endDate	date	可选；默认今天（含当日）
keyword	string	可选；匹配产品名、标签分类名、产品分类名（模糊）

2.2 响应项（ReportsPrintLogListItemDto）

含：taskId、labelCode、productName、categoryName、templateText、printedAt、printedByName、locationText、locationId（重打必填）、expiryDateText（从 PrintInputJson 中尝试解析 expiryDate / expiry / expirationDate）。

---

3. Print Log — 导出 PDF

• 方法：GET
• 路径：/api/app/reports/export-print-log-pdf
• 查询参数：与 §2 相同（分页字段忽略）；最多 5000 条，超出返回业务错误。

---

4. Print Log — 重打（Reprint）

• 方法：POST
• 路径：/api/app/reports/reprint-print-log（实现内转发至 UsAppLabelingAppService.ReprintAsync，以 Swagger 为准）
• Body：UsAppLabelReprintInputVo：locationId、taskId、printQuantity、clientRequestId（可选）、打印机字段（可选）。

---

5. Label Report — 统计聚合

• 方法：GET
• 路径：/api/app/reports/label-report（以 Swagger 为准）

5.1 查询参数（ReportsLabelReportQueryInputVo）

与 Print Log 相同的 partnerId、groupId、locationId、startDate、endDate、keyword（无分页）。

5.2 默认时间窗

未传日期时：结束日 = 今天，开始日 = 结束日前推 29 天（共约 30 个自然日，含首尾）。

5.3 返回（ReportsLabelReportOutputDto）

• summary：totalLabelsPrinted、上一同长周期 totalLabelsPrintedPrevPeriod、totalLabelsPrintedChangeRate（%）；最热门标签分类名与次数；Top 产品名与次数；avgDailyPrints 及环比等。
• labelsByCategory：按 标签分类（fl_label_category）汇总当前区间内打印次数。
• printVolumeTrend：在当前筛选日期区间内，取结束日向前最多 7 个自然日（与区间求交）的按日打印量。
• mostUsedProducts：当前区间内产品打印次数 Top20，usagePercent 为占当期总打印次数的百分比。

---

6. Label Report — 导出 PDF

• 方法：GET
• 路径：/api/app/reports/export-label-report-pdf
• 查询参数：与 §5 相同；内容为摘要 + 分类表 + 日趋势表 + Top 产品表。

---

7. 数据表与字段依赖

• 打印任务：fl_label_print_task（CreatedBy、LocationId、PrintedAt、PrintInputJson 等）
• 门店：location（Partner、GroupName、LocationCode、LocationName）
• 主数据：fl_partner、fl_group（筛选用）
• 用户：User（展示 PrintedByName）

---

8. 前端对接提示

• Print Log 行内 Reprint：使用列表返回的 locationId + taskId 调重打接口。
• 「Export Report」在 Print Log Tab 调 §3；在 Label Report Tab 调 §6。
• 下拉 Partner / Group / Location 与列表筛选字段一致；需保证门店维护的 Partner / GroupName 与主数据名称一致，否则筛选结果为空。