ai-learning-platform/docs/admin-system-plan.md

# 管理后台系统增强方案

## 概述

宇之然 AI 管理后台当前已有基础框架（用户、课程、提示词、内容、工具、订单、企业版、评论管理），缺少以下核心模块：

1. **数据统计分析/图表**
2. **系统设置/配置**
3. **运营管理（Banner、推送）**
4. **权限管理（角色、菜单）**

## 实施方案

### 1. 数据统计分析/图表

#### 前端实现
- 创建 `/admin/analytics` 页面
- 使用 `recharts` 或 `chart.js` 渲染图表
- 时间范围选择器（今日/本周/本月/自定义）

#### 后端 API
- `GET /api/v1/admin/analytics/overview` - 核心指标汇总
- `GET /api/v1/admin/analytics/users` - 用户增长趋势
- `GET /api/v1/admin/analytics/revenue` - 收入统计
- `GET /api/v1/admin/analytics/activities` - 用户活跃度

#### 展示指标
| 指标 | 说明 |
|------|------|
| 总用户数 | 累计注册用户 |
| 活跃用户 | 7日内活跃 |
| 新增用户 | 日/周/月新增 |
| 订单收入 | 日/周/月收入 |
| 订单数 | 日/周/月订单 |
| 转化率 | 付费用户占比 |
| 课程学习次数 | 累计学习次数 |
| 对话次数 | AI 沙盒对话次数 |

---

### 2. 权限管理（角色、菜单）

#### 数据库设计
```prisma
model AdminRole {
  id          String   @id @default(cuid())
  name        String   @unique // 角色名：super_admin, admin, editor, viewer
  description String?
  permissions Json     // ["users:read", "users:write", "orders:read", ...]
  status      String   @default("ACTIVE") // ACTIVE, DISABLED
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  admins      AdminUser[]
}

model AdminUser {
  id          String     @id @default(cuid())
  username    String     @unique
  passwordHash String
  nickname    String?
  roleId      String
  role        AdminRole   @relation(fields: [roleId], references: [id])
  status      String     @default("ACTIVE")
  lastLoginAt DateTime?
  createdAt   DateTime   @default(now())
  updatedAt   DateTime   @updatedAt
}
```

#### 功能清单
| 功能 | 说明 |
|------|------|
| 角色列表 | 查看所有角色 |
| 创建角色 | 新建角色，设置权限 |
| 编辑角色 | 修改角色名称、权限 |
| 删除角色 | 软删除角色 |
| 管理员列表 | 查看所有管理员 |
| 创建管理员 | 新建管理员，分配角色 |
| 编辑管理员 | 修改管理员信息、角色 |
| 禁用管理员 | 禁用/启用管理员 |

#### 后端 API
- `GET /api/v1/admin/roles` - 角色列表
- `POST /api/v1/admin/roles` - 创建角色
- `PUT /api/v1/admin/roles/:id` - 更新角色
- `DELETE /api/v1/admin/roles/:id` - 删除角色
- `GET /api/v1/admin/admins` - 管理员列表
- `POST /api/v1/admin/admins` - 创建管理员
- `PUT /api/v1/admin/admins/:id` - 更新管理员
- `DELETE /api/v1/admin/admins/:id` - 删除管理员
- `GET /api/v1/admin/permissions` - 所有权限项

#### 前端页面
- `/admin/settings/roles` - 角色管理
- `/admin/settings/admins` - 管理员列表
- `/admin/settings/permissions` - 权限配置

---

### 3. 系统设置/配置

#### 配置项分类
| 分类 | 配置项 |
|------|--------|
| 站点设置 | 网站名称、LOGO、备案号、联系方式 |
| AI 配置 | 默认模型、可用模型列表、API 密钥 |
| 会员设置 | 免费版配额、会员价格、会员权益 |
| 短信/邮件 | 验证码模板、通知模板 |
| 其他 | 维护模式、调试模式 |

#### 数据库设计
```prisma
model SystemConfig {
  id          String   @id @default(cuid())
  category    String   // site, ai, member, notification, other
  key         String   @unique // site_name, ai_models, member_prices...
  value       String   // JSON 格式存储
  description String?
  status      String   @default("ACTIVE")
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}
```

#### 后端 API
- `GET /api/v1/admin/config` - 获取所有配置
- `GET /api/v1/admin/config/:category` - 获取分类配置
- `PUT /api/v1/admin/config/:key` - 更新配置
- `POST /api/v1/admin/config/batch` - 批量更新

#### 前端页面
- `/admin/settings/general` - 通用设置
- `/admin/settings/ai` - AI 配置
- `/admin/settings/member` - 会员设置
- `/admin/settings/notification` - 通知设置

---

### 4. 运营管理

#### 4.1 Banner 管理
```prisma
model Banner {
  id          String   @id @default(cuid())
  title       String
  image       String   // 图片 URL
  link        String?  // 跳转链接
  position    String   // home, skills, courses, community...
  sortOrder   Int      @default(0)
  status      String   @default("DRAFT") // DRAFT, PUBLISHED, DISABLED
  startAt     DateTime?
  endAt       DateTime?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}
```

#### 4.2 推送通知
```prisma
model SystemNotification {
  id          String   @id @default(cuid())
  title       String
  content     String
  type        String   // system, promo, update
  target      String   // all, specific_users, specific_roles
  targetIds   String?  // 用户ID列表或角色ID列表
  status      String   @default("DRAFT")
  scheduledAt DateTime? // 定时发送
  sentAt      DateTime?
  createdAt   DateTime @default(now())
}
```

#### 后端 API
- `GET /api/v1/admin/banners` - Banner 列表
- `POST /api/v1/admin/banners` - 创建 Banner
- `PUT /api/v1/admin/banners/:id` - 更新 Banner
- `DELETE /api/v1/admin/banners/:id` - 删除 Banner
- `GET /api/v1/admin/notifications` - 推送列表
- `POST /api/v1/admin/notifications` - 发送推送
- `DELETE /api/v1/admin/notifications/:id` - 删除推送

#### 前端页面
- `/admin/operations/banners` - Banner 管理
- `/admin/operations/notifications` - 推送管理
- `/admin/operations/push` - 发送推送

---

## 开发优先级

| 优先级 | 模块 | 预计工作量 |
|--------|------|-----------|
| P0 | 数据统计分析 | 2-3 小时 |
| P1 | 权限管理 | 3-4 小时 |
| P2 | 系统设置 | 2-3 小时 |
| P3 | Banner 管理 | 1-2 小时 |
| P4 | 推送通知 | 2-3 小时 |

## 技术选型

- 图表库：`recharts` (React 友好)
- 表单：复用现有 shadcn/ui
- 权限控制：后端 Guard + 前端路由守卫
- 配置存储：数据库 + 缓存

---

## 进度追踪

- [ ] 数据统计分析/图表
- [ ] 权限管理（角色、菜单）
- [ ] 系统设置/配置
- [ ] Banner 管理
- [ ] 推送通知