24 KiB

Raw Blame History Unescape Escape

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

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

前端部分

前端项目概述

本前端基于 Electron，提供从注册→密码设置→年级选择→输入题数→答题页→评分页的完整界面流程。已内置测试功能，无需后端即可验证所有基础功能。

前端功能特性

✅ 用户注册与邮箱验证码
✅ 密码设置与修改
✅ 用户头像上传
✅ 用户名修改
✅ 年级选择（小学/初中/高中）
✅ 数学题目生成与答题
✅ 成绩统计与显示
✅ 桌面应用打包

前端技术栈

框架: Electron
前端: HTML5 + CSS3 + JavaScript (ES6+)
样式: 原生CSS（符合Google CSS规范）
代码规范: Google JavaScript/CSS/HTML规范

前端项目结构

src/frontend/
├─ api/
│   ├─ httpApi.js          # HTTP接口层
│   └─ mockApi.js          # 模拟数据接口
├─ dist/                   # 打包输出目录
├─ electron-main.js        # Electron主进程
├─ preload.js             # 预加载脚本
├─ index.html             # 主页面
├─ renderer.js            # 前端逻辑
├─ styles.css             # 样式文件
├─ package.json           # 项目配置
└─ package-lock.json      # 依赖锁定

前端快速开始

1. 环境要求

Node.js 18+
npm 或 yarn

2. 安装依赖

cd src/frontend
npm install

3. 开发模式运行

npm run dev

4. 打包发布

npm run build

产物位于 dist/ 目录，默认生成 NSIS 安装包。

前端功能验证流程

测试模式

当前为测试模式（TEST_MODE = true），可以：

模拟邮箱验证码发送（界面直接显示验证码）
模拟用户注册和密码设置
自动生成小初高数学题目
完整的答题和评分流程

1. 注册验证

输入用户名（必填，需唯一）
输入邮箱（如 test@example.com）
点击"获取验证码"：界面会显示验证码（如 123456）
输入显示的验证码，点击"注册"

2. 密码设置验证

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

3. 用户信息管理

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

4. 答题功能验证

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

前端后端对接指南

1. 切换到真实后端

编辑 api/httpApi.js：

const BASE_URL = 'http://127.0.0.1:8080'; // 你的后端地址
const TEST_MODE = false; // 关闭测试模式

2. 后端接口要求

你的后端需要实现以下接口（返回 JSON 格式）：

发送验证码

接口：POST /api/send-code
请求体：{ "email": "user@example.com", "username": "用户名" }
返回：{ "ok": true, "message": "验证码已发送" }

用户注册

接口：POST /api/register
请求体：{ "email": "user@example.com", "username": "用户名", "code": "123456" }
返回：{ "ok": true, "message": "注册成功" }

设置密码

接口：POST /api/set-password
请求体：{ "email": "user@example.com", "password": "密码" }
返回：{ "ok": true, "message": "密码设置成功" }

修改密码

接口：POST /api/change-password
请求体：{ "email": "user@example.com", "oldPassword": "原密码", "newPassword": "新密码" }
返回：{ "ok": true, "message": "密码修改成功" }

修改用户名

接口：POST /api/change-username
请求体：{ "email": "user@example.com", "username": "新用户名" }
返回：{ "ok": true, "message": "用户名修改成功" }

获取题目

接口：GET /api/questions?grade=小学&count=10
返回：{ "ok": true, "data": [题目数组], "message": "题目生成成功" }

3. 题目数据格式

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

前端核心模块说明

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

功能概述

Electron主进程模块负责创建和管理应用程序窗口，处理系统级事件，管理应用程序生命周期。

核心功能

窗口管理: 创建和管理应用窗口
菜单配置: 应用程序菜单设置
安全配置: 安全策略和权限控制
生命周期管理: 应用程序启动和关闭

窗口配置

const mainWindow = new BrowserWindow({
  width: 1200,
  height: 800,
  webPreferences: {
    nodeIntegration: false,
    contextIsolation: true,
    preload: path.join(__dirname, 'preload.js')
  }
});

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

功能概述

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

核心功能

界面管理: 页面切换和状态管理
用户交互: 表单处理、事件监听
数据管理: 本地数据存储和同步
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)

功能概述

预加载脚本负责在渲染进程中安全地暴露Node.js API，确保应用程序的安全性。

预加载安全特性

API暴露: 安全地暴露必要的Node.js API
权限控制: 限制渲染进程的权限
数据验证: 输入数据验证和清理

暴露的API

contextBridge.exposeInMainWorld('electronAPI', {
  // 文件操作
  selectFile: () => ipcRenderer.invoke('select-file'),
  
  // 窗口操作
  minimizeWindow: () => ipcRenderer.invoke('minimize-window'),
  closeWindow: () => ipcRenderer.invoke('close-window')
});

4. API接口层 (api/)

HTTP接口模块 (httpApi.js)

