History

Rumia d9b26088eb 结对项目		6 months ago
..
README.md	结对项目	6 months ago

README.md

Unescape Escape

小初高数学学习软件 - 完整项目文档

目录（所使用的代码规范地址在末尾）

前端部分

前端项目概述

本软件是一个基于 Electron 的桌面数学学习应用，采用前后端分离的模块化设计，最终打包为单一可执行程序。提供从用户注册→密码设置→年级选择→数学答题→成绩统计的完整学习流程。

前端功能特性

✅ 用户注册与邮箱验证码
✅ 密码设置与修改
✅ 用户头像上传
✅ 用户名修改
✅ 年级选择（小学/初中/高中）
✅ 数学题目生成与答题
✅ 成绩统计与显示
✅ 单一可执行程序（无需外部服务）

前端技术栈

桌面框架: Electron
前端: HTML5 + CSS3 + JavaScript (ES6+)
后端: Node.js + Express（集成到主进程）
通信方式: IPC（进程间通信）
数据存储: JSON文件
样式: 原生CSS（符合Google CSS规范）
代码规范: Google JavaScript/CSS/HTML规范

前端项目结构

src/
├─ frontend/              # 前端模块（GUI界面）
│   ├─ electron-main.js   # 主进程（集成后端逻辑）
│   ├─ preload.js         # IPC通信接口
│   ├─ renderer.js        # 渲染进程（前端逻辑）
│   ├─ index.html         # 主页面
│   ├─ styles.css         # 样式文件
│   └─ package.json       # 前端配置
└─ backend/                 # 后端模块（业务逻辑+数据）
    ├─ utils/             # 工具类
    ├─ data/              # 数据存储
    ├─ email-config.js    # 邮箱配置文件
    └─ package.json       # 后端依赖配置

前端快速开始

1. 环境要求

Node.js 18+
npm 或 yarn

2. 安装依赖

# 安装后端依赖（必需）
cd src/backend
npm install

# 安装前端依赖
cd ../frontend
npm install

3. 开发模式运行

npm start

⚠️ 重要: 必须先安装后端依赖，否则应用启动会报错 Cannot find module 'nodemailer'。

4. 打包发布

npm run build

产物位于 dist/ 目录，包含：

数学学习软件-7.0.0-Setup.exe - 安装包
win-unpacked/ - 解压后的可执行程序目录

前端使用指南

1. 用户注册

输入用户名（必填，需唯一）
输入邮箱（支持QQ邮箱和163邮箱）
点击"获取验证码"：系统会发送验证码到邮箱
输入收到的验证码，点击"注册"

2. 密码设置

设置密码（6-10位，含大小写字母和数字，如 Test123）
确认两次输入一致
点击"确认设置"

3. 用户信息管理

注册完成后，右上角显示"头像+用户名+修改按钮"
点击头像可选择本地图片更换
点击"修改用户名"可更改用户名（需唯一）
点击"修改密码"可更改密码

4. 数学学习

选择年级（小学/初中/高中）
输入题目数量（10-30）
点击"生成试卷"
逐题作答，查看最终分数

前端核心模块说明

1. 主进程模块 (electron-main.js)

功能概述

Electron主进程模块负责创建和管理应用程序窗口，同时集成了所有后端业务逻辑，实现单一可执行程序。

核心功能

窗口管理: 创建和管理应用窗口
后端逻辑集成: 用户管理、邮箱验证、题目生成
IPC通信处理: 处理渲染进程的API请求
数据管理: JSON文件数据存储
生命周期管理: 应用程序启动和关闭

集成架构

// 动态路径处理
const getBackendPath = (relativePath) => {
  if (app.isPackaged) {
    return path.join(process.resourcesPath, 'backend', relativePath);
  } else {
    return path.join(__dirname, '..', 'backend', relativePath);
  }
};

// IPC处理器
ipcMain.handle('api:send-code', async (event, { email, username }) => {
  // 发送验证码逻辑
});

ipcMain.handle('api:login', async (event, { account, password }) => {
  // 用户登录逻辑
});

2. 渲染进程模块 (renderer.js)

功能概述

渲染进程模块是前端逻辑的核心，负责处理用户界面交互、数据管理、与主进程通信等功能。

核心功能

界面管理: 页面切换和状态管理
用户交互: 表单处理、事件监听
数据管理: 本地数据存储和同步
IPC通信: 与主进程通信，调用后端API

