# Wolai-clone 协同表格方案（v3.1）——Luckysheet 体验 × Supabase 数据底座

## 0. 背景与目标

- 当前 v3.0 架构已经完成 BlockNote + Yjs + Hocuspocus + Supabase Realtime 的基础协同能力，内置块类型仅支持「简单表格」，无法满足飞书/钉钉/金山文档级交互。
- 新版本需要让用户在文档任意位置插入「在线表格块」，可在文档内预览、可全屏编辑、可多人实时协作，并支持 Excel 级功能（公式、条件格式、批量粘贴等）。
- 同时，考虑到未来要把表格作为独立数据对象（多处引用、导出、AI/OCR 写入等），必须把表格数据与 BlockNote 主文档解耦，避免大表拖垮文档 CRDT。

## 1. 设计原则

1. **用户心智优先**：界面与交互最大程度贴近 Excel/WPS/飞书表格，复制粘贴零障碍。
2. **数据解耦**：BlockNote 块只保存 `tableId` 与视图参数，真实表格数据落在 Supabase + 独立 Yjs SubDoc，确保性能、复用与权限扩展。
3. **协同一致性**：复用现有 Yjs/Hocuspocus/Supabase Realtime 通道，内嵌/全屏共享同一数据源，支持多人光标与冲突解决。
4. **渐进增强**：先满足核心编辑体验，再分阶段接入高级能力（导入导出、公式库、与 MinerU/AI 的互通）。

## 2. 技术选型与理由

| 维度             | 方案                           | 理由 |
|------------------|--------------------------------|------|
| 表格 UI/编辑器   | Luckysheet (@dream-num)        | Excel 级 UI/工具栏/公式/条件格式，复制粘贴兼容 WPS/飞书/钉钉，支持 headless 嵌入。 |
| 数据渲染内核     | Luckysheet + 虚拟滚动           | 经过大规模验证，500×100 也能稳定运行。 |
| 实时协作         | Yjs SubDoc + luckysheet-yjs-binding | 官方 binding，直接复用现有 Hocuspocus Provider；每张表格一个 SubDoc，避免主文档体积膨胀。 |
| 数据持久化       | Supabase Postgres (`document_tables`, `document_table_rows`) + 定时快照 | 让表格成为独立实体，可复用/引用/授权，同时方便后台 API、导出和 AI 写入。 |
| 内联预览         | 自研 React 轻量预览组件 + 行列摘要 | 保持文档流畅，默认展示前 5 行，支持 hover 工具条。 |
| 全屏编辑         | `<FullScreenTableEditor>` + Luckysheet | 提供 Excel 式工具栏、状态栏、协作者指示、暗黑模式。 |
| 公式引擎         | Luckysheet 内置 + HyperFormula（后续增强） | 先满足 SUM/IF 等高频场景，再按需升级。 |

> 放弃：自研 Data Grid（周期长）、Handsontable（商业授权）、AG-Grid（过重）、Tiptap Table（功能不足）。

## 3. 架构概览

```
┌───────────────────────────┐
│        Next.js 前端        │
│ ┌───────────────────────┐ │
│ │ BlockNote (文档 Y.Doc) │ │
│ │   └─ TableBlock        │ │
│ │       attrs: {tableId} │ │
│ └───────────────────────┘ │
│            │引用            │
│ ┌───────────────────────┐ │
│ │ LuckysheetProvider    │ │
│ │   └─ Y.SubDoc(tableId)│ │
│ │   └─ Supabase Realtime│ │
│ └───────────────────────┘ │
└────────────┬──────────────┘
             │REST/RPC
┌────────────▼──────────────┐
│ FastAPI 后端 + Supabase    │
│ ├─ document_tables         │
│ ├─ document_table_rows     │
│ ├─ RLS / Realtime 触发器   │
│ └─ 导出/导入/AI 接口       │
└───────────────────────────┘
```

- **BlockNote 主文档**：仅存 `tableId`、标题、视图配置等轻量信息。
- **表格 Y.SubDoc**：按需加载；Luckysheet 与之绑定，实现实时协作。
- **Supabase 数据**：提供持久化/查询/权限/导出能力；Yjs 定时把最新快照写入数据库，同时监听数据库变化以支持非 Web 客户端。

