mnote/design/implementation_checklist.md

# MNOTE v3.0 未完成项计划与检查清单（截至 2025-12-02）

> 本清单聚焦 design3.0.md 中仍未落地的要点，按依赖顺序排列。勾选项即完成，可作为阶段验收依据。

## 阶段性计划

1. **后端基础补全**：补建数据库表、打通 MinerU OCR 流程。
2. **LightRAG 全链路**：实现增量索引与 `/api/v1/chat` 流式回答。
3. **思维导图增强**：在 simple-mind-map 基础上补齐双向同步与导出。
4. **实时协作与任务反馈**：用 Supabase Realtime 推送 background_tasks 进度、完善媒体/PDF OCR API。
5. **表格后端化**：按照 design3.0 P1/P2 要求提供 FastAPI CRUD，以承载 Luckysheet 协同。

## 详细 Checklist

- [x] **背景任务表迁移**  
  - 在 `supabase/migrations` 中新增 `background_tasks` 表及 RLS、索引、触发器，与 design3.0.md 第 3 节保持一致。  
  - 验证 `task_tracker` 读写正常（POST/GET `/api/v1/tasks/*`）。

- [x] **MinerU OCR 管线**  
  - `app/workers/tasks.py` 真正串联 MinerU：下载 Supabase Storage 文件 → 调用 `services/mineru` → 写入 `documents.content/raw_text/index_status`。  
  - `/api/v1/tasks/ocr` 支持真实参数（signed URL、document_id），并返回 Celery track_id。  
  - `DocumentTaskPanel` 将示例 URL 改为真实 Storage URL，增加失败提示。

- [x] **媒体 OCR API 对齐**  
  - FastAPI 新增 `/api/v1/tasks/media-ocr`，与前端 `/api/media/ocr` 对接。  
  - 统一 media_assets.ocr_status / ocr_payload 写入逻辑，并复用 MinerU 输出。

- [x] **Supabase Realtime 任务推送**  
  - 前端订阅 `background_tasks` 频道（Supabase Channel），实时更新状态 & 提示。  
  - 关闭现有轮询 fallback 或保留为降级方案。

- [ ] **documents 表字段与索引对齐**  
  - 确认 `documents` 表已包含 `mindmap_data/raw_text/index_status` 字段与默认值，并在 `supabase/migrations` 中补齐缺失迁移。  
  - 补建更新触发器/索引，保证 `updated_at`、`index_status` 的写入由后端与 Celery 任务一致，方便 LightRAG 增量监测。

- [ ] **LightRAG 索引与聊天**  
  - `lightrag_service` 调用实际 LightRAG：初始化 PGVectorStore、支持 `queue_index` 与 `query`。  
  - 保存笔记/完成 OCR 后触发增量索引；`/api/v1/chat` 以 SSE 返回引用、来源数组。  
  - 以 `user_id`/workspace 作为 LightRAG namespace，保证多租户隔离，并实现 `/api/v1/lightrag/health` 自检 + `--init-index` 重建脚本。

- [ ] **Celery 队列优先级与并发治理**  
  - 将 OCR/索引任务放入 Redis 优先级队列，worker 默认 concurrency=3，并限制同账号并发数（避免 CPU 撑爆）。  
  - Celery 任务需写入 `progress/message` 字段，失败自动进入 retry/backoff，配合 Supabase Realtime 显示。

- [ ] **Supabase Auth JWT 校验与跨域策略**  
  - FastAPI 中使用 `supabase-py` 验证前端携带的 JWT，拉通 `user_id` 注入依赖，拒绝匿名调用。  
  - 统一 CORS 配置（Next.js 域名 + 桌面端自签），并在 `/api/*` 中校验 workspace 权限。

- [ ] **simple-mind-map ↔ BlockNote 双向同步**  
  - 在 `KMindRenderer`/Lab 页面中监听节点改动，生成概要数据写回 `documents.mindmap_data`。  
  - BlockNote 侧根据最新 `mindmap_data` 更新大纲/引用，支持跳转到具体 mindmap 节点。  
  - 实现 PNG/PDF/Markdown 导出与文档内缩略预览。

- [ ] **思维导图/笔记互跳与引用**  
  - PDF/引用面板可跳转 mindmap 节点（事件 `mindmap:jump-to-node`）。  
  - Mindmap 节点可附加 BlockNote 块链接，实现双向导航。

- [ ] **表格后端接口 & 协同**  
  - FastAPI 新增 `/api/v1/tables`, `/api/v1/tables/{id}/rows` CRUD，与 `document_tables`/`document_table_rows` RLS 一致。  
  - 前端 Luckysheet 协同使用该接口（或 Supabase Rest）写入，支持版本快照/节流。

- [ ] **BlockNote 表格块 & 预览（P3）**  
  - Slash 命令支持“插入协同表格”，创建即落库 `document_tables` 并在 BlockNote 中插入引用块。  
  - 列出前 5 行 + hover 工具栏预览，支持点击跳转全屏编辑。

- [ ] **全屏 Luckysheet 编辑器（P4）**  
  - `<FullScreenTableEditor>` 完成多选、冻结、合并单元格、条件格式、暗黑模式和在线协作者头像。  
  - 工具栏、快捷键与飞书表格一致，兼容 simple-mind-map 的快捷跳转。

- [ ] **表格持久化与性能（P5）**  
  - Yjs SubDoc → Supabase 节流写入，增量 diff 仅写改动行，并定期生成 `table_versions` 快照。  
  - 提供 CSV/Excel 导入、虚拟滚动与断线重连恢复，验证 500×50 表格不卡顿。

- [ ] **PDF Sticky OCR 与引用**  
  - `/api/pdf/ocr/[assetId]` 返回的数据来自后端 MinerU（非直接读表），支持重新拉取。  
  - PDF 引用写回 `pdf_quotes` 表，Mindmap/PDF/BlockNote 三方共享同一引用格式。

