# 宇之然 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 通用响应格式

```json
{
  "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 | 服务化拆分 |
