175 lines
4.4 KiB
Markdown
175 lines
4.4 KiB
Markdown
|
# AI Study Product API
|
|||
|
|
|
|||
|
|
AI 学习产品的后端 API 服务（v0.1），基于 NestJS + TypeScript 构建。
|
|||
|
|
|
|||
|
|
## 功能模块
|
|||
|
|
|
|||
|
|
| 模块 | 说明 | 状态 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| health | 健康检查 | ✅ |
|
|||
|
|
| auth | 用户认证（登录/注册/Token刷新） | ✅ |
|
|||
|
|
| users | 用户管理 | ✅ |
|
|||
|
|
| knowledge | 知识库/文章 | ✅ |
|
|||
|
|
| learning | 学习路径/课程/进度 | ✅ |
|
|||
|
|
| ai | AI 分析与对话（Mock） | ✅ |
|
|||
|
|
| review | 间隔重复复习任务 | ✅ |
|
|||
|
|
| feedback | 用户反馈 | ✅ |
|
|||
|
|
| waitlist | 等待名单 | ✅ |
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
# 安装依赖
|
|||
|
|
npm install
|
|||
|
|
|
|||
|
|
# 开发模式
|
|||
|
|
npm run start:dev
|
|||
|
|
|
|||
|
|
# 生产模式
|
|||
|
|
npm run build && npm run start:prod
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 接口文档
|
|||
|
|
|
|||
|
|
### 本地开发环境
|
|||
|
|
|
|||
|
|
启动服务后，访问：
|
|||
|
|
|
|||
|
|
- **Swagger UI**: http://localhost:3000/api-docs
|
|||
|
|
- **OpenAPI JSON**: http://localhost:3000/api-docs-json
|
|||
|
|
|
|||
|
|
本地开发环境默认启用 Swagger，无需认证。
|
|||
|
|
|
|||
|
|
### 服务器内测环境
|
|||
|
|
|
|||
|
|
如果需要在非本地环境启用 Swagger，配置环境变量：
|
|||
|
|
|
|||
|
|
```env
|
|||
|
|
NODE_ENV=production
|
|||
|
|
ENABLE_SWAGGER=true
|
|||
|
|
SWAGGER_USER=your_admin_username
|
|||
|
|
SWAGGER_PASSWORD=your_secure_password
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
访问时需要输入账号密码：
|
|||
|
|
|
|||
|
|
- **Swagger UI**: https://your-domain.com/api-docs
|
|||
|
|
- **OpenAPI JSON**: https://your-domain.com/api-docs-json
|
|||
|
|
|
|||
|
|
### 正式生产环境
|
|||
|
|
|
|||
|
|
默认关闭 Swagger，确保 API 结构不会公开暴露。
|
|||
|
|
|
|||
|
|
如需临时开启内网访问，配置同上并设置强密码。
|
|||
|
|
|
|||
|
|
## 环境变量
|
|||
|
|
|
|||
|
|
复制 `.env.example` 为 `.env` 并配置：
|
|||
|
|
|
|||
|
|
```env
|
|||
|
|
PORT=3000
|
|||
|
|
DATABASE_URL="mysql://user:password@localhost:3306/ai_study"
|
|||
|
|
REDIS_HOST=localhost
|
|||
|
|
REDIS_PORT=6379
|
|||
|
|
AI_PROVIDER=mock
|
|||
|
|
AI_API_KEY=
|
|||
|
|
AI_BASE_URL=
|
|||
|
|
JWT_SECRET=change_me_in_production
|
|||
|
|
|
|||
|
|
NODE_ENV=development
|
|||
|
|
ENABLE_SWAGGER=true
|
|||
|
|
SWAGGER_USER=admin
|
|||
|
|
SWAGGER_PASSWORD=change_me
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| 变量 | 说明 | 默认值 |
|
|||
|
|
|------|------|--------|
|
|||
|
|
| PORT | 服务端口 | 3000 |
|
|||
|
|
| NODE_ENV | 运行环境 | development |
|
|||
|
|
| ENABLE_SWAGGER | 是否启用 Swagger | true (开发) / false (生产) |
|
|||
|
|
| SWAGGER_USER | Swagger 用户名 | admin |
|
|||
|
|
| SWAGGER_PASSWORD | Swagger 密码 | change_me |
|
|||
|
|
|
|||
|
|
## API 端点概览
|
|||
|
|
|
|||
|
|
### 健康检查
|
|||
|
|
- `GET /` - 服务健康检查
|
|||
|
|
|
|||
|
|
### 认证
|
|||
|
|
- `POST /auth/login` - 用户登录
|
|||
|
|
- `POST /auth/register` - 用户注册
|
|||
|
|
- `POST /auth/refresh` - 刷新 Token
|
|||
|
|
- `POST /auth/logout` - 退出登录
|
|||
|
|
|
|||
|
|
### 用户
|
|||
|
|
- `POST /users` - 创建用户
|
|||
|
|
- `GET /users/:id` - 获取用户信息
|
|||
|
|
- `GET /users/:id/profile` - 获取用户详情（含统计数据）
|
|||
|
|
- `PATCH /users/:id` - 更新用户信息
|
|||
|
|
- `GET /users` - 用户列表
|
|||
|
|
|
|||
|
|
### 知识库
|
|||
|
|
- `GET /knowledge/categories` - 获取分类
|
|||
|
|
- `GET /knowledge/articles` - 获取文章列表
|
|||
|
|
- `GET /knowledge/articles/:id` - 获取文章详情
|
|||
|
|
|
|||
|
|
### 学习
|
|||
|
|
- `GET /learning/paths` - 获取所有学习路径
|
|||
|
|
- `GET /learning/paths/:id` - 获取学习路径详情
|
|||
|
|
- `GET /learning/paths/:id/courses` - 获取课程列表
|
|||
|
|
- `GET /learning/courses/:id` - 获取课程详情
|
|||
|
|
- `GET /learning/lessons/:id` - 获取课时详情
|
|||
|
|
- `GET /learning/records?userId=` - 获取用户学习记录
|
|||
|
|
- `PATCH /learning/progress` - 更新学习进度
|
|||
|
|
|
|||
|
|
### AI
|
|||
|
|
- `POST /ai/analyze` - AI 学习分析（弱点/进度/推荐）
|
|||
|
|
- `POST /ai/chat` - AI 对话
|
|||
|
|
- `GET /ai/sessions?userId=` - 获取对话历史
|
|||
|
|
- `GET /ai/sessions/:sessionId` - 获取指定会话
|
|||
|
|
|
|||
|
|
### 复习
|
|||
|
|
- `GET /learning/review?userId=` - 获取复习任务
|
|||
|
|
- `POST /learning/review` - 创建复习任务
|
|||
|
|
|
|||
|
|
### 反馈
|
|||
|
|
- `POST /feedback` - 提交反馈
|
|||
|
|
- `GET /feedback` - 获取反馈列表
|
|||
|
|
- `GET /feedback/stats` - 反馈统计
|
|||
|
|
- `PATCH /feedback/:id/status` - 更新反馈状态
|
|||
|
|
|
|||
|
|
### 等待名单
|
|||
|
|
- `POST /waitlist` - 加入等待名单
|
|||
|
|
- `GET /waitlist` - 获取所有报名
|
|||
|
|
- `GET /waitlist/stats` - 报名统计
|
|||
|
|
|
|||
|
|
## 技术栈
|
|||
|
|
|
|||
|
|
- NestJS 11.x
|
|||
|
|
- TypeScript
|
|||
|
|
- class-validator / class-transformer
|
|||
|
|
- @nestjs/swagger
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
src/
|
|||
|
|
├── main.ts # 入口
|
|||
|
|
├── app.module.ts # 根模块
|
|||
|
|
├── auth/ # 认证模块
|
|||
|
|
├── users/ # 用户模块
|
|||
|
|
├── learning/ # 学习模块
|
|||
|
|
├── ai/ # AI 模块
|
|||
|
|
├── feedback/ # 反馈模块
|
|||
|
|
├── waitlist/ # 等待名单模块
|
|||
|
|
├── knowledge/ # 知识库模块
|
|||
|
|
└── ...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 后续规划
|
|||
|
|
|
|||
|
|
- [ ] 接入真实 AI API（OpenAI / Claude）
|
|||
|
|
- [ ] 添加数据库持久化
|
|||
|
|
- [ ] 实现 JWT 认证中间件
|
|||
|
|
- [ ] 添加 Redis 缓存
|
|||
|
|
- [ ] iOS SDK 集成文档
|