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

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

---

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

- 判断依据（`ReportsRoleHelper.IsAdminRole`，满足其一即可）：① `UserName` 为内置 **`admin`**；② JWT 自定义 claim **`Roles`** 中含 **`admin`**（内置超管走 `AccountManager.UserInfoToClaim`，不写标准 `role` claim）；③ 任一 **`Permission`** claim 为 **`\*:\*:\*`**；④ 标准 **`CurrentUser.Roles`** 中含忽略大小写的 **`admin`**（普通账号绑定 `RoleCode=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` 与主数据名称一致，否则筛选结果为空。