主要功能模块

// 用户认证模块
class AuthManager {
  // 用户登录
  async login(account, password)
  
  // 用户注册
  async register(userData)
  
  // 密码设置
  async setPassword(password)
}

// 题目管理模块
class QuestionManager {
  // 获取题目
  async getQuestions(grade, count)
  
  // 提交答案
  async submitAnswer(questionId, answer)
  
  // 获取成绩
  async getScore()
}

// 用户信息管理模块
class UserManager {
  // 修改用户名
  async changeUsername(newUsername)
  
  // 修改密码
  async changePassword(oldPassword, newPassword)
  
  // 上传头像
  async uploadAvatar(file)
}

界面状态管理

页面切换: 登录页、注册页、答题页等
状态同步: 用户信息、答题进度
错误处理: 网络错误、验证错误等

3. 预加载脚本 (preload.js)

功能概述

预加载脚本负责在渲染进程中安全地暴露API接口，实现与主进程的IPC通信。

核心功能

API暴露: 安全地暴露所有业务API
IPC通信: 处理渲染进程与主进程的通信
权限控制: 限制渲染进程的权限
数据验证: 输入数据验证和清理

暴露的API

contextBridge.exposeInMainWorld('API', {
  // 用户认证
  sendRegisterCode: (email, username) => ipcRenderer.invoke('api:send-code', { email, username }),
  verifyCode: (email, username, code) => ipcRenderer.invoke('api:verify-code', { email, username, code }),
  register: (email, username, password) => ipcRenderer.invoke('api:register', { email, username, password }),
  login: (account, password) => ipcRenderer.invoke('api:login', { account, password }),
  
  // 用户管理
  changePassword: (email, oldPassword, newPassword) => ipcRenderer.invoke('api:change-password', { email, oldPassword, newPassword }),
  changeUsername: (email, username) => ipcRenderer.invoke('api:change-username', { email, username }),
  deleteAccount: (email, password) => ipcRenderer.invoke('api:delete-account', { email, password }),
  
  // 题目管理
  getQuestions: (grade, count) => ipcRenderer.invoke('api:get-questions', { grade, count })
});

前端代码规范

所有JavaScript文件符合Google JavaScript规范
CSS文件符合Google CSS规范
HTML文件符合Google HTML规范
使用2空格缩进
属性按字母顺序排列
统一的命名规范
完整的注释说明

后端部分

后端项目概述

基于 Node.js 的后端服务，提供用户管理、邮箱验证、题目生成等核心功能。支持多邮箱服务商，具备完整的用户生命周期管理。

后端功能特性

✅ 用户注册与邮箱验证码发送
✅ 密码加密存储（SHA256）
✅ 用户信息管理（用户名、密码修改）
✅ 数学题目智能生成
✅ 多邮箱服务商支持
✅ 数据持久化存储

后端技术栈

运行环境: Node.js
框架: 原生 Node.js + Express
数据存储: JSON文件
邮箱服务: Nodemailer
加密: crypto (SHA256)
代码规范: Google JavaScript规范

后端项目结构

src/backend/
├─ data/
│   └─ users.json            # 用户数据文件
├─ utils/
│   ├─ user-manager.js       # 用户管理模块
│   ├─ multi-email-service.js # 多邮箱服务
│   └─ question-generator.js # 题目生成器
├─ email-config.js           # 邮箱配置
└─ package.json              # 项目配置

后端快速开始

1. 安装依赖

cd src/backend
npm install

2. 启动服务

npm start

3. 验证服务

服务启动后会在终端显示：Server listening on http://localhost:8080

后端使用指南

1. API调用方式

所有API通过IPC通信调用，无需HTTP请求
前端通过 ipcRenderer.invoke 调用主进程中的后端逻辑

2. 用户管理流程

发送验证码 → 用户注册 → 设置密码
登录验证 → 修改信息 → 删除账户

3. 题目生成流程

选择年级 → 生成题目 → 返回题目数据
支持小学、初中、高中三个年级
自动生成选择题和计算题

后端核心模块说明

1. 用户管理模块 (user-manager.js)

功能概述

用户管理模块是整个后端系统的核心，负责处理所有用户相关的操作，包括注册、登录、密码管理、用户信息修改等。

主要功能

