# 系统架构

> 最后更新：2026-01-21（AI 配置从管理库加载）

## 整体架构

```
考培练系统
├── 前端层（Vue3 + TypeScript + pnpm）
│   ├── 学员端
│   ├── 管理端
│   ├── SaaS 超级管理后台（admin.ireborn.com.cn）
│   └── 公共组件
├── 后端层（FastAPI + Python 3.11）
│   ├── API网关
│   ├── 业务服务
│   ├── 租户配置管理
│   └── AI服务集成
├── AI平台层
│   ├── Python 原生 AI 服务（4sapi.com → OpenRouter 降级）
│   └── Coze（陪练、对话）
└── 数据层
    ├── MySQL（业务数据 + 管理后台数据）
    └── Redis（缓存、会话、课程对话历史）
```

## 技术选型

### 前端技术栈

> 参考：《瑞小美系统技术栈标准与字符标准.md》

| 项目 | 技术 | 版本 | 备注 |
|------|------|------|------|
| 语言 | **TypeScript** | 5.x | 禁止使用 JavaScript |
| 框架 | Vue 3 | 3.4+ | Composition API |
| 构建 | Vite | 5.x | 快速开发体验 |
| 包管理器 | **pnpm** | 9.x | 禁止使用 npm/yarn |
| UI 组件库 | Element Plus | 2.x | 企业级 UI |
| 状态管理 | Pinia | 2.x | 按需使用 |
| 路由 | Vue Router | 4.x | - |
| 代码规范 | **ESLint** | 8.x | 必须配置 |

### 后端技术栈

| 项目 | 技术 | 版本 | 备注 |
|------|------|------|------|
| 语言 | Python | 3.11 | - |
| 框架 | FastAPI | 0.104+ | - |
| ORM | SQLAlchemy | 2.0 | 异步支持 |
| 数据库 | MySQL | 8.0 | utf8mb4 |
| 缓存 | Redis | 7.x | - |
| 认证 | JWT | - | - |

### 基础设施

| 项目 | 技术 | 备注 |
|------|------|------|
| 容器 | Docker + Docker Compose | 必须容器化部署 |
| 反向代理 | Nginx | 独立容器，SSL 终止 |
| SSL | Let's Encrypt | 自动续期 |
| 镜像源 | 阿里云 | kjphlxn2.mirror.aliyuncs.com |

## 核心模块

### 1. 用户认证模块
- JWT Token认证
- 角色权限管理（RBAC）
- 单点登录支持

### 2. 课程管理模块
- 课程CRUD
- 知识点管理
- 文件资料管理
- AI知识提取

### 3. 考试系统模块
- 动态题目生成
- 三轮考试机制
- 成绩分析统计
- 错题强化练习

### 4. AI陪练模块
- 场景化对话
- 语音交互
- 实时评估
- 能力报告

### 5. 数据分析模块
- 学习进度追踪
- 能力雷达图
- 团队绩效分析
- 智能推荐

### 6. SaaS 超级管理后台（2026-01-18 新增）

> 域名：admin.ireborn.com.cn

| 功能 | 说明 |
|------|------|
| 租户管理 | 创建、编辑、启用/禁用租户 |
| 配置管理 | 统一管理 AI Key、数据库、Redis 等配置 |
| 提示词管理 | 查看和编辑 AI 提示词，支持版本控制 |
| 功能开关 | 按租户控制功能模块的启用/禁用 |
| 操作审计 | 记录所有管理操作日志 |

**数据库**：`kaopeilian_admin`（prod-mysql:3309）

**配置优先级**：
1. 数据库 `tenant_configs` 表
2. 环境变量 `.env` 文件
3. 代码默认值

## AI集成架构

> 参考：《瑞小美AI接入规范.md》
>
> 更新日期：2026-01-21（AI 配置从管理库加载）

### AI 配置加载架构（核心！）

```
┌─────────────────────────────────────────────────────────────┐
│  SaaS 管理后台 (admin.ireborn.com.cn)                        │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  AI 配置管理页面                                        │ │
│  │  - AI_PRIMARY_API_KEY（通用 Key）                       │ │
│  │  - AI_ANTHROPIC_API_KEY（Claude 专属 Key）             │ │
│  │  - AI_PRIMARY_BASE_URL                                 │ │
│  │  - AI_FALLBACK_API_KEY（备选）                          │ │
│  │  - AI_DEFAULT_MODEL                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                              │                               │
│                              ▼                               │
│           kaopeilian_admin.tenant_configs 表                 │
└──────────────────────────────┬──────────────────────────────┘
                               │ 同步方式查询
       ┌───────────────────────┼───────────────────────────────┐
       │                       │                               │
       ▼                       ▼                               ▼
┌─────────────┐        ┌─────────────┐                ┌─────────────┐
│  ex-backend │        │  hua-backend│                │  yy-backend │
│  AIService  │        │  AIService  │                │  AIService  │
│  TENANT=ex  │        │  TENANT=hua │                │  TENANT=yy  │
└─────────────┘        └─────────────┘                └─────────────┘
```