负责与后端服务通信，处理HTTP请求和响应。

核心功能

请求封装: 统一的HTTP请求处理
错误处理: 网络错误和业务错误处理
数据转换: 请求和响应数据格式转换
缓存管理: 请求缓存和优化

接口方法

class HttpAPI {
  // 发送验证码
  async sendCode(email, username)
  
  // 用户注册
  async register(userData)
  
  // 设置密码
  async setPassword(email, password)
  
  // 获取题目
  async getQuestions(grade, count)
  
  // 用户信息管理
  async changeUsername(email, username)
  async changePassword(email, oldPassword, newPassword)
}

模拟接口模块 (mockApi.js)

提供测试模式下的模拟数据，支持离线开发和测试。

模拟功能

验证码模拟: 界面显示验证码
用户数据模拟: 本地用户数据管理
题目生成模拟: 本地题目生成
成绩计算模拟: 本地成绩计算

5. 样式系统 (styles.css)

设计系统

颜色系统: 统一的颜色变量和主题
字体系统: 字体大小、行高、字重规范
间距系统: 统一的间距和布局规范
组件样式: 可复用的组件样式

CSS变量系统

:root {
  --bg: #0e1116;
  --border: #202734;
  --danger: #ef4444;
  --muted: #9aa4b2;
  --panel: #151a21;
  --primary: #3b82f6;
  --primary-2: #2563eb;
  --success: #22c55e;
  --text: #e8edf3;
}

响应式设计

移动端适配: 响应式布局设计
窗口适配: 不同窗口尺寸适配
主题支持: 深色主题设计

6. 用户界面组件

页面组件

登录页面: 用户认证界面
注册页面: 用户注册界面
设置密码页面: 密码设置界面
年级选择页面: 年级选择界面
答题页面: 题目答题界面
成绩页面: 成绩显示界面

交互组件

表单组件: 输入框、按钮、选择器
模态框组件: 确认对话框、提示框
导航组件: 页面导航和状态指示
反馈组件: 成功提示、错误提示

用户体验

加载状态: 加载动画和状态提示
错误处理: 友好的错误提示
操作反馈: 操作成功和失败反馈
数据验证: 实时表单验证

前端代码规范

所有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           # 邮箱配置
├─ server.js                 # 主服务器文件
├─ package.json              # 项目配置
└─ package-lock.json         # 依赖锁定

后端环境配置

1. 环境变量

在 src/backend 目录下创建 .env 文件：

PORT=8080
NODE_ENV=development
SMTP_QQ_USER=your_qq@example.com
SMTP_QQ_PASS=your_smtp_password
SMTP_163_USER=your_163@example.com
SMTP_163_PASS=your_smtp_password
MAIL_FROM_NAME=数学学习软件
DATA_PATH=./data/users.json

2. 邮箱服务配置

支持多个邮箱服务商：

QQ邮箱
163邮箱
其他SMTP服务（还没有配置，暂时只有这两个邮箱）

后端快速开始

1. 安装依赖


cd src/backend
npm install

2. 启动服务

npm start

3. 验证服务

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

API 接口文档

基础信息

基础URL: http://localhost:8080
数据格式: JSON
请求方法: GET/POST

1. 发送验证码

URL: POST /api/send-code
请求体:


{
  "email": "user@example.com",
  "username": "用户名"
}

响应:


{
  "ok": true,
  "message": "验证码已发送"
}

2. 用户注册

URL: POST /api/register
请求体:


{
  "email": "user@example.com",
  "username": "用户名",
  "code": "123456"
}

响应:


{
  "ok": true,
  "message": "注册成功"
}

3. 设置密码

URL: POST /api/set-password
请求体:


{
  "email": "user@example.com",
  "password": "新密码"
}

响应:


{
  "ok": true,
  "message": "密码已设置"
}

4. 修改密码

URL: POST /api/change-password
请求体:


{
  "email": "user@example.com",
  "oldPassword": "旧密码",
  "newPassword": "新密码"
}

响应:


{
  "ok": true,
  "message": "密码修改成功"
}

5. 修改用户名

URL: POST /api/change-username
请求体:


{
  "email": "user@example.com",
  "username": "新用户名"
}

响应:


{
  "ok": true,
  "message": "用户名修改成功"
}

6. 获取题目

URL: GET /api/questions?grade=小学&count=10
参数:
- grade: 年级（小学/初中/高中）
- count: 题目数量（10-30）
响应:

{
  "ok": true,
  "data": [
    {
      "id": "小学-1",
      "stem": "计算：2 + 3",

      "options": [
        { "key": "A", "text": "5" },
        { "key": "B", "text": "6" },
        { "key": "C", "text": "4" },
        { "key": "D", "text": "7" }
      ],
      "answer": "A"
    }
  ],
  "message": "题目生成成功"
}

后端核心模块说明

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": "四则运算"
}

