6.8 KiB
6.8 KiB
MNOTE 项目介绍（PPT 大纲草稿）
使用建议：每个
---作为一页 PPT；标题为页面标题；要点为页面内容。
说明：当前项目数据主链路以 Convex 为准；仓库中出现的 Supabase 相关内容按“历史遗留/兼容残留”处理。
0. 标题页
- 项目：MNOTE（知识管理系统）
- 形态：Web + 桌面端（Electron）
- 关键词：块编辑器 / 思维导图 / AI 工具型 Agent / Convex 数据层
1. 目录
- 架构
- 已实现功能
- 优点/特点
- 缺点
2. 架构总览（分层）
- UI/交互层：Next.js（App Router）+ React（前端）
- 业务与数据层：Convex（数据读写、鉴权与权限、文件存储）
- 辅助能力层：FastAPI + Celery（OCR / OnlyOffice / 其他集成）
- 桌面封装层：Electron（内嵌 Next.js standalone）
- 测试与运维：Playwright E2E、Convex 自托管（Docker Compose）
3. 架构图（逻辑关系）
┌──────────────────────────┐
│ 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_wsWebSocket 路由（表格/协作相关）
- 健康检查：
- 预留集成点
- MinerU：OCR 服务（位于
services/mineru） - LightRAG：RAG 检索/生成（仓库内有集成点与相关依赖）
- MinerU：OCR 服务（位于
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/桌面/本地）对配置与数据一致性提出更高要求（需要清晰的环境与开关策略）