# 代码索引（前后端）

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

## 启动链路与关键入口
- 一键启动脚本：`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` 避免通配符误匹配。