4414f9cc55
Some checks failed
Deploy API Server / build-and-deploy (push) Failing after 20s
- Admin dashboard + query endpoints (reading-events/sessions/progress/daily-activities/records) - Diagnostic (user-timeline/diagnose/material-diagnose/anomalies/temporary-materials) - Operations (recalculate/export) - Admin API design doc Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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` | 重算进行中 |
|