# math-learning-visualization

**Repository Path**: lileijiang/math-learning-visualization

## Basic Information

- **Project Name**: math-learning-visualization
- **Description**: 这是一个帮助学习数学的可视化项目，通过交互式图形和动画来帮助理解抽象的数学概念。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-13
- **Last Updated**: 2025-08-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🧮 数学学习可视化项目

<div align="center">

![Vue.js](https://img.shields.io/badge/Vue.js-3.x-4FC08D?style=for-the-badge&logo=vue.js&logoColor=white)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge&logo=typescript&logoColor=white)
![Vite](https://img.shields.io/badge/Vite-5.x-646CFF?style=for-the-badge&logo=vite&logoColor=white)
![Node.js](https://img.shields.io/badge/Node.js-18.x-339933?style=for-the-badge&logo=node.js&logoColor=white)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=for-the-badge)](CONTRIBUTING.md)

**通过交互式可视化让数学学习变得简单有趣**

[🚀 快速开始](#快速开始) • [📖 文档](#项目文档) • [🤝 贡献指南](CONTRIBUTING.md) • [📄 开源协议](LICENSE)

</div>

---

## 📋 目录

- [🎯 项目概述](#项目概述)
- [✨ 核心特性](#核心特性)
- [🏗️ 技术架构](#技术架构)
- [📁 项目结构](#项目结构)
- [🚀 快速开始](#快速开始)
- [📖 项目文档](#项目文档)
- [🔧 开发指南](#开发指南)
- [🤝 开源协作](#开源协作)
- [📈 开发计划](#开发计划)
- [🎓 学习资源](#学习资源)
- [📞 联系我们](#联系我们)

---

## 🎯 项目概述

**数学学习可视化项目** 是一个创新的教育技术项目，旨在通过交互式图形和动画帮助学习者更好地理解抽象的数学概念。

### 🎯 核心目标

- **🎨 数学概念可视化** - 让抽象的数学概念变得直观易懂
- **🖱️ 交互式学习** - 通过操作和体验来深入理解数学
- **📚 个人学习工具** - 帮助个人理解和记忆数学知识
- **🌍 开源共享** - 为全球学习者提供免费的教育资源

---

## ✨ 核心特性

### 🎨 可视化功能

- **数轴可视化** - 理解正负数、数字大小比较
- **分数可视化** - 圆形、矩形分割，分数运算演示
- **几何图形** - 面积、周长计算，动态图形变换
- **函数图像** - 实时绘制数学函数，参数动态调整
- **统计图表** - 柱状图、饼图、折线图等数据可视化

### 🖱️ 交互体验

- **拖拽操作** - 移动数字、图形，实时反馈
- **点击交互** - 选择答案、切换视图模式
- **动画演示** - 计算过程动画，概念演变展示
- **实时验证** - 即时答案验证，错误提示

### 📊 学习管理

- **个人进度** - 学习进度跟踪和记录
- **练习系统** - 自适应练习题生成
- **成绩统计** - 学习效果分析和报告
- **用户系统** - 个人账户和学习历史

---

## 🏗️ 技术架构

### 🎨 前端技术栈

| 技术           | 版本 | 用途                 |
| -------------- | ---- | -------------------- |
| **Vue.js**     | 3.x  | 前端框架，组件化开发 |
| **TypeScript** | 5.x  | 类型安全，开发体验   |
| **Vite**       | 5.x  | 构建工具，快速开发   |
| **Pinia**      | 2.x  | 状态管理             |
| **Vue Router** | 4.x  | 路由管理             |
| **SVG/Canvas** | -    | 数学图形绘制         |

### 🔧 后端技术栈

| 技术           | 版本 | 用途                 |
| -------------- | ---- | -------------------- |
| **Node.js**    | 18.x | 运行环境             |
| **Express.js** | 4.x  | Web框架              |
| **JWT**        | -    | 身份认证             |
| **JSON文件**   | -    | 数据存储（开发环境） |

### 🎯 技术选择理由

#### SVG优势

- ✅ 矢量图形，任意缩放不失真
- ✅ 与DOM集成好，事件处理简单
- ✅ 代码相对简洁，易于调试
- ✅ 支持CSS样式和动画

#### Canvas优势

- ✅ 性能最佳，适合大量图形渲染
- ✅ 完全控制像素级绘制
- ✅ 适合复杂的数学图形和动画
- ✅ 内存占用相对较低

#### 混合使用策略

- **SVG**：简单的几何图形、静态图表、交互元素
- **Canvas**：复杂的数学图形、动态动画、函数图像

---

## 📁 项目结构

```
math-learning-visualization/
├── 📄 项目配置文件
│   ├── package.json              # 前端依赖配置
│   ├── vite.config.ts            # Vite构建配置
│   ├── tsconfig.json             # TypeScript配置
│   ├── tsconfig.app.json         # 应用TypeScript配置
│   ├── tsconfig.node.json        # Node.js TypeScript配置
│   ├── eslint.config.ts          # ESLint配置
│   └── index.html                # 入口HTML
│
├── 🎨 前端源码 (src/)
│   ├── api/                      # API接口封装
│   │   ├── auth.ts              # 认证相关API
│   │   ├── practice.ts          # 练习相关API
│   │   ├── progress.ts          # 进度相关API
│   │   └── questions.ts         # 题目相关API
│   │
│   ├── http/                    # HTTP请求封装
│   │   ├── index.ts             # 请求实例
│   │   ├── request.ts           # 请求拦截器
│   │   └── types.ts             # 类型定义
│   │
│   ├── views/                   # 页面组件
│   │   ├── HomeView.vue         # 首页
│   │   ├── LearnView.vue        # 学习页面
│   │   ├── PracticeView.vue     # 练习页面
│   │   ├── ProgressView.vue     # 进度页面
│   │   ├── LoginView.vue        # 登录页面
│   │   ├── RegisterView.vue     # 注册页面
│   │   └── NotFoundView.vue     # 404页面
│   │
│   ├── stores/                  # 状态管理
│   │   └── counter.ts           # 计数器状态
│   │
│   ├── router/                  # 路由配置
│   │   └── index.ts             # 路由定义
│   │
│   ├── App.vue                  # 根组件
│   └── main.ts                  # 应用入口
│
├── 🔧 后端服务 (server/)
│   ├── package.json             # 后端依赖配置
│   ├── package-lock.json        # 依赖锁定文件
│   ├── index.js                 # 服务启动入口
│   │
│   ├── src/                     # 后端源码
│   │   ├── app.js               # Express应用配置
│   │   │
│   │   ├── config/              # 配置文件
│   │   │   └── env.js           # 环境变量配置
│   │   │
│   │   ├── middleware/          # 中间件
│   │   │   └── auth.js          # JWT认证中间件
│   │   │
│   │   ├── routes/              # 路由定义
│   │   │   ├── auth.routes.js   # 认证路由
│   │   │   ├── progress.routes.js # 进度路由
│   │   │   ├── practice.routes.js # 练习路由
│   │   │   ├── questions.routes.js # 题目路由
│   │   │   ├── health.routes.js # 健康检查路由
│   │   │   └── calculate.routes.js # 计算路由
│   │   │
│   │   └── utils/               # 工具函数
│   │       ├── fileStore.js     # 文件存储工具
│   │       ├── jwt.js           # JWT工具
│   │       └── id.js            # ID生成工具
│   │
│   ├── data/                    # 数据存储目录
│   │   └── *.json               # JSON数据文件
│   │
│   └── README.md                # 后端说明文档
│
├── 📚 项目文档
│   ├── README.md                # 项目说明文档
│   ├── CONTRIBUTING.md          # 贡献指南
│   ├── LICENSE                  # 开源协议
│   ├── CODE_OF_CONDUCT.md       # 行为准则
│   ├── DEVELOPMENT.md           # 开发指南
│   ├── FRONTEND_INTEGRATION.md  # 前端集成文档
│   ├── 需求文档.md              # 详细需求文档
│   └── readm.md                 # 项目说明
│
├── 📦 依赖管理
│   ├── pnpm-lock.yaml           # pnpm锁定文件
│   └── components.d.ts          # 组件类型声明
│
└── 🌐 静态资源
    └── public/
        └── favicon.ico          # 网站图标
```

---

## 🚀 快速开始

### 📋 环境要求

- **Node.js** >= 18.0.0
- **pnpm** >= 8.0.0 (推荐) 或 **npm** >= 9.0.0

### 🔧 安装步骤

#### 1. 克隆项目

```bash
git clone https://gitee.com/lileijiang/math-learning-visualization.git
cd math-learning-visualization
```

#### 2. 安装前端依赖

```bash
# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install
```

#### 3. 安装后端依赖

```bash
cd server
npm install
cd ..
```

#### 4. 启动开发服务器

**启动后端服务：**

```bash
cd server
npm run dev
```

**启动前端服务：**

```bash
# 新开一个终端
pnpm run dev
```

#### 5. 访问应用

- **前端地址**：http://localhost:5173
- **后端地址**：http://localhost:3001
- **API文档**：http://localhost:3001/api/health

### ⚙️ 环境配置

#### 后端环境变量 (可选)

```bash
# server/.env
PORT=3001                           # 服务端口
JWT_SECRET=your-secret-key         # JWT密钥（请替换为实际密钥）
ACCESS_TOKEN_EXPIRES_IN=2h         # Token过期时间
```

#### 前端代理配置

Vite已配置API代理，前端请求 `/api/*` 会自动转发到后端服务。

---

## 📖 项目文档

### 🔌 API接口文档

#### 认证相关 (Auth)

| 接口                 | 方法 | 描述         | 参数                                 |
| -------------------- | ---- | ------------ | ------------------------------------ |
| `/api/auth/register` | POST | 用户注册     | `{ username, password, email? }`     |
| `/api/auth/login`    | POST | 用户登录     | `{ username, password }`             |
| `/api/auth/me`       | GET  | 获取当前用户 | 需要 `Authorization: Bearer <token>` |
| `/api/auth/refresh`  | POST | 刷新Token    | 需要旧token                          |
| `/api/auth/logout`   | POST | 用户登出     | 无状态                               |

#### 学习进度 (Progress)

| 接口                    | 方法 | 描述         | 参数                        |
| ----------------------- | ---- | ------------ | --------------------------- |
| `/api/progress/:userId` | GET  | 获取学习进度 | 路径参数：userId            |
| `/api/progress/:userId` | POST | 更新学习进度 | 路径参数：userId + 进度数据 |

#### 练习记录 (Practice)

| 接口                    | 方法 | 描述         | 参数                        |
| ----------------------- | ---- | ------------ | --------------------------- |
| `/api/practice/:userId` | GET  | 获取练习记录 | 路径参数：userId            |
| `/api/practice/:userId` | POST | 保存练习记录 | 路径参数：userId + 练习数据 |

#### 题目管理 (Questions)

| 接口                      | 方法 | 描述         | 参数           |
| ------------------------- | ---- | ------------ | -------------- |
| `/api/questions/generate` | POST | 生成练习题   | 题目类型和难度 |
| `/api/questions/types`    | GET  | 获取题目类型 | 无             |

#### 数学计算 (Calculate)

| 接口             | 方法 | 描述     | 参数       |
| ---------------- | ---- | -------- | ---------- |
| `/api/calculate` | POST | 数学计算 | 计算表达式 |

#### 系统监控 (Health)

| 接口          | 方法 | 描述     | 参数 |
| ------------- | ---- | -------- | ---- |
| `/api/health` | GET  | 健康检查 | 无   |

### 📊 数据格式规范

#### 统一响应格式

```typescript
interface ApiResponse<T = any> {
  code: number // 状态码：200成功，其他失败
  data?: T // 响应数据
  msg: string // 响应消息
}
```

#### 用户数据结构

```typescript
interface User {
  id: string
  username: string
  email?: string
  createdAt: string
  updatedAt: string
}
```

#### 学习进度结构

```typescript
interface Progress {
  userId: string
  concept: string // 学习概念
  level: number // 掌握程度
  completed: boolean // 是否完成
  timestamp: string // 时间戳
}
```

---

## 🔧 开发指南

### 🛠️ 开发环境设置

#### 1. 代码规范

- **ESLint**：代码质量检查
- **Prettier**：代码格式化
- **TypeScript**：类型检查

#### 2. 提交规范

```bash
# 提交格式
git commit -m "type(scope): description"

# 示例
git commit -m "feat(auth): 添加用户登录功能"
git commit -m "fix(ui): 修复数轴显示问题"
git commit -m "docs(readme): 更新项目文档"
```

#### 3. 分支管理

- **master**：主分支，稳定版本
- **develop**：开发分支，最新功能
- **feature/\***：功能分支
- **hotfix/\***：紧急修复分支

### 🎨 组件开发规范

#### Vue组件结构

```vue
<template>
  <!-- 模板内容 -->
</template>

<script setup lang="ts">
// 组件逻辑
</script>

<style scoped>
/* 组件样式 */
</style>
```

#### TypeScript接口定义

```typescript
interface ComponentProps {
  // 组件属性定义
}

interface ComponentEmits {
  // 组件事件定义
}
```

### 🧪 测试规范

#### 单元测试

- 使用 **Vitest** 进行单元测试
- 测试文件命名：`*.test.ts` 或 `*.spec.ts`
- 测试覆盖率要求：> 80%

#### 集成测试

- API接口测试
- 组件集成测试
- 端到端测试

---

## 🤝 开源协作

### 🌟 贡献者等级

| 等级              | 贡献次数 | 特权           |
| ----------------- | -------- | -------------- |
| 🥉 **铜牌贡献者** | 1-5次    | 基础贡献者徽章 |
| 🥈 **银牌贡献者** | 6-15次   | 代码审查权限   |
| 🥇 **金牌贡献者** | 16+次    | 核心维护者权限 |

### 🎯 特殊贡献类型

- **🔧 核心维护者**：长期维护项目，技术决策
- **🌍 社区建设者**：活跃社区讨论，组织活动
- **📚 文档专家**：完善项目文档，编写教程
- **🎨 设计专家**：UI/UX设计，视觉优化

### 🏆 贡献者激励

- **🏅 贡献者徽章**：在README中展示贡献者
- **📢 技术分享机会**：组织线上技术分享
- **🚀 开源项目推荐**：推荐到开源平台
- **💼 职业发展支持**：提供职业发展建议

### 📅 开源时间线

#### 第一个月 🚀

- [x] 完成基础功能开发
- [x] 发布第一个版本
- [x] 建立基础文档
- [ ] 开始社区宣传

#### 第二个月 🌱

- [ ] 吸引第一批贡献者
- [ ] 完善开发流程
- [ ] 建立代码审查
- [ ] 组织技术分享

#### 第三个月 🌟

- [ ] 扩大社区影响
- [ ] 优化协作流程
- [ ] 建立长期规划
- [ ] 探索商业化可能

---

## 📈 开发计划

### 🎯 第一阶段：基础数学可视化 (1-2周)

#### 小学数学可视化

- [x] **数轴组件** - 理解正负数概念
- [x] **分数可视化** - 圆形、矩形分割显示
- [x] **几何图形** - 面积、周长计算
- [x] **基础运算** - 可视化计算过程
- [x] **统计图表** - 柱状图、饼图显示

#### 交互功能

- [x] **拖拽操作** - 移动数字、图形
- [x] **点击交互** - 选择答案、切换视图
- [x] **动画演示** - 计算过程动画
- [x] **实时反馈** - 即时验证答案

### 🚀 第二阶段：高级数学可视化 (3-4周)

#### Canvas增强功能

- [ ] **函数图像绘制** - 实时函数图像
- [ ] **动态几何图形** - 3D几何概念
- [ ] **数学计算动画** - 复杂计算过程
- [ ] **数据可视化** - 高级图表类型

#### 学习路径设计

```
1. 数字认识
   ├── 数轴上的数字
   ├── 数字大小比较
   └── 正负数概念

2. 基础运算
   ├── 加法可视化
   ├── 减法可视化
   └── 乘法可视化

3. 分数概念
   ├── 分数表示
   ├── 分数比较
   └── 分数运算

4. 几何基础
   ├── 基本图形
   ├── 面积计算
   └── 周长计算

5. 函数概念
   ├── 线性函数
   ├── 二次函数
   └── 三角函数
```

### 🎨 第三阶段：用户体验优化 (5-6周)

#### 界面优化

- [ ] **响应式设计** - 移动端适配
- [ ] **主题系统** - 深色/浅色主题
- [ ] **动画效果** - 流畅的过渡动画
- [ ] **无障碍访问** - 支持屏幕阅读器

#### 功能增强

- [ ] **学习分析** - 学习数据统计
- [ ] **个性化推荐** - 智能学习路径
- [ ] **社交功能** - 学习小组、排行榜
- [ ] **离线支持** - PWA应用

---

## 🎓 学习资源

### 📚 技术学习

#### SVG学习资源

- [MDN SVG教程](https://developer.mozilla.org/zh-CN/docs/Web/SVG)
- [Vue3 SVG集成指南](https://vuejs.org/guide/extras/ways-of-using-vue.html#web-components)
- [数学图形SVG绘制](https://www.w3schools.com/graphics/svg_intro.asp)

#### Canvas学习资源

- [Canvas API文档](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API)
- [数学图形Canvas绘制](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API/Tutorial)
- [动画和交互处理](https://developer.mozilla.org/zh-CN/docs/Web/API/Canvas_API/Tutorial/Basic_animations)

#### 数学可视化

- [数学教育可视化案例](https://www.geogebra.org/)
- [交互式数学网站](https://www.desmos.com/)
- [数学图形绘制算法](https://www.khanacademy.org/computing/computer-programming)

### 🛠️ 开发工具

#### 推荐工具

- **VS Code** - 代码编辑器
- **Vue DevTools** - Vue调试工具
- **Postman** - API测试工具
- **GitKraken** - Git图形化工具

#### 浏览器扩展

- **Vue.js devtools** - Vue开发调试
- **JSON Viewer** - JSON数据查看
- **ColorZilla** - 颜色拾取器

---

## 📞 联系我们

### 🌐 项目链接

- **项目地址**：[Gitee仓库](https://gitee.com/lileijiang/math-learning-visualization)
- **在线演示**：待建立
- **问题反馈**：[Issues](https://gitee.com/lileijiang/math-learning-visualization/issues)

### 💬 交流方式

- **技术讨论**：[Discussions](https://gitee.com/lileijiang/math-learning-visualization/issues)
- **开发群组**：QQ群/微信群（待建立）
- **邮件联系**：待建立

### 📢 关注我们

- **项目动态**：关注Gitee仓库获取最新更新
- **技术分享**：定期发布技术文章和教程
- **社区活动**：参与开源社区活动

---

<div align="center">

**如果这个项目对你有帮助，请给我们一个 ⭐ Star！**

[![Star History Chart](https://api.star-history.com/svg?repos=lileijiang/math-learning-visualization&type=Date)](https://star-history.com/#lileijiang/math-learning-visualization&Date)

---

**Made with ❤️ by [待建立] and Contributors**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

</div>