【Cursor _RubicsCube Diary 1】Node.js；npm；Vite

================================================================================

魔方公式可视化网站 - 启动项目详细步骤

⚠️ 重要提示：这是一个需要编译的现代Web项目，不能直接打开HTML文件！

必须按照以下步骤操作。

================================================================================

第一步：检查环境

1.1 检查是否已安装 Node.js

打开命令提示符（cmd）或 PowerShell
输入命令：node -v
如果显示版本号（如 v18.x.x 或 v20.x.x），说明已安装，跳到第二步
如果没有显示或报错，需要先安装 Node.js

1.2 安装 Node.js（如果未安装）

访问官网：https://nodejs.org/
下载 LTS（长期支持）版本
运行安装程序，全部选择默认选项
安装完成后，重启命令提示符
再次运行 node -v 确认安装成功

1.3 检查 npm（Node.js 自带，通常不需要单独安装）

输入命令：npm -v
应该显示版本号（如 9.x.x 或 10.x.x）

================================================================================

第二步：打开项目文件夹

方法1：使用文件资源管理器

打开文件资源管理器
导航到项目文件夹：
D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube
在文件夹空白处，按住 Shift 键，然后右键点击
选择"在此处打开 PowerShell 窗口"或"在此处打开命令窗口"

方法2：使用命令提示符

按 Win + R 键
输入 cmd，按回车
输入以下命令切换到项目目录：
cd /d D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube

方法3：使用 PowerShell

按 Win + X 键
选择"Windows PowerShell"或"终端"
输入以下命令切换到项目目录：
cd D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube

================================================================================

第三步：安装项目依赖

3.1 确认当前位置

在命令窗口中，你应该看到类似这样的路径：
PS D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube>
或者：
D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube>

3.2 安装依赖包

输入命令：npm install
按回车执行
等待安装完成（可能需要1-5分钟，取决于网络速度）
你会看到很多输出信息，最后应该显示类似：
added XXX packages in XXs

3.3 如果安装很慢或失败

可以使用国内镜像源加速：
npm config set registry https://registry.npmmirror.com
然后重新运行：npm install

3.4 验证安装

安装完成后，检查是否有 node_modules 文件夹
如果看到 node_modules 文件夹，说明安装成功

================================================================================

第四步：启动开发服务器

4.1 启动服务器

在命令窗口中输入：npm run dev
按回车执行
等待几秒钟，你会看到类似这样的输出：

VITE v5.x.x ready in XXX ms

➜ Local: http://localhost:5173/

➜ Network: use --host to expose

4.2 如果端口被占用

Vite 会自动使用下一个可用端口（如 5174, 5175 等）
注意查看实际显示的端口号

4.3 保持命令窗口打开

⚠️ 重要：不要关闭这个命令窗口！
关闭窗口会停止开发服务器
如果需要停止服务器，按 Ctrl + C

================================================================================

第五步：在浏览器中打开网站

5.1 打开浏览器

推荐使用 Chrome、Edge 或 Firefox
打开浏览器

5.2 访问网站

在地址栏输入：http://localhost:5173
或者点击命令窗口中显示的链接
按回车访问

5.3 确认网站正常运行

你应该看到：
- 深色背景的网页
- 顶部有"魔方公式可视化"标题
- 左侧有3D魔方模型（可以鼠标拖拽旋转）
- 右侧有公式输入框和算法库

5.4 如果页面空白或报错

检查命令窗口是否有错误信息
尝试刷新浏览器（F5）
检查浏览器控制台（F12）查看错误信息

================================================================================

第六步：使用网站

6.1 输入公式

在右侧"公式输入"框中输入公式，例如：R U R' U'
点击"执行"按钮
观察左侧3D魔方的旋转动画

6.2 使用算法库

在右侧"算法库"面板中
选择"CFOP法"或"桥式法"标签
展开分类，点击任意公式即可自动执行

6.3 交互控制