**配置加载优先级**：
1. 管理库 `kaopeilian_admin.tenant_configs` 表（按 TENANT_CODE 查询）
2. 环境变量 `.env` 文件（fallback）
3. 代码默认值

**容器必须的环境变量**：
```env
TENANT_CODE=ex                          # 租户编码
ADMIN_DB_HOST=prod-mysql                # 管理库主机
ADMIN_DB_PASSWORD=ProdMySQL2025!@#      # 管理库密码
ADMIN_DB_NAME=kaopeilian_admin          # 管理库名称
```

### AI 服务商策略

**首选 4sapi.com → 备选 OpenRouter（自动降级）**

| 优先级 | 服务商 | API 地址 |
|--------|--------|----------|
| 1（首选）| 4sapi.com | `https://4sapi.com/v1` |
| 2（备选）| OpenRouter | `https://openrouter.ai/api/v1` |

### Python 原生 AI 服务

```
前端 → 后端API → AIService → 管理库加载配置 → 4sapi/OpenRouter → JSON解析 → 返回结果
```

**已实现的服务**：
- ✅ 知识点分析 (`knowledge_analysis_v2.py`)
- ✅ 试题生成器 (`exam_generator_service.py`)
- ✅ 陪练场景提取 (`practice_scene_service.py`)
- ✅ 课程对话 (`course_chat_service.py`)
- ✅ 能力分析 (`ability_analysis_service.py`)
- ✅ 答案判断 (`answer_judge_service.py`)
- ✅ 陪练分析报告 (`practice_analysis_service.py`)

### Coze 集成

```
前端 → Coze网关 → Coze Bot → 流式响应 → 前端展示
```

**主要功能**：
- AI 陪练对话
- 语音交互
- 播课生成

## 数据流设计

### 业务数据流
1. 用户请求 → API网关 → 业务服务
2. 业务服务 → 数据验证 → 数据库操作
3. 数据库 → 缓存更新 → 响应返回

### AI处理流
1. 用户触发 → 参数构建 → AI平台调用
2. AI处理 → 结果解析 → 业务存储
3. 结果返回 → 前端展示 → 用户反馈

## 部署架构

> 详见：《部署架构-统一版.md》

### 多租户架构

```
                    ┌─────────────────────────────────────┐
                    │        kaopeilian-nginx             │
                    │       (入口反向代理服务器)            │
                    │      80/443 端口                    │
                    └───────────────┬─────────────────────┘
                                    │
    ┌───────────────────────────────┼───────────────────────────────┐
    │               │               │               │               │
    ▼               ▼               ▼               ▼               ▼
┌─────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐
│管理后台  │  │ 演示版    │  │ 多客户版   │  │ 瑞小美    │  │陪练试用版  │
│admin.*  │  │ aiedu.*  │  │yy/hl/xy.. │  │ kpl.*    │  │ pl.*     │
└─────────┘  └───────────┘  └───────────┘  └───────────┘  └───────────┘
```

### 开发环境
- Docker 容器化
- 代码热重载（HMR/auto-reload）
- 统一端口配置
- 共享代码库

### 生产环境
- 前后端分离容器
- 共享 dist 方案（一次构建，多租户更新）
- 日志轮转（max-size: 10m）
- 资源限制（前端 256M，后端 512M）

## 安全设计

### 接口安全
- JWT Token 认证
- 请求签名
- 频率限制
- SQL 注入防护（SQLAlchemy ORM）

### 数据安全
- 敏感数据加密存储
- 传输层加密（HTTPS / Let's Encrypt）
- 每日自动备份（保留 7 天）
- 操作审计日志

### 敏感信息管理

> 参考：《瑞小美系统技术栈标准与字符标准.md》

| 规范 | 说明 |
|------|------|
| 禁止硬编码 | 密码、密钥禁止写入代码或镜像 |
| 环境变量 | 通过 `.env` 文件管理 |
| 文件权限 | `.env` 文件权限设为 600 |
| 生产环境 | 使用 Docker env_file 方式 |

## 性能优化

### 前端优化
- 组件懒加载
- 资源压缩
- CDN加速
- 缓存策略

### 后端优化
- 数据库索引
- 查询优化
- 异步处理
- 连接池管理

### 缓存策略
- Redis缓存热数据
- 本地缓存静态资源
- API响应缓存
- 分布式缓存

## 扩展性设计

### 水平扩展
- 无状态服务设计
- 数据库读写分离
- 缓存集群
- 消息队列

### 垂直扩展
- 模块化设计
- 插件化架构
- API版本管理
- 配置中心