wangdl
a2cb0681d9
Some checks failed
Deploy Admin Frontend / build-and-deploy (push) Failing after 8s
- Add userId filter input to LearningRecord list - Add click-to-view detail Drawer with full record info - Fix occurredAt formatting to use dayjs - Add scroll for narrow displays Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
219 lines
8.3 KiB
Markdown
219 lines
8.3 KiB
Markdown
# 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 范围
|