feat: Phase 1-3 全部完成 — 沙盒增强、学情分析、学习路径
This commit is contained in:
yuzhiran-dev
+322
@@ -0,0 +1,322 @@
|
||||
# 宇之然 AI - 技术架构设计文档
|
||||
|
||||
> 版本：v1.0
|
||||
> 日期：2026-05-08
|
||||
|
||||
---
|
||||
|
||||
## 1. 系统总体架构
|
||||
|
||||
### 1.1 架构分层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ 客户端层 │
|
||||
│ ┌────────────┐ ┌──────────────┐ ┌────────────┐ │
|
||||
│ │ Next.js │ │ Uni-app │ │ 微信小程序 │ │
|
||||
│ │ 官网 (SSR) │ │ App (跨平台) │ │ │ │
|
||||
│ └────────────┘ └──────────────┘ └────────────┘ │
|
||||
└──────────────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||||
│ API 网关层 │
|
||||
│ Nginx / 阿里云 SLB → API Gateway │
|
||||
│ 限流 / 鉴权 / 日志 / 路由转发 │
|
||||
└──────────────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||||
│ 业务服务层 │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 用户服务 │ │ 内容服务 │ │ 课程服务 │ │ 沙箱服务 │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ 社区服务 │ │ 支付服务 │ │ 搜索服务 │ │ 审核服务 │ │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||||
└──────────────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||||
│ AI 网关层 │
|
||||
│ 统一 API → 多模型路由 → 负载均衡 → 结果缓存 │
|
||||
│ 通义千问 │ 文心一言 │ GLM │ DeepSeek │ Kimi ... │
|
||||
└──────────────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────────────────▼──────────────────────────────────────────┐
|
||||
│ 数据层 │
|
||||
│ MySQL 8.0 │ Redis 7 │ ES 8.x │ OSS │ RocketMQ │
|
||||
│ (主从/读写分离) (缓存/会话) (搜索) (存储) (消息队列) │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 技术选型详述
|
||||
|
||||
### 2.1 前端（官网）
|
||||
|
||||
| 技术 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| Next.js | 14+ | React 框架，SSR/SSG 支持 |
|
||||
| TypeScript | 5.x | 类型安全 |
|
||||
| TailwindCSS | 3.x | 原子化 CSS |
|
||||
| Shadcn/ui | latest | UI 组件库 |
|
||||
| React Query | 5.x | 数据请求管理 |
|
||||
| Zustand | latest | 状态管理 |
|
||||
|
||||
### 2.2 移动端（App / 小程序）
|
||||
|
||||
| 技术 | 说明 |
|
||||
|------|------|
|
||||
| Uni-app / Taro | 跨端框架 |
|
||||
| Vue 3 / React | 视框架而定 |
|
||||
| Pinia / Zustand | 状态管理 |
|
||||
| uView / NutUI | 移动端组件库 |
|
||||
|
||||
> 推荐 Uni-app + Vue 3，对微信小程序适配最成熟。
|
||||
|
||||
### 2.3 后端
|
||||
|
||||
| 技术 | 版本 | 说明 |
|
||||
|------|------|------|
|
||||
| Node.js | 20 LTS | 运行时 |
|
||||
| NestJS | 10.x | Node.js 后端框架 |
|
||||
| Prisma | 5.x | ORM |
|
||||
| JWT | - | 鉴权 |
|
||||
| Zod | latest | 数据校验 |
|
||||
|
||||
或备选方案：
|
||||
|
||||
| 技术 | 说明 |
|
||||
|------|------|
|
||||
| Go + Gin / Fiber | 高性能，适合 AI 网关 |
|
||||
| Python + FastAPI | 适合 AI 数据处理任务 |
|
||||
|
||||
> 建议：核心业务用 NestJS，AI 网关用 Go。
|
||||
|
||||
### 2.4 数据库
|
||||
|
||||
| 组件 | 用途 | 部署 |
|
||||
|------|------|------|
|
||||
| MySQL 8.0 | 业务主库（用户/课程/订单等） | 阿里云 RDS |
|
||||
| Redis 7 | 缓存/会话/限流计数器 | 阿里云 Redis |
|
||||
| Elasticsearch 8.x | 内容搜索 | 阿里云 ES |
|
||||
| 阿里云 OSS | 图片/视频/文件存储 | 阿里云 OSS |
|
||||
| RocketMQ | 异步任务/消息通知 | 阿里云 RocketMQ |
|
||||
|
||||
### 2.5 AI 网关
|
||||
|
||||
```
|
||||
用户请求 → 网关层
|
||||
├── 请求校验 → 内容安全审核
|
||||
├── 模型路由（基于用户配置/成本/负载）
|
||||
│ ├── 通义千问 (qwen-max)
|
||||
│ ├── 文心一言 (ERNIE-4.0)
|
||||
│ ├── GLM-4
|
||||
│ ├── DeepSeek-V3
|
||||
│ └── Kimi (moonshot-v1)
|
||||
├── 结果缓存（Redis，相同 prompt 命中缓存）
|
||||
├── 流式响应处理
|
||||
└── 计费/用量统计
|
||||
```
|
||||
|
||||
### 2.6 内容安全
|
||||
|
||||
| 服务 | 用途 |
|
||||
|------|------|
|
||||
| 阿里云内容安全 | 文本/图片鉴黄、涉政、违禁检测 |
|
||||
| 腾讯云天御 | UGC 内容安全审核 |
|
||||
| 自定义敏感词库 | 行业特定敏感词过滤 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据库设计概要
|
||||
|
||||
### 3.1 核心表结构
|
||||
|
||||
```
|
||||
users — 用户表
|
||||
├── id, phone, email, password_hash, avatar, status, created_at
|
||||
├── user_profiles — 用户扩展信息
|
||||
└── user_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 — 操作日志
|
||||
```
|
||||
|
||||
### 3.2 数据库设计原则
|
||||
|
||||
- **软删除**：所有业务表增加 `deleted_at` 字段
|
||||
- **审计字段**：`created_at`、`updated_at` 必备
|
||||
- **索引策略**：覆盖常用查询场景，避免全表扫描
|
||||
- **分表策略**：`sandbox_sessions` 按用户 ID 分表
|
||||
- **读写分离**：主库写入，从库查询
|
||||
|
||||
---
|
||||
|
||||
## 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 — 支付回调
|
||||
```
|
||||
|
||||
### 4.2 通用响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {},
|
||||
"meta": {
|
||||
"page": 1,
|
||||
"pageSize": 20,
|
||||
"total": 100
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 鉴权方案
|
||||
|
||||
- **JWT Token**（Access Token 2h + Refresh Token 7d）
|
||||
- 管理后台：Session + Cookie
|
||||
- API 签名：管理端 API 需签名校验
|
||||
|
||||
---
|
||||
|
||||
## 5. 部署架构
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ DNS │
|
||||
│ (阿里云 DNS)│
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ CDN │
|
||||
│ (静态资源) │
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌──────▼──────┐
|
||||
│ SLB │
|
||||
│ (负载均衡) │
|
||||
└──────┬──────┘
|
||||
│
|
||||
┌────────────┼────────────┐
|
||||
│ │ │
|
||||
┌──────▼──┐ ┌─────▼────┐ ┌────▼────┐
|
||||
│ Next.js │ │ NestJS │ │ Admin │
|
||||
│ 官网 │ │ API 服务 │ │ Panel │
|
||||
└─────────┘ └─────┬────┘ └─────────┘
|
||||
│
|
||||
┌───────────┼───────────┐
|
||||
│ │ │
|
||||
┌──────▼──┐ ┌────▼───┐ ┌───▼────┐
|
||||
│ MySQL │ │ Redis │ │ ES │
|
||||
│ RDS │ │ │ │ │
|
||||
└─────────┘ └────────┘ └────────┘
|
||||
```
|
||||
|
||||
### 5.1 环境规划
|
||||
|
||||
| 环境 | 用途 | 配置 |
|
||||
|------|------|------|
|
||||
| 开发 (dev) | 本地开发 | 个人电脑 / Docker Compose |
|
||||
| 测试 (staging) | 联调测试 | 阿里云 ECS 2C4G |
|
||||
| 生产 (production) | 正式运营 | 阿里云 ECS 4C8G × 2 + RDS 2C4G |
|
||||
|
||||
### 5.2 CI/CD 流程
|
||||
|
||||
```
|
||||
Git Push → GitHub Actions
|
||||
├── Lint & Type Check
|
||||
├── Unit Test
|
||||
├── Build
|
||||
└── Deploy to 阿里云
|
||||
├── 构建 Docker 镜像
|
||||
├── Push 到阿里云 CR
|
||||
└── 滚动更新 ECS/Pod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 性能与安全
|
||||
|
||||
### 6.1 性能目标
|
||||
|
||||
| 指标 | 目标 |
|
||||
|------|------|
|
||||
| API 响应时间 (P95) | < 200ms |
|
||||
| 首屏加载时间 | < 1.5s |
|
||||
| AI 对话首 Token 延迟 | < 1s |
|
||||
| 并发用户 | 支持 1000+ 同时在线 |
|
||||
| 系统可用性 | 99.9% |
|
||||
|
||||
### 6.2 安全措施
|
||||
|
||||
- HTTPS 全站加密
|
||||
- API 限流（单用户 100次/分钟）
|
||||
- SQL 注入防护（Prisma ORM 参数化查询）
|
||||
- XSS/CSRF 防护
|
||||
- 密码 bcrypt 加密
|
||||
- 敏感信息脱敏
|
||||
- 定期安全扫描 + 渗透测试
|
||||
|
||||
---
|
||||
|
||||
## 7. 技术债务与演进路线
|
||||
|
||||
| 阶段 | 任务 |
|
||||
|------|------|
|
||||
| MVP | 单体应用快速验证 |
|
||||
| V2 | 服务化拆分 |
|
||||
| V3 | AI 网关独立部署 |
|
||||
| V4 | 引入 K8s 容器编排 |
|
||||
| V5 | 多数据中心容灾 |
|
||||
Reference in New Issue
Block a user