Smart Guide 是一个面向课程学习场景的智能导学平台原型。系统围绕学生学习过程中的课程检索、学习进度、练习反馈、薄弱知识点诊断、个性化推荐和师生社区管理进行设计，并提供管理员端用于维护课程、题库、公告、论坛和用户数据。
项目采用前后端分离结构：后端基于 Spring Boot 3、Spring Data JPA 和 MySQL 实现 REST API 与业务逻辑；前端基于 Vue 3、Vue Router、Element Plus、ECharts 和 Axios 实现交互界面与学习数据可视化。
公开仓库说明：本仓库保留源码、配置、依赖清单和示例 SQL 数据，不包含
node_modules/、target/、构建产物、IDE 配置、压缩包或本地数据库密码。数据库连接信息已改为环境变量占位，避免公开硬编码本地凭据。
本项目不是单一的 CRUD 示例，而是围绕“导学”任务组织的学习支持系统。系统将课程资源、学生行为、练习结果、知识点关系和推荐逻辑放在同一数据模型中，形成从学习行为记录到学习反馈生成的闭环。
主要目标包括：
- 为学生提供课程学习、收藏、练习、笔记、学习统计和论坛交流入口。
- 基于答题记录和知识点关联关系生成掌握度与薄弱点诊断。
- 基于学习记录、收藏行为、课程分类和相似用户行为生成课程推荐。
- 为管理员提供用户、课程、分类、题库、公告、论坛和举报处理能力。
- 使用图表和知识图谱形式展示学习状态，降低学习数据的理解成本。
| 层级 | 技术 |
|---|---|
| 后端 | Java 21, Spring Boot 3, Spring Web, Spring Data JPA, Lombok |
| 数据库 | MySQL |
| 前端 | Vue 3, Vue Router, Element Plus, ECharts, Axios, Vite |
| 构建 | Maven, npm |
| 数据初始化 | SQL seed scripts |
学生端首页聚合继续学习、收藏、练习入口、系统公告和课程推荐。
课程详情页包含练习题、答题进度、答案提交和课程笔记等学习过程功能。
学情诊断页展示知识图谱、分类掌握度、薄弱知识点和推荐练习题。
管理端汇总用户、课程、论坛和举报处理状态，并提供各类管理入口。
题库管理支持按课程维护题目，并为学情诊断绑定知识点关系。
- 登录与密码修改
- 课程列表、搜索与分类筛选
- 课程详情、学习进度推进与课程笔记
- 课程收藏与“我的收藏”
- 课程练习、答案解析与答题记录
- 学情诊断、薄弱知识点和推荐题目
- 学习统计图表
- 个性化课程推荐与继续学习
- 论坛发帖、回帖、举报
- 公告与个人通知查看
- 系统概览统计
- 用户管理
- 课程管理
- 课程分类管理
- 题库管理
- 题目与知识点关系维护
- 公告管理
- 论坛分类与帖子管理
- 举报处理
系统将练习题与知识点建立多对多关系，并为关系设置权重。学生提交答案后，后端根据答题正确性、题目关联知识点和权重计算知识点掌握度。
诊断服务输出三类结果：
- 知识点掌握度列表
- 薄弱知识点列表和推荐练习题
- 知识点图谱节点与边关系
掌握度状态按阈值划分为“未练习、薄弱、中等、掌握”，前端使用 ECharts 对结果进行可视化。
推荐逻辑采用混合策略，主要使用以下信号：
- 学生已学习课程所属分类
- 学生收藏课程所属分类
- 相似学生的学习记录
- 全局课程学习热度
- 已学习课程过滤与已完成课程过滤
- 冷启动用户的热门课程回退策略
该策略不是复杂机器学习模型，而是可解释的规则与协同过滤混合推荐，适合课程资源规模较小、行为数据稀疏的教学系统原型。
管理员端负责维护课程、分类、题库、知识点、公告、论坛内容和举报记录。学生端产生的学习行为和答题行为反过来用于学习统计、诊断和推荐，从而形成“内容维护 - 学习行为 - 诊断反馈 - 推荐引导”的闭环。
smart-guide/
├── src/ # Spring Boot 后端源码
│ ├── main/java/com/guide/smartguide/
│ │ ├── controller/ # REST API 控制器
│ │ ├── entity/ # JPA 实体
│ │ ├── repository/ # 数据访问层
│ │ ├── service/ # 业务逻辑层
│ │ └── SmartGuideApplication.java
│ └── main/resources/
│ └── application.yml # 环境变量化后的公开配置
├── frontend/ # Vue 前端项目
│ ├── src/api/ # Axios API 封装
│ ├── src/router/ # 前端路由
│ ├── src/views/ # 学生端和管理端页面
│ ├── public/ # 静态资源
│ └── package.json
├── seed-data.sql # 扩展演示数据
├── seed-knowledge.sql # 知识点与题目关系演示数据
├── smart_guide.sql # 基础数据库结构/初始化数据
├── pom.xml
├── mvnw / mvnw.cmd
└── README.md
未纳入公开仓库的内容包括：
frontend/node_modules/frontend/dist/target/.idea/- 压缩包和本地构建产物
- 本地数据库密码或私有环境配置
公开版 application.yml 使用环境变量读取数据库连接信息：
spring:
datasource:
url: ${SPRING_DATASOURCE_URL:jdbc:mysql://localhost:3306/smart_guide?useSSL=false&serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=UTF-8}
username: ${SPRING_DATASOURCE_USERNAME:root}
password: ${SPRING_DATASOURCE_PASSWORD:}本地运行前请创建数据库：
CREATE DATABASE smart_guide CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;如果 MySQL 账号需要密码，请在运行后端前设置环境变量，例如 PowerShell：
$env:SPRING_DATASOURCE_USERNAME="root"
$env:SPRING_DATASOURCE_PASSWORD="your_mysql_password"或在 Linux/macOS/WSL 中：
export SPRING_DATASOURCE_USERNAME=root
export SPRING_DATASOURCE_PASSWORD=your_mysql_password然后按需要导入 SQL 文件：
mysql -u root -p smart_guide < smart_guide.sql
mysql -u root -p smart_guide < seed-data.sql
mysql -u root -p smart_guide < seed-knowledge.sqlSQL 脚本中的账号、姓名和邮箱均为演示数据。演示密码用于本地测试，不应作为生产系统的认证方案。
./mvnw spring-boot:runWindows PowerShell 可使用：
.\mvnw.cmd spring-boot:run后端默认端口为：
http://localhost:8080
cd frontend
npm install
npm run dev前端默认由 Vite 启动，实际访问地址以终端输出为准，通常为：
http://localhost:5173
导入示例数据后可使用以下账号测试：
| 角色 | 用户名 | 密码 |
|---|---|---|
| 管理员 | admin |
123456 |
| 学生 | student1 |
123456 |
这些账号仅用于本地演示。当前认证实现为课程设计/原型级别，未加入密码哈希、JWT、权限注解和审计日志等生产级安全机制。
- 使用 Controller / Service / Repository 分层组织后端逻辑。
- 用 JPA 实体表达用户、课程、学习记录、收藏、题目、知识点、公告、论坛和举报等核心对象。
- 将学习诊断逻辑集中在
DiagnosisService，把知识点关系与答题记录转化为掌握度、薄弱项和图谱数据。 - 将推荐逻辑集中在
RecommendationService，通过分类偏好、收藏行为、协同过滤和热度回退生成推荐列表。 - 前端按页面视图拆分学生端与管理端功能，使用 Axios 统一访问后端接口。
- 使用 ECharts 展示学习统计、分类掌握度和知识点图谱。
- 公开版配置移除了硬编码数据库密码，使用环境变量降低误提交风险。
- 认证流程为原型实现，演示账号密码为明文 seed 数据，不适合生产环境。
- 推荐算法是可解释的规则混合策略，不是大规模机器学习推荐系统。
- SQL 示例数据服务于功能演示，不代表真实教学数据。
- 前端背景图
frontend/public/image/bg-generated.png为本项目生成的原创界面示意图，用于降低外部素材授权风险。 - 当前系统默认依赖本地 MySQL，需要先完成数据库初始化。
本公开版已排除：
- 依赖目录：
node_modules/ - 后端构建产物：
target/ - IDE 配置：
.idea/ - 压缩包：
*.zip - 本地私密配置：
.env*、application-local.yml
如果后续继续维护仓库，请避免提交真实学生数据、真实邮箱、真实数据库备份、生产密码、访问令牌或部署服务器信息。