面向零基础新手的三阶魔方互动课堂：跟着 3D 动画看一遍，再动手跟练一遍，一步步还原你的第一颗魔方。
纯前端单页应用（Vite + Three.js），无需账号或后端，桌面与手机均可使用。字体（Noto Sans SC、Outfit）随构建一起打包，不依赖 Google Fonts 等外部服务；中文字体按字符范围分片，浏览器只下载页面用到的部分。
需要 Node.js 20.19+ 或 22.12+（推荐 Node.js 22）。
npm install
npm run dev # 本地开发，打开终端输出的地址
npm test # 运行转动模型与练习逻辑测试
npm run build # 生产构建，输出到 dist/浏览器回归测试首次运行需安装 Chromium：
npx playwright install chromium
npm run test:e2e测试会自动启动独立的本地服务（4173 端口），覆盖桌面 Chromium 与手机尺寸、触摸输入模拟。失败时截图和跟踪文件保存在 test-results/。GitHub Actions 会在提交和 PR 时运行单元测试、构建及浏览器测试。
| 章节 | 内容 | 核心公式 |
|---|---|---|
| 认识你的魔方 | 中心块、棱块、角块与转动符号 | R U R′ U′ |
| 第一步 · 底层十字 | 小雏菊与侧面对齐 | 花瓣已对齐示例：F2 R2 B2 L2 |
| 第二步 · 底层角块 | 右手四步法 | R U R′ U′ |
| 第三步 · 中层棱块 | 左右插入 | U R U′ R′ U′ F′ U F |
| 第四步 · 顶层黄色十字 | 点 → 拐角 → 一字 → 十字 | F R U R′ U′ F′ |
| 第五步 · 顶面黄色翻正 | 小鱼公式（OLL） | R U R′ U R U2 R′ |
| 第六步 · 顶层角块归位 | 车灯与角块交换 | R′ F R′ B2 R F′ R′ B2 R2 |
| 第七步 · 顶层棱块归位 | Ua / Ub 三棱换 | R U′ R U R U R U′ R′ U′ R2 及逆公式 |
共有 17 个可切换的教学局面：基础认知、小雏菊与直接对齐、白色角块的三种朝向、左右中层插入、黄色十字的一字/拐角/点态、小鱼/调整朝向/逆小鱼、顶层角块归位，以及 Ua / Ub 三棱换。长公式带有阶段提示，例如点态演示会提示何时做 U2 调整拐角。
白十字演示中的半转顺序只适用于已经对齐的花瓣，不是任意局面的通用解法。
- 动画教学：播放、暂停、逐步前进或后退，点击公式中的任一步直接跳转，支持 0.5× / 1× / 1.5× 速度。
- 跟我练习：按公式逐步检查你的转动。转错会提示正确的一步，不会改动魔方；半转（如 R2）连转两次同一面即可，顺时针、逆时针都算，转错方向可以反向撤销。
- 自由练习：随意转动，或一键随机打乱 22 步，重置即恢复六面。
三种模式在魔方上方并排切换。
辅助功能：聚焦目标块（淡化无关色块）、转动指引箭头、自由视角与缩放。箭头、动作标签和文字跟随实际执行的动作，包括回退及半转的逆向输入；整组动作完成后隐藏指引。
界面提供浅色与深色两套主题，默认跟随系统，也可以用右上角的按钮切换。
课程卡片只保留当下需要的信息：目标与达成状态、局面切换、当前局面的说明和公式。本节讲解与技巧收在可展开的「本节讲解与技巧」里；键盘快捷键、转动符号和进度规则放在右上角的帮助里。拖动视角、滑动转层的操作提示只在第一次使用前显示。
| 电脑 | 手机 / 平板 | |
|---|---|---|
| 转动某一层 | U D L R F B 键，或在魔方面上拖动 |
点按转动键，或在魔方面上滑动 |
| 逆时针 | Shift + 字母，或打开「逆时针」开关 |
打开「逆时针」开关 |
| 换视角 | 拖动魔方（教学模式）或魔方外的空白处 | 同左，单指拖动 |
| 缩放 | 滚轮 | 双指捏合 |
| 播放 / 步进 | Space，← / → |
播放栏按钮 |
所有顺时针、逆时针都以正对该面的方向为准。在魔方上拖动转层只在「跟我练习」和「自由练习」中生效，中间层暂不支持拖动。
手机上进入练习模式后，转动键盘会停靠在屏幕底部，与魔方同屏显示；连续快速点按会依次执行（最多排队 3 步）。
手机和平板上，顶部的课程栏会一直停留在屏幕上方：左右箭头切换上一节、下一节，点中间的课程名可以打开完整的课程目录。手机上课程栏是唯一的页头（右侧是帮助按钮，主题切换在课程目录里），第一屏即可看到完整的魔方和播放控制。
半转（如 F2）的动画会分成两次 90° 转动播放，每次和单次转动一样长，指引标签会提示「第 1 次」「第 2 次」。
每次动作后从 3D 魔方读取块的位置与贴纸朝向，检查当前目标以及已完成层是否保持正确。颜色朝对但块未归位、位置正确但贴纸翻转，都不会误判成功。基础认知以完成四个动作作为目标。
在「跟我练习」中完成本局面全部动作且达到真实目标后，自动保存该局面进度；本节所有局面均通过后标记章节完成。观看演示、访问章节或点击「下一节」不会新增通关记录。旧版本已有的手动完成记录会保留。
当前章节、已完成章节和局面进度保存在浏览器本地（localStorage），不上传任何数据。无痕模式或禁用存储时应用照常可用，只是不会记住进度。
src/
cube.js 转动模型：公式解析、位置旋转、逆转、拖动转层映射、跟练判定（纯函数）
cube.test.js node:test 单元测试
cube-state.js 带贴纸朝向的纯状态模型与课程目标判定
cube-state.test.js 17 个局面的目标、前置条件和形态断言
lessons.js 课程数据：多局面、公式、阶段提示、目标类型
main.js 页面结构、Three.js 场景、动画与交互
style.css 设计令牌（浅色 / 深色）、样式与响应式布局
e2e/
cube-tutor.spec.js 播放回退、跟练、主题、移动布局回归测试
playwright.config.js 桌面与手机浏览器测试配置
新增或修改课程局面可编辑 lessons.js 中的 cases。测试除检查公式可逆性外，还验证起始形态、先前层的保持情况，以及执行完整步骤后的实际目标。新增目标类型时同步修改 cube-state.js。
所有颜色都定义为 style.css 顶部的 CSS 变量，3D 场景中的魔方配色、机身与指引箭头也从这些变量读取；调整配色只需修改令牌。
本应用演示选定局面下的公式与手法，不包含任意打乱局面的自动求解器。