96 lines
6.5 KiB
Markdown
96 lines
6.5 KiB
Markdown
# 代码索引（前后端）
|
||
|
||
本文用于后续开发“快速定位入口/职责/调用链”，按目录与功能点整理。路径以仓库根目录为基准。
|
||
|
||
## 启动链路与关键入口
|
||
- 一键启动脚本：`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` 避免通配符误匹配。
|
||
|