admin-projects/docs/admin-learning-info-ops-design.md

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：

// 通用模式
<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 中注册学习信息路由组：

{
  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. 验收清单

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