mnote/CODE_INDEX.md

# 代码索引（前后端）

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

## 关键事实（防止误判）
- **当前已使用 Convex 完全替换 Supabase**：数据读写、鉴权与权限控制以 Convex 为主线。
- 仓库内若仍出现 `supabase/`、`supabase.md`、`wolai-frontend/src/lib/supabase/`、`wolai-backend/app/services/supabase_rest.py` 等，均应视为**历史遗留**（除非任务明确要求，否则不要继续扩展）。

## 启动链路与关键入口
- 一键热启动脚本：`scripts/desktop-hot.js`（启动 `wolai-frontend` + `wolai-backend`；Redis 可用时启动 Celery）。
- 前端入口（Next.js App Router）：`wolai-frontend/src/app/layout.tsx`（注入 runtime config；挂载 Convex provider）。
- 运行期配置：`wolai-frontend/src/lib/runtime-config.ts`（读取 env / public 配置并注入到 `window.__MNOTE_RUNTIME_CONFIG__`）。
- Convex 自托管（基础设施）：`infra/convex/docker-compose.yml`、`infra/convex/README.md`。
- Convex functions（后端逻辑/数据模型）：`wolai-frontend/convex/`。
- 后端入口（FastAPI）：`wolai-backend/app/main.py`（辅助能力与集成服务，例如 OCR / OnlyOffice 等）。

## 前端（wolai-frontend）

### 页面路由（App Router）
- 登录/鉴权：`wolai-frontend/src/app/(auth)/`（如 `wolai-frontend/src/app/(auth)/auth/page.tsx`）。
- 主应用布局：`wolai-frontend/src/app/(app)/layout.tsx`。
- 文档页：`wolai-frontend/src/app/(app)/documents/[id]/page.tsx`。
- 思维导图全屏页：`wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx`。
- OnlyOffice：`wolai-frontend/src/app/onlyoffice/`。
- 调试页：`wolai-frontend/src/app/dev/`（AI Agent / Mindmap 等）。

### API（Next Route Handlers / BFF）
这些接口承担“鉴权 + 调用 Convex（query/mutation/action）+ 返回前端”的 BFF 职责：
- 文档相关：`wolai-frontend/src/app/api/documents/*/route.ts`。
- 思维导图相关：`wolai-frontend/src/app/api/mindmap/**/route.ts`。
- 思维导图 AI：`wolai-frontend/src/app/api/mindmap-ai/*/route.ts`。
- 媒体/附件：`wolai-frontend/src/app/api/media/*/route.ts`。
- AI Agent 统一入口：`wolai-frontend/src/app/api/ai-agent/run/route.ts`。
- OnlyOffice 代理：`wolai-frontend/src/app/api/onlyoffice/proxy/route.ts`。

### Convex（前端接入层）
- Convex React Provider：`wolai-frontend/src/components/providers/convex-provider.tsx`。
- Convex API/Client 封装：`wolai-frontend/src/lib/convex/`（如 `api.ts`、`route.ts`、`server.ts`、`enabled.ts`）。
- Sidebar（Convex 数据来源）：`wolai-frontend/src/hooks/use-convex-sidebar-data.ts`、`wolai-frontend/src/components/sidebar/sidebar.tsx`。

### 编辑器与核心 UI
- 文档壳：`wolai-frontend/src/components/editor/document-shell.tsx`。
- 文档内容：`wolai-frontend/src/components/editor/document-content.tsx`。
- BlockNote 编辑器：`wolai-frontend/src/components/editor/blocknote-editor.tsx`。
- 思维导图 Block：`wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx`。
- 侧边栏：`wolai-frontend/src/components/sidebar/`。

### AI Agent（工具系统）
- 运行时：`wolai-frontend/src/lib/ai-agent/runtime/runAgent.ts`。
- 工具注册：`wolai-frontend/src/lib/ai-agent/tools/builtins/registryBuiltins.ts`。

### 状态管理
- Zustand stores：`wolai-frontend/src/store/*`。

## 后端（wolai-backend）
后端主要承担辅助能力与集成服务（如 OCR/异步任务/OnlyOffice 等），数据主链路以 Convex 为准：
- FastAPI 入口：`wolai-backend/app/main.py`。
- 路由聚合：`wolai-backend/app/routers/__init__.py`。
- 健康检查：`wolai-backend/app/routers/health.py`。
- OCR/任务相关：`wolai-backend/app/routers/tasks.py`、`wolai-backend/app/services/*`。
- Celery：`wolai-backend/app/workers/*`。

## 历史遗留（不要当作现行架构）
若你看到以下路径/模块，请默认它们不再是当前主线（除非任务明确要求处理）：
- `supabase/`、`supabase.md`
- `wolai-frontend/src/lib/supabase/`
- `wolai-backend/app/services/supabase_rest.py`