鼠标左键拖拽：旋转3D视角
鼠标滚轮：缩放魔方
鼠标右键拖拽：平移视角

6.4 重置魔方

点击"重置"按钮，魔方恢复到已还原状态

================================================================================

停止服务器

当你想停止开发服务器时：

回到命令窗口
按 Ctrl + C
确认停止（输入 Y 或直接按回车）

================================================================================

常见问题解决

问题1：提示 "npm 不是内部或外部命令"

解决：

Node.js 没有正确安装
重新安装 Node.js，确保勾选"添加到PATH"
重启命令窗口

问题2：npm install 报错或很慢

解决：

使用国内镜像：npm config set registry https://registry.npmmirror.com
清除缓存：npm cache clean --force
重新运行 npm install

问题3：端口 5173 已被占用

解决：

Vite 会自动使用其他端口
查看命令窗口显示的实际端口号
或者修改 vite.config.ts 指定其他端口

问题4：页面显示空白

解决：

检查命令窗口是否有错误
按 F12 打开浏览器控制台查看错误
尝试清除浏览器缓存
确保所有依赖已正确安装

问题5：3D魔方不显示

解决：

检查浏览器是否支持 WebGL
尝试更新浏览器到最新版本
检查显卡驱动是否最新

问题6：公式执行后魔方没变化

解决：

检查公式格式是否正确
确保使用标准符号（R, U, F, L, D, B）
检查浏览器控制台是否有错误

问题7：想要修改代码后自动刷新

解决：

开发服务器已启用热更新
修改代码后，浏览器会自动刷新
无需手动操作

================================================================================

快速命令参考

切换到项目目录

cd D:\Users\KRATZDISTELN\Desktop\STEFANO_Programs_Rubics_Cube

安装依赖（首次运行）

npm install

启动开发服务器

npm run dev

构建生产版本

npm run build

预览生产版本

npm run preview

设置国内镜像源（加速下载）

npm config set registry https://registry.npmmirror.com

清除 npm 缓存

npm cache clean --force

================================================================================

项目结构说明

项目文件夹包含：

src/ - 源代码文件夹
docs/ - 文档文件夹
log/ - 开发日志
_User/ - 用户文档（本文件所在位置）
package.json - 项目配置文件
index.html - HTML入口文件
vite.config.ts - Vite配置文件

重要文件：

src/App.tsx - 主应用组件
src/components/CubeVisualizer.tsx - 3D魔方组件
src/utils/cubeLogic.ts - 魔方逻辑
src/data/algorithms.ts - 算法数据

================================================================================

技术支持

如果遇到问题：

查看 log/开发日志.txt 了解项目开发过程
查看 docs/快速开始.md 获取更多帮助
检查浏览器控制台（F12）的错误信息
确认 Node.js 和 npm 版本是否兼容

项目要求：

Node.js 版本：16.x 或更高
npm 版本：7.x 或更高
现代浏览器（Chrome、Edge、Firefox 最新版本）

================================================================================

更新日志

$2024-12-19$ 创建启动步骤文档

详细说明从零开始启动项目的每一步
包含常见问题解决方案
提供快速命令参考

================================================================================

魔方公式可视化网站 - 开发日志

$2024-12-19$ 项目初始化

创建项目基础结构
- 创建 package.json，配置 React + TypeScript + Vite + Three.js
- 创建 tsconfig.json 和 tsconfig.node.json，配置 TypeScript
- 创建 vite.config.ts，配置 Vite 和 React 插件
- 创建 index.html，设置基础 HTML 结构
创建样式系统
- 创建 src/index.css，定义全局样式和 CSS 变量（深色模式）
- 定义颜色变量：
  - --bg-primary: #0a0a0a (主背景)
  - --bg-secondary: #1a1a1a (次背景)
  - --bg-tertiary: #2a2a2a (第三背景)
  - --text-primary: #ffffff (主文本)
  - --text-secondary: #b0b0b0 (次文本)
  - --accent: #4a9eff (强调色)
  - --border: #333333 (边框)
