# 学习信息后台接口 总设计

> 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` | 重算进行中 |