ai-learning-platform/docs/技术架构设计.md

宇之然 AI - 技术架构设计文档

版本：v1.1 日期：2026-05-29

---

1. 系统总体架构

1.1 架构分层

┌─────────────────────────────────────────────────────────────────────┐
│                        客户端层                                      │
│  ┌────────────────────┐  ┌──────────────────┐                      │
│  │ Next.js            │  │ 微信小程序        │                      │
│  │ 官网 (静态导出)     │  │ (规划中)          │                      │
│  └────────────────────┘  └──────────────────┘                      │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                     API 网关层 (NestJS)                              │
│          Nginx → PM2 → NestJS                                       │
│          限流 / JWT 鉴权 / 日志 / 路由转发                          │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                       业务服务层                                     │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐              │
│  │ 用户服务  │ │ 内容服务  │ │ 课程服务  │ │ 沙箱服务  │             │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐              │
│  │ 社区服务  │ │ 支付服务  │ │ 搜索服务  │ │ 审核服务  │             │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘              │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                      AI 网关层                                      │
│   统一 API → 模型路由 → 流式响应                                    │
│   qnaigc 兼容接口 → DeepSeek / SenseNova / 其他 OpenAI 兼容模型     │
└──────────────────────────┬──────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────────────┐
│                       数据层                                        │
│  MySQL 8.0  │  Redis 7                                              │
│  (主库)      │  (缓存/会话)                                         │
└─────────────────────────────────────────────────────────────────────┘

---

2. 技术选型详述

2.1 前端（官网）

技术	版本	说明
Next.js	14+	React 框架，静态导出 (output: 'export')
TypeScript	5.x	类型安全
TailwindCSS	3.x	原子化 CSS
Shadcn/ui	latest	UI 组件库
next-themes	latest	暗黑模式切换

2.2 移动端（规划中）

技术	说明
微信小程序	后续规划
Taro / uni-app	评估中

2.3 后端

技术	版本	说明
Node.js	20 LTS	运行时
NestJS	10.x	Node.js 后端框架
Prisma	5.x	ORM（MySQL）
JWT	-	鉴权（Access Token 2h + Refresh Token 7d）

2.4 数据库

组件	用途	部署
MySQL 8.0	业务主库（用户/课程/订单等）	本地 / 云 RDS
Redis 7	缓存/会话/限流计数器	本地 / 云 Redis

2.5 AI 网关

用户请求 → AIGatewayService
  ├── 模型路由（基于 modelMap 配置）
  │   ├── general → OPENAI_MODEL (default: deepseek/deepseek-v4-flash)
  │   ├── deepseek-v4-flash → deepseek/deepseek-v4-flash
  │   └── sensenova-6.7-flash-lite → sensenova-6.7-flash-lite
  ├── 流式响应 (ReadableStream SSE)
  └── 用量统计

AI 通过 OpenAI 兼容 API (api.qnaigc.com) 统一接入，不直接对接各模型厂商。

---

3. 数据库设计概要

3.1 核心表结构 (Prisma Schema)

users                  — 用户表
├── id, phone, email, password_hash, avatar, status, created_at
├── profiles           — 用户扩展信息
└── learn_records      — 学习记录

courses                — 课程表
├── id, title, description, cover, category, price, status
├── chapters           — 章节表
├── lessons            — 课时表
└── lesson_progress    — 学习进度

prompts                — 提示词表
├── id, title, content, category, tags, author_id, status
├── prompt_favorites   — 收藏
└── prompt_comments    — 评论

tools                  — AI 工具表
├── id, name, description, url, category, icon, status
└── tool_reviews       — 评价

models                 — 模型百科表
├── id, name, provider, params, features, benchmark, status
└── model_comparisons  — 对比评测

sandbox_sessions       — AI 沙箱会话表
├── id, user_id, model, messages, tokens, duration, created_at
└── sandbox_quota      — 用户沙箱额度

orders                 — 订单表
├── id, user_id, amount, plan_type, status, pay_channel, paid_at
└── subscriptions      — 订阅记录

contents               — 内容（文章/资讯）
├── id, title, content, category, tags, author, status, view_count
└── content_comments   — 评论

admin_users            — 管理员表
├── id, username, password_hash, role, permission, last_login
└── admin_logs         — 操作日志

skills                 — 技能包表
├── id, name, description, category, difficulty, system_prompt, icon
└── skill_tasks        — 练习任务

3.2 Schema 管理

• 使用 Prisma Migrate 管理 schema 变更
• migration 文件位于 backend/prisma/migrations/
• 种子数据在 backend/prisma/seed.ts

---

4. API 设计规范

4.1 命名规范

GET    /api/v1/courses          — 课程列表
GET    /api/v1/courses/:id      — 课程详情
POST   /api/v1/courses          — 创建课程（管理端）
PUT    /api/v1/courses/:id      — 更新课程（管理端）
DELETE /api/v1/courses/:id      — 删除课程（管理端）

POST   /api/v1/auth/login       — 登录
POST   /api/v1/auth/register    — 注册
POST   /api/v1/auth/refresh     — 刷新 token

POST   /api/v1/sandbox/chat     — AI 沙箱对话
GET    /api/v1/sandbox/history  — 对话历史
GET    /api/v1/sandbox/quota    — 沙箱额度查询

POST   /api/v1/orders/create    — 创建订单
GET    /api/v1/orders/:id       — 订单查询
POST   /api/v1/orders/callback  — 支付回调

GET    /api/v1/skills           — 技能列表（支持过滤）
GET    /api/v1/skills/:id       — 技能详情
GET    /api/v1/skills/categories — 技能分类
GET    /api/v1/skills/difficulties — 难度等级

4.2 通用响应格式

{
  "code": 0,
  "message": "success",
  "data": {},
  "meta": {
    "page": 1,
    "pageSize": 20,
    "total": 100
  }
}

---

5. 部署架构

5.1 当前部署

                    ┌─────────────┐
                    │   PM2       │
                    │  (进程管理)  │
                    └──────┬──────┘
                           │
               ┌───────────┼───────────┐
               │           │           │
        ┌──────▼──┐  ┌─────▼────┐ ┌───▼────┐
        │ Node.js  │  │ NestJS   │ │ Redis  │
        │ server.js│  │ API 服务  │ │        │
        │ (静态)   │  │ PM2      │ └────────┘
        └─────────┘  └─────┬────┘
                           │
                    ┌──────▼──────┐
                    │   MySQL     │
                    │   8.0       │
                    └─────────────┘

服务	端口	管理方式
前端 (静态文件)	3000	PM2: node server.js
后端 (NestJS)	4000	PM2: node dist/main.js
MySQL	3306	系统服务
Redis	6379	系统服务

5.2 构建流程

# 前端
npm run build → out/ (静态文件)
pm2 restart frontend

# 后端
npx nest build → dist/
pm2 restart backend --update-env

5.3 环境

环境	用途
开发 (dev)	本地 npm run dev / npm run start:dev
生产 (production)	PM2 + 静态导出

---

6. 性能与安全

6.1 性能目标

指标	目标
API 响应时间 (P95)	< 200ms
首屏加载时间	< 1.5s
AI 对话首 Token 延迟	< 1s
静态页面加载	即时（CDN 缓存）

6.2 安全措施

• HTTPS 全站加密
• JWT 鉴权（沙箱等核心 API）
• API 限流
• 密码 bcrypt 加密
• 敏感信息脱敏

---

7. 技术债务与演进路线

阶段	任务
当前	单体 NestJS + Next.js 静态导出
V2	AI 网关独立部署
V3	微信小程序上线
V4	服务化拆分