跳转至

三模式导览：真实 3D 与流程验收

历史记录 / Historical record：本文保留当时的计划、研究或验收证据，不代表 0.11 当前能力全集。现行说明见 文档入口；英文入口见 English overview。

日期：2026-10-20。分支：exp。实现起点：98eb32f0。

交付内容

最终采用真实 Three.js 模型、相机和材质。早期粒子与 CSS 旋转版本已被替代；CSS 模型仅用于图形不可用或模块加载失败时的功能降级。保留原有主题与自动文字对比引擎，通过 OneGUI 的媒体材质角色和配方接入。

  • 手机具有独立金属边框、圆角玻璃、后盖、镜头和侧键，银色与石墨色设备从侧背面翻转到正面。
  • 白板卡片分层排开，暂存箱有实体箱壁和铰链，卡片沿轨迹收纳；口令与组织场景使用有厚度的卡片翻转、展开和收拢。
  • 动作采用带速度状态的阻尼运动，可以中途反向；切课时旧新模型连续交接，快速操作最多保留三个模型，不排队播放历史动作。
  • 终态停止逐帧绘制；暂停、减少动态效果、离屏、页面隐藏、图形上下文丢失和卸载分别处理。资源有明确释放路径。
  • 三维代码按需加载。最终构建的独立场景包约 591 kB、gzip 153 kB；应用入口没有预加载该场景包。构建仍有超过 500 kB 的包体提醒。

三种模式与真实操作

极简模式两课：今天、五个入口。实用模式三课：今天、更多功能、替换四个常用入口。完整模式五课：白板、暂存箱、口令、碰一碰、组织；其余六个主题在完成页「继续探索」。

演示只改变自己的本地状态；课程中的操作按钮进入真实功能。原有完整模式十一处落点均保留。体验中的返回条进入当前弹层的焦点范围，支持键盘返回；清理只回退本次练习拥有的弹层，并尊重尚未结束的忙碌操作。切换模式保留原有白板、标签和设置。

验证记录

  • pnpm guard：通过，包含桌面 TypeScript 检查。
  • pnpm guard:onegui：通过，465 个令牌，未放宽已有基线。
  • pnpm test:onboarding：课程 20 项、导航 21 项及首启导览静态契约通过。
  • pnpm --filter @onethu/desktop build：通过。
  • tools/onboarding-browser-test.mjs：最终 Three.js 版本 58 项通过，桌面与手机尺寸的真实十一处入口、键盘返回、模式切换和偏好保留覆盖；浏览器自然退出。
  • tools/experience-browser-test.mjs：最终版本 87 项通过，模式存档隔离、组织、分享、实用入口持久化和 390/320 布局覆盖；浏览器自然退出，结果见 模式回归报告。
  • tools/onboarding-motion-browser-test.mjs 的最终定向套：73 项通过，其中包含四尺寸整周重播的逐帧投影与中途操作，以及 51 项实际 WebGL/生命周期检查。直接观察 WebGL 调用、非空 framebuffer 像素变化、实际网格与相机矩阵；验证终态停止、暂停、减少动态、隐藏、离屏、上下文恢复、无 WebGL 降级、切课资源数量和卸载。浏览器自然退出。
  • 首次开场补验：四尺寸 28 项通过，943 个实际绘制帧的模型矩阵投影均完整入镜；手机首次进入确实播放连续运镜，同时验证暂停与减少动态效果。
  • NFC 接收状态补验：9 项通过。等待与完成使用独立的真实屏幕纹理，每一时刻只显示对应的一面；真实按钮触发等待与接收结果切换。

以上动效验证统一合并到 完整动效报告，共 902 项检查、180 条几何记录，覆盖 1280×860、390×844、320×568 和 844×390。报告按来源保留检查项、真实矩阵、像素采样、录像与性能数据；七组计入结果均自然退出且返回 0，已排除旧版本的重复检查和失败运行。sourceRuns 保留来源文件的摘要与计数，objectMotion、introMotion、nfcVisibleTextures 分别保存转身、开场和接收状态证据。before/ 是原始基线，after/、frames/ 和 recordings/ 仅保存最终真实三维版本的结果。

主 agent 已人工查看最终五个核心场景、390 宽双手机、320 短屏和 844 横屏交互画面，并审阅真实录像的连续帧及转身中间帧。由此修复了仅看终态截图无法发现的暂存箱转身中段裁切。重播先拉远到完整旋转包络，转身后回到原有近景；普通终态的模型大小保持。

最终源码在本机无并发重任务时进行了 4 倍 CPU 降速参考采样：2.4 秒内取得 144 个 RAF 间隔，p50/p95 约 16.7 ms，最大 16.8 ms，没有观测到 Long Task。它只是这一台机器与这一段交互的参考，不能代表实体手机帧率。原始记录保存在完整报告的 samples 字段。

实际录像

证据边界

手机验收是 Chromium 的移动尺寸与触摸模拟，不是实体手机性能测试。NFC 画面是操作示意，不代表真实设备碰一碰联调；组织演示也不代表双账号权限同步联调。录像保存浏览器实际合成帧及其时间间隔，不插值补帧；录像采集本身会产生开销。桌面录像完整保留 1280×860 页面；手机原始合成帧宽 500，只裁掉 390×844 CSS 视口以外的右侧 110 像素窗口区域，页面内容完整保留，原始尺寸与裁剪范围均记录在报告中。

依赖安装后，旧 Vite 进程曾无法正确提供 client；重启后的首次访问又发现已有的 aes-js 依赖，测试禁用热更新时出现旧新 React 预打包混用。缓存稳定后的全新隔离页面完成上述验证。临时截图脚本曾在关闭浏览器时超时，仅用作人工看图，未计为通过的自动化套件。