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

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

1. 背景

Notion 好用，但兩個痛點：

要訂閱付費
功能唔啱心水（語音輸入、自訂 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. 整體架構

整體架構

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 雙格式方案

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

語音板工作流程

插入邏輯：文字插喺游標位置，包一層可 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）

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

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

7. 資料模型（簡化）

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. 里程碑

里程碑路線圖

里程碑	內容	粗估
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 留到正式化。

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