# k12-AI私教平台

**Repository Path**: yang-changqing/k12

## Basic Information

- **Project Name**: k12-AI私教平台
- **Description**: 
K12 AI 私教平台是一款专注于 K12 阶段的 AI 个性化辅导系统，采用苏格拉底式引导教学方法，结合知识图谱和 RAG 检索增强生成技术，为学生提供智能答疑、错题本管理、个性化学习路径等功能。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 1
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# K12 AI 私教平台 (完整版)

> 基于 Java JDK17 + Vue3 的 K12 个性化 AI 辅导平台
>
> 👉 **当前版本：v1.0.0 完整版** - 已完成学生端、家长端、管理端三端全功能开发

## 项目简介

K12 AI 私教平台是一款专注于 K12 阶段的 AI 个性化辅导系统，采用苏格拉底式引导教学方法，结合知识图谱和 RAG 检索增强生成技术，为学生提供智能答疑、错题本管理、个性化学习路径等功能。

## ✨ 核心特性

### 🎓 AI 智能功能
- 🧠 **AI 学习助手** - 支持自由问答、知识点讲解、学习方法建议
- 📝 **AI 作文批改** - 语文/英语作文智能评分、逐句点评、优化建议
- 📊 **AI 错题分析** - 深度分析错误类型、原因，提供同类题推荐
- 📈 **AI 学情报告** - 智能分析学习数据，生成个性化报告
- 🤖 **AI 题目生成** - 一键生成高质量练习题，支持自定义难度和知识点

### 📚 学习功能
- 🔊 **英语听力练习** - AI 语音播报，支持多档语速调节
- 📖 **智能题库** - K12全年级9学科覆盖，670+道题目
- 🗺️ **知识图谱** - 270+知识点的图谱化管理
- ✅ **在线练习** - 选择题、填空题、解答题多种题型
- 📋 **错题本** - 自动收集错题，支持导出和打印

### 👨‍👩‍👧 多端支持
- 👨‍🎓 **学生端** - 学习看板、智能答疑、在线练习、学习记录、能力预测
- 👪 **家长端** - 孩子学习看板、学习统计、错题分析、AI 学情报告
- 🔧 **管理端** - 数据统计、用户管理、知识点管理、题库管理、AI 功能管理

### 🎨 交互体验
- 💬 **TTS 语音播报** - 中英文支持，语速音调音量可调
- ✨ **功能许愿池** - 用户可提交功能建议，点赞支持，透明化处理进度
- 📱 **响应式设计** - 适配多种屏幕尺寸
- 🌙 **深色模式** - 保护视力

## 🛠️ 技术栈

### 后端技术栈
| 技术组件 | 版本 | 用途 |
|---------|------|------|
| JDK | 17 | 核心开发环境 |
| Spring Boot | 3.2.x | 后端主框架 |
| MyBatis-Plus | 3.5.x | ORM 框架 |
| MySQL | 8.0 | 关系型数据库 |
| Redis | 7.x+ | 缓存层 |
| LangChain4j | 支持接入 | 大模型集成框架 |
| Knife4j | 4.4.x | API 文档 |
| HuTool | 5.8.x | 工具类库 |

### 前端技术栈
| 技术组件 | 版本 | 用途 |
|---------|------|------|
| Vue 3 | 3.4.x | 前端核心框架 |
| Vite | 5.x | 构建工具 |
| Element Plus | 2.6.x | UI 组件库 |
| Pinia | 2.1.x | 状态管理 |
| Vue Router | 4.3.x | 路由管理 |
| Axios | 1.6.x | HTTP 客户端 |
| ECharts | 5.4.x | 图表库 |
| Marked | 12.x | Markdown 渲染 |

## 📁 项目结构