创建主应用组件
- 创建 src/main.tsx，React 应用入口
- 创建 src/App.tsx，主应用组件
- 创建 src/App.css，应用布局样式
- 实现响应式布局（桌面端和移动端）
实现魔方核心逻辑
- 创建 src/utils/cubeLogic.ts
  - 定义颜色常量（白、黄、红、橙、蓝、绿）
  - 实现 CubeState 类型（6个面的状态）
  - 实现 createSolvedCube() - 创建已还原的魔方
  - 实现 rotateFace() - 旋转单个面（顺时针90度）
  - 实现所有基础旋转：
    - rotateR / rotateRPrime - 右层旋转
    - rotateU / rotateUPrime - 上层旋转
    - rotateF / rotateFPrime - 前层旋转
    - rotateL / rotateLPrime - 左层旋转
    - rotateD / rotateDPrime - 下层旋转
    - rotateB / rotateBPrime - 后层旋转
  - 实现 applyRotation() - 应用旋转操作（支持 R2, U2 等）
实现公式解析器
- 创建 src/utils/formulaParser.ts
  - 实现 parseFormula() - 解析公式字符串（如 "R U R' U'"）
  - 支持标准符号：R, U, F, L, D, B 及其 ' 和 2 变体
  - 实现 isValidFormula() - 验证公式有效性
实现3D魔方可视化组件
- 创建 src/components/CubeVisualizer.tsx
  - 使用 @react-three/fiber 和 @react-three/drei
  - 实现 Cubie 组件 - 单个小方块（6个面）
  - 实现 RubiksCube 组件 - 完整3D魔方（27个小方块）
  - 实现颜色映射逻辑（根据魔方状态显示正确颜色）
  - 实现公式执行逻辑（逐步动画，每步300ms）
  - 添加 OrbitControls - 鼠标交互控制
  - 添加光照系统（环境光、方向光、点光源）
- 创建 src/components/CubeVisualizer.css
实现公式输入组件
- 创建 src/components/FormulaInput.tsx
  - 输入框组件
  - 提交和重置按钮
  - 错误提示
  - 帮助文本（支持的符号说明）
- 创建 src/components/FormulaInput.css
实现算法库组件
- 创建 src/components/AlgorithmLibrary.tsx
  - 标签页切换（CFOP法 / 桥式法）
  - 可折叠分类列表
  - 点击公式自动执行
- 创建 src/components/AlgorithmLibrary.css
收集和整理算法数据
- 创建 src/data/algorithms.ts
  - CFOP法算法：
    - F2L (前两层): 42个公式
    - OLL (顶层朝向): 57个公式（分类：点、线、L型、T型、C型、其他）
    - PLL (顶层换位): 21个公式（分类：角块、棱块、角块+棱块）
  - 桥式法算法：
    - 左桥: 6个基础公式
    - 右桥: 6个基础公式
    - CMLL: 42个公式
    - LSE: 多个公式（EO、UL/UR、M层）
创建文档
- 创建 README.md - 项目说明文档
- 创建 docs/CFOP算法公式.md - CFOP法完整公式库
- 创建 docs/桥式法算法公式.md - 桥式法完整公式库
- 创建 docs/快速开始.md - 使用指南
创建配置文件
- 创建 .gitignore - Git 忽略文件配置
代码优化
- 移除未使用的导入（useFrame, useRef）
- 清理代码，确保无 lint 错误

================================================================================

$2024-12-19$ 问题修复

问题：用户直接打开 index.html 文件，网页显示空白

原因分析：

这是一个 Vite + React + TypeScript 项目
index.html 中的脚本是 TypeScript (.tsx)，需要编译
直接打开 HTML 文件无法处理模块导入和 TypeScript
必须通过 Vite 开发服务器运行

解决方案：

创建开发日志文件（当前文件）
检查并确保所有文件正确配置
提供正确的启动说明
可能需要添加一些错误处理和提示

操作记录：

