# edu-companion-system

**Repository Path**: swner_admin/edu-companion-system

## Basic Information

- **Project Name**: edu-companion-system
- **Description**: 教育智能伴学系统 - AI驱动的教学可视化对话平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-02-10
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 教育智能伴学系统

基于 AI 的智能教育平台，集成教学可视化对话、作业自动批改、学情分析等功能。

![系统架构](docs/images/architecture.svg)

## 核心亮点

- **教学可视化对话** — AI 驱动的多轮对话，自动生成 7 种可视化图表（概念图、流程图、函数图、几何图等），内联展示在对话流中
- **LaTeX + Markdown 渲染** — 对话内容支持数学公式和富文本格式化，交互效果完整
- **多轮上下文保持** — AI 理解之前生成的可视化内容，支持逐步深入的教学对话
- **标准案例库** — 内置 22+ 教学案例（含高考真题），支持一键多轮演示
- **一键导出** — 完整对话（含可视化）导出为高清图片

## 功能演示

### 对话界面

![对话演示](docs/images/chat-demo.svg)

### 可视化模板

![模板示例](docs/images/templates.svg)

### 多轮对话流程

![多轮对话](docs/images/multi-turn-flow.svg)

## 功能模块

### 1. 教学可视化对话
- 输入教学问题，AI 自动生成结构化可视化
- 支持 7 种模板：概念图、流程图、时间线、对比表、柱状图、函数图、几何图
- Canvas 2D 渲染，支持坐标轴、刻度、数学符号
- 内置规则兜底机制，确保可视化生成稳定性
- 案例库支持多轮逐步演示

### 2. 作业自动批改与个性化练习
- 教师布置作业，提交答案与思路
- 学生通过学伴获取并提交作业
- AI 智能批改，支持主观题自动评分
- 智能错题本，个性化推荐练习

### 3. 学情面板统计与展示
- 学生个体画像：成绩、排名、知识点掌握
- 班级整体分析：分数分布、临界生识别
- 知识点追踪：薄弱点分析、进步趋势

### 4. 题库与智能组卷
- 题目管理：分类、标签、难度
- 智能组卷：按知识点、难度组合
- 导出 PDF/Word，支持打印

## 技术架构

```
edu-companion-system/
├── backend/                    # 后端服务 (FastAPI + SQLAlchemy)
│   ├── app/
│   │   ├── api/v1/            # API 路由
│   │   ├── models/            # 数据模型 (SQLAlchemy ORM)
│   │   ├── schemas/           # Pydantic 校验模型
│   │   ├── services/          # 业务逻辑层
│   │   │   └── visual_chat.py # 可视化对话核心服务
│   │   ├── data/              # 种子数据 (案例库 JSON)
│   │   └── core/              # 配置、安全、数据库
│   └── requirements.txt
├── frontend/                   # 前端 (Vue 3 + Element Plus)
│   └── src/
│       ├── views/
│       │   └── visualization/ # 可视化对话页面
│       ├── utils/
│       │   └── canvasTemplates.js  # 7 种 Canvas 渲染模板
│       ├── api/               # Axios API 封装
│       ├── router/            # Vue Router
│       └── stores/            # Pinia 状态管理
├── api_center/                # AI API 配置
├── docs/                      # 文档与示意图
├── docker-compose.yml         # Docker 编排
└── README.md
```

### 技术栈

| 层级 | 技术 |
|------|------|
| 前端框架 | Vue 3 (Composition API) + Vite |
| UI 组件 | Element Plus |
| 可视化 | Canvas 2D API (自研 7 模板) |
| 公式渲染 | KaTeX |
| 文本格式 | Marked (Markdown) |
| 图片导出 | html2canvas |
| 后端框架 | FastAPI (async) |
| ORM | SQLAlchemy 2.0 (async) |
| 数据库 | PostgreSQL |
| AI 服务 | 火山引擎 / 豆包大模型 API |

## 快速开始

### 前置要求

- Python 3.10+
- Node.js 18+
- PostgreSQL 14+

### 1. 启动数据库

```bash
# Docker 方式
docker-compose up -d postgres

# 或使用本地 PostgreSQL
```

### 2. 启动后端

```bash
cd backend
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 填入数据库连接和 AI API 密钥

# 启动服务
python run.py
```

### 3. 启动前端

```bash
cd frontend
npm install
npm run dev
```

访问 http://localhost:5173 即可使用。

## API 文档

启动后端后访问：
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

### 核心 API

#### 可视化对话
- `POST /api/v1/visual-chat/session` — 创建会话
- `POST /api/v1/visual-chat/send` — 发送消息（返回文本 + 可视化数据）
- `POST /api/v1/visual-chat/session/{id}/reset` — 重置会话
- `GET /api/v1/visual-chat/templates` — 获取模板列表
- `GET /api/v1/visual-chat/cases` — 获取案例库

#### 作业管理
- `POST /api/v1/assignments/` — 创建作业
- `POST /api/v1/assignments/{id}/publish` — 发布作业
- `POST /api/v1/assignments/batch-grade` — 批量 AI 批改
- `POST /api/v1/assignments/submit` — 提交作业

#### 学情分析
- `GET /api/v1/learning/profile` — 学习画像
- `GET /api/v1/learning/wrong-questions` — 错题本
- `GET /api/v1/learning/recommendations` — 个性化推荐

#### 题库
- `GET /api/v1/questions/` — 查询题目
- `POST /api/v1/questions/exam-paper/export` — 导出试卷

## 数据库结构

主要表：
- `users` — 用户（教师/学生）
- `classrooms` — 班级
- `questions` — 题目
- `assignments` — 作业
- `assignment_submissions` — 作业提交
- `wrong_questions` — 错题本
- `student_profiles` — 学生画像
- `learning_records` — 学习记录
- `visual_cases` — 可视化案例库

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| DATABASE_URL | PostgreSQL 连接 | postgresql+asyncpg://... |
| REDIS_URL | Redis 连接 | redis://localhost:6379/0 |
| SECRET_KEY | JWT 密钥 | - |
| VOLC_API_KEY_PATH | 火山引擎 API 密钥路径 | - |
| VOLC_MODEL_ENDPOINT | AI 模型端点 | - |
| CORS_ORIGINS | 允许的跨域来源 | http://localhost:5173 |

## 开发计划

- [x] Phase 1: 作业管理与 AI 批改
- [x] Phase 2: 教学可视化对话（7 模板 + 多轮上下文 + 案例库）
- [x] Phase 3: 前端 Vue 3 界面（对话 + LaTeX + Markdown + 导出）
- [ ] Phase 4: 完整学情面板（学生/班级画像、错题本、推荐）
- [ ] Phase 5: 辅助备课功能（备课建议、推题与课堂反馈闭环）

## License

MIT