Wang Zhuoxuan
87a1f39d51
- CLAUDE.md: 更新 Current Status、Architecture 树、Auth flow 说明 - dev-spec.md: 更新状态为 Phase 3 已完成 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
418 lines
17 KiB
Markdown
418 lines
17 KiB
Markdown
# duoqi-admin 开发规格
|
||
|
||
> 多奇管理后台 — 工程实施指南
|
||
> 本文档为 duoqi-admin 库的自包含开发参考。产品设计细节见 [共享设计文档](../docs/specs/shared/)。
|
||
|
||
---
|
||
|
||
## 一、库职责与定位
|
||
|
||
| 维度 | 内容 |
|
||
|------|------|
|
||
| **库** | `duoqi-admin` |
|
||
| **定位** | 多奇内部管理后台，面向开发者/运营人员 |
|
||
| **产品阶段** | Phase 1 起持续迭代（题库管理从 Phase 1 即需要） |
|
||
| **核心目标** | 题库内容管理、用户管理、数据看板、系统配置 |
|
||
| **用户** | 开发者本人（Phase 1-2），后续可能扩展至运营团队 |
|
||
|
||
### 在架构中的位置
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ duoqi-harmony │ duoqi-flutter │ duoqi-web │ ← 用户端
|
||
└────────┬────────┴────────┬─────────┴────────┬────────┘
|
||
└─────────────────┼───────────────────┘
|
||
│
|
||
duoqi-api (REST API)
|
||
├── /v1/* 用户端 API
|
||
└── /admin/* 管理端 API ← 新增
|
||
│
|
||
┌─────────────────┼───────────────────┐
|
||
│ │ │
|
||
阿里云 RDS MySQL 阿里云 OSS PostHog + ClickHouse
|
||
│
|
||
duoqi-admin (CSR) ← 本库
|
||
调用 /admin/* API
|
||
```
|
||
|
||
---
|
||
|
||
## 二、技术栈
|
||
|
||
| 层面 | 选型 | 版本 | 理由 |
|
||
|------|------|------|------|
|
||
| 框架 | Vite + React | React 18 | CSR 足够，无需 SSR；比 Next.js 轻量 |
|
||
| 语言 | TypeScript | — | 与项目其他仓库统一 |
|
||
| UI 组件 | shadcn/ui | 源码级复用 | 与 duoqi-web 统一，可定制 |
|
||
| 样式 | Tailwind CSS | — | 与 shadcn/ui 集成 |
|
||
| 数据表格 | TanStack Table | v8 | 管理后台核心组件：排序、筛选、分页 |
|
||
| 表单 | React Hook Form + Zod | — | 表单校验，管理后台大量表单 |
|
||
| HTTP 客户端 | ky / fetch | — | 调用 duoqi-api admin 端点 |
|
||
| 路由 | React Router | v7 | CSR 路由，管理后台够用 |
|
||
| 状态管理 | Zustand | — | 与 duoqi-web 统一 |
|
||
| 图表 | Recharts | — | 数据看板可视化 |
|
||
| 运行方式 | `npm run dev` → `vite dev` | — | 生产构建为静态文件，部署至 CDN/OSS |
|
||
|
||
### 选型理由
|
||
|
||
- **Vite + React 而非 Next.js**：管理后台不需要 SEO、不需要 SSR、不需要 API Routes。Vite 更轻量、构建更快、开发体验更好。duoqi-web 用 Next.js 是因为它是面向用户的 Web 产品；admin 是内部工具，没必要承担 Next.js 的复杂度。
|
||
- **shadcn/ui**：与 duoqi-web 统一组件库，降低学习成本，可按需引入组件。
|
||
- **TanStack Table**：管理后台最核心的交互是数据表格（题库列表、用户列表等）。TanStack Table 是 headless table，配合 shadcn/ui 样式，灵活度最高。
|
||
- **Recharts**：轻量 React 图表库，满足数据看板需求（折线图、柱状图、饼图）。
|
||
|
||
---
|
||
|
||
## 三、项目结构
|
||
|
||
```
|
||
duoqi-admin/
|
||
├── CLAUDE.md # Agent 指引
|
||
├── dev-spec.md # 本文件
|
||
├── src/
|
||
│ ├── main.tsx # 入口
|
||
│ ├── App.tsx # 根组件（路由 + 布局）
|
||
│ ├── routes/ # 页面路由
|
||
│ │ ├── __root.tsx # 根布局（侧边栏 + 顶栏）
|
||
│ │ ├── index.tsx # 首页（数据看板）
|
||
│ │ ├── login.tsx # 管理员登录
|
||
│ │ ├── questions/ # 题库管理
|
||
│ │ │ ├── index.tsx # 题目列表
|
||
│ │ │ ├── new.tsx # 新建题目
|
||
│ │ │ └── $id.tsx # 编辑题目
|
||
│ │ ├── categories/ # 分类管理
|
||
│ │ │ ├── index.tsx # 分类列表
|
||
│ │ │ └── new.tsx # 新建/编辑分类
|
||
│ │ ├── knowledge-cards/ # 知识卡管理
|
||
│ │ │ └── index.tsx # 知识卡列表（关联题目）
|
||
│ │ ├── skill-tree/ # 技能树管理
|
||
│ │ │ └── index.tsx # 章节管理
|
||
│ │ ├── users/ # 用户管理
|
||
│ │ │ └── index.tsx # 用户列表
|
||
│ │ ├── feedback/ # 用户反馈
|
||
│ │ │ └── index.tsx # 反馈列表
|
||
│ │ └── settings/ # 系统设置
|
||
│ │ └── index.tsx # 全局配置
|
||
│ ├── components/
|
||
│ │ ├── ui/ # shadcn/ui 基础组件
|
||
│ │ ├── layout/
|
||
│ │ │ ├── Sidebar.tsx # 侧边栏导航
|
||
│ │ │ ├── Header.tsx # 顶栏（管理员信息）
|
||
│ │ │ └── AdminLayout.tsx # 管理布局容器
|
||
│ │ ├── data-table/ # 数据表格封装
|
||
│ │ │ ├── DataTable.tsx # 通用数据表格
|
||
│ │ │ ├── columns.tsx # 列定义工具
|
||
│ │ │ └── filters.tsx # 筛选器组件
|
||
│ │ ├── question-form/ # 题目编辑表单
|
||
│ │ │ ├── QuestionForm.tsx # 题目表单主组件
|
||
│ │ │ ├── StemEditor.tsx # 题干编辑（支持多媒体）
|
||
│ │ │ └── DistractorEditor.tsx # 干扰项编辑
|
||
│ │ └── charts/ # 图表组件
|
||
│ │ ├── StatsCard.tsx # 统计卡片
|
||
│ │ ├── LineChart.tsx # 折线图
|
||
│ │ └── BarChart.tsx # 柱状图
|
||
│ ├── lib/
|
||
│ │ ├── api-client.ts # duoqi-api HTTP 客户端（admin 端点）
|
||
│ │ ├── auth.ts # admin 认证（token 管理）
|
||
│ │ ├── utils.ts # 工具函数
|
||
│ │ └── constants.ts # 常量（状态枚举、难度等级等）
|
||
│ ├── hooks/
|
||
│ │ ├── use-auth.ts # 认证状态 hook
|
||
│ │ └── use-pagination.ts # 分页 hook
|
||
│ ├── stores/
|
||
│ │ └── auth-store.ts # 认证状态
|
||
│ └── types/
|
||
│ ├── question.ts # 题目相关类型
|
||
│ ├── user.ts # 用户相关类型
|
||
│ ├── category.ts # 分类相关类型
|
||
│ └── api.ts # API 响应类型
|
||
├── public/
|
||
│ └── favicon.svg
|
||
├── package.json
|
||
├── vite.config.ts
|
||
├── tailwind.config.ts
|
||
├── tsconfig.json
|
||
└── .env.example
|
||
```
|
||
|
||
---
|
||
|
||
## 四、功能范围
|
||
|
||
### 4.1 Phase 1 — 基础管理（与 duoqi-api Phase 1 并行）
|
||
|
||
| # | 功能 | 页面 | 说明 |
|
||
|---|------|------|------|
|
||
| 1 | **管理员登录** | `/login` | 环境变量 admin token 认证（Phase 1 只有你一人） |
|
||
| 2 | **题库 CRUD** | `/questions` | 新建/编辑/删除/发布题目，支持批量操作 |
|
||
| 3 | **分类管理** | `/categories` | 管理题库分类（中国历史、经典剧集、相声小品） |
|
||
| 4 | **知识卡编辑** | `/knowledge-cards` | 编辑基础版 + 深度版知识卡 |
|
||
| 5 | **技能树管理** | `/skill-tree` | 管理章节结构、排序、通过条件 |
|
||
| 6 | **数据看板** | `/` | 基础统计：用户数、答题数、正确率、留存 |
|
||
| 7 | **题目状态流转** | 题目编辑页 | 草稿 → 审核中 → 已发布 → 已下架 |
|
||
|
||
### 4.2 Phase 2 — 用户与运营
|
||
|
||
| # | 功能 | 页面 | 说明 |
|
||
|---|------|------|------|
|
||
| 8 | **用户列表** | `/users` | 查看用户、搜索、查看详情 |
|
||
| 9 | **用户反馈** | `/feedback` | 查看用户反馈（👍👎）和意见反馈 |
|
||
| 10 | **订阅管理** | `/users/$id` | 查看/调整用户订阅状态 |
|
||
| 11 | **批量导入** | `/questions` | 从 JSON/CSV 批量导入题目 |
|
||
|
||
### 4.3 Phase 3 — UGC 审核
|
||
|
||
| # | 功能 | 页面 | 说明 |
|
||
|---|------|------|------|
|
||
| 12 | **UGC 审核** | `/questions?source=ugc` | 用户投稿题目审核队列 |
|
||
| 13 | **举报处理** | `/reports` | 处理用户举报内容 |
|
||
| 14 | **运营配置** | `/settings` | 活动配置、推送文案管理 |
|
||
|
||
---
|
||
|
||
## 五、页面设计
|
||
|
||
### 5.1 布局结构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Header — 多奇管理后台 管理员: admin 退出 │
|
||
├──────────┬──────────────────────────────────────┤
|
||
│ │ │
|
||
│ 侧边栏 │ 主内容区 │
|
||
│ │ │
|
||
│ 数据看板 │ 页面标题 + 操作按钮 │
|
||
│ 题库管理 │ ───────────────────── │
|
||
│ 题目 │ │
|
||
│ 分类 │ 数据表格 / 表单 / 图表 │
|
||
│ 知识卡 │ │
|
||
│ 技能树 │ │
|
||
│ 用户管理 │ │
|
||
│ 用户反馈 │ │
|
||
│ 系统设置 │ │
|
||
│ │ │
|
||
└──────────┴──────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.2 页面清单
|
||
|
||
#### 数据看板（首页）
|
||
|
||
| 区域 | 内容 |
|
||
|------|------|
|
||
| 统计卡片 | 总用户数、今日活跃、总答题数、平均正确率 |
|
||
| 折线图 | 近 7/30 天 DAU 趋势 |
|
||
| 柱状图 | 各分类答题量分布 |
|
||
| 排行 | 今日答题最多用户 Top 5 |
|
||
|
||
#### 题目列表
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 数据表格 | 列：ID、题干摘要、分类、难度、状态、创建时间、操作 |
|
||
| 筛选 | 按分类、难度、状态筛选 |
|
||
| 搜索 | 按题干文本搜索 |
|
||
| 批量操作 | 批量发布、批量下架、批量删除 |
|
||
| 排序 | 按创建时间、难度排序 |
|
||
|
||
#### 题目编辑
|
||
|
||
| 区域 | 内容 |
|
||
|------|------|
|
||
| 题干编辑 | 文本输入 + 多媒体上传（图片/音频/视频） |
|
||
| 正确答案 | 文本输入 |
|
||
| 干扰项 | 多行输入，至少 3 个干扰项（出题时随机抽 2 个） |
|
||
| 分类选择 | 下拉选择 |
|
||
| 难度选择 | 1-5 级 |
|
||
| 知识卡编辑 | 基础版摘要（必填）+ 深度版（可选，Pro 专属） |
|
||
| 状态操作 | 保存草稿 / 提交审核 / 发布 |
|
||
|
||
#### 分类管理
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 列表 | ID、名称、slug、题目数量、状态 |
|
||
| 编辑 | 名称、slug、父分类、排序、状态 |
|
||
| 统计 | 每个分类的题目数和答题数据 |
|
||
|
||
---
|
||
|
||
## 六、Admin API 端点（duoqi-api 新增）
|
||
|
||
duoqi-api 需要新增以下 admin 路由，所有路由需要 admin 权限中间件。
|
||
|
||
### 6.1 认证
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/admin/auth/login` | 管理员登录（token 验证） |
|
||
| GET | `/admin/auth/me` | 获取当前管理员信息 |
|
||
|
||
### 6.2 题库管理
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/questions` | 题目列表（分页、筛选、搜索） |
|
||
| GET | `/admin/questions/:id` | 题目详情（含正确答案和干扰项） |
|
||
| POST | `/admin/questions` | 创建题目 |
|
||
| PUT | `/admin/questions/:id` | 更新题目 |
|
||
| DELETE | `/admin/questions/:id` | 删除题目 |
|
||
| PATCH | `/admin/questions/:id/status` | 更新题目状态 |
|
||
| POST | `/admin/questions/batch` | 批量操作（发布/下架/删除） |
|
||
| POST | `/admin/questions/import` | 批量导入题目 |
|
||
|
||
### 6.3 分类管理
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/categories` | 分类列表 |
|
||
| POST | `/admin/categories` | 创建分类 |
|
||
| PUT | `/admin/categories/:id` | 更新分类 |
|
||
| DELETE | `/admin/categories/:id` | 删除分类 |
|
||
|
||
### 6.4 知识卡管理
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/knowledge-cards` | 知识卡列表 |
|
||
| PUT | `/admin/knowledge-cards/:id` | 更新知识卡 |
|
||
|
||
### 6.5 技能树管理
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/skill-tree` | 技能树章节列表 |
|
||
| POST | `/admin/skill-tree` | 创建章节 |
|
||
| PUT | `/admin/skill-tree/:id` | 更新章节 |
|
||
| DELETE | `/admin/skill-tree/:id` | 删除章节 |
|
||
| PATCH | `/admin/skill-tree/reorder` | 调整章节排序 |
|
||
|
||
### 6.6 用户管理
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/users` | 用户列表（分页、搜索） |
|
||
| GET | `/admin/users/:id` | 用户详情 |
|
||
| PATCH | `/admin/users/:id` | 更新用户（封禁、调整 tier） |
|
||
|
||
### 6.7 数据看板
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/stats/overview` | 总览统计（用户数、答题数、正确率） |
|
||
| GET | `/admin/stats/daily` | 每日数据趋势（DAU、答题量） |
|
||
| GET | `/admin/stats/categories` | 各分类答题分布 |
|
||
|
||
### 6.8 用户反馈
|
||
|
||
| 方法 | 路由 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/admin/feedback` | 反馈列表（分页） |
|
||
| PATCH | `/admin/feedback/:id` | 更新反馈状态（已读/已处理） |
|
||
|
||
---
|
||
|
||
## 七、认证方案
|
||
|
||
### Phase 1：静态 Token
|
||
|
||
Phase 1 只有开发者一人使用，认证方案极简：
|
||
|
||
```
|
||
登录流程:
|
||
1. 访问 /login
|
||
2. 输入 admin token（环境变量 ADMIN_TOKEN 的值）
|
||
3. 前端调用 POST /admin/auth/login { token }
|
||
4. 后端验证 token，签发 admin JWT
|
||
5. 前端存储 admin JWT，后续请求携带
|
||
|
||
中间件验证:
|
||
- Authorization: Bearer <admin_jwt>
|
||
- 后端验证 JWT 中的 role: 'admin'
|
||
```
|
||
|
||
### Phase 2+：账号密码（可选）
|
||
|
||
如需多人使用，扩展为用户名 + 密码登录。
|
||
|
||
---
|
||
|
||
## 八、环境变量
|
||
|
||
```env
|
||
# duoqi-api 地址
|
||
VITE_API_BASE_URL=http://localhost:3000
|
||
|
||
# 无需其他环境变量（admin token 通过登录页输入）
|
||
```
|
||
|
||
---
|
||
|
||
## 九、阶段路线图
|
||
|
||
### Phase 1a — 骨架搭建（与 duoqi-api Phase 1a 同步）
|
||
|
||
```
|
||
├── 项目初始化（Vite + React + TypeScript + Tailwind）
|
||
├── shadcn/ui 配置 + 基础组件引入
|
||
├── 路由配置 + 管理布局（侧边栏 + 顶栏）
|
||
├── API 客户端封装 + admin 认证
|
||
├── 登录页
|
||
└── 数据看板骨架（统计卡片 + 占位图表）
|
||
```
|
||
|
||
### Phase 1b — 题库管理核心（与 duoqi-api Phase 1b 同步）
|
||
|
||
```
|
||
├── 题目列表（DataTable + 筛选 + 搜索 + 分页）
|
||
├── 题目编辑表单（题干、正确答案、干扰项、分类、难度）
|
||
├── 知识卡编辑（基础版 + 深度版）
|
||
├── 分类管理（CRUD）
|
||
├── 题目状态流转（草稿 → 审核 → 发布 → 下架）
|
||
└── 批量导入题目（JSON）
|
||
```
|
||
|
||
### Phase 1c — 完善（与 duoqi-api Phase 1c 同步）
|
||
|
||
```
|
||
├── 技能树章节管理
|
||
├── 数据看板真实数据（对接 stats API）
|
||
├── 批量操作（发布/下架/删除）
|
||
└── 用户列表基础版（只读）
|
||
```
|
||
|
||
### Phase 2 — 用户与运营
|
||
|
||
```
|
||
├── 用户详情页（进度、订阅、答题历史）
|
||
├── 用户反馈管理
|
||
├── 订阅状态管理
|
||
└── 导出功能（CSV）
|
||
```
|
||
|
||
### Phase 3 — UGC 审核
|
||
|
||
```
|
||
├── UGC 题目审核队列
|
||
├── 举报处理
|
||
├── 运营配置（活动、推送文案）
|
||
└── 多管理员支持（账号密码登录）
|
||
```
|
||
|
||
---
|
||
|
||
## 十、设计文档索引
|
||
|
||
| 文档 | 路径 | 本库相关章节 |
|
||
|------|------|-------------|
|
||
| 题目格式设计 | [shared/question-format-design.md](../docs/specs/shared/question-format-design.md) | 全文（题目 CRUD 核心数据模型） |
|
||
| 游戏化+变现设计 | [shared/gamification-monetization-design.md](../docs/specs/shared/gamification-monetization-design.md) | §2（技能树结构） |
|
||
| 数据埋点设计 | [shared/analytics-feedback-design.md](../docs/specs/shared/analytics-feedback-design.md) | 数据看板参考 |
|
||
| 产品总纲 | [product-overview.md](../docs/product-overview.md) | 内容策略、阶段路线图 |
|
||
| 技术选型 | [tech-stack.md](../docs/tech-stack.md) | §六（代码库组织） |
|
||
| duoqi-api 开发规格 | [duoqi-api/dev-spec.md](../docs/specs/duoqi-api/dev-spec.md) | §四（数据库设计）、§五（API 设计） |
|
||
|
||
---
|
||
|
||
*创建日期：2026-04-06*
|
||
*状态：Phase 3 已完成（UGC 审核、举报处理、运营配置、多管理员）。所有计划内功能开发完毕。*
|