173 lines
6.8 KiB
Markdown
173 lines
6.8 KiB
Markdown
|
# 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/桌面/本地）对配置与数据一致性提出更高要求（需要清晰的环境与开关策略）
|
|||
|
|
|