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