【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：使用文件资源管理器

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

方法2：使用命令提示符

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

方法3：使用 PowerShell

1. 按 Win + X 键
2. 选择"Windows PowerShell"或"终端"
3. 输入以下命令切换到项目目录：
   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 重置魔方

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

================================================================================
停止服务器

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

1. 回到命令窗口
2. 按 Ctrl + C
3. 确认停止（输入 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 - 算法数据

================================================================================
技术支持

如果遇到问题：

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

项目要求：

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

================================================================================
更新日志

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

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

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

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

[2024-12-19] 项目初始化

1. 创建项目基础结构

   • 创建 package.json，配置 React + TypeScript + Vite + Three.js
   • 创建 tsconfig.json 和 tsconfig.node.json，配置 TypeScript
   • 创建 vite.config.ts，配置 Vite 和 React 插件
   • 创建 index.html，设置基础 HTML 结构

2. 创建样式系统

   • 创建 src/index.css，定义全局样式和 CSS 变量（深色模式）
   • 定义颜色变量：
     • –bg-primary: #0a0a0a (主背景)
     • –bg-secondary: #1a1a1a (次背景)
     • –bg-tertiary: #2a2a2a (第三背景)
     • –text-primary: #ffffff (主文本)
     • –text-secondary: #b0b0b0 (次文本)
     • –accent: #4a9eff (强调色)
     • –border: #333333 (边框)

3. 创建主应用组件

   • 创建 src/main.tsx，React 应用入口
   • 创建 src/App.tsx，主应用组件
   • 创建 src/App.css，应用布局样式
   • 实现响应式布局（桌面端和移动端）

4. 实现魔方核心逻辑

   • 创建 src/utils/cubeLogic.ts
     • 定义颜色常量（白、黄、红、橙、蓝、绿）
     • 实现 CubeState 类型（6个面的状态）
     • 实现 createSolvedCube() - 创建已还原的魔方
     • 实现 rotateFace() - 旋转单个面（顺时针90度）
     • 实现所有基础旋转：
       • rotateR / rotateRPrime - 右层旋转
       • rotateU / rotateUPrime - 上层旋转
       • rotateF / rotateFPrime - 前层旋转
       • rotateL / rotateLPrime - 左层旋转
       • rotateD / rotateDPrime - 下层旋转
       • rotateB / rotateBPrime - 后层旋转
     • 实现 applyRotation() - 应用旋转操作（支持 R2, U2 等）

5. 实现公式解析器

   • 创建 src/utils/formulaParser.ts
     • 实现 parseFormula() - 解析公式字符串（如 “R U R’ U’”）
     • 支持标准符号：R, U, F, L, D, B 及其 ’ 和 2 变体
     • 实现 isValidFormula() - 验证公式有效性

6. 实现3D魔方可视化组件

   • 创建 src/components/CubeVisualizer.tsx
     • 使用 @react-three/fiber 和 @react-three/drei
     • 实现 Cubie 组件 - 单个小方块（6个面）
     • 实现 RubiksCube 组件 - 完整3D魔方（27个小方块）
     • 实现颜色映射逻辑（根据魔方状态显示正确颜色）
     • 实现公式执行逻辑（逐步动画，每步300ms）
     • 添加 OrbitControls - 鼠标交互控制
     • 添加光照系统（环境光、方向光、点光源）
   • 创建 src/components/CubeVisualizer.css

7. 实现公式输入组件

   • 创建 src/components/FormulaInput.tsx
     • 输入框组件
     • 提交和重置按钮
     • 错误提示
     • 帮助文本（支持的符号说明）
   • 创建 src/components/FormulaInput.css

8. 实现算法库组件

   • 创建 src/components/AlgorithmLibrary.tsx
     • 标签页切换（CFOP法 / 桥式法）
     • 可折叠分类列表
     • 点击公式自动执行
   • 创建 src/components/AlgorithmLibrary.css

9. 收集和整理算法数据

   • 创建 src/data/algorithms.ts
     • CFOP法算法：
       • F2L (前两层): 42个公式
       • OLL (顶层朝向): 57个公式（分类：点、线、L型、T型、C型、其他）
       • PLL (顶层换位): 21个公式（分类：角块、棱块、角块+棱块）
     • 桥式法算法：
       • 左桥: 6个基础公式
       • 右桥: 6个基础公式
       • CMLL: 42个公式
       • LSE: 多个公式（EO、UL/UR、M层）

10. 创建文档

    • 创建 README.md - 项目说明文档
    • 创建 docs/CFOP算法公式.md - CFOP法完整公式库
    • 创建 docs/桥式法算法公式.md - 桥式法完整公式库
    • 创建 docs/快速开始.md - 使用指南

11. 创建配置文件

    • 创建 .gitignore - Git 忽略文件配置

12. 代码优化

    • 移除未使用的导入（useFrame, useRef）
    • 清理代码，确保无 lint 错误

================================================================================
[2024-12-19] 问题修复

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

原因分析：

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

解决方案：

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

操作记录：

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

================================================================================
[2024-12-19] 修复网页空白问题

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

根本原因：
这是一个现代前端项目，使用：

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

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

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

正确启动方式：

1. 安装依赖：npm install
2. 启动开发服务器：npm run dev
3. 在浏览器中访问显示的地址（通常是 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旋转

用户反馈问题：

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

问题分析：

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

解决方案：

1. 修复useEffect清理逻辑，正确管理setTimeout
2. 实现真正的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安装）
  • 第二步：打开项目文件夹
  • 第三步：安装项目依赖
  • 第四步：启动开发服务器
  • 第五步：在浏览器中打开网站
  • 第六步：使用网站
  • 停止服务器方法
  • 常见问题解决
  • 快速命令参考
  • 项目结构说明
• 更新日志记录此操作

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

先睡了，晚安