SyncDocs 是一款受 Google Docs 啟發、基於現代技術堆疊打造的網頁協作文件編輯器。它允許使用者即時與他人建立、編輯和共享文件。
該專案利用 Django Ninja 建構高效能的後端 API，並使用 SvelteKit 提供反應式且快速的前端使用者介面。
本專案使用 Cline 完成, 可參考 .clinerules/MVP_Development.md
後續開發使用 Claude Code 實作
即時更新
可以共用文件
可查看在線狀態以及游標位置顯示
文字摘要和潤稿
版本歷史功能
評論功能
- 即時協作：多位使用者可同時編輯同一份文件，變更會即時反映給所有參與者，由 Django Channels 提供支援。
- 游標位置顯示：即時顯示協作者的游標位置和選取範圍，使用 quill-cursors 套件實現。
- 在線狀態指示：顯示目前正在查看或編輯文件的使用者，包含用戶名稱和代表色。
- 豐富文本編輯：基於 Quill.js Delta 的核心技術結構 的簡潔直觀編輯器，支援多種格式選項。
- AI 寫作助手：整合 Google Gemini API，提供文字摘要和潤稿功能，幫助使用者提升寫作效率。
- 版本歷史：自動保存文件版本，可查看歷史紀錄並還原至先前版本。
- 評論系統：支援在文件上添加評論和回覆，評論即時同步給所有協作者。
- 使用者驗證：安全的用戶註冊和登入系統。
- 文件管理：使用者可以從個人儀表板建立、查看和管理自己的文件。
- 文件共享：輕鬆與其他使用者共享文件。
- 快速且現代化的技術堆疊：後端 API 使用 Django Ninja，前端使用 SvelteKit，確保高效能和現代化的開發體驗。
- 框架：Django 搭配 Django Ninja 建構 REST API
- 即時通訊：Django Channels 處理 WebSocket
- 資料庫：PostgreSQL（Docker 環境預設使用）
- ASGI 伺服器：Daphne（生產環境，支援 HTTP + WebSocket）
- 依賴套件：
djangodjango-ninjachannelschannels-redisgoogle-genai（AI 功能）
專案主要分為兩個目錄：
.
├── backend/ # 包含 Django 專案
│ ├── docs_app/ # 處理文件和使用者的核心 Django 應用程式
│ └── backend/ # Django 專案設定
└── frontend/ # 包含 SvelteKit 專案
├── src/
│ ├── routes/ # SvelteKit 基於檔案的路由
│ └── lib/ # Svelte 元件和工具函數請依照以下步驟在您的本機電腦上設定並執行專案。
在開始之前，請先複製環境變數範本：
# 根目錄（Docker Compose 使用）
cp .env.example .env
# 前端（SvelteKit 使用，Docker 和本地開發都需要）
cp frontend/.env.example frontend/.env注意：
.env檔案包含敏感資訊，已加入.gitignore，不會被提交到版本控制。
本專案使用 Docker Compose 的 override 機制 區分開發與生產環境：
docker-compose.yml— 基礎配置（後端使用 Daphne ASGI 伺服器）docker-compose.override.yml— 開發覆蓋（後端改用 runserver + volume mount 支援熱重載）
# 開發環境（自動載入 override，使用 runserver，支援熱重載）
docker compose up --build
# 生產環境（僅用基礎配置，使用 Daphne）
docker compose -f docker-compose.yml up -d注意：生產部署需建立
.env檔案，提供DJANGO_SECRET_KEY、POSTGRES_PASSWORD、DJANGO_ALLOWED_HOSTS、CORS_ALLOWED_ORIGINS等必要變數。
Docker 環境變數說明：
- 根目錄
.env→ Docker Compose 讀取 → 注入到 backend container frontend/.env→ 掛載到 container → SvelteKit 直接讀取
⚠️ 注意：本地開發需要自行安裝並啟動 PostgreSQL 和 Redis 服務。
# 前往 backend 目錄
cd backend
# 建立並啟用虛擬環境
python -m venv venv
source venv/bin/activate # Windows 請使用 `venv\Scripts\activate`
# 安裝 Python 依賴套件
pip install -r requirements.txt
# 套用資料庫遷移
python manage.py migrate
# 啟動 Django 開發伺服器
# API 將可在 http://127.0.0.1:8000 取得
python manage.py runserver後端環境變數說明：
本地開發時，Django 會使用 settings.py 中的預設值：
- 預設連接
django-postgres:5432（適合 Docker） - 本地開發需修改
POSTGRES_HOST=localhost
可用的環境變數請參考 backend/.env.example。
開啟一個新的終端機視窗。
# 前往 frontend 目錄
cd frontend
# 複製環境變數範本（如果還沒做的話）
cp .env.example .env
# 安裝 Node.js 依賴套件
npm install
# 啟動 SvelteKit 開發伺服器
# 前端將可在 http://localhost:5173 取得
npm run dev -- --open前端環境變數說明：
frontend/.env 必須存在，SvelteKit 會直接讀取此檔案：
PUBLIC_API_URL=http://127.0.0.1:8000PUBLIC_前綴的變數會暴露給客戶端- 修改後需重新啟動開發伺服器
- 前端：開啟瀏覽器並前往
http://localhost:5173。 - 後端 API 文件：自動產生的 API 文件可在
http://127.0.0.1:8000/api/docs取得。
後端 API 使用 Django Ninja 建構，它提供自動化的互動式文件 http://127.0.0.1:8000/api/docs
使用 Docker 運行測試
docker compose --profile testing up在本地運行測試
pytest --cov=. --cov-report=html
本專案作為教學示範項目，提供完整的學習文檔幫助你理解系統設計和實作細節：
-
- 📋 6 個階段的循序漸進學習計畫
- 🎯 每個階段的檢查點和實作練習
- 💡 關鍵代碼的詳細解釋和教學註釋
- ⏱️ 預計學習時間：15-20 天
- 🎓 適合：全端開發初學者、想學習即時協作功能的開發者
-
- 🎨 完整的系統架構圖和數據流程圖
- 🤔 技術選型理由和對比分析
- 🎭 設計模式的實際應用（Repository、Observer、Middleware...）
- 🔐 安全性設計和效能優化策略
- 📊 架構決策記錄 (ADR)
- 🎓 適合：中級開發者、架構師、面試準備
-
⚙️ Quill.js Delta 核心技術 (Delta.md)
- 🔍 深入理解 Delta 資料模型
- 💡 為什麼選擇 Delta 而非 HTML
- 🤝 Delta 如何支援即時協作
- 🎓 適合：想理解富文本編輯器原理的開發者
- 📋 MVP 開發清單 (.clinerules/MVP_Development.md)
- 完整的開發階段規劃
- 前後端功能清單
- 🎯 初學者：Delta.md → LEARNING_PATH.md（跟著步驟學習）
- 🏗️ 有經驗的開發者：ARCHITECTURE.md → LEARNING_PATH.md（選擇性深入）
- 👨🏫 教師/講師：ARCHITECTURE.md（課程大綱）+ LEARNING_PATH.md（教學進度）
此專案為 MVP (最小可行性產品)，尚有許多改進空間。以下是一些未來可能的功能：
- 資料夾組織：實作資料夾系統以更好地管理文件。
- 部署：使用 Nginx 反向代理搭配現有的 Daphne ASGI 伺服器，建立更完整的生產部署設定。
- 全面測試：新增更多單元測試和端對端測試以確保穩定性。
文章都是我自己研究內化後原創，如果有幫助到您，也想鼓勵我的話，歡迎請我喝一杯咖啡 😆
綠界科技ECPAY ( 不需註冊會員 )
歐付寶 ( 需註冊會員 )
MIT license