- [ ] **文档保存 → LightRAG 自动更新**  
  - `DocumentContent` 提交后触发后台任务（轻量 queue）写入 LightRAG，而不仅是 Supabase。  
  - 失败时在 UI 中提示“索引重试”按钮。

- [ ] **实时协作共享链接与权限控制**  
  - 基于 Supabase Realtime Presence 实现 20 人同时编辑的游标/选择框，并测量延迟 < 800ms。  
  - 提供私有/工作区/公共只读分享链接，结合 `workspace_members` RLS 校验访问级别。

- [ ] **Supabase Storage 签名 URL 与服务端下载闭环**  
  - 前端仅生成短时 signed URL，FastAPI 使用 service_role 拉取原始文件，超时自动重新签名。  
  - 针对桌面端上传，补充失败重传/断点续传与 Storage 目录规划（user_id/workspace/document_id）。

- [ ] **性能优化 & 自动化测试（阶段 7）**  
  - 前端提供 skeleton + lazy chunk，BlockNote/思维导图切分 bundle，桌面端 `npm run desktop:hot` 自检指标 < 800ms。  
  - 后端加入速率限制、pytest + Celery 集成测试、Cypress 多人协作 E2E，并在 CI 中跑。

完成上述清单后，即可宣告 design3.0 的核心路径（OCR + LightRAG + simple-mind-map + 协同表格）满足验收标准。

现状速记

• 后端 OCR 流程已串好：wolai-backend/app/workers/tasks.py 中 ocr_pipeline 通过 storage_fetcher 下载签
  名 URL，调用 mineru_service.extract_markdown_sync（VLM 后端可配置），写回 documents.content/raw_text/ index_status 并自动投递 lightrag_index_pipeline。media_ocr_pipeline 也会更新 media_assets.ocr_status/ ocr_payload。
• 数据面同步到位：supabase/migrations/20251204_alter_documents_add_mindmap_fields.sql 补齐 mindmap_data/ raw_text/index_status 及索引/触发器，20251203_add_background_tasks.sql 完成任务表 + RLS。
• 前端任务面板已接入 Realtime：wolai-frontend/src/components/document-task-panel.tsx 订阅
  background_tasks 频道，可手工输入 Storage URL 触发 /api/v1/tasks/ocr，并展示 OCR/索引进度。
• 文档保存会触发索引：wolai-frontend/src/app/api/documents/save/route.ts 在保存内容时写入 raw_text/
  index_status=pending，并向后端 /api/v1/lightrag/index 异步投递。
• LightRAG 壳已就绪：wolai-backend/app/services/lightrag_service.py 支持 workspace/user namespace，/api/ v1/chat 提供 SSE，占位的 scripts/init_lightrag.py 可批量重建索引（未验证实链）。

主要缺口 / 风险

• LightRAG 功能未闭环：缺少前端聊天 UI（未消费 /api/v1/chat SSE），也未验证真实 LightRAG PGVector/LLM 调 用，当前 fallback 可能静默返回占位数据。
• Celery 治理不足：虽配置了优先级队列与并发=3，但未做账号级限流/去重/重试回退，进度消息较粗，失败场景
  无 backoff。
• 鉴权与隔离：FastAPI 仅做 token 校验，写库全部用 service_role（supabase_rest），缺少 workspace 成员校验 与 CORS/桌面端域名统一策略。
• 思维导图 ↔ 笔记未同步：mindmap_data 仅在导图页保存，BlockNote 无法反哺/消费导图结构，也未实现节点 ↔
  BlockNote 块/引用的互跳。
• 表格后端缺失：FastAPI 无 /api/v1/tables CRUD，当前全靠 Next 路由直写 Supabase，Luckysheet 协同仅有 WS 转发，未落库增量/节流/快照。
• PDF OCR/引用链路半成品：前端 pdf-asset-viewer 读取 /api/pdf/ocr 和 pdf_quotes，但后端没有 MinerU PDF
  OCR 接口，media_ocr_pipeline 仅填空 payload，无法重新拉取真 OCR。
• Storage 签名与续签：OCR 触发仍靠手填 URL，后端也未实现 service_role 下载 + 失效重签。

下一步优先级建议

1. 验证并打通 LightRAG 实链：为 PG/LLM 配好 env，跑一条索引 + /api/v1/chat 流式问答自检，补全引用数组格 式；前端落地聊天侧边栏消费 SSE。
2. 强化 Celery 任务治理：增加 per-user 并发/队列优先级策略、重试/退避、进度消息细化
   （pending→processing→completed/failed），并确保 Realtime 推送正确。
3. 补齐鉴权与 CORS：在 FastAPI 统一用 supabase-py 校验 JWT，所有写操作检查 workspace 成员；整理 CORS 允 许列表覆盖桌面端自签域。
4. 实现导图↔笔记双向同步：BlockNote 监听节点摘要写回 documents.mindmap_data，导图侧消费最新大纲/块链接， 增加互跳事件（block_id/mindmap node id）。
5. 表格后端化：在 FastAPI 增加 /api/v1/tables 与 /api/v1/tables/{id}/rows，对齐 document_tables/
   document_table_rows RLS；Luckysheet 读写走该接口并加节流/快照。
6. 完善 PDF OCR/引用链路：新增 /api/v1/tasks/pdf-ocr 或复用 media-ocr 生成带页码/rect 的 OCR payload；/ api/pdf/ocr/[assetId] 回源 MinerU 结果并支持重拉。
7. Storage 签名闭环：前端生成短时 signed URL，后端负责下载/过期重签，任务触发面板改为自动选取文档关联文 件而非手填 URL。