# Tbook（暫定名）· 自製雲端筆記 Web App 設計文件

> 版本 v0.1（草案）· 2026-10-18 · 狀態：待審閱
> 定位：免費、自控、Notion 風格的雲端筆記系統（個人使用優先）

---

## 1. 背景

Notion 好用，但兩個痛點：

1. **要訂閱付費**
2. **功能唔啱心水**（語音輸入、自訂 AI、MD/HTML 雙格式等想自己加）

目標：做一個自己全權控制、零訂閱費嘅 Notion-like web app，並加入自己想加嘅功能（語音板、AI、雙格式）。

## 2. 目標 / 非目標

**目標（MVP 範圍內）**

- Web app 形式，需登入使用
- Notion 風格 UI（左側邊欄 + 區塊化頁面）
- 筆記上雲端，任何裝置開瀏覽器即可存取
- Markdown 為主格式，**同時探索 HTML 支援**（雙格式）
- 語音輸入面板（語音 → 文字，插入筆記）
- AI 功能：文字輔助、圖片生成、語音轉文字

**非目標（暫時唔做）**

- 行動原生 App（先做 PWA，可安裝）
- 多人即時協作（CRDT 留到後期）
- 團隊權限管理（個人 workspace 為先）

## 3. 需求清單

| # | 需求 | 說明 | 優先級 |
|---|------|------|--------|
| R1 | 登入 | 帳號系統，註冊/登入 | P0 |
| R2 | 雲端 | 筆記上雲，瀏覽器存取，自動儲存 | P0 |
| R3 | Web app | 純 web 形式（PWA 加分） | P0 |
| R4 | Notion 風格 UI | 側邊欄 + 區塊編輯 + slash menu | P0 |
| R5 | Markdown | 主要文件格式，可匯入/匯出 .md | P0 |
| R6 | HTML | 亦支援 HTML（手打方便），探索雙格式同時支援嘅方式 | P1 |
| R7 | 語音板 | 語音輸入面板，喺部電腦嘅瀏覽器內測試可用 | P1 |
| R8 | AI | 文字輔助、圖片生成、語音轉文字 | P2 |
| R9 | 內容遷移 | 將現有自己做嘅嘢（筆記/作品）搬入新 app | P2 |

## 4. 整體架構

![整體架構](diagrams/architecture.svg)

## 5. 技術棧（建議）

| 層 | 建議 | 備選 | 理由 |
|---|------|------|------|
| 前端 | Next.js + React + TypeScript | Vite + React | API routes 一鍋端、SSR、部署簡單 |
| 編輯器 | Tiptap（ProseMirror 核心） | BlockNote、CodeMirror 6 | 區塊式 WYSIWYG 最似 Notion；原生支援 MD/HTML 匯入匯出 |
| 資料庫 | PostgreSQL | SQLite（MVP 可先简化） | 結構化資料 + 全文搜尋 |
| 認證 | Email + 密碼（Argon2id）+ JWT（httpOnly cookie） | Better Auth / Supabase Auth | 零依賴、自控 |
| 檔案 | MinIO（S3 協議） | 本地磁碟 + 靜態伺服 | S3 協議日後遷移容易 |
| STT | faster-whisper（自託管） | OpenAI Whisper API、Web Speech API | 粵語準確度好、可離線、無按字計費 |
| AI | Provider 抽象層（OpenAI / Anthropic / Ollama / 本地 SD） | — | 用家可自帶 key，成本自控 |
| 部署 | Docker Compose（next + postgres + minio） | VPS / 家用伺服器 | 一鍵部署、搬遷容易 |

> 成本角度：全部自託管 = 只係電費/伺服器錢，AI API 先係唯一變數（可用本地模型壓低）。

## 6. 關鍵功能設計

### 6.1 登入

- Email + 密碼註冊/登入；密碼 Argon2id hash
- JWT 雙 token：access（15 分鐘）+ refresh（30 日），httpOnly cookie 存放
- 忘記密碼：email reset link
- v2：GitHub / Google OAuth

### 6.2 雲端儲存與同步

- 前端 debounce 1–2 秒自動儲存 → `PUT /notes/:id`
- 歷史版本：每次儲存留 snapshot（MVP 先留最近 50 版）
- MVP：單裝置「雲端儲存」模式
- v2：Yjs CRDT + WebSocket 多裝置即時同步（Tiptap 有原生 collab 擴充，成本低）

### 6.3 編輯器：Markdown + HTML 雙格式（重點探索）

**Plan A · JSON 文件為單一事實來源（進階，最終形態）**

