docs & cleanup: update stack info, remove dead code, fix backend bugs

- Fix AGENTS.md and 技术架构设计.md to reflect actual stack (Prisma+MySQL, static export, PM2) - Remove 4 unused frontend components (page-transition, page-layout, image-upload, section-card) - Fix card.tsx hardcoded colors → CSS variables - Remove provider name from model selector, remove sensenova-u1-fast from models - Fix analytics.controller.ts raw SQL table names (runtime bug) - Add JWT auth guard to tools POST endpoint - Fix AI gateway test: update env vars and model names - Fix admin test: mock role structure for Prisma relation
2026-05-29 10:26:50 +08:00
parent 417fb266d4
commit 6f3fe50ee0
15 changed files with 118 additions and 304 deletions
@@ -1,7 +1,7 @@
 # 宇之然 AI - 技术架构设计文档

-> 版本：v1.0  
-> 日期：2026-05-08
+> 版本：v1.1
+> 日期：2026-05-29

 ---

@@ -12,16 +12,16 @@
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
 │                        客户端层                                      │
-│  ┌────────────┐  ┌──────────────┐  ┌────────────┐                 │
-│  │ Next.js    │  │ Uni-app      │  │ 微信小程序  │                 │
-│  │ 官网 (SSR) │  │ App (跨平台) │  │            │                 │
-│  └────────────┘  └──────────────┘  └────────────┘                 │
+│  ┌────────────────────┐  ┌──────────────────┐                      │
+│  │ Next.js            │  │ 微信小程序        │                      │
+│  │ 官网 (静态导出)     │  │ (规划中)          │                      │
+│  └────────────────────┘  └──────────────────┘                      │
 └──────────────────────────┬──────────────────────────────────────────┘
                           │
 ┌──────────────────────────▼──────────────────────────────────────────┐
-│                     API 网关层                                      │
-│          Nginx / 阿里云 SLB → API Gateway                           │
-│          限流 / 鉴权 / 日志 / 路由转发                              │
+│                     API 网关层 (NestJS)                              │
+│          Nginx → PM2 → NestJS                                       │
+│          限流 / JWT 鉴权 / 日志 / 路由转发                          │
 └──────────────────────────┬──────────────────────────────────────────┘
                           │
 ┌──────────────────────────▼──────────────────────────────────────────┐
@@ -36,14 +36,14 @@
                           │
 ┌──────────────────────────▼──────────────────────────────────────────┐
 │                      AI 网关层                                      │
-│  统一 API → 多模型路由 → 负载均衡 → 结果缓存                       │
-│  通义千问 │ 文心一言 │ GLM │ DeepSeek │ Kimi ...                   │
+│   统一 API → 模型路由 → 流式响应                                    │
+│   qnaigc 兼容接口 → DeepSeek / SenseNova / 其他 OpenAI 兼容模型     │
 └──────────────────────────┬──────────────────────────────────────────┘
                           │
 ┌──────────────────────────▼──────────────────────────────────────────┐
 │                       数据层                                        │
