# 学科引擎SubjEngine

**Repository Path**: codekpy/subj-engine

## Basic Information

- **Project Name**: 学科引擎SubjEngine
- **Description**: 概述：EduTools 是一套面向高中教学的交互式网页教材与实验演示集合，包含物理、化学等学科的可视化模拟与教学工具。
特点：基于轻量 HTML/CSS/JavaScript（使用 Tailwind 等工具），界面响应式、交互友好、参数可调，便于课堂演示与学生自主探索。
目标受众：高中教师与学生，也适合作为教材补充与课堂实验预习资源。
贡献与部署：源码友好、便于扩展，欢迎加入项目
- **Primary Language**: JavaScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://subj-engine.cloudroo.top/
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 4
- **Created**: 2025-12-13
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SubjEngine · 学科引擎

> **让知识可视化，让学习更生动** | Making Knowledge Visible, Making Learning More Vivid

SubjEngine 是一个开源的学科交互式模拟动画聚合平台，致力于将物理、化学、数学、信息技术等学科的抽象概念转化为可视化的交互式演示。项目聚合了 **24+** 个高质量的模拟演示页面，支持多维度搜索筛选、收藏、下载和 Canvas 录制功能。

[![Gitee](https://img.shields.io/badge/Gitee-subj--engine-0071e3?style=flat-square)](https://gitee.com/codekpy/subj-engine.git)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](LICENSE)

---

## 目录

- [在线预览](#在线预览)
- [核心特性](#核心特性)
- [项目结构](#项目结构)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [学科项目总览](#学科项目总览)
- [子项目详解](#子项目详解)
- [数据格式](#数据格式)
- [贡献指南](#贡献指南)
- [开发指南](#开发指南)
- [许可证](#许可证)
- [致谢](#致谢)

---

## 在线预览

| 页面 | 截图 | 描述 |
|------|------|------|
| **首页** | ![首页预览](docs/home.png) | Apple 风格导航，推荐项目水平滚动，瀑布流展示 |
| **分子浏览器** | ![分子浏览器](docs/MoleculeViewer.png) | 基于 Three.js 的 3D 分子查看器 |
| **双缝干涉** | ![双缝干涉](docs/double-slit-interference.png) | 光的波动性交互演示 |
| **横波干涉** | ![横波干涉](docs/wave-interference.png) | 机械波叠加原理演示 |
| **寻路算法** | ![寻路算法](docs/pathfinding.png) | 四种经典寻路算法可视化 |

> 在线访问：[https://subj-engine.cloudroo.top/](https://subj-engine.cloudroo.top/)

---

## 核心特性

### 多学科覆盖
涵盖 **物理**、**化学**、**数学**、**信息技术** 四个学科，从初中到高中选必修阶段，共 **24+** 个交互式模拟演示。

### 现代化 UI/UX
- **Apple 风格设计**：SF Pro 字体、玻璃态磨砂质感、沉浸式暗色模式
- **智能筛选**：支持关键词搜索、学科筛选、阶段筛选、热门标签云
- **收藏系统**：基于 localStorage 的持久化收藏功能
- **推荐滚动**：两排相向滚动的推荐项目展示

### 统一查看器
所有演示页面通过 `viewer.html` 统一加载，提供：
- iframe 嵌套加载演示页面
- 项目信息展示（名称、作者、学科、简介）
- 前后导航和相关推荐
- **下载功能**：支持单文件下载或 ZIP 包打包下载

### Canvas 录制
内置 `canvas-recorder.js` 录制组件，支持：
- 录制/停止/下载控制
- 多格式导出（WebM / MP4 / GIF）
- 视频裁剪功能（设置起始/结束时间）
- 录制时长实时显示

### 3D 交互可视化
基于 Three.js 构建的 3D 化学工具套件：
- **分子浏览器**：分子搜索、VSEPR 模型、孤电子对显示
- **分子编辑器 MolForge**：分子构建、编辑、导入/导出
- **晶胞查看器**：多种晶体结构 3D 展示

---

## 项目结构

```
EduTools/
├── index.html                    # 首页（Apple 风格，水平滚动 + 瀑布流）
├── viewer.html                   # 统一查看页面（iframe 嵌套演示）
├── list.json                     # 演示条目数据（24+ 项目）
├── author.json                   # 创作者信息（3 位贡献者）
├── plan.md                       # 项目开发计划
├── task.md                       # 任务进度跟踪
├── prompt.md                     # 页面构建开发指南/模板
├── blog-post.md                  # 项目推广博客文章
├── LICENSE                       # Apache 2.0 许可证
│
├── Physics/                      # 物理学科模拟（13 个演示）
├── Chemistry/                    # 化学学科模拟
│   ├── CrystalCell/              #    晶胞 3D 交互可视化 (Vite + TS)
│   ├── MolForge/                 #    3D 分子编辑器 (Vite + TS)
│   ├── MoleculeViewer/           #    3D 分子浏览器 (Vite + TS)
│   ├── PeriodicLab/              #    主族元素周期律交互实验室
│   └── virtual-lab/              #    化学虚拟实验室（仪器 + 试剂 + 反应）
├── Math/                         # 数学学科模拟（2 个演示）
├── Information/                  # 信息技术学科模拟（2 个演示）
│
├── static/                       # 公共静态资源
│   ├── css/                      #    样式文件（Tailwind, Font Awesome, index.css...）
│   ├── js/                       #    JavaScript 库（Tailwind, MathJax, Three.js, 录制组件...）
│   ├── fonts/                    #    字体文件
│   ├── img/                      #    图片资源
│   └── webfonts/                 #    Web 字体
│
├── tools/                        # 工具类页面
│   └── editor.html               #    list.json 浏览器端编辑器
│
├── docs/                         # 文档截图
└── .trae/                        # AI 辅助开发记录与规范
    ├── rules/                    #    项目规则
    ├── specs/                    #    功能规格文档
    ├── documents/                #    设计文档
    └── skills/                   #    开发技能定义
```

---

## 技术栈

| 类别 | 技术 | 说明 |
|------|------|------|
| **前端基础** | HTML5 / CSS3 / JavaScript (ES6+) | 原生开发，零框架依赖 |
| **TypeScript** | TypeScript 5.3+ | 用于 3 个 Vite 子项目 |
| **CSS 框架** | [Tailwind CSS](https://tailwindcss.com/) 3.4 | 本地文件加载，无需构建 |
| **图标库** | [Font Awesome](https://fontawesome.com/) 4.7 / 6.4 | 本地文件加载 |
| **数学公式** | [MathJax](https://www.mathjax.org/) 3 | 本地文件，支持 LaTeX |
| **3D 图形** | [Three.js](https://threejs.org/) r160 | 3 个化学子项目使用 |
| **2D 图形** | HTML5 Canvas API | 所有演示页面核心渲染 |
| **构建工具** | [Vite](https://vitejs.dev/) 5 | 3 个 TypeScript 子项目 |
| **录制组件** | MediaRecorder API | Canvas 录制与导出 |
| **打包下载** | JSZip | CDN 引入，ZIP 打包 |

---

## 快速开始

### 前置要求

- 现代浏览器（Chrome 90+ / Firefox 90+ / Edge 90+ / Safari 15+）
- 可选：Python 3.x 或 Node.js（用于本地预览）

### 本地预览

本项目为纯静态网站，无需构建即可运行。使用任意 HTTP 服务器启动：

**方式一：Python**
```powershell
cd f:\program\StarBit\code\EduTools
python -m http.server 8000
```

**方式二：Node.js**
```powershell
cd f:\program\StarBit\code\EduTools
npx http-server -p 8000
```

### 访问页面

- **首页**：[http://localhost:8000/](http://localhost:8000/)
- **统一查看器**：`http://localhost:8000/viewer.html?demo=Physics/lorentz-force-circular-motion.html`
- **编辑器工具**：[http://localhost:8000/tools/editor.html](http://localhost:8000/tools/editor.html)

### 构建 Vite 子项目

3 个 TS 子项目需要构建后才能访问：

```powershell
# 1. 晶胞查看器
cd Chemistry/CrystalCell
npm install
npm run build

# 2. 分子浏览器
cd ../MoleculeViewer
npm install
npm run build

# 3. 分子编辑器
cd ../MolForge
npm install
npm run build
```

构建完成后，通过 `dist/index.html` 或首页链接访问。

---

## 学科项目总览

### 物理 (Physics) — 13 个演示

| 项目 | 文件 | 阶段 | 简介 |
|------|------|------|------|
| 洛伦兹力圆周运动 | `lorentz-force-circular-motion.html` | XB2 | 带电粒子在匀强磁场中的圆周运动 |
| 力合成与分解 | `Composition&decomposition&forces.html` | B1 | 平行四边形定则和三角形定则 |
| 万有引力计算 | `CalculationOfUniversalGravitationOfCelestialBodies.html` | B2 | 牛顿万有引力定律交互计算 |
| 运动学模拟 | `kinematics-simulation.html` | B1 | 匀变速直线、自由落体、平抛运动 |
| 横波干涉 | `wave-interference-simulation.html` | XB1 | 双波源干涉、波的叠加原理 |
| 双缝干涉 | `double-slit-interference.html` | XB1 | 杨氏双缝干涉、条纹间距计算 |
| 气体分子速率分布 | `gas-molecule-motion.html` | XB3 | 麦克斯韦-玻尔兹曼分布 |
| 理想气体状态方程 | `ideal-gas-law.html` | XB3 | PV=nRT 交互验证 |
| 透镜成像 | `middle-school-physics-lens-imaging-simulation.html` | J3 | 凸/凹透镜光线轨迹 |
| 放缩圆临界问题 | `放缩圆分析临界问题.html` | XB2 | 洛伦兹力放缩圆分析 |
| 旋转圆/心轨迹 | `旋转圆2.html` | XB2 | 洛伦兹力旋转圆轨迹 |
| 电磁流量计 | `电磁流量计 .html` | XB2 | 电磁流量计工作原理 |
| 电场线演示 | `Eletrical_lineDemo/index.html` | B3 | 等量异种电荷电场线分布 |

### 化学 (Chemistry) — 6 个模块

| 项目 | 路径 | 简介 |
|------|------|------|
| 化学反应速率 | `Chemical Reaction Rate Simulation.html` | 影响反应速率因素模拟 |
| 虚拟实验室 | `virtual-lab/` | 14 种仪器 + 16 种试剂 + 实时反应 |
| 分子浏览器 | `MoleculeViewer/` | 3D 分子查看、VSEPR 模型、孤电子对 |
| 分子编辑器 MolForge | `MolForge/` | 3D 分子构建、编辑、导入/导出 |
| 晶胞交互可视化 | `CrystalCell/` | 简单立方/FCC/金刚石/CaF₂ 结构 |
| 主族元素周期律 | `PeriodicLab/` | 电离能、电负性、键极性周期律 |

### 数学 (Math) — 2 个演示

| 项目 | 文件 | 简介 |
|------|------|------|
| 数列动画 | `sequence-animation.html` | 等差/等比数列可视化 |
| 反比例函数 | `ReciprocalSimulator.html` | 反比例函数动态演示 |

### 信息技术 (Information) — 2 个演示

| 项目 | 文件 | 简介 |
|------|------|------|
| 寻路算法演示 | `pathfinding-algorithms.html` | DFS/BFS/Dijkstra/A* 四种算法可视化 |
| 高精度计算 | `high-precision-calculation.html` | 大数竖式计算（加/减/乘/除） |

---

## 子项目详解

### 化学虚拟实验室

仿真实体实验室的交互式化学实验平台。

- **14 种仪器**：烧杯、试管、锥形瓶、圆底烧瓶、量筒、酒精灯、石棉网、铁架台、玻璃棒、滴管、漏斗、药匙、温度计、pH 试纸
- **16 种试剂**：3 酸 + 3 碱 + 3 盐 + 3 指示剂 + 4 金属
- **实时反应引擎**：酸碱中和、金属与酸、复分解、指示剂变色
- **视觉效果**：液体颜色混合、气泡动画、沉淀沉降、温度变化
- **8 个预设实验**：开箱即用的经典化学实验场景

### 3D 分子浏览器 (MoleculeViewer)

基于 Three.js + TypeScript + Vite 构建的全屏 3D 分子查看器。

- **分子搜索**：内置 10+ 常见分子数据（H₂O, CO₂, CH₄, NH₃ 等）
- **3D 交互**：鼠标旋转/缩放，OrbitControls
- **坐标系参考轴**：Blender 风格，点击快速切换视角（X/Y/Z 正负方向）
- **VSEPR 模型**：支持分子几何构型切换
- **孤电子对显示**：可视化孤电子对位置
- **双渲染模式**：支持坐标定义和键角计算两种原子坐标生成方式

### 3D 分子编辑器 (MolForge)

功能完备的 3D 分子编辑器。

- **分子构建**：支持原子添加/删除、化学键创建/编辑
- **预设模板**：水、甲烷、乙烷、乙烯、乙炔、苯、氨、乙醇等
- **变换工具**：选择、移动、旋转、缩放（支持轴向锁定）
- **快捷键系统**：编辑/查看双模式快捷键
- **测量工具**：键长、键角、二面角测量（查看模式）
- **导入导出**：PNG/GLTF/GLB/PDB/JSON 格式
- **自动旋转**：一键开启 Y 轴自动旋转
- **全屏模式**：隐藏 UI 全屏沉浸查看

### 晶胞 3D 交互可视化 (CrystalCell)

基于 Three.js 的晶胞结构展示工具。

- **四种晶体结构**：简单立方、面心立方 (FCC)、金刚石、全填充萤石 (CaF₂)
- **原子分组控制**：顶点/面心/内部原子独立显示
- **交互操作**：点击原子高亮变色，正交投影相机自由观察
- **显示控制**：边框/化学键/标签独立开关，自动旋转

### 主族元素周期律交互实验室 (PeriodicLab)

交互式主族元素（IA-VIIA 及 0 族）周期律学习工具。

- **四种查看模式**：卡片/列表/对比/周期表
- **可视化周期律**：电离能、电负性、化学键极性
- **元素选择交互**：点击元素查看详细信息

### 寻路算法演示

四种经典寻路算法的全流程可视化。

- **算法支持**：DFS（栈）、BFS（队列）、Dijkstra（优先队列）、A\*（启发式搜索）
- **地图编辑**：绘制/擦除障碍物，设置起点终点
- **预设地图**：空旷、随机、迷宫、U 型墙
- **运行控制**：开始/暂停/单步/重置 + 速度调节
- **可视化面板**：队列数据结构实时展示、伪代码高亮、步骤说明
- **数据统计**：访问节点数、队列长度、路径长度、运行时间

---

## 数据格式

### list.json 条目格式

```json
{
  "name": "洛伦兹力圆周运动演示",
  "link": "Physics/lorentz-force-circular-motion.html",
  "summary": "演示带电粒子在匀强磁场中受洛伦兹力作用做匀速圆周运动",
  "author": "CodeKpy-豆包",
  "contact": "codekpy@foxmail.com",
  "time": "2026-04-12",
  "subject": "物理",
  "grade": "XB2",
  "tags": ["洛伦兹力", "圆周运动", "磁场", "带电粒子", "电磁学"]
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 项目名称 |
| `link` | string | 演示文件路径（相对根目录） |
| `summary` | string | 项目简介 |
| `author` | string | 作者名称 |
| `contact` | string | 联系方式（邮箱） |
| `time` | string | 创建/更新时间 (YYYY-MM-DD) |
| `subject` | string | 所属学科（物理/化学/数学/信息技术） |
| `grade` | string | 适用阶段（J3-九年级, B1-必修一, XB2-选必修二等） |
| `tags` | string[] | 标签数组 |

### author.json 创作者格式

```json
{
  "name": "CodeKpy",
  "avatar": "https://q1.qlogo.cn/g?b=qq&nk=1942171924&s=100",
  "bio": "前端开发，专注于 Web 动画和交互设计",
  "contact": {
    "github": "https://gitee.com/codekpy",
    "email": "codekpy@foxmail.com"
  },
  "contribution": "负责项目的前端架构设计和动画效果实现"
}
```

---

## 贡献指南

欢迎任何形式的贡献！无论是提交新的演示页面、改进现有代码、完善文档还是反馈问题。

### 添加新演示

1. **创建演示文件**：在对应学科目录下创建 HTML 页面（可参考 [prompt.md](prompt.md) 模板）
2. **遵循 UI 规范**：使用 Tailwind CSS + Font Awesome，确保与现有风格一致
3. **更新 list.json**：在数组中添加新条目
4. **提交 Pull Request**：通过 [Gitee](https://gitee.com/codekpy/subj-engine.git) 提交

### 使用编辑工具

无需手动编辑 JSON，可使用浏览器端编辑器：

1. 打开 `tools/editor.html`
2. 加载当前 `list.json`（支持文件上传或 URL 加载）
3. 在图形界面中编辑条目
4. 导出 JSON 文件替换本地文件

### Git 工作流

```powershell
# 克隆仓库
git clone https://gitee.com/codekpy/subj-engine.git

# 创建新分支
git checkout -b feat/your-new-demo

# 添加修改
git add list.json
git add Physics/your-demo.html

# 提交更改（遵循 Conventional Commits）
git commit -m "feat: 添加[演示名称]交互式模拟"

# 推送并创建 PR
git push origin feat/your-new-demo
```

---

## 开发指南

### 页面构建规范

参考 [prompt.md](prompt.md) 中定义的模板和规范：

- **布局**：CSS Grid 左右分栏 (`lg:grid-cols-[320px_1fr]`)，小屏自动切换上下布局
- **配色**：蓝色系主色调（primary `#2563eb`，secondary `#4f46e5`）
- **Canvas 渲染**：所有模拟内容使用 Canvas API 绘制，背景白色
- **模态框**：理论/解析内容使用模态框按需展示，支持 MathJax 公式
- **本地资源**：所有静态资源使用本地文件，不依赖 CDN
- **录制集成**：引入 `canvas-recorder.js`，提供录制/下载功能

### 开发一个演示页面的标准流程

1. 使用 `ui-ux-pro-max` 技能进行 UI/UX 设计
2. 参考 [prompt.md](prompt.md) 的 HTML 模板创建页面
3. 实现 Canvas 绘制和交互逻辑
4. 集成 Canvas 录制组件
5. 更新 `plan.md` 记录开发计划
6. 更新 `list.json` 添加条目
7. 更新 `task.md` 记录完成进度

### Vite 子项目开发

对于 3 个 TypeScript 子项目（MoleculeViewer、CrystalCell、MolForge）：

```powershell
# 开发模式
cd Chemistry/MoleculeViewer
npm run dev

# 生产构建
npm run build

# 预览构建结果
npm run preview
```

---

## 许可证

本项目基于 **Apache License 2.0** 开源，详情请参见 [LICENSE](LICENSE) 文件。

---

## 致谢

### 创作者

| 贡献者 | 角色 | 贡献 |
|--------|------|------|
| **CodeKpy** | 项目发起人 & 主开发者 | 前端架构设计、动画实现、核心功能开发 |
| **资深小白程序员** | 贡献者 | 电场线演示项目 |
| **郑老师** | 一线教师 & 贡献者 | 洛伦兹力系列演示项目（放缩圆、旋转圆、电磁流量计） |

### 开源项目

- [Tailwind CSS](https://tailwindcss.com/) — 现代化 CSS 框架
- [Font Awesome](https://fontawesome.com/) — 图标库
- [MathJax](https://www.mathjax.org/) — 数学公式渲染引擎
- [Three.js](https://threejs.org/) — 3D 图形引擎
- [Vite](https://vitejs.dev/) — 前端构建工具
- [JSZip](https://stuk.github.io/jszip/) — ZIP 打包库

### 教育机构

感谢所有支持本项目的学校和教育机构，以及每一位为项目贡献资源的学习者。

---

## 相关链接

- **Gitee 仓库**：[https://gitee.com/codekpy/subj-engine.git](https://gitee.com/codekpy/subj-engine.git)
- **在线访问**：[https://subj-engine.cloudroo.top/](https://subj-engine.cloudroo.top/)
- **联系我们**：[codekpy@foxmail.com](mailto:codekpy@foxmail.com)
- **提交 Issue**：[Gitee Issues](https://gitee.com/codekpy/subj-engine/issues)

---

<p align="center">
  <strong>SubjEngine · 让知识可视化，让学习更生动</strong>
</p>