- 用 Tiptap 區塊編輯器，內部存 JSON 文件
- MD / HTML 只係同一文件嘅兩種**檢視**：匯入（.md / .html）＋匯出（.md / .html）
- ✅ WYSIWYG 體驗最好；兩格式自然雙向；AI 理解結構容易
- ❌ 學習曲線較陡

**Plan B · 每篇筆記標記單一格式（簡單，MVP 建議）**

- `notes.format = 'markdown' | 'html'`
- MD 筆記：Tiptap WYSIWYG 編輯
- HTML 筆記：CodeMirror 6 手打 + iframe sandbox 即時預覽
- ✅ 實作快；「同時支援 MD 同 HTML」即刻成立（每篇各選一種）
- ❌ 兩種編輯體驗唔統一；單一筆記唔可以混合

**Plan C · Markdown 為單一來源**

- 存 raw MD，編輯器係 code editor + 預覽
- 容許 MD 內嵌 HTML block（要 sanitize）
- ✅ 最簡單、最 portable
- ❌ WYSIWYG 弱、HTML 混排有安全風險

**建議路線：M1/M2 用 Plan B 快速落地 → M4 之後遷移 Plan A。**
Tiptap 本身有 MD/HTML serializer，Plan B 嘅 MD 筆記內容可以直接過檔，遷移成本可控。

![MD / HTML 雙格式方案](diagrams/dual-format.svg)

**HTML 安全措施：**

- 預覽用 `<iframe sandbox>`（null origin，必要時 allow-scripts）
- 匯入時 DOMPurify 清洗
- 唔信任任何第三方資源（CSP 限制）

### 6.4 語音板

**UI**：編輯器右側浮動按鈕 → 彈出小面板

- 狀態：待命 / 錄音中（波幅 + 計時）/ 轉寫預覽
- 動作：開始、暫停、停止、**插入游標處**、捨棄
- 可選：即時上線顯示（streaming）或錄完先轉寫

**引擎（兩套並存，可切換）**

| 引擎 | 實作 | 优点 | 缺點 |
|---|---|---|---|
| 瀏覽器引擎（MVP） | Web Speech API（Chrome） | 零成本、即刻有、即時上線 | 僅 Chrome；離線差；粵語準確度中等 |
| 伺服器引擎（v2） | MediaRecorder 錄 .webm → faster-whisper（`yue` 模型） | 粵語準確、可離線、無按字計費 | 要等錄完、伺服器要有 CPU/GPU |

![語音板工作流程](diagrams/voice-flow.svg)

- 插入邏輯：文字插喺游標位置，包一層可 undo 嘅 transaction
- 測試範圍（R7）：本機 Chrome + 呢個 web app，粵語/普通話/英文各測一次，記錄準確度

### 6.5 AI 功能

統一 AI 閘道（`/ai/*`），provider 抽象：

| 功能 | 實作 | 備註 |
|---|------|------|
| 文字輔助 | LLM（續寫/摘要/翻譯/改寫） | 選定段落 + 指令 → 結果可插入 |
| 圖片生成 | DALL-E / FLUX / SD API 或本地 ComfyUI | 結果存 attachments，插入圖片 block |
| 語音轉文字 | STT（見 6.4） | |

設計原則：

- **用家自帶 API key**（或伺服器端共用 key），成本透明（每次調用記錄 `ai_jobs`）
- 本地模型（Ollama / 本地 SD）作免費 fallback
- AI 結果一律先預覽、人手確認先插入（唔自動改動筆記）

### 6.6 UI（Notion 風格）

![UI 概念圖（Notion 風格 wireframe）](diagrams/ui-mockup.svg)

> 🖥 **可互動模擬介面（審閱用）**：<https://5211.qrhk.app/mockup/> — 試吓側邊欄切頁、`/` 斜線選單、🎤 語音板、⌘K 搜尋、深色模式。UI 確認後先開 M0 執行。

- **左側**：workspace 側邊欄 → 筆記樹（可拖曳排序）、搜尋、標籤
- **中央**：頁面 = 封面（可選）+ 標題 + blocks（標題/文字/清單/代碼/圖片/表格/分割線）
- **右側（可選）**：屬性 / TOC
- 互動：`/` slash menu、鍵盤 shortcut、`[]` 選區浮動選單
- 深色模式、PWA manifest（可安裝到桌面，接近原生體驗）

## 7. 資料模型（簡化）