智能特性

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

4. 服务器主模块 (server.js)

功能概述

服务器主模块是整个后端系统的入口，负责处理HTTP请求、路由分发、中间件配置等核心功能。

核心功能

HTTP服务器: 基于Express框架的Web服务器
路由管理: RESTful API路由设计
中间件配置: 跨域、解析、错误处理等
端口监听: 可配置的端口监听

API路由设计

// 用户相关路由
app.post('/api/send-code', sendCodeHandler);
app.post('/api/register', registerHandler);
app.post('/api/set-password', setPasswordHandler);
app.post('/api/change-password', changePasswordHandler);
app.post('/api/change-username', changeUsernameHandler);

// 题目相关路由
app.get('/api/questions', getQuestionsHandler);

错误处理

统一错误格式: 标准化的错误响应
日志记录: 详细的错误日志
异常捕获: 全局异常处理机制

安全配置

CORS设置: 跨域请求处理
请求验证: 输入数据验证
错误信息: 安全的错误信息返回

5. 邮箱配置模块 (email-config.js)

功能概述

邮箱配置模块负责管理所有邮箱相关的配置，包括服务商配置、模板配置、发送参数等。

配置管理

环境变量: 从.env文件读取配置
服务商配置: 多邮箱服务商支持
模板管理: 邮件模板配置
参数验证: 配置参数验证

配置结构

const emailConfig = {
  services: {
    qq: { /* QQ邮箱配置 */ },
    netease: { /* 163邮箱配置 */ }
  },
  templates: {
    verification: { /* 验证码模板 */ }
  },
  settings: {
    timeout: 30000,
    retryCount: 3
  }
}

6. 数据管理

数据存储

文件存储: JSON文件存储用户数据
数据备份: 自动备份机制
数据恢复: 数据恢复功能
数据验证: 数据完整性检查

数据安全

加密存储: 敏感数据加密
访问控制: 数据访问权限控制
备份策略: 定期数据备份
恢复机制: 数据恢复流程

性能优化

缓存机制: 数据缓存策略
异步处理: 异步数据操作
内存管理: 内存使用优化
并发控制: 并发请求处理

数据存储

用户数据: src/backend/data/users.json
数据格式: JSON数组
加密方式: SHA256

安全特性

密码SHA256加密存储
邮箱验证码验证
用户名唯一性检查
输入数据验证

部署与问题

完整部署指南

开发环境部署

1. 后端部署

# 进入后端目录
cd src/backend

# 安装依赖
npm install

# 配置环境变量（创建.env文件）
# 启动服务
npm start

2. 前端部署

# 进入前端目录
cd src/frontend

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 或打包发布
npm run build

生产环境部署

1. 后端部署

配置生产环境变量
设置邮箱服务商
配置数据备份
使用PM2等进程管理工具

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目录权限
确认文件路径配置
备份重要数据

项目特色

代码质量

✅ 完全符合Google代码规范
✅ 统一的代码风格
✅ 完整的错误处理
✅ 详细的注释说明

用户体验

✅ 直观的界面设计
✅ 流畅的操作体验
✅ 完善的错误提示
✅ 响应式布局

技术架构

✅ 前后端分离
✅ 模块化设计
✅ 可扩展架构
✅ 安全可靠

项目状态: 生产就绪 ✅
最后更新: 2025年10月12日

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

24 KiB Raw Blame History Unescape Escape

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

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

📱 前端部分

🔧 后端部分

📋 部署与问题

前端部分

前端项目概述

前端功能特性

前端技术栈

前端项目结构

前端快速开始

1. 环境要求

2. 安装依赖

3. 开发模式运行

4. 打包发布

前端功能验证流程

测试模式

1. 注册验证

2. 密码设置验证

3. 用户信息管理

4. 答题功能验证

前端后端对接指南

1. 切换到真实后端

2. 后端接口要求

发送验证码

用户注册

设置密码

修改密码

修改用户名

获取题目

3. 题目数据格式

前端核心模块说明

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

功能概述

核心功能

窗口配置

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

功能概述

核心功能

主要功能模块

界面状态管理

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

功能概述

预加载安全特性

暴露的API

4. API接口层 (api/)

HTTP接口模块 (httpApi.js)

核心功能

接口方法

模拟接口模块 (mockApi.js)

模拟功能

5. 样式系统 (styles.css)

设计系统

CSS变量系统

响应式设计

6. 用户界面组件

页面组件

交互组件

用户体验

前端代码规范

后端部分

后端项目概述

后端功能特性

后端技术栈

后端项目结构

后端环境配置

1. 环境变量

2. 邮箱服务配置

后端快速开始

1. 安装依赖

2. 启动服务

3. 验证服务

API 接口文档

基础信息

1. 发送验证码

2. 用户注册

3. 设置密码

4. 修改密码

5. 修改用户名

24 KiB

Raw Blame History Unescape Escape