用户注册: 邮箱验证、用户名唯一性检查
用户登录: 邮箱/用户名登录验证
密码管理: 密码设置、修改、验证
用户信息: 用户名修改、账户删除
数据存储: JSON文件数据持久化

核心方法

createUser(email, username): 创建新用户
findUserByEmail(email): 根据邮箱查找用户
findUserByUsername(username): 根据用户名查找用户
updateUser(email, updates): 更新用户信息
deleteUser(email): 删除用户账户
verifyPassword(email, password): 验证密码

用户管理安全特性

邮箱唯一性: 每个邮箱只能注册一个账户
用户名唯一性: 用户名必须唯一
密码安全: 密码验证和加密存储
数据完整性: 用户数据一致性检查

数据存储格式

{
  "email": "user@example.com",
  "username": "用户名",
  "registeredAt": "2024-01-01T00:00:00.000Z"
}

2. 邮箱服务模块 (multi-email-service.js)

功能概述

邮箱服务模块负责发送验证码邮件，支持多个邮箱服务商，提供统一的邮件发送接口。

支持的服务商

QQ邮箱: 支持QQ邮箱SMTP服务
163邮箱: 支持163邮箱SMTP服务
测试模式: 开发环境下的模拟发送

核心功能

验证码生成: 6位数字验证码
邮件发送: 通过SMTP发送验证码
模板渲染: 使用HTML邮件模板
错误处理: 发送失败时的降级处理

配置示例

// QQ邮箱配置
const qqConfig = {
  host: 'smtp.qq.com',
  port: 587,
  secure: false,
  auth: {
    user: 'your_qq@qq.com',
    pass: 'your_smtp_password'
  }
};

// 163邮箱配置
const config163 = {
  host: 'smtp.163.com',
  port: 587,
  secure: false,
  auth: {
    user: 'your_163@163.com',
    pass: 'your_smtp_password'
  }
};

邮件模板

<h2>数学学习软件验证码</h2>
<p>您的验证码是：<strong>{{code}}</strong></p>
<p>验证码有效期为10分钟，请及时使用。</p>

3. 题目生成模块 (question-generator.js)

功能概述

题目生成模块负责根据年级和数量生成数学题目，支持小学、初中、高中三个年级的题目生成。

生成逻辑（与个人项目逻辑类似）

年级适配: 根据年级调整题目难度
题型多样: 选择题、计算题、应用题
选项生成: 智能生成干扰选项
答案验证: 确保答案正确性

题目类型

小学: 基础四则运算、简单应用题
初中: 代数运算、几何计算、函数基础
高中: 复杂代数、三角函数、立体几何

核心算法

// 题目生成算法
generateQuestion(grade, type) {
  const difficulty = this.getDifficultyByGrade(grade);
  const operation = this.selectOperation(type);
  const numbers = this.generateNumbers(difficulty);
  const expression = this.buildExpression(numbers, operation);
  const answer = this.calculateAnswer(expression);
  const options = this.generateOptions(answer);
  
  return {
    stem: expression,
    options: options,
    answer: answer
  };
}

题目质量控制

难度梯度: 根据年级调整题目难度
选项合理性: 干扰选项不能过于明显
计算准确性: 确保所有计算正确
格式统一: 题目格式标准化

题目数据结构

{
  "id": "小学-1",
  "stem": "计算：2 + 3 = ?",
  "options": [
    {"key": "A", "text": "4", "isCorrect": false},
    {"key": "B", "text": "5", "isCorrect": true},
    {"key": "C", "text": "6", "isCorrect": false},
    {"key": "D", "text": "7", "isCorrect": false}
  ],
  "answer": "B"
}

智能特性

自适应难度: 根据用户表现调整难度
题型平衡: 确保各种题型均匀分布
错误分析: 分析常见错误类型

后端代码规范

JavaScript代码规范

命名规范: 使用camelCase命名变量和函数
函数长度: 单个函数不超过40行
注释规范: 关键函数和复杂逻辑必须添加注释
错误处理: 使用try-catch处理异步操作
代码风格: 遵循Google JavaScript规范

模块化规范

单一职责: 每个模块只负责一个功能
依赖注入: 通过参数传递依赖关系
接口设计: 统一的API响应格式
错误处理: 统一的错误处理机制

数据安全规范

