mnote/CODE_INDEX.md

代码索引（前后端）

本文用于后续开发“快速定位入口/职责/调用链”，按目录与功能点整理。路径以仓库根目录为基准。

启动链路与关键入口

• 一键启动脚本：scripts/desktop-hot.js（启动 wolai-frontend + wolai-backend，Redis 可用时启动 Celery）。
• 前端入口（Next App Router）：
  • 根布局：wolai-frontend/src/app/layout.tsx（创建 Supabase Server Client，注入 SupabaseProvider/QueryProvider）。
  • 首页跳转：wolai-frontend/src/app/page.tsx（未登录跳 /login；确保默认工作区；跳转首个文档或创建“新页面”）。
• 后端入口（FastAPI）：wolai-backend/app/main.py（挂载 root_router 与 /api/v1 的 api_router）。

前端（wolai-frontend）

页面路由（App Router）

• 登录页：wolai-frontend/src/app/(auth)/login/page.tsx
• 主应用布局：wolai-frontend/src/app/(app)/layout.tsx（组装侧边栏数据：workspaces、documents、trash、media、mindmap 资产等）。
• 文档页：wolai-frontend/src/app/(app)/documents/[id]/page.tsx（读取 documents 表的标题/选项/统计，渲染 DocumentShell）
• 思维导图全屏页：wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx
• 在线表格页：wolai-frontend/src/app/tables/[tableId]/view/page.tsx
• OnlyOffice 页：wolai-frontend/src/app/onlyoffice/page.tsx
• 调试页：
  • AI Agent：wolai-frontend/src/app/dev/ai-agent/page.tsx
  • Mindmap：wolai-frontend/src/app/dev/mindmap/page.tsx

API（Next Route Handlers）

这些接口基本承担“鉴权 + 读写 Supabase + 返回给前端”的 BFF 职责：

• 文档：wolai-frontend/src/app/api/documents/*/route.ts
  • content/title/options/save/create/duplicate/move/delete/restore/purge/stats/copy-tree/...
• 思维导图：wolai-frontend/src/app/api/mindmap/**/route.ts
  • api/mindmap/[docId]/route.ts、api/mindmap/[docId]/[mindmapId]/route.ts、api/mindmap/[docId]/[mindmapId]/ops/route.ts
  • api/mindmap/[id]/route.ts（按 id 的路由分支）
• 思维导图 AI：wolai-frontend/src/app/api/mindmap-ai/*/route.ts
  • agent / assets / expand-node / outline-to-mindmap / test-pdf
• 媒体/附件：wolai-frontend/src/app/api/media/*/route.ts
  • upload/sign/signed-url/assets/batch/ocr/empty-trash/purge
• AI Agent（统一入口）：wolai-frontend/src/app/api/ai-agent/run/route.ts
  • 负责：加载在线/本地模型配置、构建 tool registry、按 scope 过滤工具、SSE 流式返回。
• 后端探活转发：wolai-frontend/src/app/api/backend/health/route.ts
• 其它：wolai-frontend/src/app/api/search/*、wolai-frontend/src/app/api/sidebar/route.ts、wolai-frontend/src/app/api/workspaces/switch/route.ts 等。

编辑器与核心 UI

• 文档壳（客户端动态加载编辑器）：wolai-frontend/src/components/editor/document-shell.tsx
• 文档内容（核心编辑/保存/选项/历史/AI 面板）：wolai-frontend/src/components/editor/document-content.tsx
• BlockNote 编辑器：wolai-frontend/src/components/editor/blocknote-editor.tsx
• Block 级功能（重点在思维导图/媒体/表格）：
  • 思维导图 Block：wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx
  • 思维导图侧栏/工具栏：wolai-frontend/src/components/editor/blocks/MindmapSidebar.tsx、wolai-frontend/src/components/editor/blocks/MindmapToolbar.tsx
  • AI Agent 面板：wolai-frontend/src/components/editor/blocks/MindmapAiAgentPanel.tsx、wolai-frontend/src/components/editor/DocumentAiAgentPanel.tsx
• 侧边栏（文件树/回收站/资源）：wolai-frontend/src/components/sidebar/sidebar.tsx、wolai-frontend/src/components/sidebar/file-tree.tsx

状态与业务库（lib/store）

• Supabase 客户端封装：wolai-frontend/src/lib/supabase/{client.ts,server.ts,admin.ts}
• 工作区与侧边栏数据：wolai-frontend/src/lib/workspaces.ts、wolai-frontend/src/lib/sidebar-tree.ts
• 文件树算法与单测：wolai-frontend/src/lib/file-tree/*（*.test.ts 是 Vitest 单测入口之一）
• 思维导图存储/操作：wolai-frontend/src/lib/mindmap/*、wolai-frontend/src/lib/mindmap-files.ts
• AI 配置：wolai-frontend/src/lib/ai/*
• AI Agent 引擎：
  • 运行时：wolai-frontend/src/lib/ai-agent/runtime/runAgent.ts
  • 工具注册：wolai-frontend/src/lib/ai-agent/tools/registry.ts
  • 内置工具集合：wolai-frontend/src/lib/ai-agent/tools/builtins/registryBuiltins.ts 与 tools/builtins/*/*Tools.ts
• Zustand stores：wolai-frontend/src/store/*（如 editor-bridge.ts、sidebar.ts、ai-agent-ui.ts）

后端（wolai-backend）

FastAPI 路由与鉴权

• 路由聚合：wolai-backend/app/routers/__init__.py
  • root_router：/health + ws（Luckysheet）
  • api_router（前缀 /api/v1）：tasks/chat
• 健康检查：wolai-backend/app/routers/health.py（GET /health）
• 任务（OCR）：wolai-backend/app/routers/tasks.py
  • POST /api/v1/tasks/ocr（鉴权：AuthDep，创建 background_tasks 记录并投递 Celery）
  • GET /api/v1/tasks/{task_id}（查询任务状态）
• SSE 占位对话：wolai-backend/app/routers/chat.py（GET /api/v1/chat?query=...&document_id=...）
• Luckysheet 协同 WS：wolai-backend/app/routers/luckysheet_ws.py（/ws/luckysheet，校验 Supabase 用户与 workspace 成员关系）
• 鉴权依赖：wolai-backend/app/deps.py（通过 Supabase /auth/v1/user 验证 Bearer token）

Celery 与服务层

• Celery 配置：wolai-backend/app/workers/celery_app.py
• Celery 任务：wolai-backend/app/workers/tasks.py
  • ocr_pipeline：stage0 占位实现（更新 background_tasks 状态；回写 documents.content/raw_text/index_status）
• Supabase REST 封装：wolai-backend/app/services/supabase_rest.py
• 任务追踪：wolai-backend/app/services/task_tracker.py（写入/读取 background_tasks）
• 占位集成点：
  • MinerU：wolai-backend/app/services/mineru_service.py
  • LightRAG：wolai-backend/app/services/lightrag_service.py
• 配置：wolai-backend/app/config.py（.env，UTF-8）

Supabase（本地与迁移）

• 本地端口与 URL 说明：supabase.md
• 迁移目录：supabase/migrations/

备注（避免踩坑）

• wolai-frontend 才是 desktop-hot 启动的实际前端；根目录的 src/ 与其结构相似，可能是历史/镜像目录，改动前建议先确认是否仍在使用。
• 路由目录包含括号与中括号（如 (app)、[id]），在 PowerShell 中操作建议用 -LiteralPath 避免通配符误匹配。