-│  MySQL 8.0  │  Redis 7  │  ES 8.x  │  OSS  │  RocketMQ            │
-│  (主从/读写分离) (缓存/会话) (搜索) (存储)  (消息队列)              │
+│  MySQL 8.0  │  Redis 7                                              │
+│  (主库)      │  (缓存/会话)                                         │
 └─────────────────────────────────────────────────────────────────────┘
 ```

@@ -55,23 +55,18 @@

 | 技术 | 版本 | 说明 |
 |------|------|------|
-| Next.js | 14+ | React 框架，SSR/SSG 支持 |
+| Next.js | 14+ | React 框架，静态导出 (`output: 'export'`) |
 | TypeScript | 5.x | 类型安全 |
 | TailwindCSS | 3.x | 原子化 CSS |
 | Shadcn/ui | latest | UI 组件库 |
-| React Query | 5.x | 数据请求管理 |
-| Zustand | latest | 状态管理 |
+| next-themes | latest | 暗黑模式切换 |

-### 2.2 移动端（App / 小程序）
+### 2.2 移动端（规划中）

 | 技术 | 说明 |
 |------|------|
-| Uni-app / Taro | 跨端框架 |
-| Vue 3 / React | 视框架而定 |
-| Pinia / Zustand | 状态管理 |
-| uView / NutUI | 移动端组件库 |
-
-> 推荐 Uni-app + Vue 3，对微信小程序适配最成熟。
+| 微信小程序 | 后续规划 |
+| Taro / uni-app | 评估中 |

 ### 2.3 后端

@@ -79,64 +74,41 @@
 |------|------|------|
 | 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。
+| Prisma | 5.x | ORM（MySQL） |
+| JWT | - | 鉴权（Access Token 2h + Refresh Token 7d）|

 ### 2.4 数据库

 | 组件 | 用途 | 部署 |
 |------|------|------|
-| MySQL 8.0 | 业务主库（用户/课程/订单等） | 阿里云 RDS |
-| Redis 7 | 缓存/会话/限流计数器 | 阿里云 Redis |
-| Elasticsearch 8.x | 内容搜索 | 阿里云 ES |
-| 阿里云 OSS | 图片/视频/文件存储 | 阿里云 OSS |
-| RocketMQ | 异步任务/消息通知 | 阿里云 RocketMQ |
+| MySQL 8.0 | 业务主库（用户/课程/订单等） | 本地 / 云 RDS |
+| Redis 7 | 缓存/会话/限流计数器 | 本地 / 云 Redis |

 ### 2.5 AI 网关

 ```
-用户请求 → 网关层
-  ├── 请求校验 → 内容安全审核
-  ├── 模型路由（基于用户配置/成本/负载）
-  │   ├── 通义千问 (qwen-max)
-  │   ├── 文心一言 (ERNIE-4.0)
-  │   ├── GLM-4
-  │   ├── DeepSeek-V3
-  │   └── Kimi (moonshot-v1)
-  ├── 结果缓存（Redis，相同 prompt 命中缓存）
-  ├── 流式响应处理
-  └── 计费/用量统计
+用户请求 → 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)
+  └── 用量统计
 ```

-### 2.6 内容安全
-
-| 服务 | 用途 |
-|------|------|
-| 阿里云内容安全 | 文本/图片鉴黄、涉政、违禁检测 |
-| 腾讯云天御 | UGC 内容安全审核 |
-| 自定义敏感词库 | 行业特定敏感词过滤 |
+AI 通过 OpenAI 兼容 API (`api.qnaigc.com`) 统一接入，不直接对接各模型厂商。

 ---

 ## 3. 数据库设计概要

-### 3.1 核心表结构
+### 3.1 核心表结构 (Prisma Schema)

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

 courses                — 课程表
 ├── id, title, description, cover, category, price, status
@@ -172,15 +144,17 @@ contents               — 内容（文章/资讯）
 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 数据库设计原则
+### 3.2 Schema 管理

- **软删除**：所有业务表增加 `deleted_at` 字段
- **审计字段**：`created_at`、`updated_at` 必备
- **索引策略**：覆盖常用查询场景，避免全表扫描
- **分表策略**：`sandbox_sessions` 按用户 ID 分表
- **读写分离**：主库写入，从库查询
+- 使用 Prisma Migrate 管理 schema 变更
+- migration 文件位于 `backend/prisma/migrations/`
+- 种子数据在 `backend/prisma/seed.ts`

 ---

@@ -206,6 +180,11 @@ 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 通用响应格式
@@ -223,68 +202,58 @@ POST   /api/v1/orders/callback  — 支付回调
 }
 ```

-### 4.3 鉴权方案
-
- **JWT Token**（Access Token 2h + Refresh Token 7d）
- 管理后台：Session + Cookie
- API 签名：管理端 API 需签名校验
-
 ---

 ## 5. 部署架构

