WangDL
bd44b7e138
- NestJS + TypeScript 后端 API - 用户认证 (auth) - 用户管理 (users) - 学习路径与课程 (learning) - AI 分析与对话 (ai) - 用户反馈 (feedback) - 等待名单 (waitlist) - 知识库 (knowledge) - Swagger API 文档（中文、访问控制） - Basic Auth 保护生产环境文档
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 集成文档 |