数据结构课程设计项目 —— 通过图形、动画和步骤列表直观展示算法执行过程
本平台是一个前后端分离的 Web 应用，用于可视化展示经典算法的执行过程。用户可以选择算法、输入或生成测试数据，通过动画、图形和步骤列表观察算法的关键状态变化，帮助理解算法思想和执行逻辑。
- 4 个类型算法的过程可视化：排序（快速排序）、图算法（Dijkstra 最短路径）、树结构（哈夫曼树构造）、递归（汉诺塔）
- 3 种数据输入方式：手动输入、随机生成、预置用例（共 9 条）
- 完整播放控制：播放、暂停、单步执行、上一步回退、重置、速度调节（0.5x ~ 4x）
- 步骤列表：展示每一步文字说明，点击可跳转到对应步骤
- 算法信息展示：时间复杂度、空间复杂度、伪代码
- 后端持久化（可选）：自定义测试数据保存、历史执行日志管理、用户反馈收集
- 离线降级：后端不可用时，核心可视化功能不受影响
| 序号 | 类型 | 算法 | 难度 | 可视化方式 |
|---|---|---|---|---|
| 1 | 排序 | 快速排序 (Quick Sort) | 中等 | Canvas 柱状图 + 分区动画 |
| 2 | 图算法 | Dijkstra 最短路径 | 中等 | SVG 节点-边图 + 距离表 |
| 3 | 树结构 | 哈夫曼树构造 | 中等 | SVG 二叉树 + 编码表 |
| 4 | 递归 | 汉诺塔 (Tower of Hanoi) | 中-高 | Canvas 三柱 + 盘子移动动画 |
| 类别 | 要求 |
|---|---|
| 浏览器 | Chrome 90+ / Edge 90+ / Firefox 88+（需支持 ES Modules） |
| Node.js | 16+（仅用于运行 http-server 静态服务，非必需） |
| 端口 | 8080（前端） |
| 类别 | 要求 |
|---|---|
| JDK | 17+（Spring Boot 3.2 最低要求） |
| Maven | 3.8+ |
| 数据库 | MySQL 8.0（默认）或 H2（内嵌，零安装） |
| 端口 | 3001 |
| 操作系统 | Windows / macOS / Linux |
说明：后端为可选组件。不启动后端时，算法可视化、预置用例、输入校验、日志导出（JSON/Markdown）等核心功能均可正常使用。
无需安装任何依赖。 项目使用浏览器原生 ES Modules，不依赖 npm 包。
只需一个静态 HTTP 服务器（因为 ES Modules 不支持 file:// 协议加载）：
# 方式一：使用 npx（推荐，Node.js 自带）
npx http-server -p 8080 -c-1
# 方式二：全局安装 http-server
npm install -g http-server
http-server -p 8080 -c-1
# 方式三：使用 Python
python -m http.server 8080
# 方式四：使用 VS Code Live Server 插件
# 右键 index.html → "Open with Live Server"H2 是内嵌文件数据库，无需单独安装任何数据库软件：
cd backend
mvn spring-boot:run -Dspring-boot.run.profiles=h2首次启动后，会在 backend/data/ 目录下自动创建数据库文件。
- 安装 MySQL 8.0
- 创建数据库（可选，应用首次启动会自动创建）：
CREATE DATABASE IF NOT EXISTS algo_viz
DEFAULT CHARACTER SET utf8mb4
DEFAULT COLLATE utf8mb4_unicode_ci;- 确认
backend/src/main/resources/application.yml中的数据库连接信息：
spring:
datasource:
url: jdbc:mysql://localhost:3306/algo_viz?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf-8&allowPublicKeyRetrieval=true&createDatabaseIfNotExist=true
username: root
password: "123456"# 在项目根目录执行
npx http-server -p 8080 -c-1
# 或双击 Windows 启动脚本
run.bat浏览器打开 http://localhost:8080
终端 1 — 启动后端：
cd backend
# H2 模式（推荐，零依赖）
mvn spring-boot:run -Dspring-boot.run.profiles=h2
# MySQL 模式
mvn spring-boot:run终端 2 — 启动前端：
# 在项目根目录执行
npx http-server -p 8080 -c-1验证后端运行：
# 健康检查
curl http://localhost:3001/api/test-data/quick-sort
# 应返回: {"success":true,"data":[],"error":null}
# H2 控制台（仅 H2 模式）
# 浏览器打开 http://localhost:3001/h2-console
# JDBC URL: jdbc:h2:file:./data/algo_viz
# 用户名: sa，密码留空前端会在右上角显示后端连接状态（🟢 在线 / 🔴 离线）。
cd backend
mvn test| 功能 | 验证方法 |
|---|---|
| 算法可视化 | 选择算法 → 加载预置用例 → 点击「执行」→ 观察动画 |
| 手动输入 | 手动输入合法数据 → 点击「执行」 |
| 输入校验 | 输入非法数据 → 观察即时错误提示 |
| 随机生成 | 点击「🎲 随机生成」→ 自动填充合法数据 |
| 播放控制 | 测试播放/暂停/单步/回退/重置/速度调节 |
| 步骤跳转 | 点击步骤列表中的某一步 |
| 保存自定义数据 | 点击「💾 保存」（需后端在线） |
| 历史日志 | 执行完成后保存日志 → 侧边栏查看/导出/删除（需后端在线） |
| 反馈提交 | 侧边栏填写反馈 → 提交（需后端在线） |
| 日志导出 | 展开历史日志 → 导出 JSON / 导出 Markdown |
| 离线降级 | 停止后端 → 观察 15 秒后 UI 按钮变灰 + tooltip 提示 |
| 算法 | 用例名称 | 输入数据 | 说明 |
|---|---|---|---|
| 快速排序 | 随机数组（7个元素） | 64, 34, 25, 12, 22, 11, 90 |
正常用例 |
| 快速排序 | 逆序数组（最坏情况） | 50, 40, 30, 20, 10 |
边界：逆序 |
| 快速排序 | 含重复元素 | 42, 23, 42, 17, 23, 8, 42 |
边界：重复值 |
| Dijkstra | 5节点带权图 | 节点 A-E，起点 A | 正常用例 |
| Dijkstra | 稀疏路径图 | 节点 S,A,B,C,T，起点 S | 边界：稀疏图 |
| 哈夫曼树 | 标准频率分布 | a:5, b:9, c:12, d:13, e:16, f:45 |
正常用例 |
| 哈夫曼树 | 等频率边界 | x:10, y:10, z:10, w:10 |
边界：等频率 |
| 汉诺塔 | 3层汉诺塔 | 3（7步完成） |
正常用例 |
| 汉诺塔 | 4层汉诺塔 | 4（15步完成） |
较大输入 |
输入格式: 数字数组，用逗号分隔
示例: 64, 34, 25, 12, 22, 11, 90
约束: 3-50 个数字，值范围 1-100
更多示例
# 正常数组
64, 34, 25, 12, 22, 11, 90
# 逆序数组（快速排序最坏情况）
50, 40, 30, 20, 10
# 含重复元素
42, 23, 42, 17, 23, 8, 42
# 随机生成（点击 🎲 按钮）
输入格式:
第一行 — 节点列表（逗号分隔）
第二行 — 边及权值（格式：起点-终点:权值，逗号分隔）
第三行 — 起点
示例:
A, B, C, D, E
A-B:4, A-C:2, B-C:1, B-D:5, C-D:8, C-E:10, D-E:2
A
约束: 3-10 个节点，边权值 1-99
更多示例
# 5节点连通图
A, B, C, D, E
A-B:4, A-C:2, B-C:1, B-D:5, C-D:8, C-E:10, D-E:2
A
# 稀疏路径图（仅有一条唯一最短路径）
S, A, B, C, T
S-A:7, S-B:2, S-C:3, A-B:3, A-D:4, B-D:4, B-H:1, C-L:2, D-F:5, H-F:3, H-G:2, L-G:4, L-J:4, G-E:2, J-E:5, F-T:4, G-T:3, E-T:5
S
输入格式: 字符:频率，逗号分隔
示例: a:5, b:9, c:12, d:13, e:16, f:45
约束: 3-10 个字符，频率范围 1-100
更多示例
# 标准频率分布（哈夫曼编码经典示例）
a:5, b:9, c:12, d:13, e:16, f:45
# 等频率边界情况
x:10, y:10, z:10, w:10
# 递减频率
m:40, n:30, o:20, p:10
# 随机生成（点击 🎲 按钮）
输入格式: 单个整数（盘子数量）
示例: 3
约束: 2-8 个盘子
步数对照
| 盘子数 | 最少移动步数 |
|---|---|
| 2 | 3 |
| 3 | 7 |
| 4 | 15 |
| 5 | 31 |
| 6 | 63 |
| 7 | 127 |
| 8 | 255 |
⚠️ n=7 或 n=8 时步数较多，建议调高播放速度（2x ~ 4x）。
Algorithm/
├── index.html # 应用入口
├── run.bat # Windows 一键启动脚本
├── css/
│ └── main.css # 全局样式 + 主题 + 响应式布局
├── js/
│ ├── app.js # 应用入口，组件初始化与事件总线接线
│ ├── core/
│ │ ├── AlgorithmEngine.js # 算法引擎基类（模板方法模式）
│ │ ├── ExecutionController.js # 执行控制器（状态机）
│ │ └── DataValidator.js # 数据校验器
│ ├── algorithms/
│ │ ├── QuickSortEngine.js # 快速排序引擎
│ │ ├── DijkstraEngine.js # Dijkstra 最短路径引擎
│ │ ├── HuffmanEngine.js # 哈夫曼树构造引擎
│ │ └── HanoiEngine.js # 汉诺塔递归引擎
│ ├── visualization/
│ │ ├── CanvasRenderer.js # Canvas 渲染器基类
│ │ ├── SvgRenderer.js # SVG 渲染器基类
│ │ ├── SortVisualizer.js # 排序柱状图可视化
│ │ ├── GraphVisualizer.js # 图节点-边可视化
│ │ ├── TreeVisualizer.js # 哈夫曼树可视化
│ │ └── HanoiVisualizer.js # 汉诺塔可视化
│ ├── ui/
│ │ ├── AlgorithmSelector.js # 算法选择卡片
│ │ ├── DataInputPanel.js # 数据输入面板
│ │ ├── InfoPanel.js # 算法信息面板
│ │ ├── PlaybackControls.js # 播放控制按钮
│ │ ├── StepListPanel.js # 步骤列表面板
│ │ ├── LogPanel.js # 历史日志面板
│ │ └── FeedbackPanel.js # 意见反馈面板
│ └── utils/
│ ├── EventBus.js # 事件总线（发布/订阅）
│ ├── constants.js # 算法元数据 + 测试用例 + 颜色常量
│ └── ApiClient.js # 后端 API 通信客户端
├── backend/
│ ├── pom.xml # Maven 构建配置
│ └── src/main/java/com/algoviz/
│ ├── AlgoVizApplication.java # Spring Boot 启动入口
│ ├── dto/ApiResponse.java # 统一 API 响应格式
│ ├── entity/ # JPA 实体（TestData, ExecutionLog, Feedback）
│ ├── repository/ # JPA 数据仓库接口
│ ├── service/ # 业务逻辑层
│ ├── controller/ # REST 控制器
│ └── config/ # CORS 配置 + 全局异常处理
└── docs/
├── 需求分析文档.md # 需求分析文档（含 UML 图）
├── 系统设计文档.md # 系统设计文档（含架构设计）
└── 后端代码说明文档.md # 后端代码详细说明
所有接口返回统一格式：{ "success": true/false, "data": {...}, "error": "..." }
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/test-data/{algorithmId} |
查询已保存数据列表 |
| POST | /api/test-data/{algorithmId} |
保存新数据 { name, input } |
| PUT | /api/test-data/{algorithmId}/{dataId} |
更新已保存数据 |
| DELETE | /api/test-data/{algorithmId}/{dataId} |
删除已保存数据 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/logs |
日志列表（不含步骤详情） |
| GET | /api/logs/{id} |
日志详情（含完整步骤快照） |
| POST | /api/logs |
保存日志 |
| DELETE | /api/logs/{id} |
删除日志 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/feedback |
反馈列表 |
| POST | /api/feedback |
提交反馈 { type, content, contact? } |
在左侧边栏的「算法选择」区域，点击任意算法卡片。选中后右侧可视化区域准备就绪，数据输入面板自动切换为对应格式。
支持三种方式：
| 方式 | 说明 |
|---|---|
| 手动输入 | 根据算法类型输入对应格式的数据 |
| 随机生成 | 点击「🎲 随机生成」按钮自动生成合法测试数据 |
| 预置用例 | 从下拉菜单选择预置的测试用例 |
输入非法数据时，系统会即时显示错误提示。
底部控制栏提供完整的播放控制：
| 按钮 | 功能 |
|---|---|
| ⏮ 重置 | 回到初始状态 |
| ◀ 上一步 | 回退一个步骤 |
| ▶ 播放 / ⏸ 暂停 | 自动播放/暂停执行过程 |
| 下一步 ▶ | 前进一个步骤 |
| 速度滑块 (0.5x ~ 4x) | 调节播放速度 |
- 中间可视化区域：显示算法执行的图形动画
- 右侧步骤列表：显示每一步的文字说明，点击可跳转到对应步骤
- 左侧算法信息面板：显示时间复杂度、空间复杂度和伪代码
后端上线/掉线的检测周期为 15 秒（ApiClient 心跳间隔）。停止后端后，前端右上角状态指示器最多延迟 15 秒才会切换为「离线」。如需立即刷新，可刷新页面让 app.js 初始化时触发即时检查。
n=8 时共 255 步，长时间自动播放可能导致浏览器标签页性能下降。建议调高播放速度至 4x，或使用单步执行模式逐步观察。
使用 H2 profile 启动后端时，数据库文件创建在 backend/data/ 目录下。如切换到 MySQL profile 后再切回 H2，之前的数据仍保留在文件中，不会丢失。该目录已被 .gitignore 排除。
由于浏览器安全策略，ES Modules (import/export) 不支持 file:// 协议。直接双击 index.html 打开会导致模块加载失败（控制台报错 Failed to load module script）。必须通过 HTTP 服务器访问。
后端要求 JDK 17 或更高版本。如果系统安装了多个 JDK 版本，可在 backend/pom.xml 中修改 <java.version> 配置，或通过 JAVA_HOME 环境变量指定。
后端默认使用 3001 端口。如果端口被占用，修改 application.yml 中的 server.port 值，同时修改前端 js/utils/ApiClient.js 中的 BASE_URL 常量。
| 文档 | 路径 | 说明 |
|---|---|---|
| 题目要求 | docs/题目要求.txt |
课程设计原始题目 |
| 需求分析文档 | docs/需求分析文档.md |
问题定义、可行性研究、需求分析、UML 图 |
| 系统设计文档 | docs/系统设计文档.md |
架构设计、模块划分、数据结构、接口设计 |
| 后端代码说明 | docs/后端代码说明文档.md |
后端分层架构、API 接口、数据流转 |
| 项目进度 | PROGRESS.md |
开发进度和验收清单 |
📝 课程: 程序设计课程设计
📅 日期: 2026-06
🤖 AI 辅助: 本项目使用 Claude Code (Anthropic) 辅助完成需求分析、系统设计和代码生成