报表Reports接口对接说明.md
5.64 KB
报表 Reports 接口对接说明（Print Log / Label Report）
适用范围：美国版 Web「Reports」— Print Log 列表与导出、Label Report 统计与导出、重打
实现：IReportsAppService/ReportsAppService；重打复用IUsAppLabelingAppService.ReprintAsync（已支持 admin 跳过创建人校验）
路由前缀：/api/app
0. 角色与数据范围（必读）
- 判断依据（
ReportsRoleHelper.IsAdminRole，满足其一即可）：①UserName为内置admin；② JWT 自定义 claimRoles中含admin（内置超管走AccountManager.UserInfoToClaim，不写标准roleclaim）；③ 任一Permissionclaim 为\*:\*:\*；④ 标准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与主数据名称一致，否则筛选结果为空。