120 lines
3.4 KiB
Markdown
120 lines
3.4 KiB
Markdown
|
# 学习信息后台接口 总设计
|
|||
|
|
|
|||
|
|
> API-ADMIN-INFO-000 | v1.0 | 2026-06-09
|
|||
|
|
|
|||
|
|
## 1. 概述
|
|||
|
|
|
|||
|
|
基于 M8 核心数据表（ReadingEvent / LearningSession / MaterialReadingProgress / DailyLearningActivity / LearningRecord / TemporaryReadingMaterial），为 Admin Dashboard 提供管理查询、诊断、操作接口。
|
|||
|
|
|
|||
|
|
### 路由前缀
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
/admin/learning/*
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 鉴权
|
|||
|
|
|
|||
|
|
- 所有接口需要 `AdminJwtGuard`
|
|||
|
|
- 角色要求：`ADMIN` 或 `SUPER_ADMIN`
|
|||
|
|
- 审计日志记录操作人和时间
|
|||
|
|
|
|||
|
|
## 2. 接口总览
|
|||
|
|
|
|||
|
|
### 查询接口
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| GET | `/admin/learning/dashboard` | Dashboard 概览 |
|
|||
|
|
| GET | `/admin/learning/reading-events` | ReadingEvent 列表/详情 |
|
|||
|
|
| GET | `/admin/learning/reading-events/:id` | ReadingEvent 详情 |
|
|||
|
|
| GET | `/admin/learning/reading-events/failed` | 失败/警告/重复事件 |
|
|||
|
|
| GET | `/admin/learning/sessions` | LearningSession 列表 |
|
|||
|
|
| GET | `/admin/learning/sessions/:id` | LearningSession 详情 |
|
|||
|
|
| GET | `/admin/learning/progress` | MaterialReadingProgress 列表 |
|
|||
|
|
| GET | `/admin/learning/progress/:id` | 资料进度详情 |
|
|||
|
|
| GET | `/admin/learning/daily-activities` | DailyLearningActivity 列表 |
|
|||
|
|
| GET | `/admin/learning/records` | LearningRecord 列表 |
|
|||
|
|
| GET | `/admin/learning/records/:id` | LearningRecord 详情 |
|
|||
|
|
| GET | `/admin/learning/user-timeline?userId=` | 用户学习时间线 |
|
|||
|
|
| GET | `/admin/learning/user-diagnose?userId=` | 单用户诊断 |
|
|||
|
|
| GET | `/admin/learning/material-diagnose?materialId=` | 单资料诊断 |
|
|||
|
|
| GET | `/admin/learning/anomalies` | 异常数据查询 |
|
|||
|
|
| GET | `/admin/learning/sessions/interrupted` | 中断 session 列表 |
|
|||
|
|
| GET | `/admin/learning/temporary-materials` | 临时资料列表 |
|
|||
|
|
|
|||
|
|
### 操作接口
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 说明 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| POST | `/admin/learning/reading-events/:id/reprocess` | 重处理单事件 |
|
|||
|
|
| POST | `/admin/learning/reading-events/reprocess-batch` | 批量重处理 |
|
|||
|
|
| POST | `/admin/learning/recalculate` | 重算学习数据 |
|
|||
|
|
| GET | `/admin/learning/export` | 导出学习数据 |
|
|||
|
|
| PUT | `/admin/learning/event-config` | 事件处理配置 |
|
|||
|
|
|
|||
|
|
## 3. 分页/筛选/排序规范
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface PaginationQuery {
|
|||
|
|
page?: number; // default 1
|
|||
|
|
limit?: number; // default 20, max 100
|
|||
|
|
sortBy?: string; // 排序字段
|
|||
|
|
order?: 'asc' | 'desc'; // default desc
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
interface EventFilter extends PaginationQuery {
|
|||
|
|
userId?: string;
|
|||
|
|
materialId?: string;
|
|||
|
|
readingTargetType?: string;
|
|||
|
|
eventType?: string;
|
|||
|
|
status?: string;
|
|||
|
|
startDate?: string;
|
|||
|
|
endDate?: string;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. Dashboard 数据结构
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
interface AdminDashboard {
|
|||
|
|
overview: {
|
|||
|
|
totalEvents: number;
|
|||
|
|
todayEvents: number;
|
|||
|
|
failedEvents: number;
|
|||
|
|
duplicateEvents: number;
|
|||
|
|
};
|
|||
|
|
sessions: {
|
|||
|
|
active: number;
|
|||
|
|
interrupted: number;
|
|||
|
|
completed: number;
|
|||
|
|
total: number;
|
|||
|
|
};
|
|||
|
|
users: {
|
|||
|
|
activeToday: number;
|
|||
|
|
totalWithEvents: number;
|
|||
|
|
};
|
|||
|
|
materials: {
|
|||
|
|
totalRead: number;
|
|||
|
|
totalMarkedRead: number;
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 5. 审计日志
|
|||
|
|
|
|||
|
|
每个管理操作记录：
|
|||
|
|
- `action`: 操作类型 (READ/WRITE/DELETE/EXPORT)
|
|||
|
|
- `resource`: 资源路径
|
|||
|
|
- `adminId`: 操作人
|
|||
|
|
- `timestamp`: 时间
|
|||
|
|
- `details`: 详情（查询参数/操作结果摘要）
|
|||
|
|
|
|||
|
|
## 6. 错误码
|
|||
|
|
|
|||
|
|
| 码 | 含义 |
|
|||
|
|
|----|------|
|
|||
|
|
| `ADMIN_ACCESS_DENIED` | 非管理员 |
|
|||
|
|
| `INVALID_DATE_RANGE` | 日期范围无效 |
|
|||
|
|
| `EXPORT_LIMIT_EXCEEDED` | 导出超限 |
|
|||
|
|
| `RECALCULATE_IN_PROGRESS` | 重算进行中 |
|