M4-05 Reporting & Export Module #39

New Issue

wangdl · 2026-05-22T21:09:51+08:00

wangdl commented

2026-05-22 21:09:51 +08:00

目标

设计知习报表与数据导出模块，为 Admin 提供运营报表、学习报表、成本报表和 CSV/XLSX 导出能力。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

Admin 需要定期查看运营数据（用户增长、活跃度）、学习数据（学习时长、知识点掌握率）、成本数据（AI 调用费用趋势），并支持导出为 CSV/XLSX 文件。大文件导出应异步执行避免超时。

模块职责

本模块负责：
- 运营报表（用户增长、活跃度、留存）
- 学习报表（学习时长、知识点掌握率、复习完成率）
- 成本报表（按服务商/模块/时间的成本趋势）
- CSV 导出
- XLSX 导出（带格式）
- 异步大文件导出（通过 BullMQ）
- 定时报表（通过 Cron 或定时任务）

候选数据对象

Report（报表记录）
ExportJob（导出任务）
ScheduledReport（定时报表配置）

禁止事项

禁止导出包含用户隐私敏感数据
禁止大文件导出同步执行阻塞 HTTP

不建议当前阶段实现

报表可视化（Dashboard 负责）
PDF 导出
自定义报表 SQL

## 目标设计知习报表与数据导出模块，为 Admin 提供运营报表、学习报表、成本报表和 CSV/XLSX 导出能力。本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明 Admin 需要定期查看运营数据（用户增长、活跃度）、学习数据（学习时长、知识点掌握率）、成本数据（AI 调用费用趋势），并支持导出为 CSV/XLSX 文件。大文件导出应异步执行避免超时。 ## 模块职责 1. 本模块负责： - 运营报表（用户增长、活跃度、留存） - 学习报表（学习时长、知识点掌握率、复习完成率） - 成本报表（按服务商/模块/时间的成本趋势） - CSV 导出 - XLSX 导出（带格式） - 异步大文件导出（通过 BullMQ） - 定时报表（通过 Cron 或定时任务） ## 候选数据对象 - Report（报表记录） - ExportJob（导出任务） - ScheduledReport（定时报表配置） ## 禁止事项 - 禁止导出包含用户隐私敏感数据 - 禁止大文件导出同步执行阻塞 HTTP ## 不建议当前阶段实现 - 报表可视化（Dashboard 负责） - PDF 导出 - 自定义报表 SQL

wangdl added this to the M4：Admin 生产级运维深化（P3） milestone 2026-05-22 21:09:51 +08:00

wangdl self-assigned this 2026-05-22 21:09:51 +08:00

wangdl commented

2026-05-24 18:01:48 +08:00

✅ M4-05 实施完成

已有基础

admin-costs 模块已有 export-csv 端点（成本 CSV 导出）。

本 Issue 新增

模块	说明
ExportJob Prisma 模型	记录导出任务
ReportingService	userReport / learningReport / reviewReport
ReportingController	3 个 CSV 导出端点 + 导出任务历史
ReportingAdmin 页面	用户/学习/复习 CSV 下载，时间范围选择

AAPI 端点

端点	方法	说明
/admin-api/reporting/export/users?days=30	GET	用户数据 CSV
/admin-api/reporting/export/learning?days=30	GET	学习数据 CSV
/admin-api/reporting/export/reviews?days=30	GET	复习数据 CSV
/admin-api/reporting/jobs	GET	导出任务历史
/admin-api/costs/export-csv?days=30	GET	成本数据 CSV（已有）

菜单

新增「报表导出」菜单项

## ✅ M4-05 实施完成 ### 已有基础 admin-costs 模块已有 export-csv 端点（成本 CSV 导出）。 ### 本 Issue 新增 | 模块 | 说明 | |------|------| | ExportJob Prisma 模型 | 记录导出任务 | | ReportingService | userReport / learningReport / reviewReport | | ReportingController | 3 个 CSV 导出端点 + 导出任务历史 | | ReportingAdmin 页面 | 用户/学习/复习 CSV 下载，时间范围选择 | ### AAPI 端点 | 端点 | 方法 | 说明 | |------|------|------| | /admin-api/reporting/export/users?days=30 | GET | 用户数据 CSV | | /admin-api/reporting/export/learning?days=30 | GET | 学习数据 CSV | | /admin-api/reporting/export/reviews?days=30 | GET | 复习数据 CSV | | /admin-api/reporting/jobs | GET | 导出任务历史 | | /admin-api/costs/export-csv?days=30 | GET | 成本数据 CSV（已有） | ### 菜单新增「报表导出」菜单项

wangdl closed this issue

2026-06-05 20:17:12 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#39