创建 log/开发日志.txt 文件，记录所有开发操作
检查项目文件结构，确认所有文件存在
验证 package.json、vite.config.ts、tsconfig.json 配置正确
确认所有组件文件已创建

================================================================================

$2024-12-19$ 修复网页空白问题

问题：用户直接打开 index.html 显示空白

根本原因：

这是一个现代前端项目，使用：

Vite 作为构建工具
TypeScript 需要编译
ES6 模块系统
React JSX 需要转换

直接打开 HTML 文件无法工作，因为：

浏览器无法直接执行 TypeScript (.tsx)
无法处理 import/export 模块系统
无法处理 JSX 语法
需要 Vite 开发服务器进行实时编译和热更新

正确启动方式：

安装依赖：npm install
启动开发服务器：npm run dev
在浏览器中访问显示的地址（通常是 http://localhost:5173）

操作：

创建 START_HERE.txt 文件，提供清晰的启动说明
更新日志文件记录此操作
确保所有配置文件正确
修复 CubeVisualizer.tsx 中的代码错误：
- 添加缺失的 useRef 导入
- 移除未使用的 isProcessingRef 引用

================================================================================

$2024-12-19$ 代码修复

修复 CubeVisualizer.tsx 组件中的错误：

问题1：缺少 useRef 导入

第17行使用了 useRef 但未导入
修复：在导入语句中添加 useRef

问题2：未定义的 isProcessingRef

第103和116行引用了不存在的 isProcessingRef
修复：移除这些引用，使用 isAnimating 状态即可

操作：

修复 src/components/CubeVisualizer.tsx
验证代码无 lint 错误
更新日志记录

================================================================================

$2024-12-19$ 修复代码逻辑和实现真正的3D旋转

用户反馈问题：

输入 RUR'U' 后执行半天没停下来
需要真正的3D层旋转动画，而不是刷新颜色

问题分析：

useEffect的依赖问题导致重复执行
setTimeout没有正确清理
当前实现只是更新颜色，没有真正的3D旋转

解决方案：

修复useEffect清理逻辑，正确管理setTimeout
实现真正的3D旋转动画系统：
- 创建RotatingLayer组件处理单层旋转
- 使用useFrame实现平滑动画
- 按层分组方块，旋转整个层
- 动画完成后更新cubeState

实现细节：

RotatingLayer组件使用useFrame逐帧更新旋转角度
根据move类型确定旋转轴（X/Y/Z）和角度
正确识别需要旋转的方块（按层分组）
使用递归executeMove函数逐步执行公式
每个move等待600ms（动画500ms + 缓冲100ms）

操作：

完全重写 CubeVisualizer.tsx
实现RotatingLayer组件
修复动画同步问题
更新日志记录

================================================================================

$2024-12-19$ 创建用户启动文档

用户要求：创建详细的启动步骤文档，放在_User文件夹中

操作：

创建 _User 文件夹
创建 _User/启动项目步骤.txt 文件
包含完整的启动步骤：
- 第一步：检查环境（Node.js安装）
- 第二步：打开项目文件夹
- 第三步：安装项目依赖
- 第四步：启动开发服务器
- 第五步：在浏览器中打开网站
- 第六步：使用网站
- 停止服务器方法
- 常见问题解决
- 快速命令参考
- 项目结构说明
更新日志记录此操作

================================================================================

先睡了，晚安

【Cursor _RubicsCube Diary 1】Node.js；npm；Vite

================================================================================

================================================================================

================================================================================

================================================================================

================================================================================

================================================================================

================================================================================

================================================================================

================================================================================

================================================================================

切换到项目目录

安装依赖（首次运行）

启动开发服务器

构建生产版本

预览生产版本

设置国内镜像源（加速下载）

清除 npm 缓存

================================================================================

================================================================================

================================================================================

================================================================================

魔方公式可视化网站 - 开发日志

2024-12-19 项目初始化

================================================================================

================================================================================

================================================================================

================================================================================

$2024-12-19$ 项目初始化