```
k12/
├── k12-backend/                 # 后端 Spring Boot 项目
│   ├── src/main/java/com/k12/tutor/
│   │   ├── controller/          # 控制器层
│   │   │   ├── AuthController      # 认证接口
│   │   │   ├── QaController        # 答疑接口
│   │   │   ├── AIController        # AI 智能功能接口
│   │   │   ├── FeedbackController  # 功能反馈接口
│   │   │   ├── AdminQuestionController # 题库管理
│   │   │   ├── AdminKnowledgeController # 知识点管理
│   │   │   └── ...
│   │   ├── service/             # 服务层
│   │   ├── mapper/              # 数据访问层
│   │   ├── entity/              # 实体类
│   │   ├── dto/                 # 数据传输对象
│   │   └── config/              # 配置类
│   ├── sql/                     # 数据库脚本
│   └── pom.xml
│
├── k12-web/                     # 统一前端应用（学生/家长/管理三端合一）
│   ├── src/
│   │   ├── api/                 # API 接口封装
│   │   ├── components/          # 公共组件
│   │   ├── router/              # 路由配置（角色动态路由）
│   │   ├── stores/              # Pinia 状态管理
│   │   ├── utils/               # 工具函数
│   │   └── views/               # 页面
│   │       ├── login/             # 登录注册
│   │       ├── study/             # 学习相关
│   │       │   ├── ai-tutor.vue    # AI 学习助手
│   │       │   ├── answer.vue      # 答题页面
│   │       │   └── listening.vue   # 英语听力
│   │       ├── knowledge/         # 知识点管理
│   │       ├── question/          # 题库管理
│   │       ├── parent/            # 家长端页面
│   │       ├── admin/             # 管理端页面
│   │       ├── feedback/          # 功能反馈
│   │       │   └── wish-pool.vue  # 功能许愿池
│   │       └── layout/            # 布局组件
│   └── package.json
│
├── sql/                          # 数据库初始化脚本
├── docs/                         # 文档
├── QUICKSTART.md                 # 快速启动指南
├── ROADMAP.md                    # 开发路线图
└── README.md                     # 本文件
```

## 🚀 快速开始

### 环境要求
- JDK 17+
- MySQL 8.0+
- Redis 7.x+ (可选，Mock模式可不启动)
- Node.js 20.x+
- Maven 3.8+

### 一、数据库初始化

```bash
# 创建数据库
mysql -u root -p -e "CREATE DATABASE k12_tutor DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 执行初始化脚本
mysql -u root -p k12_tutor < k12-backend/sql/init.sql
```

### 二、后端启动

1. 修改配置文件 `k12-backend/src/main/resources/application.yml`
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/k12_tutor?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false
    username: root
    password: 你的数据库密码
  data:
    redis:
      host: localhost
      port: 6379
      password: 你的Redis密码（如无则留空）

# AI 配置（可选，Mock模式下无需配置即可体验所有功能）
ai:
  provider: mock  # 可选值: mock / openai / qwen / ernie
  api-key:        # 真实大模型API Key
```

2. 启动项目
```bash
cd k12-backend
mvn spring-boot:run
```

3. 接口文档地址: http://localhost:8080/api/doc.html

### 三、前端启动

```bash
cd k12-web
npm install
npm run dev
```

访问: http://localhost:3000

### Docker 一键启动（可选）

```bash
docker-compose up -d
```

详细启动说明请查看 [QUICKSTART.md](./QUICKSTART.md)

## 🎯 功能清单

### 学生端功能
| 功能模块 | 功能名称 | 状态 | 说明 |
|---------|---------|------|------|
| **学习中心** | 学习看板 | ✅ | 学习数据可视化、今日任务 |
| | 学习计划 | ✅ | 学习任务安排、进度跟踪 |
| | 学习记录 | ✅ | 历史学习记录查看 |
| | 学习日历 | ✅ | 学习日历视图展示 |
| **AI 智能** | AI 学习助手 | ✅ | 多模式智能问答 |
| | 错题深度分析 | ✅ | AI 分析错误原因 |
| | 作文智能批改 | ✅ | 评分、点评、范文生成 |
| | 能力预测分析 | ✅ | 学习能力趋势预测 |
| **在线练习** | 题库练习 | ✅ | 分学科分年级练习 |
| | 英语听力 | ✅ | AI 语音播报，多档语速 |
| | TTS 语音播报 | ✅ | 题目朗读、答案朗读 |
| **错题本** | 错题管理 | ✅ | 错题列表、标记掌握程度 |
| | 错题分析 | ✅ | AI 智能分析建议 |
| | 导出/打印 | ✅ | 支持导出和打印 |
| **知识图谱** | 知识点学习 | ✅ | 知识点体系可视化 |
| **个人中心** | 个人信息 | ✅ | 信息修改、设置 |

### 家长端功能
| 功能模块 | 功能名称 | 状态 | 说明 |
|---------|---------|------|------|
| **孩子学习** | 学习看板 | ✅ | 孩子学习总览 |
| | 学习统计 | ✅ | 学习数据统计图表 |
| **AI 分析** | 错题分析 | ✅ | 孩子错题智能分析 |
| | AI 学情报告 | ✅ | 个性化学习报告生成 |
| **教育建议** | 家庭教育建议 | ✅ | AI 生成个性化建议 |
| **反馈** | 功能许愿池 | ✅ | 提交功能建议 |

### 管理端功能
| 功能模块 | 功能名称 | 状态 | 说明 |
|---------|---------|------|------|
| **数据统计** | 数据看板 | ✅ | 用户、题目、学习数据统计 |
| **用户管理** | 学生管理 | ✅ | 学生信息管理 |
| | 家长管理 | ✅ | 家长信息管理 |
| **内容管理** | 知识点管理 | ✅ | 知识点增删改查 |
| | 题库管理 | ✅ | 题目增删改查 |
| | 一键初始化 | ✅ | 670+题批量初始化 |
| **AI 功能** | AI 题目生成 | ✅ | 智能生成练习题 |
| | 内容质量分析 | ✅ | AI 审核题库内容 |
| **反馈管理** | 功能建议管理 | ✅ | 用户反馈处理 |
| | 功能许愿池 | ✅ | 查看用户需求 |

## 🎁 AI 功能详解

### AI 学习助手
- 5种对话模式：自由问答、知识点讲解、错题分析、作文批改、学习方法建议
- 支持 Markdown 格式回答
- 相关知识点关联推荐
- 后续问题智能推荐

### AI 错题分析
- 自动识别错误类型
- 深度分析错误原因
- 提供同类题推荐
- 生成个性化巩固建议

### AI 作文批改
- 智能评分（0-100分）
- 详细总体评价
- 逐句点评与修改建议
- 优化后的范文生成

### AI 学情报告
- 多维学习数据统计
- 优势/薄弱科目分析
- 个性化学习建议
- 下一阶段目标规划

### AI 题目生成
- 支持 K12 全学科
- 1-12 年级全覆盖
- 3档难度可调
- 自定义知识点范围
- 题型比例可配置

## 🌟 功能许愿池

平台内置功能许愿池，欢迎各位用户提出宝贵建议！

**特色功能：**
- 提交功能建议 / 问题反馈 / 使用体验
- 点赞支持你喜欢的建议
- 透明化处理进度（评估中 → 开发中 → 已实现）
- 官方回复及时同步
- 已实现功能展示墙

## 🔑 默认账号

| 角色 | 用户名 | 密码 | 说明 |
|------|--------|------|------|
| 管理员 | admin | admin123 | 管理后台全部权限 |
| 测试学生 | student1 | student123 | 学生端完整功能 |
| 测试家长 | parent1 | parent123 | 家长端完整功能 |

## 📐 API 接口示例

### 登录接口
```bash
POST /api/auth/login
Content-Type: application/json

