# 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：完善与优化

- [ ] 版本历史 / 回退
- [ ] 废纸篓
- [ ] 暗色模式
- [ ] 插件系统
- [ ] 性能优化
- [ ] 打包发布