# MNOTE 项目介绍（PPT 大纲草稿）

> 使用建议：每个 `---` 作为一页 PPT；标题为页面标题；要点为页面内容。  
> 说明：当前项目数据主链路以 **Convex** 为准；仓库中出现的 **Supabase** 相关内容按“历史遗留/兼容残留”处理。

---

## 0. 标题页

- 项目：MNOTE（知识管理系统）
- 形态：Web + 桌面端（Electron）
- 关键词：块编辑器 / 思维导图 / AI 工具型 Agent / Convex 数据层

---

## 1. 目录

1. 架构
2. 已实现功能
3. 优点/特点
4. 缺点

---

## 2. 架构总览（分层）

- UI/交互层：Next.js（App Router）+ React（前端）
- 业务与数据层：Convex（数据读写、鉴权与权限、文件存储）
- 辅助能力层：FastAPI + Celery（OCR / OnlyOffice / 其他集成）
- 桌面封装层：Electron（内嵌 Next.js standalone）
- 测试与运维：Playwright E2E、Convex 自托管（Docker Compose）

---

## 3. 架构图（逻辑关系）

```text
┌──────────────────────────┐
│        Desktop / Web       │
│  Electron（可选） + Next.js │
└─────────────┬────────────┘
              │ 页面渲染 / 交互
              v
┌──────────────────────────┐
│   Next.js App Router UI    │
│  - 页面：/documents /mindmap│
│  - BFF：/api/* route handler│
└───────┬───────────┬───────┘
        │           │
        │ 读写/权限  │ 集成/重计算（按需）
        v           v
┌─────────────────┐   ┌──────────────────────┐
│ Convex Backend   │   │ FastAPI + Celery      │
│ - 数据/鉴权/权限  │   │ - OCR / OnlyOffice 等  │
│ - Files 存储      │   │ - 可对接 MinerU/RAG     │
└─────────────────┘   └──────────────────────┘
```

---

## 4. 核心目录与职责（落地到仓库）

- `wolai-frontend/`：主前端（Next.js），源码在 `wolai-frontend/src/`
- `wolai-frontend/convex/`：Convex functions（schema / query / mutation / action）
- `infra/convex/`：Convex 自托管（Docker Compose + Dashboard）
- `wolai-backend/`：FastAPI + Celery（辅助能力与集成服务）
- `desktop-electron/`：Electron 桌面端包装
- `services/`：配套服务/集成点（如 `services/mineru`、LightRAG 等）
- `pw-tests/`：端到端测试（Playwright）

---

## 5. 数据流（典型请求）

- 登录/鉴权：前端挂载 Convex Auth Provider；由 Convex 负责身份与权限主线
- 数据读写：页面/组件通过 Convex 或 Next.js `/api/*`（BFF）访问业务数据
- 文件与附件：通过 Convex Files（或 BFF 代理）管理上传/下载与元信息
- 重计算/集成：需要 OCR、OnlyOffice、RAG 时走 FastAPI（可异步由 Celery 承载）

---

## 6. 已实现功能（概览）

- 文档系统：文档页、块编辑器外壳、基础读写链路
- 思维导图：导图页面/全屏、导图数据模型与读写、导图相关 API
- 协作与权限：工作区、群组/成员、分享（Share/Invite/Star/Recent 等数据模型）
- 媒体与引用：媒体资源、引用（references）、图片/附件 OCR 文本读取入口
- AI 能力：工具型 Agent 框架 + 内置工具集（含读/写工具与确认机制）
- OnlyOffice：前端页面与 BFF 代理接口（用于嵌入/代理访问）
- 桌面端：Electron 运行、热启动脚本、Windows 打包配置
- 运维/开发：Convex 自托管方案、开发脚本、E2E 测试脚本

---

## 7. 已实现功能（按模块细化：前端）

- 路由页面（示例）
  - 登录/鉴权：`/(auth)/login`、`/(auth)/auth`
  - 文档：`/(app)/documents/[id]`
  - 思维导图：`/mindmap/[docId]/[mindmapId]`
  - OnlyOffice：`/onlyoffice/*`，以及 `onlyoffice-server` 相关代理路由
  - 本地模式入口：`/local/*`
  - 表格：`/tables/[tableId]`
  - 调试：`/dev/*`（AI Agent / Mindmap）
- BFF API（示例）
  - 文档：`/api/documents/*`
  - 思维导图：`/api/mindmap/**`、`/api/mindmap-ai/*`
  - 媒体：`/api/media/*`
  - AI Agent：`/api/ai-agent/run`
  - OnlyOffice：`/api/onlyoffice/proxy`

---

## 8. 已实现功能（按模块细化：Convex）

- 业务数据与能力（按 functions 文件归类）
  - 文档：`documents.ts`、`comments.ts`、`recents.ts`、`documentStars.ts`
  - 分享与权限：`documentShares.ts`、`documentGroupShares.ts`、`groups.ts`、`groupMembers.ts`、`groupInvitations.ts`
  - 思维导图：`mindmaps.ts`
  - 媒体与附件：`mediaAssets.ts`
  - 引用：`references.ts`
  - 表格：`tables.ts`
  - 工作区与用户：`workspaces.ts`、`users.ts`
  - 异步任务骨架：`jobs.ts`

---

## 9. 已实现功能（按模块细化：后端/服务）

- FastAPI（阶段 0 骨架）
  - 健康检查：`/health`
  - 任务占位：`/api/v1/tasks/ocr`、`/api/v1/tasks/{id}`
  - SSE 占位：`/api/v1/chat`
  - 其他：`luckysheet_ws` WebSocket 路由（表格/协作相关）
- 预留集成点
  - MinerU：OCR 服务（位于 `services/mineru`）
  - LightRAG：RAG 检索/生成（仓库内有集成点与相关依赖）

---

## 10. 优点/特点（产品与体验）

- “文档 + 思维导图”一体化：导图是一等公民，可与文档块/附件/引用形成闭环
- 兼容 Web 与桌面端：同一套前端代码在不同运行环境复用
- AI 以“工具系统”落地：读写工具分级、写入前确认，便于可控扩展
- 具备本地/内网部署可能：Convex 支持自托管，适合内网或私有化场景

---

## 11. 优点/特点（工程与架构）

- 主链路清晰：Convex 统一承担数据 + 鉴权/权限 + 文件存储
- BFF 模式：Next.js Route Handlers 统一对外 API 形态，便于前端联调与权限收口
- 多能力可插拔：OCR / OnlyOffice / RAG 等通过后端服务或工具接口渐进接入
- 自动化基础较全：热启动脚本 + E2E（Playwright）脚本为联调与回归提供支撑

---

## 12. 缺点（架构复杂度与运维）

- 组件较多：Next.js + Convex + FastAPI/Celery + Electron（学习与排障成本高）
- 部署面更广：Convex 自托管 + 后端服务 +（可选）OCR/RAG 服务，运维链路更长
- 桌面端成本：Electron 体积与打包/升级链路带来额外维护负担

---

## 13. 缺点（技术债与一致性风险）

- Supabase 相关依赖/目录仍在仓库中，容易造成新同学误用或逻辑分叉（需要持续收敛）
- 后端多项能力仍为“阶段 0 占位”，与前端能力深度集成仍需补齐（OCR/RAG/SSE 等）
- 多运行模式（Web/桌面/本地）对配置与数据一致性提出更高要求（需要清晰的环境与开关策略）