{
  "username": "student1",
  "password": "student123"
}
```

### AI 对话接口
```bash
POST /api/ai/chat
Content-Type: application/json

{
  "sessionId": "xxx",
  "message": "帮我讲解一下一元二次方程",
  "chatType": "knowledge"
}
```

更多接口文档请访问: http://localhost:8080/api/doc.html

## 🗺️ 开发路线图

### 已完成 ✅ (v1.0.0)
- ✅ 项目框架搭建
- ✅ 数据库设计与初始化
- ✅ 学生端 Web 应用（全功能）
- ✅ 家长端 Web 应用（全功能）
- ✅ 管理后台 Web 应用（全功能）
- ✅ AI 智能功能（学习助手、错题分析、作文批改、题目生成）
- ✅ 英语听力练习 + TTS 语音播报
- ✅ 题库一键初始化（670+题，9学科）
- ✅ 知识点一键初始化（270+知识点）
- ✅ 功能许愿池用户反馈系统
- ✅ Docker 容器化支持

### 下一阶段规划 🚧
- 📱 家长端小程序开发
- 🤖 接入真实大模型 API（OpenAI / 通义千问 / 文心一言）
- 📷 OCR 拍照搜题功能
- 🔍 RAG 向量检索与知识图谱
- 📊 自适应学习算法
- 🎮 学习激励与成就系统

详细路线图请查看 [ROADMAP.md](./ROADMAP.md)

## 📚 相关文档

- [快速启动指南](./QUICKSTART.md) - 详细的环境搭建和启动步骤
- [开发路线图](./ROADMAP.md) - 功能开发计划与里程碑
- [操作手册](./K12平台操作手册.md) - 平台使用详细说明

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

也可以通过**功能许愿池**提交你的想法，我们会认真评估每一条建议！

## 📄 许可证

MIT License - 查看 [LICENSE](LICENSE) 文件了解详情

## 📞 联系方式

如有问题或建议，欢迎：
1. 通过平台内「功能许愿池」提交反馈
2. 提交 Issue
3. 直接联系项目维护者

---

**如果这个项目对你有帮助，请给个 ⭐ Star 支持一下！**

Made with ❤️ for K12 Education