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

---

## For AI Agents

### 负责 Agent

Backend Agent（`@backend-agent`），配置在 `.claude/agents/backend-agent.md`。

### 关键规则

- 接口变更必须更新 Swagger 装饰器
- 不能私自新增未确认的接口/字段/数据库表
- 数据库变更必须经 Global Agent + 用户确认

### 工作台

`api-server/AI_BACKEND_WORKSPACE.md` — 仅跨模块多 Agent 任务时填写，小任务跳过。

### 禁止

- 不能修改 ios-projects、web-projects
- 不能修改服务器 Nginx/Docker 配置（DevOps Agent 职责）