# Admin 学习信息运维模块 总设计

> ADMIN-INFO-000 | v1.0 | 2026-06-12

## 1. 概述

Admin 学习信息运维模块是运营人员查看、诊断、修复学习信息数据的 Web 管理后台。本里程碑只做 Admin 前端，所有数据通过 API-ADMIN-INFO 接口获取，mock 只能用于开发调试，不得作为最终验收。

## 2. 职责边界

| 层 | 负责 | 不负责 |
|----|------|--------|
| **Admin 前端** | 页面渲染、筛选、分页、图表、操作按钮 | 数据聚合、权限校验、落库 |
| **API-ADMIN-INFO** | 数据查询、权限校验、分页、导出、重算 | 前端 UI |
| **业务 API** | 事件采集、分析、题目/卡片生成 | Admin 查询 |

## 3. 技术栈

- React 19 + TypeScript
- Vite (build)
- Ant Design 5 + @ant-design/pro-components (ProTable)
- @tanstack/react-query (data fetching)
- ECharts (charts)
- react-router-dom v6 (routing)
- TailwindCSS 4 (utilities)

## 4. 页面路由结构

```
/admin/learning/
├── dashboard                    # ADMIN-INFO-001
├── events
│   ├── list                     # ADMIN-INFO-002 (ReadingEvent)
│   ├── :eventId                 # ADMIN-INFO-002 (详情)
│   ├── failed                   # ADMIN-INFO-003 (failed/warning/duplicate)
│   └── replay                   # ADMIN-INFO-004 (重放)
├── sessions
│   ├── list                     # ADMIN-INFO-005
│   ├── :sessionId               # ADMIN-INFO-005 (详情)
│   └── interrupted              # ADMIN-INFO-013
├── progress
│   └── list                     # ADMIN-INFO-006
├── activity
│   ├── daily                    # ADMIN-INFO-007 (日历/热力图)
│   └── timeline/:userId         # ADMIN-INFO-009 (用户时间线)
├── records
│   └── list                     # ADMIN-INFO-008
├── export                       # P1
└── audit                        # P1
```

## 5. API 端点映射

| 页面 | Issue | API 端点 | 方法 |
|------|-------|----------|------|
| Dashboard | 001 | `/admin/learning/dashboard` | GET |
| ReadingEvent 列表 | 002 | `/admin/learning/events` | GET |
| ReadingEvent 详情 | 002 | `/admin/learning/events/:id` | GET |
| failed/warning/duplicate | 003 | `/admin/learning/events?status=failed&status=warning&status=duplicate` | GET |
| 重放/修复 | 004 | `/admin/learning/events/:id/replay` | POST |
| Session 列表 | 005 | `/admin/learning/sessions` | GET |
| Session 详情 | 005 | `/admin/learning/sessions/:id` | GET |
| MaterialProgress | 006 | `/admin/learning/progress` | GET |
| DailyActivity | 007 | `/admin/learning/activity` | GET |
| LearningRecord | 008 | `/admin/learning/records` | GET |
| 用户时间线 | 009 | `/admin/learning/activity?userId=...` | GET |
| interrupted session | 013 | `/admin/learning/sessions?status=interrupted` | GET |
| TemporaryReadingMaterial | P1 | `/admin/learning/temporary-materials` | GET |

> **TemporaryReadingMaterial**（P1）：临时文件阅读数据管理，包括列表、详情、过期清理。API 路径待 API-ADMIN-INFO-014 定义后确认。

所有接口统一前缀 `/admin/learning/`，查询参数支持 `page`/`pageSize`/`userId`/`materialId`/`eventType`/`status`/`startDate`/`endDate`/`knowledgeBaseId`。

## 6. API Service 层

```
src/services/learningAdmin.ts
├── getDashboard(params) → DashboardDTO
├── getEvents(params) → PaginatedResponse<ReadingEventDTO>
├── getEventDetail(id) → ReadingEventDTO
├── replayEvent(id) → ReplayResultDTO
├── getSessions(params) → PaginatedResponse<SessionDTO>
├── getSessionDetail(id) → SessionDTO
├── getProgressList(params) → PaginatedResponse<MaterialProgressDTO>
├── getDailyActivity(params) → DailyActivityDTO[]
├── getRecords(params) → PaginatedResponse<LearningRecordDTO>
├── getUserTimeline(userId, params) → TimelineDTO[]
└── getInterruptedSessions(params) → PaginatedResponse<SessionDTO>
```

统一使用 `@tanstack/react-query` 管理缓存和加载状态。所有请求通过 `http-client.ts` 发送，自动携带 admin token。

## 7. 类型系统

```
src/types/admin.ts (扩展)
├── ReadingEventDTO
├── SessionDTO
├── MaterialProgressDTO
├── DailyActivityDTO
├── LearningRecordDTO
├── TimelineDTO
├── DashboardDTO
├── PaginatedResponse<T>
├── EventFilterParams
├── SessionFilterParams
```

