yuzhiran-dev
538de50bb1
- Prisma User 模型新增 username 字段（唯一索引） - 注册先查重复再创建，返回友好中文提示（非 500） - 登录支持用户名/手机号/邮箱三种方式 - 前端注册表单增加用户名输入框，预校验 2-20 位格式 - 新增 scripts/deploy.sh：一键构建并部署主站+镜像站+重启后端+重载 Nginx - 镜像站 www.yuzhiran.com.cn Nginx 配置与主站同步 - AI 助手架构升级：用户端/管理后台均采用完整 Tool Calling 架构 - 新增 UserAiAssistantService（18 工具）+ AiAssistantController - admin 助手新增 search + mark-all-notifications-read 工具 - 修复注册 500 错误：catch Prisma P2002 → BadRequestException - Baidu Analytics Script 注入 root layout
288 lines
11 KiB
Markdown
Executable File
288 lines
11 KiB
Markdown
Executable File
# 宇之然 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 | 服务化拆分 |
|