mnote/recycle/design/luckysheet-checklist.md

Luckysheet 全屏首次加载异常（问题清单与修复 Checklist）

现象（用户反馈）

• 全屏打开在线表格时，前 1～2 次渲染不完整：Luckysheet 工具栏/公式栏缺失或布局异常；刷新后再打开才恢复正常。
• DevTools 的 Sources/页面树里看不到预期的 /luckysheet/* 静态资源（怀疑资源未加载或加载顺序异常）。

目标

• 全屏首次打开就稳定显示完整 Luckysheet UI（工具栏、公式栏、sheetbar 等）。
• 资源加载可观测（能确认 JS/CSS 确实加载完成）。
• 不破坏现有 Convex 数据读写链路（/api/tables/* -> Convex query/mutation）。

Checklist（按优先级）

A. 资源加载与初始化时序（高优先级）

• 确认 Luckysheet CSS 与 JS 都已加载完成，再允许 create()（避免“JS ready 但 CSS 未 ready”导致的高度/布局计算错误）。
• 首次创建后触发一次 resize（部分情况下 Luckysheet 需要通过 resize 重新计算 UI 布局）。
• 记录/暴露资源清单（仅 dev）：便于确认当前页面是否完成注入与版本号是否一致。

B. 全屏容器可见性与布局（高优先级）

• Luckysheet create() 时容器必须“已占位且可计算尺寸”（不要在 display:none 的容器里初始化）。
• Loading/Error 采用绝对定位遮罩，避免通过隐藏容器实现 loading（防止尺寸为 0 导致布局计算异常）。

C. 与 Convex 数据链路的时序（中优先级）

• 表格数据（snapshot/schema/title）获取完成后再创建实例，避免多次 create/destroy 抖动。
• 保存/同步触发频率可控（debounce），避免高频 mutation 导致卡顿（尤其在外网高延迟场景）。

D. 观测与回归（中优先级）

• 在控制台输出关键阶段日志（仅 dev）：资源加载完成 / create / destroy / resize。
• 复现用例：首次全屏打开（冷启动）、关闭后再开、刷新后再开、嵌入 iframe 与全屏互不影响。

已实施修复（对应 A/B）

• wolai-frontend/src/components/online-table/useLuckysheetLoader.ts：CSS 注入改为等待 onload，并与 JS 一起作为 ready 条件；dev 下暴露 window.__wolaiLuckysheetResources 便于排查。
• wolai-frontend/src/components/online-table/FullScreenTableEditor.tsx：容器始终占位 + overlay 遮罩；create() 后触发 resize（含兜底调用 luckysheet.resize?.()）。

验证步骤（建议）

1. 冷启动后打开含在线表格的文档，点击“全屏编辑”，观察工具栏/公式栏是否一次成功显示。
2. 打开 DevTools -> Network / Sources，确认首次打开会请求 /luckysheet/*，且 CSS/JS 不报错。
3. 控制台查看 window.__wolaiLuckysheetResources（dev 模式）是否存在，以及资源路径版本号是否一致。