WangDL
277c375f82
All checks were successful
Deploy API Server / build-and-deploy (push) Successful in 20s
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
208 lines
6.5 KiB
Markdown
208 lines
6.5 KiB
Markdown
# AI Study Product API
|
||
|
||
AI 学习产品的后端 API 服务（v0.1），基于 NestJS + TypeScript 构建。
|
||
|
||
## 功能模块
|
||
|
||
| 模块 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| health | 健康检查 | ✅ |
|
||
| auth | 用户认证（dev-login / Apple / 刷新 / 登出） | ✅ |
|
||
| users | 用户管理 | ✅ |
|
||
| knowledge-base | 知识库 CRUD → Prisma | ✅ |
|
||
| knowledge-items | 知识点 CRUD → Prisma | ✅ |
|
||
| ai | AI 三层架构（Provider → Gateway → Workflow）15 文件 | ✅ |
|
||
| ai-analysis | AI 分析结果查询 → Prisma | ✅ |
|
||
| active-recall | 主动回忆（提交答案触发分析）→ Prisma | ✅ |
|
||
| learning-session | 学习会话 → Prisma | ✅ |
|
||
| review | 间隔重复复习 → Prisma | ✅ |
|
||
| focus-items | 待巩固项 → Prisma | ✅ |
|
||
| learning-activity | 学习活跃统计 → Prisma | ✅ |
|
||
| document-import | 文档导入 → Prisma | ✅ |
|
||
| notifications | 通知 → Prisma | ✅ |
|
||
| feedback | 用户反馈 → Prisma | ✅ |
|
||
| waitlist | 等待名单 → Prisma | ✅ |
|
||
|
||
## 快速开始
|
||
|
||
```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 后，Swagger UI 和 OpenAPI JSON 均受 **Basic Auth** 保护：
|
||
|
||
- **Swagger UI**: https://api.longde.cloud/api-docs
|
||
- **OpenAPI JSON**: https://api.longde.cloud/api-docs-json
|
||
|
||
Apifox 导入时在 URL 中带上认证：
|
||
`https://admin:your_password@api.longde.cloud/api-docs-json`
|
||
|
||
配置环境变量：
|
||
|
||
```env
|
||
NODE_ENV=production
|
||
ENABLE_SWAGGER=true
|
||
SWAGGER_USER=your_admin_username
|
||
SWAGGER_PASSWORD=your_secure_password
|
||
```
|
||
|
||
如需临时开启内网访问，配置同上并设置强密码。
|
||
|
||
## 环境变量
|
||
|
||
复制 `.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-recall` - AI 主动回忆分析
|
||
- `GET /ai/models` - 查看模型分流配置
|
||
- `POST /ai-analysis` - 提交 AI 分析
|
||
- `GET /ai-analysis/:id` - 获取分析结果
|
||
|
||
### 主动回忆
|
||
- `GET /active-recalls` - 获取问题列表
|
||
- `POST /active-recalls/:id/submit` - 提交回答（自动触发 AI 分析）
|
||
|
||
### 复习
|
||
- `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 # 根模块
|
||
├── config/ # 配置（app / jwt / ai / database / redis）
|
||
├── common/ # 公共（guard / decorator / filter / pipe）
|
||
├── infrastructure/ # 基础设施（Prisma / Redis / Storage / Logger / Queue）
|
||
│ └── ai/ # ❌ 已删除，迁至 modules/ai/
|
||
└── modules/
|
||
├── auth/ # 认证模块（dev-login / Apple / refresh / logout）
|
||
├── users/ # 用户模块
|
||
├── knowledge-base/ # 知识库模块
|
||
├── knowledge-items/ # 知识点模块
|
||
├── active-recall/ # 主动回忆模块（提交答案 → 触发 AI 分析）
|
||
├── ai/ # ✅ 三层 AI 架构（Provider → Gateway → Workflow）
|
||
│ ├── gateway/ # AiGatewayService（选模型、记日志、JSON容错、超时重试）
|
||
│ ├── providers/ # DeepSeek / MiniMax / Mock
|
||
│ ├── prompts/ # System Prompt + Zod Schema
|
||
│ ├── usage/ # UsageLog + CostCalculator
|
||
│ └── workflows/ # ActiveRecallAnalysisWorkflow
|
||
├── ai-analysis/ # AI 分析结果查询
|
||
├── review/ # 复习模块
|
||
├── learning-session/ # 学习会话
|
||
├── learning-activity/ # 学习活跃
|
||
├── focus-items/ # 待巩固项
|
||
├── document-import/ # 文档导入
|
||
├── notifications/ # 通知
|
||
├── feedback/ # 用户反馈
|
||
├── waitlist/ # 等待名单
|
||
└── system/ # 系统状态
|
||
```
|
||
|
||
## 后续规划
|
||
|
||
- [x] 接入真实 AI API（DeepSeek + MiniMax 三层架构）
|
||
- [x] JWT 认证中间件
|
||
- [x] 数据库持久化（Prisma + MySQL）
|
||
- [x] 12 个业务 Repository 从内存 Map 迁到 Prisma
|
||
- [x] 全局 JwtAuthGuard
|
||
- [x] Swagger 端点 Basic Auth 保护
|
||
- [ ] 更多 AI Workflow（知识导入、费曼分析、复习卡片生成）
|
||
- [ ] AI 联调 + Prompt 调优
|
||
- [ ] 添加 Redis 缓存
|
||
- [ ] iOS 集成 |