输入验证: 所有用户输入必须验证
数据加密: 敏感数据使用适当加密
权限控制: 实现用户权限验证
日志记录: 记录关键操作和错误

1. 用户管理模块 (user-manager.js)

功能概述

用户管理模块是整个后端系统的核心，负责处理所有用户相关的操作，包括注册、登录、密码管理、用户信息修改等。

主要功能

用户注册: 支持邮箱和用户名唯一性验证
密码管理: SHA256加密存储，支持密码设置和修改
用户信息管理: 用户名修改、用户删除
数据持久化: JSON文件存储，支持数据备份和恢复

核心方法

// 用户注册
createUser(email, username)

// 密码设置
setPassword(email, password)

// 密码验证
verifyPassword(email, password)

// 密码修改
changePassword(email, oldPassword, newPassword)

// 用户名修改
changeUsername(email, newUsername)

// 用户删除
deleteUser(email)

用户管理安全特性

密码加密: 使用SHA256哈希算法加密存储
数据验证: 严格的输入验证和格式检查
唯一性检查: 邮箱和用户名的唯一性保证
错误处理: 完善的异常处理和错误信息返回

数据存储格式

{
  "email": "user@example.com",
  "username": "用户名",
  "password": "sha256加密后的密码",
  "registeredAt": "2025-01-01T00:00:00.000Z",
  "updatedAt": "2025-01-01T00:00:00.000Z"
}

2. 邮箱服务模块 (multi-email-service.js)

功能概述

邮箱服务模块负责处理所有邮件发送功能，支持多个邮箱服务商，提供验证码发送、邮件模板管理等功能。

支持的服务商

QQ邮箱: 支持SMTP协议，需要授权码
163邮箱: 支持SMTP协议，需要授权码
其他SMTP服务: 可扩展支持更多邮箱服务商

核心功能

多服务商支持: 自动选择可用的邮箱服务商
验证码发送: 6位数字验证码生成和发送
邮件模板: 统一的邮件格式和样式
错误处理: 服务商切换和错误重试机制

配置示例

// 邮箱服务配置
const emailServices = {
  qq: {
    host: 'smtp.qq.com',
    port: 587,
    secure: false,
    auth: {
      user: process.env.SMTP_QQ_USER,
      pass: process.env.SMTP_QQ_PASS
    }
  },
  netease: {
    host: 'smtp.163.com',
    port: 587,
    secure: false,
    auth: {
      user: process.env.SMTP_163_USER,
      pass: process.env.SMTP_163_PASS
    }
  }
}

邮件模板

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>验证码</title>
</head>
<body>
    <h2>数学学习软件验证码</h2>
    <p>您的验证码是：<strong>{code}</strong></p>
    <p>验证码有效期为5分钟，请及时使用。</p>
</body>
</html>

3. 题目生成模块 (question-generator.js)

功能概述

题目生成模块是系统的智能核心，能够根据年级和数量要求自动生成数学题目，支持小学、初中、高中三个年级的题目类型。

生成逻辑（与个人项目逻辑类似）

小学题目: 基础四则运算、简单应用题
初中题目: 代数运算、几何计算、函数基础
高中题目: 复杂函数、三角函数、立体几何

题目类型

四则运算题
- 基础加减乘除
- 带括号的复合运算
- 小数和分数运算
应用题
- 生活场景问题
- 逻辑推理题
- 图形计算题
几何题
- 面积和周长计算
- 角度计算
- 立体几何

核心算法

// 题目生成主流程
generateQuestions(grade, count) {
  // 1. 根据年级选择题目类型
  // 2. 生成题目内容
  // 3. 计算正确答案
  // 4. 生成干扰选项
  // 5. 验证题目质量
  // 6. 返回题目数组
}

// 小学题目生成
generatePrimaryQuestion() {
  // 基础四则运算
  // 简单应用题
  // 图形计算
}

// 初中题目生成
generateMiddleSchoolQuestion() {
  // 代数运算
  // 几何计算
  // 函数基础
}

// 高中题目生成
generateHighSchoolQuestion() {
  // 复杂函数
  // 三角函数
  // 立体几何
}

题目质量控制

难度梯度: 根据年级调整题目难度
答案验证: 确保答案正确性
选项设计: 合理的干扰选项
重复检查: 避免重复题目

题目数据结构

