cirry/tunji2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
cirry
2026-06-01 17:28:00 +08:00
commit 23aa61401a
35 changed files with 5810 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

913
docs/DESIGN.md Normal file
View File

@@ -0,0 +1,913 @@
# Tunji - 笔记应用设计文档
> 类印象笔记 + Typora 的桌面笔记应用，基于 Electron + Vue 3 + Tailwind CSS + PrimeVue (Unstyled) 构建
---
## 一、技术栈
| 层级 | 技术 | 说明 |
|------|------|------|
| 桌面框架 | Electron | 跨平台桌面应用 |
| 前端框架 | Vue 3 (Composition API) | 响应式 UI |
| 路由 | Vue Router 4 | SPA 路由管理 |
| 状态管理 | Pinia | 全局状态管理 |
| 样式 | Tailwind CSS 4 | 原子化 CSS |
| 组件库 | PrimeVue (Unstyled Mode) | 无样式组件，配合 Tailwind 自定义样式 |
| 图标 | lucide-vue-next | 轻量级图标库 |
| Markdown 处理 | unified (remark + rehype) | Markdown 解析 / 渲染 / 编辑 |
| 编辑器引擎 | ProseMirror / Tiptap | 富文本块编辑（Typora 风格） |
| 本地数据库 | better-sqlite3 (主进程) | 搜索索引、元数据缓存 |
| 文件监控 | chokidar | 工作目录文件变更监听 |
| 同步引擎 | 自研抽象层 | 支持 Git / WebDAV / S3 / 坚果云 |
---
## 二、主题色系统
参考 PrimeVue Lara 主题设计，采用蓝色为主色调，搭配中性灰色系。
### 2.1 主色 (Primary)
| 变量名 | 色值 | 用途 |
|--------|------|------|
| `--p-primary-50` | `#eff6ff` | 最浅背景 |
| `--p-primary-100` | `#dbeafe` | 浅色背景 / hover 背景 |
| `--p-primary-200` | `#bfdbfe` | 边框 / 分割线 |
| `--p-primary-300` | `#93c5fd` | 禁用状态 |
| `--p-primary-400` | `#60a5fa` | hover 边框 |
| `--p-primary-500` | `#3b82f6` | **默认按钮 / 链接** |
| `--p-primary-600` | `#2563eb` | **按钮 hover** |
| `--p-primary-700` | `#1d4ed8` | 按钮 active / pressed |
| `--p-primary-800` | `#1e40af` | 深色文字 |
| `--p-primary-900` | `#1e3a8a` | 最深色 |
### 2.2 表面色 (Surface)
| 变量名 | 色值 | 用途 |
|--------|------|------|
| `--p-surface-0` | `#ffffff` | 页面背景 / 卡片背景 |
| `--p-surface-50` | `#f8fafc` | 左侧栏背景 |
| `--p-surface-100` | `#f1f5f9` | 次级背景 / hover 背景 |
| `--p-surface-200` | `#e2e8f0` | 分割线 / 边框 |
| `--p-surface-300` | `#cbd5e1` | 禁用边框 |
| `--p-surface-400` | `#94a3b8` | 占位符文字 |
| `--p-surface-500` | `#64748b` | 次要文字 |
| `--p-surface-600` | `#475569` | 正文文字 |
| `--p-surface-700` | `#334155` | 标题文字 |
| `--p-surface-800` | `#1e293b` | 主标题文字 |
| `--p-surface-900` | `#0f172a` | 最深文字 |
### 2.3 语义色
| 语义 | 色值 | 说明 |
|------|------|------|
| `--p-success-500` | `#22c55e` | 成功 / 新建 |
| `--p-success-600` | `#16a34a` | 成功 hover |
| `--p-warn-500` | `#f59e0b` | 警告 |
| `--p-warn-600` | `#d97706` | 警告 hover |
| `--p-danger-500` | `#ef4444` | 危险 / 删除 |
| `--p-danger-600` | `#dc2626` | 危险 hover |
| `--p-info-500` | `#06b6d4` | 信息提示 |
### 2.4 暗色模式
暗色模式下 surface 反转，primary 色保持不变但降低饱和度：
| 变量名 | 色值 | 用途 |
|--------|------|------|
| `--p-surface-0` (dark) | `#0f172a` | 页面背景 |
| `--p-surface-50` (dark) | `#1e293b` | 左侧栏背景 |
| `--p-surface-100` (dark) | `#334155` | 卡片背景 |
| `--p-surface-200` (dark) | `#475569` | 边框 / 分割线 |
| `--p-surface-700` (dark) | `#e2e8f0` | 标题文字 |
| `--p-surface-800` (dark) | `#f1f5f9` | 主标题文字 |
---
## 三、工作目录设计
### 3.1 核心概念
参考 Obsidian 的 Vault 模型：**用户首次启动时必须选择一个工作目录**，所有数据（笔记、笔记本、标签、配置、插件）都在该目录下管理。
### 3.2 目录结构
```
<用户选择的工作目录>/
├── .tunji/ # 应用元数据目录（隐藏）
│ ├── config.json # 应用配置（主题、编辑器设置等）
│ ├── tags.json # 标签定义（全局标签库）
│ ├── notebooks.json # 笔记本元数据（排序、颜色等）
│ ├── sync.json # 同步配置（WebDAV/S3/Git 凭据引用）
│ ├── plugins/ # 插件目录（未来扩展）
│ │ └── ...
│ ├── trash/ # 废纸篓（已删除笔记的临时存放）
│ │ ├── <note-id>.md
│ │ └── ...
│ ├── versions/ # 本地版本快照（Git-like 内容寻址）
│ │ ├── <hash1> # 文件内容的 SHA-256 哈希
│ │ ├── <hash2>
│ │ └── ...
│ └── index.sqlite # 本地搜索索引（不同步！）
│
├── 笔记本A/ # 用户的笔记本（即文件夹）
│ ├── 笔记1.md # 笔记文件
│ ├── 笔记1.assets/ # 笔记1 的专属附件目录（同名配对）
│ │ ├── 架构图.png
│ │ └── 需求文档.pdf
│ ├── 笔记2.md
│ ├── 笔记2.assets/ # 笔记2 的专属附件目录
│ │ └── screenshot.jpg
│ ├── 子笔记本C/ # 笔记本支持嵌套
│ │ ├── 笔记3.md
│ │ ├── 笔记3.assets/
│ │ │ └── 流程图.png
│ │ └── ...
│ └── ...
│
├── 笔记本B/
│ ├── 笔记4.md
│ ├── 笔记4.assets/
│ │ └── 演示视频.mp4
│ └── ...
│
└── 无归属笔记.md # 根目录下不属于任何笔记本的笔记
└── 无归属笔记.assets/
└── logo.png
```
### 3.3 笔记文件格式
每个 `.md` 文件使用 YAML Front Matter 存储元数据：
```markdown
---
id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
title: "笔记标题"
created: "2026-06-01T10:00:00.000Z"
updated: "2026-06-01T12:30:00.000Z"
tags: ["工作", "会议", "项目A"]
notebook: "笔记本A"
pinned: false
favorited: false
---
# 笔记标题
这是笔记正文内容...
```
### 3.4 附件存储设计
#### 设计原则
**每个笔记文件拥有一个同名的 `.assets/` 目录**，附件与笔记一一配对。这是 VS Code Markdown 预览和 Typora 验证过的成熟模式。
命名规则：`笔记名.md` ↔ `笔记名.assets/`
#### 存储方式
```
笔记本A/
├── 笔记1.md # 引用: ![架构图](笔记1.assets/架构图.png)
├── 笔记1.assets/ # 笔记1 的专属附件
│ ├── 架构图.png # 保留用户原始文件名
│ ├── 架构图(1).png # 同名文件自动编号
│ └── 需求文档.pdf
├── 笔记2.md
├── 笔记2.assets/
│ └── screenshot.jpg
└── 子笔记本C/
├── 笔记3.md
├── 笔记3.assets/
│ └── 流程图.png
└── ...
```
#### 文件名策略（不用 UUID）
| 场景 | 处理方式 | 示例 |
|------|----------|------|
| 首次保存 | 保留原始文件名 | `架构图.png` |
| 同名冲突 | 自动追加数字后缀 | `架构图(1).png`、`架构图(2).png` |
| 粘贴/截图 | 使用时间戳命名 | `image-20260601-143022.png` |
| 剪贴板图片 | 使用时间戳命名 | `clipboard-20260601-143022.png` |
#### 引用方式
笔记中引用附件使用**相对于自身**的路径：
```markdown
![架构图](笔记1.assets/架构图.png)
[需求文档](笔记1.assets/需求文档.pdf)
```
#### 移动笔记时的附件处理
这是本设计的核心优势——**移动笔记零成本**：
```
移动前：
笔记本A/
├── 会议纪要.md
└── 会议纪要.assets/
└── 白板照片.jpg
移动后（拖拽到笔记本B）：
笔记本B/
├── 会议纪要.md # 引用路径不变：![照片](会议纪要.assets/白板照片.jpg)
└── 会议纪要.assets/
└── 白板照片.jpg
笔记本A/
└── （干净，无残留）
```
**只需要移动两个东西**：
1. `会议纪要.md`
2. `会议纪要.assets/` 目录
引用路径 `会议纪要.assets/白板照片.jpg` 是相对于 `.md` 文件的，所以**完全不需要修改笔记内容**。
#### 重命名笔记时的附件处理
重命名笔记时自动重命名对应的 `.assets/` 目录：
```
重命名前：笔记1.md + 笔记1.assets/
重命名后：项目方案.md + 项目方案.assets/
```
同时批量替换笔记内所有 `笔记1.assets/` → `项目方案.assets/` 的引用。
#### 删除笔记时的附件处理
- 删除笔记 → `.md` 文件 + 同名 `.assets/` 目录一起移入废纸篓
- 恢复笔记 → 一起恢复
- 彻底删除 → 一起彻底删除
- 不存在孤儿附件文件
#### 对比其他方案
| 方案 | 移动笔记 | 重命名笔记 | 删除笔记 | 用户可读性 | 同步冲突 |
|------|---------|-----------|---------|-----------|---------|
| 全局附件 + UUID | 需迁移附件+改引用 | 需改引用 | 需扫描孤儿文件 | 差（UUID） | 高（大目录） |
| 每笔记本 assets | 需迁移附件+改引用 | 需改引用 | 需扫描孤儿文件 | 好 | 中 |
| **每笔记 .assets（推荐）** | **移动两个文件/目录即可** | **改目录名+批量替换引用** | **自动跟随** | **好** | **低（分散）** |
### 3.5 笔记本 vs 文件夹
- **笔记本 = 文件夹**：直接映射，用户在文件管理器中看到的结构就是应用中的结构
- 支持无限层级嵌套
- `.tunji/` 目录下的 `notebooks.json` 存储笔记本的额外元数据（颜色、图标、排序）
---
## 四、同步架构设计
### 4.1 设计原则
1. **数据库不同步**：`index.sqlite` 纯本地，同步后在本地重建
2. **版本快照不同步**：`.tunji/versions/` 纯本地
3. **配置可选同步**：`.tunji/config.json` 可选是否同步
4. **只同步用户内容**：`.md` 文件 + 同名 `.assets/` 目录 + `.tunji/tags.json` + `.tunji/notebooks.json`
### 4.2 同步抽象层
```
┌─────────────────────────────────────────┐
│ SyncManager │
│ (事件驱动，统一接口) │
├─────────────────────────────────────────┤
│ - sync() 触发全量同步 │
│ - pull() 拉取远程变更 │
│ - push() 推送本地变更 │
│ - getConflicts() 获取冲突列表 │
│ - resolve() 解决冲突 │
│ - getStatus() 同步状态 │
├──────────┬──────────┬──────────┬─────────┤
│ GitSync │WebDavSync│ S3Sync │坚果云Sync│
│ (libgit2)│(webdav) │(aws-sdk) │(webdav) │
└──────────┴──────────┴──────────┴─────────┘
```
### 4.3 同步策略
#### Git 同步
```javascript
// 策略：自动 commit + push，冲突时提示用户
// config 示例：
{
type: 'git',
repoUrl: 'https://github.com/user/notes.git',
branch: 'main', // 默认 main
autoCommit: true, // 每次变更自动 commit
autoPush: true, // 每次 commit 后自动 push
commitMessage: '{{date}} {{action}}', // 支持模板
sshKeyPath: '', // SSH 私钥路径（可选）
token: '' // HTTPS token（可选）
}
```
#### WebDAV 同步（坚果云等）
```javascript
// config 示例：
{
type: 'webdav',
serverUrl: 'https://dav.jianguoyun.com/dav/',
username: 'user@example.com',
password: 'app-specific-password', // 应用专用密码
remotePath: '/tunji-notes/', // 远程目录路径
syncInterval: 300 // 自动同步间隔（秒）
}
```
#### S3 同步
```javascript
// config 示例：
{
type: 's3',
endpoint: 'https://s3.amazonaws.com', // S3 兼容端点
bucket: 'my-notes',
accessKey: 'AKIAIOSFODNN7EXAMPLE',
secretKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
region: 'us-east-1',
prefix: 'tunji/' // 对象前缀
}
```
### 4.4 冲突解决策略
| 场景 | 策略 |
|------|------|
| 仅本地修改 | 直接推送 |
| 仅远程修改 | 直接拉取 |
| 双方都修改 | **冲突**：生成冲突副本 `笔记名(冲突-本地).md` + `笔记名(冲突-远程).md`，提示用户手动合并 |
| 本地删除 vs 远程修改 | 提示用户确认：恢复 or 确认删除 |
| 远程删除 vs 本地修改 | 提示用户确认：重新推送 or 确认删除 |
### 4.5 同步状态机
```
IDLE → SYNCING → SUCCESS
→ CONFLICT (需用户介入)
→ ERROR (网络错误等，自动重试)
```
---
## 五、本地数据库设计
### 5.1 为什么需要本地数据库
1. **全文搜索**：纯文件遍历搜索太慢，需要倒排索引
2. **元数据查询**：按标签、创建时间、更新时间等维度快速筛选
3. **排序和分页**：大量笔记的列表展示需要高效查询
4. **跨笔记本搜索**：模糊搜索需要全局索引
### 5.2 数据库选型
**better-sqlite3**（Electron 主进程）
- 纯本地，无需网络
- 同步到工作目录 `.tunji/index.sqlite`
- **不同步到远程**
### 5.3 数据库 Schema
```sql
-- 笔记索引表（从 .md 文件解析的元数据）
CREATE TABLE notes (
id TEXT PRIMARY KEY, -- UUID
title TEXT NOT NULL,
file_path TEXT NOT NULL UNIQUE, -- 相对于工作目录的路径
notebook_path TEXT, -- 所属笔记本路径
created_at TEXT, -- ISO 8601
updated_at TEXT,
pinned INTEGER DEFAULT 0,
favorited INTEGER DEFAULT 0,
word_count INTEGER DEFAULT 0,
is_deleted INTEGER DEFAULT 0 -- 软删除（废纸篓）
);
-- 标签表
CREATE TABLE tags (
id TEXT PRIMARY KEY,
name TEXT NOT NULL UNIQUE,
color TEXT -- 标签颜色
);
-- 笔记-标签关联表
CREATE TABLE note_tags (
note_id TEXT NOT NULL,
tag_id TEXT NOT NULL,
PRIMARY KEY (note_id, tag_id),
FOREIGN KEY (note_id) REFERENCES notes(id),
FOREIGN KEY (tag_id) REFERENCES tags(id)
);
-- 全文搜索虚拟表（FTS5）
CREATE VIRTUAL TABLE notes_fts USING fts5(
title,
content, -- 笔记正文（不含 front matter）
note_id UNINDEXED,
tokenize='unicode61'
);
-- 笔记本元数据表
CREATE TABLE notebooks (
path TEXT PRIMARY KEY, -- 相对于工作目录的路径
name TEXT NOT NULL,
parent_path TEXT,
color TEXT,
icon TEXT,
sort_order INTEGER DEFAULT 0
);
-- 同步状态表
CREATE TABLE sync_state (
key TEXT PRIMARY KEY,
value TEXT
);
```
### 5.4 索引重建流程
当用户在其他设备同步后打开应用，或删除了 `index.sqlite`：
```
1. 扫描工作目录下所有 .md 文件
2. 解析 front matter 元数据
3. 提取正文内容
4. 批量写入 notes 表
5. 批量写入 notes_fts 全文索引
6. 解析 tags.json，写入 tags 表
7. 建立 note_tags 关联
8. 完成，进入正常模式
```
---
## 六、版本控制与文件防丢失
### 6.1 本地版本快照（不依赖 Git）
**原理**：每次保存笔记时，将旧内容的 SHA-256 哈希作为文件名，存入 `.tunji/versions/` 目录。
```
.tunji/versions/
├── a1b2c3d4... # 笔记某次修改的内容快照
├── e5f6g7h8...
└── ...
.tunji/versions-manifest.json # 版本清单
{
"note-id-1": [
{ "hash": "a1b2c3d4...", "timestamp": "2026-06-01T10:00:00Z", "message": "自动保存" },
{ "hash": "e5f6g7h8...", "timestamp": "2026-06-01T09:30:00Z", "message": "自动保存" }
]
}
```
### 6.2 版本回退机制
```
用户点击"版本历史"
→ 读取 versions-manifest.json 获取该笔记的所有版本
→ 按时间倒序展示版本列表
→ 用户选择某个版本
→ 从 versions/<hash> 读取内容
→ 预览差异（diff view）
→ 确认回退
→ 将当前版本存为新快照（可撤销）
→ 将选中版本内容写回 .md 文件
→ 更新数据库索引
```
### 6.3 防丢失策略
| 策略 | 说明 |
|------|------|
| **自动保存** | 编辑器内容每 5 秒自动保存到 .md 文件 |
| **版本快照** | 每次保存前，旧版本自动存入 versions/ |
| **废纸篓** | 删除笔记不直接删除，移入 .tunji/trash/，保留 30 天 |
| **崩溃恢复** | Electron 主进程监听 crash 事件，编辑器状态暂存 localStorage |
| **同步前备份** | 同步拉取远程变更前，先备份本地当前版本 |
### 6.4 版本快照清理策略
- 保留最近 50 个版本
- 超过 30 天的版本，仅保留每天第一个
- 超过 90 天的版本，仅保留每周第一个
- 用户可手动清理所有历史版本
---
## 七、页面布局设计
### 7.1 整体布局
```
┌──────────────────────────────────────────────────────────┐
│ Electron Title Bar │
├──────────┬───────────────────────────────────────────────┤
│ │ │
│ LEFT │ RIGHT AREA │
│ AREA │ (Router View) │
│ │ │
│ 240- │ ┌─────────────────────────────────────────┐ │
│ 480px │ │ Notes View / Tags View / Note Detail │ │
│ 可拖拽 │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
│ │ └─────────────────────────────────────────┘ │
│ │ │
└──────────┴───────────────────────────────────────────────┘
```
### 7.2 左侧栏 (LeftArea) 详细设计
```
┌────────────────────────────┐
│ 👤 用户名称 [◀] │ ← 第一行：头像 + 名称 + 折叠按钮
├────────────────────────────┤
│ 🔍 搜索笔记... [+] │ ← 第二行：搜索框 + 新建按钮
├────────────────────────────┤
│ 📝 笔记 │ ← 第三行：Menu Item - 跳转笔记列表
├────────────────────────────┤
│ 🏷️ 标签 │ ← 第四行：Menu Item - 跳转标签页
├────────────────────────────┤
│ 📚 笔记本 │ ← 第五行：Menu Label
│ ├─ 📂 笔记本A │ ← PanelMenu：可展开/折叠
│ │ ├─ 📄 笔记1 │
│ │ ├─ 📄 笔记2 │
│ │ └─ 📂 子笔记本C │
│ │ └─ 📄 笔记3 │
│ └─ 📂 笔记本B │
│ └─ 📄 笔记4 │
│ │
│ │
│ │
├────────────────────────────┤
│ ⚙️ 设置 🗑️ 废纸篓│ ← 底部固定：设置 + 废纸篓
└────────────────────────────┘
```
#### 交互细节
- **折叠按钮**：点击后左侧栏收起为 0px 或 48px（仅显示图标），右侧区域全屏
- **搜索框**：实时搜索（debounce 300ms），结果在右侧区域展示
- **新建按钮**：点击后在当前选中的笔记本下创建新笔记（若未选中笔记本则创建在根目录）
- **笔记本 PanelMenu**：点击笔记本切换展开/折叠；点击笔记在右侧打开详情
- **拖拽调整宽度**：左侧栏右边框可拖拽，范围 240px ~ 480px
### 7.3 右侧区域 (RightArea) 路由设计
| 路由 | 视图 | 说明 |
|------|------|------|
| `/` | 首页 / 欢迎页 | 首次打开或未选中笔记时展示 |
| `/notes` | 笔记列表 | 工作目录下所有笔记，支持列表/卡片视图切换 |
| `/notes?notebook=<path>` | 笔记列表(过滤) | 指定笔记本下的笔记 |
| `/tags` | 标签列表 | 展示所有标签，点击标签查看关联笔记 |
| `/tags/:tagId` | 标签详情 | 某个标签下的所有笔记，支持列表/卡片视图 |
| `/note/:id` | 笔记详情 | 笔记编辑/预览/双栏视图 |
| `/search?q=xxx` | 搜索结果 | 全局搜索结果 |
| `/settings` | 设置页面 | 应用设置 |
| `/trash` | 废纸篓 | 已删除笔记列表 |
### 7.4 笔记详情页 (NoteDetail) 详细设计
```
┌──────────────────────────────────────────────────────────┐
│ 笔记标题（可编辑） │
├──────────────────────────────────────────────────────────┤
│ [编辑] [预览] [双栏] │ 🏷️ 标签 │ ⋯ 更多操作 │
├──────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 笔记内容区域 │ │
│ │ │ │
│ │ 支持： │ │
│ │ - Markdown 实时渲染 │ │
│ │ - 块级编辑（Typora 风格） │ │
│ │ - 拖拽移动块 │ │
│ │ - 图片粘贴 / 拖入 │ │
│ │ - 代码块高亮 │ │
│ │ - 表格编辑 │ │
│ │ - 数学公式 (KaTeX) │ │
│ │ - Mermaid 图表 │ │
│ │ │ │
│ └────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────┘
```
#### 三种视图模式
| 模式 | 说明 |
|------|------|
| **编辑模式** | 纯 Markdown 编辑（类似 VS Code） |
| **预览模式** | 纯渲染预览（只读） |
| **双栏模式** | 左侧 Markdown 源码，右侧实时预览（类似 Typora 的源码模式） |
> 注：后期实现块编辑后，默认进入"所见即所得"模式，编辑/预览/双栏作为切换选项
---
## 八、组件架构
### 8.1 核心组件树
```
App.vue
├── MainLayout
│ ├── LeftArea
│ │ ├── UserProfile # 头像 + 用户名
│ │ ├── CollapseButton # 折叠按钮
│ │ ├── SearchInput # 搜索框
│ │ ├── AddNoteButton # 新建笔记按钮
│ │ ├── MenuItem (笔记) # 路由跳转
│ │ ├── MenuItem (标签) # 路由跳转
│ │ ├── NotebookTree # 笔记本树（PanelMenu）
│ │ │ ├── NotebookNode # 笔记本节点（可展开）
│ │ │ │ ├── NoteItem # 笔记条目
│ │ │ │ └── NotebookNode # 递归嵌套
│ │ ├── SettingsLink # 设置入口
│ │ └── TrashLink # 废纸篓入口
│ │
│ ├── ResizeHandle # 拖拽调整宽度
│ │
│ └── RightArea (RouterView)
│ ├── WelcomeView # 欢迎页
│ ├── NotesListView # 笔记列表
│ │ ├── NoteCard # 卡片模式
│ │ └── NoteListItem # 列表模式
│ ├── TagsView # 标签列表
│ ├── TagDetailView # 标签详情
│ ├── NoteDetailView # 笔记详情
│ │ ├── NoteTitle # 标题编辑
│ │ ├── NoteToolbar # 操作栏
│ │ ├── NoteEditor # 编辑器
│ │ │ ├── TiptapEditor # Tiptap 编辑器实例
│ │ │ └── BlockMenu # 块操作菜单
│ │ └── NotePreview # 渲染预览
│ ├── SearchView # 搜索结果
│ ├── SettingsView # 设置页面
│ └── TrashView # 废纸篓
│
└── StatusBar # 底部状态栏（可选）
```
### 8.2 Electron 进程架构
```
┌─────────────────────────────────────────────────────────┐
│ Main Process │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ FileManager│ │ Database │ │ SyncEngine│ │
│ │ (chokidar)│ │(sqlite3) │ │ (各后端) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │
│ └──────────────┼──────────────┘ │
│ │ IPC Bridge │
├───────────────────────┼─────────────────────────────────┤
│ │ │
│ Renderer Process (Vue 3) │
│ │ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ fileStore │ │ noteStore │ │ syncStore │ │
│ │ (Pinia) │ │ (Pinia) │ │ (Pinia) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
```
### 8.3 IPC 通信接口
```javascript
// preload.js 暴露到渲染进程的 API
// 通过 contextBridge 暴露，渲染进程通过 window.tunjiAPI 调用
// 文件操作
window.tunjiAPI.file.read(filePath) // → string
window.tunjiAPI.file.write(filePath, content) // → void
window.tunjiAPI.file.delete(filePath) // → void
window.tunjiAPI.file.rename(oldPath, newPath) // → void
window.tunjiAPI.file.list(dirPath) // → FileEntry[]
window.tunjiAPI.file.watch(callback) // 监听文件变更事件
// 数据库操作
window.tunjiAPI.db.searchNotes(query) // → NoteSearchResult[]
window.tunjiAPI.db.getNotes(filter) // → NoteMeta[]
window.tunjiAPI.db.getNote(id) // → NoteMeta
window.tunjiAPI.db.updateNoteMeta(id, meta) // → void
window.tunjiAPI.db.getTags() // → Tag[]
window.tunjiAPI.db.getNotebooks() // → Notebook[]
window.tunjiAPI.db.rebuildIndex() // → void
// 同步操作
window.tunjiAPI.sync.getStatus() // → SyncStatus
window.tunjiAPI.sync.start() // → void
window.tunjiAPI.sync.configure(config) // → void
window.tunjiAPI.sync.resolveConflict(noteId, resolution) // resolution: 'local'|'remote'|'merge'
// 工作目录
window.tunjiAPI.workspace.select() // → string|null 打开目录选择对话框
window.tunjiAPI.workspace.get() // → string|null 获取当前工作目录
window.tunjiAPI.workspace.set(path) // → void 设置工作目录
// 系统
window.tunjiAPI.system.getAppVersion() // → string
window.tunjiAPI.system.getPlatform() // → string
window.tunjiAPI.system.openExternal(url) // → void
window.tunjiAPI.system.showItemInFolder(path) // → void
```
---
## 九、Pinia Store 设计
所有 Store 使用 Vue 3 Composition API 风格（`setup` 函数），纯 JavaScript。
```javascript
// stores/workspace.js - 工作目录状态
// state: { path, isReady }
// actions: selectWorkspace(), initWorkspace(path)
// stores/notes.js - 笔记状态
// state: { notes, currentNote, viewMode, filter }
// actions: fetchNotes(filter), openNote(id), createNote(notebookPath),
// deleteNote(id), saveNote(id, content)
// stores/notebooks.js - 笔记本状态
// state: { notebooks, expandedPaths }
// actions: fetchNotebooks(), toggleExpand(path), createNotebook(name, parentPath),
// renameNotebook(path, newName), deleteNotebook(path)
// stores/tags.js - 标签状态
// state: { tags }
// actions: fetchTags(), createTag(name, color), deleteTag(id),
// addTagToNote(noteId, tagId), removeTagFromNote(noteId, tagId)
// stores/sync.js - 同步状态
// state: { status, config, conflicts }
// actions: startSync(), configureSync(config), resolveConflict(noteId, resolution)
// stores/ui.js - UI 状态
// state: { leftCollapsed, leftWidth, theme }
// actions: toggleLeft(), setLeftWidth(width), setTheme(theme)
```
---
## 十、项目结构
```
tunji/
├── docs/
│ └── DESIGN.md # 本文档
│
├── electron/
│ ├── main.js # Electron 主进程入口
│ ├── preload.js # 预加载脚本（IPC 桥接）
│ ├── ipc/
│ │ ├── file.ipc.js # 文件操作 IPC 处理
│ │ ├── db.ipc.js # 数据库 IPC 处理
│ │ ├── sync.ipc.js # 同步 IPC 处理
│ │ └── workspace.ipc.js # 工作目录 IPC 处理
│ ├── services/
│ │ ├── file-manager.js # 文件管理服务
│ │ ├── database.js # SQLite 数据库服务
│ │ ├── index-builder.js # 索引构建服务
│ │ ├── version-manager.js # 版本管理服务
│ │ └── sync/
│ │ ├── sync-manager.js # 同步管理器
│ │ ├── git-sync.js # Git 同步实现
│ │ ├── webdav-sync.js # WebDAV 同步实现
│ │ └── s3-sync.js # S3 同步实现
│ └── utils/
│ ├── markdown-parser.js # Front matter 解析
│ └── file-hash.js # 文件哈希计算
│
├── src/
│ ├── App.vue # 根组件
│ ├── main.js # Vue 入口
│ ├── router/
│ │ └── index.js # 路由配置
│ ├── stores/ # Pinia 状态管理
│ │ ├── workspace.js
│ │ ├── notes.js
│ │ ├── notebooks.js
│ │ ├── tags.js
│ │ ├── sync.js
│ │ └── ui.js
│ ├── layouts/
│ │ └── MainLayout.vue # 主布局
│ ├── components/
│ │ ├── left-area/
│ │ │ ├── LeftArea.vue
│ │ │ ├── UserProfile.vue
│ │ │ ├── SearchInput.vue
│ │ │ ├── AddNoteButton.vue
│ │ │ ├── MenuItem.vue
│ │ │ ├── NotebookTree.vue
│ │ │ ├── NotebookNode.vue
│ │ │ └── NoteItem.vue
│ │ ├── right-area/
│ │ │ ├── NotesListView.vue
│ │ │ ├── NoteCard.vue
│ │ │ ├── NoteListItem.vue
│ │ │ ├── TagsView.vue
│ │ │ ├── TagDetailView.vue
│ │ │ ├── NoteDetailView.vue
│ │ │ ├── SearchView.vue
│ │ │ ├── SettingsView.vue
│ │ │ └── TrashView.vue
│ │ ├── editor/
│ │ │ ├── NoteEditor.vue
│ │ │ ├── NotePreview.vue
│ │ │ ├── TiptapEditor.vue
│ │ │ └── BlockMenu.vue
│ │ └── common/
│ │ ├── ResizeHandle.vue
│ │ ├── ViewToggle.vue # 列表/卡片视图切换
│ │ └── EmptyState.vue
│ ├── composables/
│ │ ├── useDragResize.js # 拖拽调整宽度
│ │ ├── useSearch.js # 搜索逻辑
│ │ ├── useAutoSave.js # 自动保存
│ │ └── useVersionHistory.js # 版本历史
│ └── styles/
│ ├── theme.css # 主题变量定义
│ └── tailwind.css # Tailwind 入口
│
├── index.html # HTML 入口
├── package.json
├── vite.config.js
├── tailwind.config.js
├── electron-builder.json # Electron 打包配置
└── README.md
```
---
## 十一、开发路线图
### Phase 1：基础骨架（MVP）
- [ ] Electron + Vue 3 + Vite 项目初始化
- [ ] Tailwind CSS + PrimeVue (Unstyled) 集成
- [ ] 主题色系统实现
- [ ] 工作目录选择功能
- [ ] 两栏布局 + 拖拽调整宽度
- [ ] 左侧栏基础组件
- [ ] 路由基础配置
### Phase 2：核心笔记功能
- [ ] Markdown 文件读写
- [ ] Front matter 解析
- [ ] 笔记创建 / 编辑 / 删除
- [ ] 笔记本（文件夹）管理
- [ ] Tiptap 编辑器集成
- [ ] Markdown 实时预览
### Phase 3：索引与搜索
- [ ] SQLite 数据库集成
- [ ] 笔记索引构建
- [ ] 全文搜索
- [ ] 标签系统
### Phase 4：同步功能
- [ ] 同步抽象层
- [ ] Git 同步
- [ ] WebDAV 同步
- [ ] S3 同步
- [ ] 冲突解决
### Phase 5：高级编辑
- [ ] Typora 风格块编辑
- [ ] 拖拽排序
- [ ] 图片管理
- [ ] 代码高亮
- [ ] 数学公式
- [ ] Mermaid 图表
### Phase 6：完善与优化
- [ ] 版本历史 / 回退
- [ ] 废纸篓
- [ ] 暗色模式
- [ ] 插件系统
- [ ] 性能优化
- [ ] 打包发布