跳转至

PR 57 白板部分审查与模板修复

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

审查对象：PR 57 第一提交 9426f7fc382c225c6fbeea0859b0fe1bf569f60c，对照本地 exp 基线 f3ba4dd6。不涉及后续 i18n 提交。未整体应用 PR，也未加入默认吸附。

结论

  • 接纳并适配“恢复默认首页”确实应重置真实白板的修复。
  • 不接纳默认启用、只能用 Alt 临时关闭的吸附；四列高密度首页也不作为默认布局。
  • 另行修复现有三个旧模板的像素尺寸错误。保留首个默认首页，其他模板统一 1104px 基准、宽卡与纵向滚动。
  • 已保存的自定义白板不自动重排。模板仅在用户明确套用时替换当前板；恢复默认只影响首页。

PR 实际改变了什么

四列本身只是预设，不是持久化网格约束。PR 的 boardCore.ts:339–359 将默认 7 件组件变为 13 件，四列每列 264px；migrateHomeCanvas 的版本判断仍使已有 v2 白板保持原样。它没有把所有用户旧布局强行转成四列。

但拖动行为确实会改变。PR FreeBoard.tsx:760–795 每帧默认调用 snapMove / snapResize，只有 ev.altKey 才跳过。没有可见开关或手势说明，普通触屏和笔也不能按 Alt 临时解除。吸附半径按 8 / displayScale 换算，屏幕手感尺度一致，但这是持续改变落点的默认规则，不符合当前自由拖动方向。

候选边线来自所有组件，未限制另一轴距离或可见范围（boardSnap.ts:80–105）。独立运行该提交的纯函数：处于 (104,20) 的卡会被 y=5000 的离屏卡拉到 x=100，并给出跨越 5080px 的参考线。即使未来提供可选吸附，也应先解决这一点。

可复现缺陷

P2：西/北缩放吸附在最小尺寸处移动了对侧边

位置：PR apps/desktop/src/state/boardSnap.ts:133–150。

输入矩形 (x=100,y=100,w=120,h=64)、minW=120,minH=64：

  • 西边吸到 x=105 后，宽仍被夹到 120，右边从 220 变为 225。
  • 北边吸到 y=105 后，高仍被夹到 64，底边从 164 变为 169。

与其“只移动正在拖的边、对侧不动”的契约相反。应限制候选边到 right-minW / bottom-minH，无法满足最小尺寸的候选不吸附。该纯函数缺陷已通过读取指定 Git 提交并实际执行复现，结果在 /tmp/onethu-pr57-board-snap-repro.json；没有修改运行中的生产源码来复现。

不应覆盖当前暂存箱接管修复

PR 的 FreeBoard.tsx:802–819 在 pointerup 和 pointercancel 共用提交路径，只要 liveRef 存在就落库；onMove 也只看瞬时 gestureOwner()。当前分支已将接管锁存在整个按压会话：一旦暂存箱接管就清除 live，此次不再移动或缩放原组件。不能用 PR 文件覆盖当前实现，否则会回到“已绿色命中但白板仍移动”的旧边界。未来若单独加入参考线，也要在接管/取消时清理它们。

当前三个模板为什么挤

基线 boardTemplates.ts:33–58 的今日/学习/极简仍用旧四格布局，boardCore.ts:169–176 将其换成主卡 286px、侧栏 90px。基线 FreeBoard.tsx:834–837 又统一转 rectFromCell 并标成 manual:true。与此同时桌面 100% 的窗口适配宽度至少是 1104px，所以 Mac 宽窗口也只在左侧挤成一小列；放大屏幕没有解决作者尺寸本身错误。

PR 只更换默认首页，没有修改这条模板应用路径；新增四列里的通知/作业仅 264×116px，也不能解决这些列表的阅读问题。

本轮适配实现

  • boardTemplates.ts：模板保存原生 rect，派生的 cell 只保留插件/OH 兼容契约。今日与学习主卡宽 540px，列表高 392–480px；极简为 1104px 标题、740px 课程和 340px 余额。组件间距至少 24px。每次生成独立数据对象。
  • FreeBoard.tsx：应用模板直接保留 rect 与尺寸归属。未固定尺寸的模板允许原有按内容拟合；用户手动改变大小后仍由原 withRect 接管。显式应用模板才恢复当前 100% 和 1104px 参考宽度，不改变日常拖动/缩放策略。
  • board.ts / Settings.tsx：恢复默认重建首页两朝向的真实组件，清旧布局偏好并阻止旧自由板延迟回灌。所有用户 OnePage、活动板和排序偏好保留。首页各视图倍率归 100%，专用事件使已挂载的首页同步重设参考宽度；普通保存不会触发。

没有加入吸附，没有调整现有用户组件位置，没有修改首页版本迁移或原 7 件默认布局。

验证范围

已自然退出通过：

  • pnpm --filter @onethu/desktop typecheck
  • node --import ./tools/ts-resolve-register.mjs tools/board-templates-test.mjs：保留旧组件注册/渲染覆盖，另验证原生宽度、间距、兼容 cell、数据独立和手调尺寸优先。
  • node --import ./tools/ts-resolve-register.mjs tools/board-reset-test.mjs：24 项实际状态模块检查，含两个朝向、其他板/缩放保留、缓存刷新、重置后旧数据不复活。
  • tools/board-model-test.mjs、tools/board-fit-test.mjs：既有数据与拟合行为回归。

新增 tools/board-template-browser-test.mjs 最终 315 项自然退出通过：

  • Chromium 与已安装的 Playwright WebKit，各跑 1280×900、900×900、390×844，四模板共 24 份几何记录、34 张截图；两个浏览器均完成正常清理，页面异常为零。
  • 使用中性 ?explorer-preview=onboarding、实际已加载模块的 seedPreviewData 和隔离云盘夹具。课程、作业、通知由真实组件显示示例数据；模板通过真实“模板”按钮和 ActionSheet 菜单项选择，没有调用内部 applyTemplate 回调。
  • 每次验证原生 1104px 宽、卡片不互叠、画布包含完整卡体、首卡实际命中测试、手机阅读顺序/全宽投影/无横向卡体裁切、其他 OnePage 存档不变。手机阅读模式本来隐藏缩放按钮，因此该项查真实应用的 viewOf 倍率，同时验实际阅读布局。
  • 两个引擎的 1280 场景均执行可信鼠标任意位移、真实角点缩放、125% 画布缩放、刷新后持久化以及键盘复位。没有默认吸附。
  • 实看 1280 学习、900 今日、390 学习和 WebKit 390 极简截图：宽卡与阅读顺序清晰；移动视口需要正常纵向滚动才能查看后续卡片。此范围是浏览器视口模拟，不宣称实体手机或已安装 App 验收。

浏览器发现并修正了显式复位的一个问题：scrollIntoView(start) 会把首卡送进固定顶栏后面，现改成滚动祖先的 scrollTop/scrollLeft 归零，保留页面顶部自然留白；首卡命中检查已纳入回归。

最终报告与截图：/tmp/onethu-pr57-board/report.json，日志 /tmp/onethu-board-browser-final.log。此前两次诊断失败分别为新滚动复位问题和手机阅读模式隐藏缩放按钮的测试预期；另一次夹具清理竞态通过先等待 unrouteAll({behavior:"wait"}) 再释放请求上下文解决。它们不计入最终 315 项通过。

归档证据：完整浏览器报告、桌面学习模板、窄窗口今日模板、手机极简模板。

另已通过真实默认组件拖入暂存箱的 28 项鼠标回归，覆盖立即拖动、长按、微移后长按及 pointer capture 丢失，保留原接管行为。