feat: 初始化考培练系统项目

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
2026-01-24 19:33:28 +08:00
commit 998211c483
1197 changed files with 228429 additions and 0 deletions

View File

@@ -0,0 +1,623 @@
# 考培练系统与Dify平台对接深度分析报告
## 目录
1. [系统概述](#系统概述)
2. [Dify API接口分析](#dify-api接口分析)
3. [前端页面对接实现](#前端页面对接实现)
4. [业务流程分析](#业务流程分析)
5. [技术架构图](#技术架构图)
6. [配置参数详解](#配置参数详解)
7. [数据流向分析](#数据流向分析)
8. [错误处理机制](#错误处理机制)
9. [性能优化建议](#性能优化建议)
## 系统概述
本考培练系统是一个基于 **Python + Vue3 + MySQL + FastAPI** 架构的智能教育平台与两个主要的AI平台进行深度对接
- **Dify平台**:用于动态题目生成和知识提取
- **Coze平台**用于AI陪练和智能对话
### 核心功能模块
- 动态考试题目生成基于Dify工作流
- 知识点提取与分析基于Dify工作流
- AI智能陪练基于Coze智能体
- 三轮考试机制(错题重练)
## Dify API接口分析
### 1. 主要接口端点
系统中使用了 **1个核心Dify API端点**
```
POST https://aiedu.ireborn.com.cn/v1/workflows/run
```
### 2. 使用的工作流Token
系统中发现了 **2个不同的工作流Token**
#### 2.1 动态题目生成工作流
- **Token**: `app-tDlrmXyS9NtWCShsOx5FH49L`
- **用途**: 根据考试ID和错题信息生成动态题目
- **文件位置**: `ExamsSystem/frontend/src/views/system/exams/start_exams.vue`
#### 2.2 知识提取工作流
- **Token**: `app-LZhZcMO6CiriLMOLB2PwUGHx`
- **用途**: 从考试附件中提取知识点
- **文件位置**: `ExamsSystem/frontend/src/views/system/exams/index.vue`
### 3. API请求参数详解
#### 3.1 动态题目生成API参数
```javascript
const payload = {
inputs: {
examsId: examId, // 考试ID必需
error: errorNums // 错题编号(可选,用于第二轮、第三轮)
},
response_mode: "blocking", // 同步模式
user: "abc-123" // 用户标识
};
```
**参数说明:**
- `examsId`: 当前考试的唯一标识符,用于工作流识别要生成哪个考试的题目
- `error`: 错题编号字符串,格式为逗号分隔的知识点编号,用于生成针对性的错题练习
- `response_mode`: 固定为"blocking",表示同步等待工作流执行完成
- `user`: 用户标识,固定为"abc-123"
#### 3.2 知识提取API参数
```javascript
const payload = {
inputs: {
examsTitle: exams_title, // 考试标题
file: [file], // 文件信息数组
examsId: row.id // 考试ID
},
response_mode: "blocking",
user: "abc-123"
};
// 文件对象结构
const file = {
transfer_method: "remote_url",
url: fileUrl, // 完整的文件URL
type: "document" // 文件类型
};
```
**参数说明:**
- `examsTitle`: 考试名称,帮助工作流理解文档内容的上下文
- `file`: 文件信息数组支持PDF等文档格式的知识提取
- `transfer_method`: 固定为"remote_url"表示通过URL方式传递文件
- `url`: 文件的完整访问URL支持相对路径自动补全为绝对路径
- `type`: 固定为"document",表示文档类型
### 4. API响应数据结构
#### 4.1 成功响应结构
```javascript
{
data: {
status: "succeeded", // 执行状态
outputs: {
result: [...] // 工作流输出结果
}
}
}
```
#### 4.2 题目数据结构
动态题目生成的响应数据中,`result`字段包含题目数组:
```javascript
[
{
topic: {
title: "题目内容", // 题目文本
options: {
opt1: "选项A",
opt2: "选项B",
opt3: "选项C",
opt4: "选项D"
}
},
correct: "A", // 正确答案
analysis: "解析内容", // 题目解析
know_title: "知识点编号" // 知识点标识
}
]
```
## 前端页面对接实现
### 1. 核心页面文件
#### 1.1 考试开始页面 (`start_exams.vue`)
- **路径**: `ExamsSystem/frontend/src/views/system/exams/start_exams.vue`
- **功能**: 动态题目生成、三轮考试机制、错题统计
- **关键函数**: `callDifyWorkflow()`
#### 1.2 考试管理页面 (`index.vue`)
- **路径**: `ExamsSystem/frontend/src/views/system/exams/index.vue`
- **功能**: 知识提取、考试管理
- **关键函数**: `update_know()`
#### 1.3 AI陪练页面 (`training.vue`)
- **路径**: `ExamsSystem/frontend/src/views/system/exams/training.vue`
- **功能**: 嵌入Coze聊天界面
- **实现方式**: iframe嵌入
### 2. 前端调用实现
#### 2.1 动态题目生成调用
```javascript
async function callDifyWorkflow(error = '') {
loading.value = true;
const url = "https://aiedu.ireborn.com.cn/v1/workflows/run";
const token = 'app-tDlrmXyS9NtWCShsOx5FH49L';
const payload = {
inputs: { examsId: examId },
response_mode: "blocking",
user: "abc-123"
};
// 错题重练时添加错题参数
if (error) {
payload.inputs.error = error;
}
try {
const res = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
const data = await res.json();
if (data.data.status != 'succeeded') throw new Error("请求失败");
questions.value = data.data.outputs.result;
loading.value = false;
return data;
} catch (err) {
console.error("Dify 工作流调用异常:", err);
loading.value = false;
return null;
}
}
```
#### 2.2 知识提取调用
```javascript
async function update_know(row) {
// 获取考试附件信息
const exams_title = row.title || '';
const fileList = Array.isArray(row.attachmentList) ? row.attachmentList : [];
if (!fileList.length) {
proxy.$modal.msgWarning("该考试没有附件,无法提取知识!");
return;
}
// 构建文件对象
const fileUrl = fileList[0].fileUrl || fileList[0].url || '';
const file = {
transfer_method: "remote_url",
url: fileUrl.startsWith('http') ? fileUrl : `https://aiedu.ireborn.com.cn${fileUrl}`,
type: "document"
};
const payload = {
inputs: {
examsTitle: exams_title,
file: [file],
examsId: row.id
},
response_mode: "blocking",
user: "abc-123"
};
const token = "app-LZhZcMO6CiriLMOLB2PwUGHx";
const url = "https://aiedu.ireborn.com.cn/v1/workflows/run";
proxy.$modal.loading("正在提取知识,请稍候...");
try {
const res = await fetch(url, {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify(payload)
});
if (!res.ok) {
proxy.$modal.msgError("知识提取失败!");
return;
}
const data = await res.json();
proxy.$modal.msgSuccess("知识提取成功!");
console.log("Dify知识提取结果:", data);
} catch (err) {
proxy.$modal.closeLoading();
proxy.$modal.msgError("知识提取异常!");
console.error("Dify知识提取异常:", err);
}
}
```
### 3. 前端状态管理
#### 3.1 考试状态管理
```javascript
// 核心状态变量
const questions = ref([]); // 题目数组
const loading = ref(true); // 加载状态
const currentIndex = ref(0); // 当前题目索引
const selected = ref(''); // 选中答案
const answered = ref(false); // 是否已答题
const score = ref(0); // 当前分数
const wrongQuestions = ref([]); // 错题记录
const round = ref(1); // 当前轮次 (1,2,3)
// 三轮成绩记录
const firstRoundScore = ref(0);
const firstRoundTime = ref(null);
const secondRoundScore = ref(0);
const secondRoundTime = ref(null);
const thirdRoundScore = ref(0);
const thirdRoundTime = ref(null);
```
#### 3.2 轮次流转逻辑
```javascript
// 第二轮:基于第一轮错题
function restartWithWrongQuestions() {
const errorNums = wrongQuestions.value.map(item => item.title).join(',');
// 重置状态
currentIndex.value = 0;
score.value = 0;
wrongQuestions.value = [];
round.value = 2;
// 调用Dify生成针对性题目
callDifyWorkflow(errorNums);
}
// 第三轮:基于第二轮错题
function restartWithThirdQuestions() {
const errorNums = wrongQuestions.value.map(item => item.title).join(',');
// 重置状态
currentIndex.value = 0;
score.value = 0;
thirdWrongQuestions.value = [...wrongQuestions.value];
wrongQuestions.value = [];
round.value = 3;
// 调用Dify生成针对性题目
callDifyWorkflow(errorNums);
}
```
## 业务流程分析
### 1. 动态考试流程
```mermaid
graph TD
A[用户选择考试] --> B[获取考试ID]
B --> C[调用Dify工作流]
C --> D[生成第一轮题目]
D --> E[用户答题]
E --> F[记录错题]
F --> G{是否完成所有题目}
G -->|否| E
G -->|是| H[显示第一轮成绩]
H --> I{用户选择第二轮}
I -->|是| J[传递错题信息给Dify]
J --> K[生成第二轮针对性题目]
K --> L[用户答题]
L --> M[记录错题]
M --> N{是否完成所有题目}
N -->|否| L
N -->|是| O[显示第二轮成绩]
O --> P{用户选择第三轮}
P -->|是| Q[传递第二轮错题给Dify]
Q --> R[生成第三轮题目]
R --> S[完成三轮考试]
S --> T[保存最终成绩]
```
### 2. 知识提取流程
```mermaid
graph TD
A[管理员上传考试附件] --> B[点击知识提取按钮]
B --> C[获取附件URL]
C --> D[构建文件对象]
D --> E[调用Dify知识提取工作流]
E --> F[Dify处理PDF文档]
F --> G[提取知识点]
G --> H[返回提取结果]
H --> I[前端显示成功消息]
```
### 3. AI陪练流程
```mermaid
graph TD
A[用户进入陪练页面] --> B[iframe加载Coze聊天界面]
B --> C[用户发送语音/文本]
C --> D[Coze智能体处理]
D --> E[返回AI回复]
E --> F[支持语音合成]
F --> G[用户继续对话]
G --> C
```
## 技术架构图
### 1. 整体架构
```mermaid
graph TB
subgraph "前端层 (Vue3)"
A1[考试管理页面]
A2[动态考试页面]
A3[AI陪练页面]
end
subgraph "后端层 (FastAPI)"
B1[考试管理API]
B2[成绩管理API]
B3[文件管理API]
end
subgraph "AI平台层"
C1[Dify工作流]
C2[Coze智能体]
end
subgraph "数据层"
D1[MySQL数据库]
D2[文件存储]
end
A1 --> B1
A2 --> C1
A3 --> C2
A2 --> B2
B1 --> D1
B2 --> D1
B3 --> D2
C1 --> D2
```
### 2. Dify集成架构
```mermaid
graph LR
subgraph "前端"
A[Vue组件]
end
subgraph "Dify平台"
B[工作流引擎]
C[题目生成工作流]
D[知识提取工作流]
end
A -->|HTTP POST| B
B --> C
B --> D
C -->|题目数据| A
D -->|知识点数据| A
```
## 配置参数详解
### 1. 系统配置
#### 1.1 域名配置
- **主域名**: `https://aiedu.ireborn.com.cn`
- **API端点**: `/v1/workflows/run`
- **文件服务**: `/dev-api/profile/upload/`
#### 1.2 工作流配置
| 功能 | Token | Bot ID | 用途 |
|------|-------|--------|------|
| 题目生成 | app-tDlrmXyS9NtWCShsOx5FH49L | - | 根据考试ID和错题生成动态题目 |
| 知识提取 | app-LZhZcMO6CiriLMOLB2PwUGHx | - | 从PDF文档中提取知识点 |
| 高情商回复 | - | 7509380917472280617 | AI智能回复 |
| 咨询师陪练 | - | 7509379008556089379 | 语音陪练 |
| 动态考题 | - | 7509379046204162074 | 动态题目生成 |
### 2. 环境配置
#### 2.1 前端配置 (`vite.config.js`)
```javascript
server: {
host: '0.0.0.0',
port: 80,
proxy: {
'/dev-api': {
target: 'https://aiedu.ireborn.com.cn',
changeOrigin: true,
rewrite: (p) => p.replace(/^\/dev-api/, '')
}
}
}
```
#### 2.2 后端配置 (`config/env.py`)
```python
app_host: str = 'https://aiedu.ireborn.com.cn/'
```
## 数据流向分析
### 1. 题目生成数据流
```
用户操作 → Vue组件状态 → Dify API调用 → 工作流处理 → 题目数据返回 → 前端渲染
```
**详细流程:**
1. 用户点击开始考试
2. 获取URL参数中的`examId`
3. 调用`callDifyWorkflow(examId)`
4. 发送POST请求到Dify工作流
5. 工作流根据`examsId`生成题目
6. 返回JSON格式的题目数组
7. 前端解析数据并渲染题目界面
### 2. 错题重练数据流
```
错题收集 → 错题编号拼接 → Dify API调用(带error参数) → 针对性题目生成 → 前端渲染
```
**详细流程:**
1. 第一轮答题过程中收集错题
2. 将错题的`know_title`字段拼接成字符串
3. 调用`callDifyWorkflow(errorNums)`
4. Dify工作流根据错题信息生成针对性题目
5. 返回专门针对薄弱知识点的题目
6. 前端进入第二轮/第三轮答题模式
### 3. 知识提取数据流
```
文件上传 → 附件URL获取 → Dify API调用 → PDF解析 → 知识点提取 → 结果返回
```
**详细流程:**
1. 管理员在考试管理页面上传PDF附件
2. 系统生成文件访问URL
3. 点击"知识提取"按钮触发`update_know()`
4. 构建包含文件URL的请求参数
5. 调用Dify知识提取工作流
6. 工作流下载并解析PDF文档
7. 提取关键知识点并返回结果
## 错误处理机制
### 1. API调用错误处理
#### 1.1 网络错误处理
```javascript
try {
const res = await fetch(url, options);
const data = await res.json();
// 处理成功响应
} catch (err) {
console.error("Dify 工作流调用异常:", err);
loading.value = false;
return null;
}
```
#### 1.2 业务错误处理
```javascript
if (data.data.status != 'succeeded') {
throw new Error("请求失败");
}
```
#### 1.3 用户提示机制
```javascript
// 成功提示
proxy.$modal.msgSuccess("知识提取成功!");
// 警告提示
proxy.$modal.msgWarning("该考试没有附件,无法提取知识!");
// 错误提示
proxy.$modal.msgError("知识提取失败!");
// 加载提示
proxy.$modal.loading("正在提取知识,请稍候...");
proxy.$modal.closeLoading();
```
### 2. 数据验证机制
#### 2.1 前端验证
- 检查考试ID是否存在
- 验证附件列表是否为空
- 确认URL格式正确性
#### 2.2 响应数据验证
- 检查`data.data.status`是否为"succeeded"
- 验证`data.data.outputs.result`是否存在
- 确保题目数据结构完整
## 性能优化建议
### 1. 前端优化
#### 1.1 请求优化
- **缓存机制**: 对相同考试ID的题目进行本地缓存
- **请求去重**: 防止用户快速点击导致的重复请求
- **超时处理**: 设置合理的请求超时时间
#### 1.2 用户体验优化
- **加载状态**: 显示详细的加载进度和状态
- **错误重试**: 提供手动重试机制
- **离线支持**: 缓存已生成的题目支持离线答题
### 2. 后端优化
#### 2.1 API性能
- **连接池**: 使用HTTP连接池减少连接开销
- **异步处理**: 对于知识提取等耗时操作使用异步处理
- **结果缓存**: 缓存Dify工作流的执行结果
#### 2.2 监控告警
- **API监控**: 监控Dify API的响应时间和成功率
- **错误日志**: 记录详细的错误日志便于问题排查
- **性能指标**: 统计题目生成时间和知识提取效率
### 3. Dify工作流优化
#### 3.1 工作流设计
- **参数验证**: 在工作流中添加输入参数验证
- **错误处理**: 完善工作流内部的错误处理逻辑
- **性能调优**: 优化工作流的执行效率
#### 3.2 资源管理
- **并发控制**: 控制同时执行的工作流数量
- **资源限制**: 设置合理的内存和CPU使用限制
- **成本优化**: 监控和优化AI模型的调用成本
## 总结
本考培练系统通过与Dify平台的深度对接实现了智能化的题目生成和知识提取功能。系统采用了成熟的技术架构具备良好的扩展性和可维护性。主要特点包括
1. **智能题目生成**: 基于考试内容和学员错题情况动态生成个性化题目
2. **三轮考试机制**: 通过多轮练习帮助学员巩固薄弱知识点
3. **知识自动提取**: 从PDF文档中自动提取关键知识点
4. **AI智能陪练**: 结合Coze平台提供语音陪练功能
系统在实现上注重用户体验和错误处理,具备较强的实用性和稳定性。建议在后续开发中进一步优化性能和扩展功能模块。
---
**文档版本**: v1.0
**生成时间**: 2025年9月20日
**分析范围**: ExamsSystem、coze-chat-backend、coze-chat-frontend模块