DTO 字段与 API-ADMIN-INFO 响应保持一致，使用 camelCase。

## 8. P0 / P1 / P2 范围

### P0（11 issues — 当前里程碑）

| Issue | 页面 | 核心功能 |
|-------|------|---------|
| ADMIN-INFO-000 | — | 总体设计（本文档） |
| ADMIN-INFO-001 | Dashboard | 全局统计、时间范围、knowledgeBaseId 筛选 |
| ADMIN-INFO-002 | ReadingEvent 列表/详情 | 分页、筛选（userId/materialId/eventType/status/时间） |
| ADMIN-INFO-003 | 异常事件视图 | failed/warning/duplicate 列表 + 筛选 |
| ADMIN-INFO-004 | 重放/修复 | 单事件重放、批量操作 |
| ADMIN-INFO-005 | Session 列表/详情 | 分页、按用户/资料/状态筛选 |
| ADMIN-INFO-006 | MaterialProgress 列表 | 分页、按用户/资料筛选 |
| ADMIN-INFO-007 | DailyActivity 热力图 | 日历视图、按用户/日期筛选 |
| ADMIN-INFO-008 | LearningRecord 列表 | 分页、按类型/用户筛选 |
| ADMIN-INFO-009 | 用户时间线 | 单用户活动时间线 |
| ADMIN-INFO-013 | interrupted session | active/interrupted session 列表 + 操作 |

### P1（本里程碑之后）

- 单用户学习数据诊断页
- 单资料学习数据诊断页
- 异常数据筛选与跨表诊断
- 学习数据重算工具
- 临时文件阅读数据管理（TemporaryReadingMaterial — 对应 Issue §11，API 端点待 API-ADMIN-INFO-014 定义）
- 学习事件处理配置
- 学习数据导出
- 权限与审计日志

### P2（最后）

- Admin 页面/接口测试
- 后台使用文档
- 全局搜索

## 9. 通用页面模式

每个 P0 列表页统一使用 Ant Design ProTable：

```tsx
// 通用模式
<ProTable<RecordType>
  columns={columns}
  request={async (params, sort, filter) => {
    const { data, total } = await api.getXxx({ ...params, ...filter });
    return { data, success: true, total };
  }}
  rowKey="id"
  search={{ labelWidth: 'auto' }}
  pagination={{ defaultPageSize: 20 }}
  dateFormatter="string"
/>
```

详情页统一使用 Ant Design Descriptions + 关联数据子表。

## 10. 筛选器公共组件

```
src/components/learning/
├── EventStatusFilter.tsx      # ReadingEvent status 筛选
├── EventTypeFilter.tsx        # eventType 筛选
├── DateRangeFilter.tsx        # 时间范围筛选
├── UserMaterialFilter.tsx     # userId / materialId 筛选
└── KnowledgeBaseFilter.tsx    # knowledgeBaseId 筛选
```

## 11. 依赖说明

- **阻塞项**: 所有 P0 Issue 标记 `blocked-by:api-admin-info`，API 接口就绪后才能对接
- **开发策略**: 先搭建页面框架 + TypeScript 类型 + ProTable 列定义，使用 `mock-data.ts` 做开发占位，API 就绪后切换 `learningAdmin.ts` 的真实调用
- **不使用 mock 验收**: mock 仅限 `npm run dev` 开发阶段，CR 和上线必须以真实 API 数据为准

## 12. 路由注册

在 `src/routes/index.tsx` 中注册学习信息路由组：

```tsx
{
  path: '/admin/learning',
  element: <LearningLayout />,
  children: [
    { index: true, element: <LearningDashboard /> },
    { path: 'events', element: <EventList /> },
    { path: 'events/:eventId', element: <EventDetail /> },
    { path: 'events/failed', element: <FailedEvents /> },
    { path: 'sessions', element: <SessionList /> },
    { path: 'sessions/:sessionId', element: <SessionDetail /> },
    { path: 'progress', element: <ProgressList /> },
    { path: 'activity', element: <DailyActivity /> },
    { path: 'records', element: <RecordList /> },
  ]
}
```

## 13. 开发顺序

000（本文档）→ 搭建路由框架 + 类型定义 → 001 Dashboard → 002 Events → 003 Failed → 004 Replay → 005 Sessions → 006 Progress → 007 Activity → 008 Records → 009 Timeline → 013 Interrupted

## 14. 验收清单

- [x] 输出 docs/admin-learning-info-ops-design.md
- [x] 明确本里程碑只做 Admin 前端
- [x] 明确依赖 API-ADMIN-INFO
- [x] 明确不使用 mock 作为最终验收
- [x] 明确页面路由和 tab 结构
- [x] 明确每个页面对应的 API
- [x] 明确 P0/P1/P2 范围