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	✅

快速开始

# 安装依赖
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

配置环境变量：

NODE_ENV=production
ENABLE_SWAGGER=true
SWAGGER_USER=your_admin_username
SWAGGER_PASSWORD=your_secure_password

如需临时开启内网访问，配置同上并设置强密码。

环境变量

复制 .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-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/              # 系统状态

后续规划

• 接入真实 AI API（DeepSeek + MiniMax 三层架构）
• JWT 认证中间件
• 数据库持久化（Prisma + MySQL）
• 12 个业务 Repository 从内存 Map 迁到 Prisma
• 全局 JwtAuthGuard
• Swagger 端点 Basic Auth 保护
• 更多 AI Workflow（知识导入、费曼分析、复习卡片生成）
• AI 联调 + Prompt 调优
• 添加 Redis 缓存
• iOS 集成