# learn-fed

**Repository Path**: zptcsoft/learn-fed

## Basic Information

- **Project Name**: learn-fed
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-07
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Learn Fed - 前端学习平台

<div align="center">

![Learn Fed Logo](https://img.shields.io/badge/version-1.2.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen)
![Node.js](https://img.shields.io/badge/Node.js-18+-green)

</div>

## 项目概述

Learn Fed 是一个现代化的前端学习平台，通过关卡式教学帮助用户轻松掌握 HTML、CSS、JavaScript 和 Vue.js 等前端技术。项目采用轻量级前后端分离架构，提供完整的学习体验，包括教程学习、代码练习、测试验证、成就系统等功能。

### 核心特性

- 🎯 **关卡式学习**：100个精心设计的关卡，循序渐进
- 💻 **在线代码编辑器**：集成 Monaco Editor，支持实时代码执行
- 🧪 **测试系统**：自动验证代码，实时反馈
- 🏆 **成就系统**：解锁称号和成就，激励学习动力
- 📊 **学习进度跟踪**：详细记录学习时长、关卡进度
- 📱 **响应式设计**：支持桌面端和移动端
- 🌙 **深色模式**：保护视力，提升学习体验
- 🔐 **用户认证**：安全的JWT认证机制
- 🧪 **自动化测试**：完整的单元测试、集成测试和E2E测试

## 技术栈

### 前端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue.js | 3.5+ | 前端框架 |
| TypeScript | 5.9+ | 类型系统 |
| Pinia | 3.0+ | 状态管理 |
| Vue Router | 4.6+ | 路由管理 |
| Axios | 1.13+ | HTTP客户端 |
| Monaco Editor | 1.7+ | 代码编辑器 |
| TDesign Vue Next | 1.18+ | UI组件库 |
| Highlight.js | 11.11+ | 代码高亮 |
| Marked | 17.0+ | Markdown渲染 |
| Vitest | 4.0+ | 单元测试 |
| Playwright | 1.58+ | E2E测试 |

### 后端技术栈

| 技术 | 版本 | 用途 |
|------|------|------|
| Node.js | 18+ | 运行环境 |
| Express.js | 4.18+ | Web框架 |
| SQLite | 5.1+ | 轻量级数据库 |
| JWT | 9.0+ | 身份认证 |
| bcrypt | 5.1+ | 密码加密 |
| CORS | 2.8+ | 跨域处理 |
| Morgan | 1.10+ | 日志管理 |
| Helmet | 8.1+ | 安全增强 |
| Express Rate Limit | 8.2+ | 速率限制 |
| Jest | 30.2+ | 单元测试 |
| Supertest | 7.2+ | API测试 |

## 项目结构

```
learn-fed/
├── backend/                 # 后端服务
│   ├── index.js            # Express应用入口
│   ├── database.js         # SQLite数据库操作
│   ├── sandbox.js          # 代码执行沙箱
│   ├── package.json         # 后端依赖配置
│   ├── jest.config.json     # Jest测试配置
│   ├── jest.setup.js        # Jest测试设置
│   └── __tests__/         # 后端测试文件
│       └── api.test.js    # API接口测试
├── frontend/               # 前端应用
│   ├── src/
│   │   ├── assets/         # 静态资源
│   │   ├── components/     # Vue组件
│   │   │   ├── tutorial/  # 教程相关组件
│   │   │   │   ├── TutorialView.vue
│   │   │   │   ├── WebIDE.vue
│   │   │   │   └── WebIDELogic.ts
│   │   ├── data/          # 数据文件
│   │   │   ├── caseStudies.ts
│   │   │   ├── levels.ts
│   │   │   └── quizData.ts
│   │   ├── pages/         # 页面组件
│   │   │   ├── HomePage.vue
│   │   │   ├── LoginPage.vue
│   │   │   ├── RegisterPage.vue
│   │   │   ├── ProfilePage.vue
│   │   │   ├── TutorialPage.vue
│   │   │   ├── CasePage.vue
│   │   │   ├── QuizPage.vue
│   │   │   └── EditorPage.vue
│   │   ├── router/        # 路由配置
│   │   ├── services/      # 服务层
│   │   │   ├── apiService.ts
│   │   │   ├── authService.ts
│   │   │   ├── storageService.ts
│   │   │   └── performanceService.ts
│   │   ├── store/         # Pinia状态管理
│   │   │   ├── index.ts
│   │   │   ├── user.ts
│   │   │   ├── progress.ts
│   │   │   ├── achievements.ts
│   │   │   ├── learningRecords.ts
│   │   │   └── points.ts
│   │   ├── styles/        # 全局样式
│   │   │   └── global.scss
│   │   ├── test/          # 测试文件
│   │   │   ├── setup.ts
│   │   │   ├── codeRunner.test.ts
│   │   │   └── Footer.test.ts
│   │   ├── types/         # TypeScript类型定义
│   │   │   └── level.ts
│   │   ├── utils/         # 工具函数
│   │   │   └── codeRunner.ts
│   │   ├── workers/       # Web Workers
│   │   │   └── dataProcessor.worker.ts
│   │   ├── App.vue        # 根组件
│   │   └── main.ts        # 应用入口
│   ├── public/              # 公共资源
│   │   ├── cases/         # 案例内容
│   │   ├── tests/         # 测试内容
│   │   └── tutorials/     # 教程内容
│   ├── index.html           # HTML入口
│   ├── package.json         # 前端依赖配置
│   ├── vite.config.ts       # Vite配置
│   ├── tsconfig.json       # TypeScript配置
│   └── playwright.config.ts # Playwright配置
└── docs/                 # 项目文档
    ├── api-documentation.md    # API文档
    ├── development-plan.md      # 开发计划
    └── test-plan.md           # 测试计划
```

## 快速开始

### 环境要求

- **Node.js**: 18.0 或更高版本
- **npm**: 8.0 或更高版本
- **浏览器**: Chrome、Firefox、Safari、Edge 最新版本

### 安装步骤

1. **克隆项目**
```bash
git clone https://github.com/your-username/learn-fed.git
cd learn-fed
```

2. **安装后端依赖**
```bash
cd backend
npm install
```

3. **安装前端依赖**
```bash
cd frontend
npm install
```

4. **启动后端服务**
```bash
cd backend
npm run dev
```
后端服务将在 `http://localhost:3001` 启动

5. **启动前端开发服务器**
```bash
cd frontend
npm run dev
```
前端应用将在 `http://localhost:5173` 启动

6. **访问应用**
在浏览器中打开 `http://localhost:5173`，开始学习！

### 开发环境

- **后端端口**: 3001
- **前端端口**: 5173
- **数据库**: SQLite (learn-fed.db)

## 功能模块

### 1. 用户管理

- ✅ 用户注册（支持详细个人信息）
- ✅ 用户登录（JWT认证）
- ✅ 用户退出
- ✅ 个人资料管理
- ✅ 头像上传
- ✅ 密码修改

### 2. 学习系统

- ✅ 教程浏览（HTML、CSS、JavaScript、Vue.js）
- ✅ 关卡式学习（100个关卡）
- ✅ 在线代码编辑器
- ✅ 实时代码执行
- ✅ 代码高亮和自动补全
- ✅ 测试验证
- ✅ 案例学习

### 3. 进度跟踪

- ✅ 学习进度记录
- ✅ 关卡完成状态
- ✅ 学习时长统计
- ✅ 连续学习天数
- ✅ 最佳学习记录

### 4. 成就系统

- ✅ 成就解锁
- ✅ 称号系统
- ✅ 积分奖励
- ✅ 成就展示

### 5. 学习记录

- ✅ 登录时间记录
- ✅ 学习时长记录
- ✅ 学习历史查看
- ✅ 数据统计

## 数据库设计

### users（用户表）
- 存储用户基本信息
- 包含登录时间和学习时长
- 支持密码加密存储

### progresses（学习进度表）
- 记录用户学习进度
- 跟踪关卡完成状态
- 关联用户ID

### achievements（成就表）
- 存储用户成就数据
- 包含成就解锁时间
- 支持成就分类和稀有度

### learning_records（学习记录表）
- 记录用户学习历史
- 包含登录和退出时间
- 统计学习时长

## API文档

### 认证接口

#### 注册用户
```http
POST /api/auth/register
Content-Type: application/json

{
  "username": "testuser",
  "password": "password123",
  "gender": "male",
  "studyGoal": "learn frontend",
  "school": "example university",
  "major": "computer science",
  "className": "CS101",
  "studentId": "12345",
  "realName": "张三",
  "age": 20,
  "phone": "13800138000",
  "email": "test@example.com"
}
```

#### 用户登录
```http
POST /api/auth/login
Content-Type: application/json

{
  "username": "testuser",
  "password": "password123"
}
```

### 用户接口

#### 获取用户资料
```http
GET /api/user/profile
Authorization: Bearer {token}
```

### 健康检查
```http
GET /api/health
```

## 测试

### 前端测试

```bash
cd frontend
npm run test           # 运行所有测试
npm run test:ui      # 运行测试UI
npm run test:coverage # 生成测试覆盖率报告
```

### 后端测试

```bash
cd backend
npm run test           # 运行所有测试
npm run test:watch    # 监听模式运行测试
npm run test:coverage # 生成测试覆盖率报告
```

### E2E测试

```bash
cd frontend
npx playwright test
```

## 部署

### 前端部署（Vercel）

1. **安装Vercel CLI**
```bash
npm install -g vercel
```

2. **部署前端**
```bash
cd frontend
vercel
```

### 后端部署（Vercel Functions）

1. **配置Vercel**
```bash
vercel
```

2. **配置环境变量**
- `JWT_SECRET`: JWT密钥
- `DATABASE_URL`: 数据库路径

## 开发指南

### 添加新关卡

1. 在 `frontend/public/tutorials/{module}/` 目录下创建新的关卡文件
2. 在 `frontend/src/data/levels.ts` 中添加关卡数据
3. 在 `frontend/public/tests/{module}/` 目录下添加测试用例

### 添加新成就

1. 在 `frontend/src/data/achievements.ts` 中添加成就数据
2. 确保成就ID唯一
3. 设置合理的解锁条件

### 修改样式

1. 全局样式：编辑 `frontend/src/styles/global.scss`
2. 组件样式：编辑对应组件的 `<style>` 标签
3. 使用CSS变量保持一致性

## 贡献指南

### 代码规范

- **前端代码**：遵循 Vue 3 + TypeScript 编码规范
- **后端代码**：遵循 Node.js + Express 编码规范
- **提交信息**：使用 Conventional Commits 规范

### 提交流程

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

### 分支策略

- `main`: 生产分支
- `develop`: 开发分支
- `feature/*`: 功能分支
- `bugfix/*`: 修复分支

## 性能优化

### 前端优化

- 使用 Vite 进行快速构建
- 代码分割和懒加载
- 图片优化和压缩
- 使用 Web Workers 处理大数据

### 后端优化

- SQLite 索引优化
- API 响应缓存
- 速率限制防止滥用
- 数据库连接池

## 安全措施

- ✅ JWT 认证机制
- ✅ 密码 bcrypt 加密
- ✅ CORS 跨域保护
- ✅ Helmet 安全头
- ✅ 速率限制
- ✅ SQL 注入防护
- ✅ XSS 攻击防护

## 浏览器支持

| 浏览器 | 版本 | 支持状态 |
|---------|------|----------|
| Chrome | 最新版本 | ✅ 完全支持 |
| Firefox | 最新版本 | ✅ 完全支持 |
| Safari | 最新版本 | ✅ 完全支持 |
| Edge | 最新版本 | ✅ 完全支持 |

## 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 联系方式

- **问题反馈**: [GitHub Issues](https://github.com/your-username/learn-fed/issues)
- **功能建议**: [GitHub Discussions](https://github.com/your-username/learn-fed/discussions)
- **邮件**: support@example.com

## 致谢

感谢所有为 Learn Fed 项目做出贡献的开发者！

## 更新日志

### v1.2.0 (2026-02-07)

#### 新增功能
- ✨ 实现用户认证系统（注册、登录、JWT认证）
- ✨ 实现学习进度跟踪
- ✨ 实现成就系统
- ✨ 实现学习记录功能
- ✨ 集成在线代码编辑器
- ✨ 添加测试验证系统
- ✨ 实现响应式设计
- ✨ 添加深色模式支持
- ✨ 优化ProfilePage页面布局
- ✨ 整合用户信息卡片结构

#### 技术改进
- 🔧 采用前后端分离架构
- 🔧 使用 SQLite 轻量级数据库
- 🔧 集成 TDesign UI 组件库
- 🔧 使用 Monaco Editor 代码编辑器
- 🔧 添加自动化测试（Vitest、Jest、Playwright）
- 🔧 配置完整的测试环境
- 🔧 创建单元测试和集成测试
- 🔧 添加测试覆盖率报告

#### 文档
- 📝 添加 API 文档
- 📝 添加开发计划
- 📝 添加测试计划
- 📝 创建完整的 README
- 📝 更新项目结构说明
- 📝 添加API文档、测试指南、部署指南

#### 测试
- 🧪 创建前端单元测试（codeRunner.test.ts、Footer.test.ts）
- 🧪 创建后端API测试（api.test.js）
- 🧪 配置Vitest和Jest测试环境
- 🧪 添加测试脚本和覆盖率报告

#### 版本管理
- 🏷️ 版本号从v1.1.0更新到v1.2.0
- 🏷️ 创建Git标签v1.2.0

## 常见问题

### Q: 如何重置数据库？

A: 删除 `backend/learn-fed.db` 文件，重启后端服务即可。

### Q: 如何修改端口？

A: 修改 `backend/index.js` 中的 `PORT` 常量和 `frontend/vite.config.ts` 中的 `server.port` 配置。

### Q: 如何添加新的学习模块？

A: 参考 `frontend/public/tutorials/` 目录结构，创建新的模块文件夹和关卡文件。

### Q: 测试失败怎么办？

A: 检查依赖是否正确安装，确保后端服务正在运行，查看错误日志。

### Q: 如何运行测试？

A: 
- 前端测试：`cd frontend && npm run test`
- 后端测试：`cd backend && npm run test`
- E2E测试：`cd frontend && npx playwright test`

### Q: 如何查看测试覆盖率？

A: 
- 前端：`cd frontend && npm run test:coverage`
- 后端：`cd backend && npm run test:coverage`

## 流程图

```mermaid
graph LR
    A[用户] --> B[注册/登录]
    B --> C[选择学习模块]
    C --> D[学习关卡]
    D --> E[完成练习]
    E --> F[通过测试]
    F --> G[解锁成就]
    G --> H[查看进度]
    H --> I[学习记录]
    I --> J[个人资料]
```

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件