# StarVue3

**Repository Path**: dcesama/star-vue3

## Basic Information

- **Project Name**: StarVue3
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-16
- **Last Updated**: 2026-08-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 前端学院（LearnVue）

多邻国风格的交互式前端学习平台：以「关卡制 + 生命值 + 连胜 + 徽章 + XP」的玩法，通过选择题、填空题、排序题与代码沙箱题，系统学习 **HTML / CSS / JavaScript / Vue3**。

## 技术栈

| 端 | 技术 |
| --- | --- |
| 前端 `vue/` | Vue 3.5（`<script setup>` + TypeScript）、Pinia、Vue Router（Hash 模式）、Tailwind CSS 3、GSAP、CodeMirror 6、marked |
| 后端 `backend/` | Spring Boot 3.4（Java 21）、Spring Data JPA、MySQL、JWT（jjwt 0.12）、BCrypt |

## 目录结构

```
star-vue3/
├── vue/                        # 前端（Vite 工程）
│   └── src/
│       ├── api/                # 后端 API 封装（统一错误处理、Token 管理）
│       ├── components/         # 布局 / 关卡 / 学习地图 / 个人中心组件
│       ├── composables/        # 组合式函数（沙箱、礼花、本地存储等）
│       ├── data/               # 关卡、项目、游戏配置数据（核心数据源）
│       ├── router/             # 路由配置与登录守卫
│       ├── stores/             # Pinia：认证状态 / 用户进度 / 关卡运行状态
│       ├── types/              # 全局 TypeScript 类型定义
│       ├── utils/              # 沙箱测试执行器、校验工具
│       └── views/              # 页面视图（Home, Learn, Lesson, Profile 等）
│
└── backend/                    # 后端（Spring Boot 工程）
    └── src/main/
        ├── java/com/learnvue/
        │   ├── config/         # JWT 过滤器、跨域配置
        │   ├── controller/     # REST API 控制器
        │   ├── entity/         # JPA 实体类
        │   ├── repository/     # 数据访问层
        │   ├── service/        # 业务逻辑层
        │   └── util/           # JWT 工具类
        └── resources/          # 配置文件、数据库脚本
```

## 快速开始

### 1. 数据库（MySQL）

1. 确保本地 MySQL 服务运行在 `localhost:3306`。
2. 默认账号密码为 `root / root`（可在 `backend/src/main/resources/application.properties` 中修改）。
3. **注意**：后端启动时会自动执行 `schema.sql` 和 `data.sql` 初始化数据库结构与初始关卡数据（由 `spring.sql.init.mode=always` 控制）。

### 2. 启动后端（端口 3001）

```bash
cd backend
mvn spring-boot:run
```

### 3. 启动前端（端口 5173，`/api` 代理到 3001）

```bash
cd vue
npm install
npm run dev
```

浏览器访问 http://localhost:5173 即可体验。首次使用请先注册账号。

## 常用脚本（前端）

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动开发服务器（代理 `/api` → `localhost:3001`） |
| `npm run typecheck` | `vue-tsc --noEmit` 执行类型检查 |
| `npm run build` | 类型检查 + 生产环境构建 |

## 核心玩法

- **学习路径**：蛇形技能树结构，关卡具有前置依赖关系；完成后点亮星级并解锁下一关。
- **题型支持**：
    - 选择题、填空补全题
    - 拖拽排序题
    - **代码沙箱**（CodeMirror 编辑 + iframe 实时预览 + 自动化测试用例校验）。
- **游戏化机制**：
    - **生命值**：答错扣心，通关补满，错题复习答对可恢复。
    - **XP 与称号**：获取经验值提升等级。
    - **连胜系统**：记录连续学习天数。
    - **徽章墙**：达成特定条件自动授予并展示徽章。
- **错题本**：答错的题目自动记录，提供「错题复习」模式供强化记忆。
- **实战项目**：`js-project` 关卡进入项目页，需按需求文档完成代码并通过测试用例。
- **排行榜**：展示真实 XP 排名（需后端连接，否则使用前端模拟数据降级）。

## API 接口一览

| 方法 | 路径 | 说明 |
| --- | --- | --- |
| POST | `/api/auth/register` | 注册用户（用户名 ≥2 字符，密码 ≥6 位） |
| POST | `/api/auth/login` | 登录，获取 JWT Token |
| GET | `/api/lessons` | 获取全部关卡列表（按顺序） |
| GET | `/api/lessons/{id}` | 获取单个关卡详情 |
| GET | `/api/user/progress` | 获取当前用户进度（需 JWT） |
| PUT | `/api/user/progress` | 更新用户进度（如闯关、获得 XP）（需 JWT） |
| GET/POST | `/api/user/wrong-answers` | 获取错题列表 / 添加错题记录（需 JWT） |
| DELETE | `/api/user/wrong-answers/{lessonId}/{questionId}` | 移除指定错题（需 JWT） |
| GET/POST | `/api/user/badges`、`/api/user/badges/{badgeId}` | 获取徽章列表 / 授予新徽章（需 JWT） |
| GET | `/api/leaderboard?limit=20` | 获取排行榜（公开接口） |
| GET | `/api/game/config` | 获取游戏基础配置（公开接口） |

> **说明**：前端关卡数据以 `vue/src/data/lessons.ts` 为唯一真实数据源，后端的 `lessons` 表/接口主要保留用于后续功能扩展及排行榜逻辑支撑。

## 说明与已知边界

- **排行榜逻辑**：仅对「产生过进度记录的用户」进行排名；新用户需完成至少一次操作（如下一关或修改进度）后才会出现在榜上。
- **生命值规则**：目前为 MVP 规则——关卡通关补满生命值，错题复习答对恢复 1 颗，暂不包含时间自动恢复机制。
- **安全提示**：JWT 密钥 `app.jwt.secret` 使用了开发默认值，**在生产环境部署时务必修改**。