+### 5.1 当前部署
+
 ```
                    ┌─────────────┐
-                    │   DNS       │
-                    │  (阿里云 DNS)│
+                    │   PM2       │
+                    │  (进程管理)  │
                    └──────┬──────┘
                           │
+               ┌───────────┼───────────┐
+               │           │           │
+        ┌──────▼──┐  ┌─────▼────┐ ┌───▼────┐
+        │ Node.js  │  │ NestJS   │ │ Redis  │
+        │ server.js│  │ API 服务  │ │        │
+        │ (静态)   │  │ PM2      │ └────────┘
+        └─────────┘  └─────┬────┘
+                           │
                    ┌──────▼──────┐
-                    │  CDN        │
-                    │ (静态资源)   │
-                    └──────┬──────┘
-                           │
-                    ┌──────▼──────┐
-                    │  SLB        │
-                    │ (负载均衡)   │
-                    └──────┬──────┘
-                           │
-              ┌────────────┼────────────┐
-              │            │            │
-       ┌──────▼──┐  ┌─────▼────┐ ┌────▼────┐
-       │ Next.js │  │ NestJS   │ │ Admin   │
-       │ 官网    │  │ API 服务  │ │ Panel   │
-       └─────────┘  └─────┬────┘ └─────────┘
-                          │
-              ┌───────────┼───────────┐
-              │           │           │
-       ┌──────▼──┐  ┌────▼───┐  ┌───▼────┐
-       │ MySQL   │  │ Redis  │  │   ES   │
-       │ RDS     │  │        │  │        │
-       └─────────┘  └────────┘  └────────┘
+                    │   MySQL     │
+                    │   8.0       │
+                    └─────────────┘
 ```

-### 5.1 环境规划
+| 服务 | 端口 | 管理方式 |
+|------|------|----------|
+| 前端 (静态文件) | 3000 | PM2: `node server.js` |
+| 后端 (NestJS) | 4000 | PM2: `node dist/main.js` |
+| MySQL | 3306 | 系统服务 |
+| Redis | 6379 | 系统服务 |

-| 环境 | 用途 | 配置 |
-|------|------|------|
-| 开发 (dev) | 本地开发 | 个人电脑 / Docker Compose |
-| 测试 (staging) | 联调测试 | 阿里云 ECS 2C4G |
-| 生产 (production) | 正式运营 | 阿里云 ECS 4C8G × 2 + RDS 2C4G |
-
-### 5.2 CI/CD 流程
+### 5.2 构建流程

 ```
-Git Push → GitHub Actions
-  ├── Lint & Type Check
-  ├── Unit Test
-  ├── Build
-  └── Deploy to 阿里云
-      ├── 构建 Docker 镜像
-      ├── Push 到阿里云 CR
-      └── 滚动更新 ECS/Pod
+# 前端
+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. 性能与安全
@@ -296,18 +265,15 @@ Git Push → GitHub Actions
 | API 响应时间 (P95) | < 200ms |
 | 首屏加载时间 | < 1.5s |
 | AI 对话首 Token 延迟 | < 1s |
-| 并发用户 | 支持 1000+ 同时在线 |
-| 系统可用性 | 99.9% |
+| 静态页面加载 | 即时（CDN 缓存） |

 ### 6.2 安全措施

 - HTTPS 全站加密
- API 限流（单用户 100次/分钟）
- SQL 注入防护（Prisma ORM 参数化查询）
- XSS/CSRF 防护
+- JWT 鉴权（沙箱等核心 API）
+- API 限流
 - 密码 bcrypt 加密
 - 敏感信息脱敏
- 定期安全扫描 + 渗透测试

 ---

@@ -315,8 +281,7 @@ Git Push → GitHub Actions

 | 阶段 | 任务 |
 |------|------|
-| MVP | 单体应用快速验证 |
-| V2 | 服务化拆分 |
-| V3 | AI 网关独立部署 |
-| V4 | 引入 K8s 容器编排 |
-| V5 | 多数据中心容灾 |
+| 当前 | 单体 NestJS + Next.js 静态导出 |
+| V2 | AI 网关独立部署 |
+| V3 | 微信小程序上线 |
+| V4 | 服务化拆分 |