```sql
users(
  id UUID PK, email TEXT UNIQUE, password_hash TEXT,
  created_at TIMESTAMPTZ
)

notes(
  id UUID PK,
  user_id UUID REFERENCES users(id),
  parent_id UUID NULL REFERENCES notes(id),  -- 樹結構
  title TEXT,
  format TEXT CHECK (format IN ('md','html','block')),  -- Plan B → A 過渡
  content TEXT,        -- raw MD 或 raw HTML
  doc_json JSONB,      -- Plan A：Tiptap 文件
  position INT,        -- 排序
  updated_at TIMESTAMPTZ, created_at TIMESTAMPTZ
)

attachments(
  id UUID PK, note_id UUID, user_id UUID,
  filename TEXT, url TEXT, mime TEXT, size INT,
  created_at TIMESTAMPTZ
)

note_versions(
  id UUID PK, note_id UUID, content TEXT, doc_json JSONB,
  created_at TIMESTAMPTZ
)

ai_jobs(
  id UUID PK, user_id UUID, kind TEXT,  -- 'transcribe'|'chat'|'image'
  provider TEXT, input_ref TEXT, result_ref TEXT,
  cost NUMERIC, created_at TIMESTAMPTZ
)
```

## 8. API（MVP）

```
POST   /auth/register          註冊
POST   /auth/login             登入
POST   /auth/refresh           刷新 token

GET    /notes?parent=          列出（樹）
POST   /notes                  建立
GET    /notes/:id              詳情（含 content）
PUT    /notes/:id              儲存（含 format/content）
PATCH  /notes/:id/move         移動/排序
DELETE /notes/:id              刪除（軟刪 → 30 日回收站）
POST   /notes/:id/import       匯入 .md / .html
GET    /notes/:id/export?fmt=  匯出 md | html

POST   /upload                 附件上傳
GET    /files/:id              附件下載

POST   /ai/transcribe          語音 → 文字（multipart audio）
POST   /ai/chat                文字輔助
POST   /ai/image               圖片生成
```

## 9. 里程碑

![里程碑路線圖](diagrams/milestones.svg)

| 里程碑 | 內容 | 粗估 |
|---|------|------|
| **M0** | 倉庫 scaffold（Next.js + Postgres + Docker）＋ 登入/註冊 ＋ 筆記樹 CRUD | 1 週 |
| **M1** | MD 編輯器（Tiptap）＋ 自動儲存 ＋ .md 匯入/匯出 | 1 週 |
| **M2** | HTML 雙格式（CodeMirror + sandbox 預覽 + .html 匯入/匯出） | 3–5 日 |
| **M3** | 語音板（Web Speech API 先行，粵語測試） | 3–5 日 |
| **M4** | AI 閘道（文字輔助 + 圖片生成）；開始 Plan A 遷移評估 | 1 週 |
| **M5** | faster-whisper 自託管引擎、歷史版本、PWA 打磨、內容遷移工具 | 持續 |
| **M6** | Yjs 即時同步、行動端體驗 | 後期 |

## 10. 風險與待決定

| # | 問題 | 影響 | 建議 |
|---|------|------|------|
| Q1 | **部署喺邊？**（家用伺服器 / VPS？） | 決定 domain、HTTPS、公網 IP、成本 | 待你確認；M0 前定好 |
| Q2 | **粵語準確度係咪硬需求？** | 係 → 語音板直接上 Whisper（`yue`）；唔係 → Web Speech API 先 | 建議 M3 兩套都測一次先決定 |
| Q3 | AI 費用上限？ | 圖片生成較貴 | 用家自帶 key + 每次調用記錄成本；本地模型 fallback |
| Q4 | 現有內容格式係咩？（Notion 匯出 / MD 檔案 / 其他） | 決定匯入工具設計（R9） | 你話我知格式，M5 做對應 importer |
| Q5 | MD ↔ HTML 雙向轉換損耗 | 複雜 block（表格/嵌入）轉換可能失細節 | 匯入/匯出要一組測試用例；Plan A 可以徹底解決 |
| Q6 | 單人用定多人用？ | 影響權限系統複雜度 | 目前按「個人 workspace、多裝置」設計 |

## 11. 下一步

> ✅ **2026-10-18 更新**：Prototype v0.1 已部署 — <https://5211.qrhk.app/>（landing + 登入 + 筆記 CRUD，手機/桌面響應式）。
> 設計文件：<https://5211.qrhk.app/plan.html> ｜ 模擬介面：<https://5211.qrhk.app/mockup/>
> 代碼位置：`~/server/running/tbook/`。技術棧由 Next.js + Postgres 簡化做 **Node 24 + 內建 SQLite（零依賴）**，Postgres 留到正式化。

1. 審閱 prototype：建/改/刪筆記、匯出 .md、深色模式、用 iPhone 試一試
2. 你確認 Q1/Q2（部署環境、語音引擎優先級）
3. M1：強化編輯 — 待辦 block、表格 block、圖片上傳、拖曳排序
4. M3 前置：語音板 30 分鐘 POC（Web Speech API 錄粵語，睇準確度）