## 4. 数据模型

```sql
create table document_tables (
  id uuid primary key default gen_random_uuid(),
  workspace_id uuid not null references workspaces(id) on delete cascade,
  document_id uuid not null references documents(id) on delete cascade,
  title text not null default '未命名表格',
  schema jsonb not null default '{}'::jsonb,         -- 列定义/格式/宽度
  view_preferences jsonb not null default '{}'::jsonb,
  is_archived boolean not null default false,
  snapshot jsonb,
  last_synced_at timestamptz,
  created_by uuid references profiles(id) on delete set null,
  updated_by uuid references profiles(id) on delete set null,
  created_at timestamptz not null default timezone('utc', now()),
  updated_at timestamptz not null default timezone('utc', now())
);

create table document_table_rows (
  id uuid primary key default gen_random_uuid(),
  workspace_id uuid not null references workspaces(id) on delete cascade,
  document_id uuid not null references documents(id) on delete cascade,
  table_id uuid not null references document_tables(id) on delete cascade,
  row_index integer not null,                        -- 稳定排序键
  row_data jsonb not null default '{}'::jsonb,       -- 单元格字典，按列 key 存储
  row_hash text,
  is_deleted boolean not null default false,
  updated_by uuid references profiles(id) on delete set null,
  created_at timestamptz not null default timezone('utc', now()),
  updated_at timestamptz not null default timezone('utc', now())
);
```

- ✅（2025-02-22）`supabase_local` 已执行建表 + 索引 + 触发器 + RLS，迁移文件：`supabase/migrations/20250222_add_document_tables.sql`。
- RLS：沿用 `workspace_members`，`document_tables`/`document_table_rows` 在写入前通过触发器校验 workspace/document 一致，所有读写均需加入同一 workspace。
- 每张表格的实时编辑依赖 Yjs SubDoc；后台任务（导出 CSV/Excel、AI 填表、MinerU OCR 转表）通过 REST API 操作数据库。
- BlockNote 块示例：

```json
{
  "id": "block_xxx",
  "type": "table",
  "props": {
    "tableId": "d3d7-...",
    "displayMode": "compact",
    "previewRows": 5
  }
}
```

## 5. 功能模块拆解

1. **块插入与预览**
   - 斜杠命令 `/table`、工具栏按钮、AI 建议等入口。
   - 默认创建 10×5 空表，预览显示前 5 行 + 列头，hover 显示快速操作（新建/全屏/复制链接）。
2. **全屏编辑器**
   - Excel 风格工具栏（行列操作、合并、筛选、条件格式、公式插入、单元格格式）。
   - 协作者状态：顶部显示头像、单元格边框高亮。
   - 暗黑模式、移动端强制全屏。
3. **数据同步**
   - Luckysheet ↔ Y.SubDoc：官方 binding。
   - SubDoc ↔ Supabase：节流（1-2s）后写入 `document_tables`/`document_table_rows`；大表行级 diff。
   - 后端提供导出 CSV/Excel、批量导入 API。
4. **高级能力**
   - 条件格式模版、冻结行列、查看历史版本。
   - 允许多个文档引用同一 `tableId`（只读/编辑权限可控）。
   - AI/ MinerU 写表：后端接口 `/api/v1/tables/{id}/rows` 支持 append/merge。

## 6. 实施计划

