AI Study Product API

AI 学习产品的后端 API 服务（v0.1），基于 NestJS + TypeScript 构建。

功能模块

模块	说明	状态
health	健康检查	✅
auth	用户认证（登录/注册/Token刷新）	✅
users	用户管理	✅
knowledge	知识库/文章	✅
learning	学习路径/课程/进度	✅
ai	AI 分析与对话（Mock）	✅
review	间隔重复复习任务	✅
feedback	用户反馈	✅
waitlist	等待名单	✅

快速开始

# 安装依赖
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，配置环境变量：

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 并配置：

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 集成文档