{
  "id": "小学-1",
  "stem": "计算：2 + 3",
  "options": [
    { "key": "A", "text": "5" },
    { "key": "B", "text": "6" },
    { "key": "C", "text": "4" },
    { "key": "D", "text": "7" }
  ],
  "answer": "A",
  "difficulty": "简单",
  "type": "四则运算"
}

智能特性

自适应难度: 根据年级自动调整
题目去重: 避免重复题目
答案验证: 多重验证确保正确性
格式统一: 标准化的题目格式

部署与问题

完整部署指南

开发环境部署

1. 安装依赖

# 安装后端依赖（必需，否则应用启动会报错）
cd src/backend
npm install

# 安装前端依赖
cd ../frontend
npm install

重要说明: 后端依赖是必需的，因为前端通过IPC调用后端工具类（如nodemailer），如果后端node_modules不存在，应用会报错 Cannot find module 'nodemailer'。

2. 开发模式运行

# 启动应用（集成前后端）
npm start

生产环境部署

1. 生成安装包

cd src/frontend
npm run build

生成安装包，包含：

数学学习软件-7.0.0-Setup.exe - 安装包
win-unpacked/ - 解压后的可执行程序目录

2. 分发安装程序

将安装包分发给用户
用户双击安装即可使用
无需额外配置或服务

常见问题解决

npm 安装问题

1. 清理环境

# 清理npm缓存
npm cache clean --force  


# 删除node_modules和package-lock.json
Remove-Item -Recurse -Force node_modules -ErrorAction SilentlyContinue  
Remove-Item -Force package-lock.json -ErrorAction SilentlyContinue

2. 配置镜像源

# 设置国内镜像源
npm config set registry https://registry.npmmirror.com  


# 设置Electron镜像
$env:ELECTRON_MIRROR = "https://npmmirror.com/mirrors/electron/"

3. 优化网络配置（并非必需，网络良好的话不进行该配置也能正常安装）

# 设置下载超时时间
npm config set fetch-timeout 300000

# 设置重试机制
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000

4. 重新安装

npm install

邮箱服务问题

检查邮箱服务商SMTP设置
确认邮箱密码（使用授权码）
检查网络连接
验证邮箱服务商限制

端口冲突问题

修改环境变量中的PORT设置
检查端口占用情况
重启服务

数据文件问题

检查data目录权限
确认文件路径配置
备份重要数据

项目状态: 生产就绪 ✅
最后更新: 2025年10月12日
架构: 前后端分离 + 单一可执行程序 + 纯IPC通信

参考规范: Google JavaScript Style Guide | Google HTML/CSS Style Guide

README.md Unescape Escape

小初高数学学习软件 - 完整项目文档

目录（所使用的代码规范地址在末尾）

🖥️ 前端部分

🔧 后端部分

📋 部署与问题

前端部分

前端项目概述

前端功能特性

前端技术栈

前端项目结构

前端快速开始

1. 环境要求

2. 安装依赖

3. 开发模式运行

4. 打包发布

前端使用指南

1. 用户注册

2. 密码设置

3. 用户信息管理

4. 数学学习

前端核心模块说明

1. 主进程模块 (electron-main.js)

功能概述

核心功能

集成架构

2. 渲染进程模块 (renderer.js)

功能概述

核心功能

主要功能模块

界面状态管理

3. 预加载脚本 (preload.js)

功能概述

核心功能

暴露的API

前端代码规范

后端部分

后端项目概述

后端功能特性

后端技术栈

后端项目结构

后端快速开始

1. 安装依赖

2. 启动服务

3. 验证服务

后端使用指南

1. API调用方式

2. 用户管理流程

3. 题目生成流程

后端核心模块说明

1. 用户管理模块 (user-manager.js)

功能概述

主要功能

核心方法

用户管理安全特性

数据存储格式

2. 邮箱服务模块 (multi-email-service.js)

功能概述

支持的服务商

核心功能

配置示例

邮件模板

3. 题目生成模块 (question-generator.js)

功能概述

生成逻辑（与个人项目逻辑类似）

题目类型

核心算法

题目质量控制

题目数据结构

智能特性

后端代码规范

JavaScript代码规范

模块化规范

数据安全规范

1. 用户管理模块 (user-manager.js)

功能概述

主要功能

核心方法

用户管理安全特性

数据存储格式

README.md

Unescape Escape