| 阶段 | 时间 | 目标 | 关键任务 | 产出 / 验收 |
|------|------|------|----------|-------------|
| P0 需求巩固 | 0.5d | 明确体验 & 数据需求 | - 联合设计/产品确认预览、高级功能优先级<br>- 定义列类型 MVP（文本/数字/货币/日期/选择/复选/公式/引用）<br>- 确认与 MinerU/AI 的接口需求 | 更新 PRD + 交互稿 |
| P1 数据面准备 | 1d | 建 Supabase 表 & API | - 执行 SQL 建表 + RLS + 触发器（Supabase Realtime 通知）<br>- FastAPI 增加 `/tables` CRUD、`/tables/{id}/rows` 批量读写<br>- 单元测试 + API 文档 | 后端分支 + Swagger |
| P2 Yjs/Luckysheet 骨架 | 2d | 协同内核跑通 | - 引入 @dream-num/luckysheet、luckysheet-yjs-binding<br>- 实现 `<LuckysheetProvider>`，封装 SubDoc 生命周期、连接状态提示<br>- 支持单独打开表格编辑页（不依赖 BlockNote） | 可共享链接、协同无冲突 |
| P3 BlockNote 表格块 & 预览 | 2d | 文档内插入与缩略展示 | - 自定义 block schema + slash command<br>- 预览组件（前5行、hover toolbar、loading/错误态）<br>- 表格块和 Supabase 数据绑定（创建时写表、删除时软删） | 文档里可插入表格并跳转全屏 |
| P4 全屏编辑器 & 工具栏 | 3d | 飞书式编辑体验 | - `<FullScreenTableEditor>`：工具栏、状态栏、协作者列表<br>- 支持插入/删除/合并/冻结/条件格式/基础公式<br>- 完善暗黑/移动端 UI | 500×50 表格流畅、多端一致 |
| P5 持久化 & 性能 | 2d | 数据安全 & 优化 | - SubDoc → Supabase 节流、row-level diff<br>- 历史快照（定时写入 table_versions）<br>- 预览模式虚拟滚动、全屏懒加载资源 | 刷新不丢数据、大表不卡顿 |
| P6 高级扩展 | 2d+ | 导入导出 & AI | - CSV/Excel 导入导出<br>- MinerU OCR 输出自动转表 + 写入<br>- 表格引用共享、权限控制 UI | E2E 测试 + 文档 |

> 若时间紧，可先完成 P0~P4 形成可用 MVP，之后再迭代 P5/P6。

**进展速记（2025-02-22）**
- ✅ P1「执行 SQL 建表 + RLS + 触发器」已完成（详见上文数据模型 & 迁移文件），剩余 `/tables`/`/tables/{id}/rows` API + 单元测试待开发。
- ✅ P2「Luckysheet Provider + Yjs SubDoc 骨架」：Next.js 侧封装 `LuckysheetCanvas`，复用 Hocuspocus 通道，表格编辑自动广播到 Y.Doc 与 Supabase snapshot。
- ✅ P3「BlockNote 表格块 & 预览」：自定义 `tableBlock` + slash `/table`，支持在线创建、缩略展示、重命名、全屏入口。
- ✅ P4「全屏编辑器」：落地 `<TableEditorOverlay>`，集成 Luckysheet 工具栏、保存状态、协同提示，500×50 表格实测流畅。

## 7. 依赖与工具

```bash
pnpm add @dream-num/luckysheet luckysheet-yjs-binding @hocuspocus/provider yjs y-protocols zustand lucide-react

# 后端
pip install fastapi supabase-py psycopg[binary] uvicorn[standard]
```

- 设计稿：Figma（飞书表格参考）。
- 协同测试：Cypress + Playwright（多客户端场景）。

## 8. 验收清单

- [ ] `/table` 插入后出现缩略预览，支持命名/重命名。
- [ ] 多端同时编辑同一表，光标位置、单元格内容同步延迟 < 800ms。
- [ ] 刷新或重连后表格数据一致，Supabase 中有对应记录。
- [ ] 全屏编辑支持：插入/删除行列、调整列宽、冻结、合并、条件格式、公式 (SUM/AVERAGE/IF)。
- [ ] 支持从 Excel/WPS/飞书/钉钉直接粘贴，保留行列和基础格式。
- [ ] CSV/Excel 导出可用，至少支持 UTF-8。
- [ ] 移动端默认全屏，横屏提示可编辑。

## 9. 后续路线（与整体架构衔接）

1. **多视图**：基于同一 `tableId` 派生看板、画廊，复用 Supabase 数据。
2. **AI Assist**：支持「生成表格」「自动补数据」「智能公式建议」，后端复用 LightRAG + GPT-4o。
3. **OCR 写表**：MinerU 解析复杂表格后直接写入 `document_table_rows`，用户可在 Luckysheet 中二次确认。
4. **权限与共享**: 表格可独立分享/只读/协作，并在后台记录操作日志。

此方案兼顾用户熟悉的 Excel 体验与 Supabase 数据化能力，为后续多视图、AI、OCR 等模块铺平道路。接下来可按 P0~P4 推进 MVP，实现飞书级表格块体验。*** End Patch