diff --git a/README.md b/README.md index c6f4e1d..8943e1d 100644 --- a/README.md +++ b/README.md @@ -23,5 +23,301 @@ uv(python 3.13) - [ ] 網站設定（如網站名稱、網站描述、網站logo等） - [ ] 自動導覽列模組（根據頁面名稱自動生成導覽列） +- [ ] 電子報設計功能 + # 招募貢獻 -目前還在開發中，歡迎有興趣的開發者一起參與開發，可以[來信](mailto:hi@l.nudoragon.com)跟我說！ \ No newline at end of file +目前還在開發中，歡迎有興趣的開發者一起參與開發，可以[來信](mailto:hi@l.nudoragon.com)跟我說！ + + + +## 📋 **分步計畫架構** + +根據你的需求，我建議將開發分為 **5 個優先級階段**，共 1-2 個月： + +### **Phase 1️⃣：網站核心功能（第 1-2 週）** +✨ 對標 Google Sites 的基礎管理功能 + +**步驟：** +1. **網站設定模組** — 獨立儀表板頁面，支援編輯「網站名稱、描述、Logo、主色、favicon」 + - 儲存到 `project.json` 擴展結構 + - 前端：新增 `/dashboard/project-settings` 路由 + +2. **檔案管理系統** — 統一的媒體資源管理 + - 改進現有 `upload.php` → 遷移到 Flask + - 支援資料夾分類上傳 + - 圖片預覽 + 刪除功能 + +3. **頁面組織改進** — 支援頁面群組和排序 + - 在 `project.json` 新增「頁面樹狀結構」和「頁面順序」 + - 編輯器面板顯示頁面層級關係 + +**相關文件**： +- main.py — 擴展 `/api/projects//settings` 端點 +- dashboard.html — 新增設定頁面 +- my-editor.js — 更新檔案管理器 + +**依賴**: 無 | **驗證**: ✅ 能建立和編輯網站基本資訊 + +Phase 1：檔案管理優化 +API 端點：POST /api/projects//media/upload +圖片預覽和刪除 +自動生成縮圖 +本地圖片上傳結構： +websites/ + └─ my-website/ + └─ media/ + ├─ 2026-05/ + │ ├─ banner.jpg + │ └─ thumbnail.png + └─ index.json (圖片元數據：上傳時間、大小、alt文本) + +--- + +### **Phase 2️⃣：自動導覽列模組（第 2-3 週）** +🧭 根據頁面結構自動生成 + +**步驟：** +1. **導覽列配置系統** — 支援多種模式 + - 模式 A：自動（頁面層級自動生成） + - 模式 B：手動（拖拽排序選擇） + - 模式 C：混合（自動+手動覆蓋） + +2. **導覽列組件化** — 建立可拖拽的導覽列編輯UI + - 在 `project.json` 儲存導覽結構 + - 前端：建立可視化編輯器（拖拽排序、新增/刪除項目） + +3. **導覽列注入** — 自動將導覽列代碼注入所有頁面 + - 建立 HTML 範本 (`_navbar.html`) + - 編輯器保存時自動合併（防止重複注入） + +**相關文件**： +- main.py — 新增 `/api/projects//navbar` 端點 +- templates — 新增導覽列管理頁面 +- Vvvebjs — 建立導覽列組件庫 + +**依賴**: 依賴 Phase 1 | **驗證**: ✅ 導覽列在所有頁面正確顯示和更新 + +--- + +### **Phase 3️⃣：部落格模組基礎（第 3-4 週）** +📰 文章列表、分類、存檔 + +**步驟：** +1. **部落格資料模型** — 擴展頁面結構 + - 新增文章元數據：`title`, `date`, `category`, `tags`, `excerpt`, `author` + - 儲存位置：`websites//blog/posts/` 下的 `post.json` + `post.html` + +2. **文章管理 API** — 專用的部落格 CRUD 端點 + - `POST /api/projects//blog/posts` — 建立文章 + - `GET /api/projects//blog/posts?category=xxx` — 篩選 + - 支援日期排序、分類篩選 + +3. **部落格頁面範本** — 自動生成部落格首頁 + - 文章列表（含摘要） + - 分類側邊欄 + - 存檔面板（按月份） + +4. **前端整合** — 編輯器新增「部落格」編輯模式 + - 部落格文章編輯表單（填充元數據） + - 預覽實時更新 + +**相關文件**： +- main.py — 新增 `/api/projects//blog/*` 端點 +- `templates/blog-editor.html` — 新增部落格編輯頁面 +- blog — 參考範本 + +**依賴**: 依賴 Phase 1 | **驗證**: ✅ 能建立/編輯/分類文章，自動生成列表 + + +Phase 3：部落格文件組織 +搜尋策略： + +啟動時掃描所有 post.json，建立內存索引 +簡單全文搜尋（title + excerpt 關鍵詞匹配） +快取文章索引（5 分鐘更新一次） +websites/my-website/ + └─ blog/ + ├─ posts/ + │ ├─ 2026-05-20-first-post/ + │ │ ├─ post.json {title, date, category, tags, author, excerpt} + │ │ └─ index.html {完整文章內容} + │ └─ 2026-05-19-second-post/ + ├─ categories.json {category_name: count} + └─ index.json {最後更新時間、文章總數} + +--- + +### **Phase 4️⃣：進階部落格功能（第 4-5 週）** +💬 評論、標籤、RSS + +**步驟：** +1. **評論系統** — 支援簡單評論（可選認證） + - 後端：`comments/` 資料夾儲存評論 JSON + - 前端：評論表單 + 列表顯示 + - 可選垃圾過濾（簡單關鍵詞檢查） + +2. **標籤系統** — 完整的標籤索引 + - `tags/` 頁面自動生成（顯示所有標籤及文章計數） + - 支援標籤雲視覺化 + +3. **RSS 源** — 自動生成 RSS feed + - `GET /sites//blog/feed.xml` — 最新 N 篇文章 + - 支援類別篩選 RSS + +4. **搜尋功能** — 部落格內搜尋 + - 簡單全文搜尋（Python 端搜尋文章標題/內容） + - 前端搜尋表單 + +**相關文件**： +- main.py — 新增 RSS 端點、評論端點、搜尋端點 +- templates — 評論表單、搜尋結果頁面 +- 新增 `utils/rss_generator.py` — RSS 生成工具 + +**依賴**: 依賴 Phase 3 | **驗證**: ✅ RSS 訂閱有效，評論顯示正確，搜尋功能工作 + +Phase 4：評論和垃圾過濾 +垃圾過濾（基礎）： + +檢查過多連結（>3 個 URL = 高風險） +大寫字母比例（>70% = 可疑） +黑名單關鍵詞 +評論長度限制（最多 5000 字） +websites/my-website/blog/posts/2026-05-20-first-post/ + └─ comments.json + [ + { + "id": "uuid", + "author": "name", + "email": "test@example.com", + "content": "Great article!", + "timestamp": "2026-05-20T10:30:00", + "spam_score": 0.1 // 簡單評分 + } + ] + +--- + +### **Phase 5️⃣：簡易認證 + 共享機制（第 5-6 週）** +🔐 社團成員協作與角色管理 + +**步驟：** +1. **簡易認證系統** — 輕量級密碼保護 + - 後端：管理員密碼 + session token + - 可選：CSV 匯入成員清單（每人隨機密碼） + +2. **角色與權限** — 基於角色的訪問控制 + - 角色：管理員（完全控制）、編輯者（編輯頁面）、查看者（只讀） + - 儲存在 `project.json` 的 `members` 陣列 + +3. **共享邀請** — 簡單的邀請機制 + - 產生邀請連結（有效期 7 天） + - 訪客可透過邀請連結加入 + +4. **審計日誌** — 追蹤編輯歷史 + - 簡單版本控制：記錄每次保存的「時間、使用者、變更內容」 + - 前端：「版本歷史」側邊欄，支援回溯預覽 + +**相關文件**： +- main.py — 認證中介軟體、權限檢查 +- main.py — 新增 `/api/auth/*` 端點（登入、邀請、成員管理） +- `templates/login.html`, `members.html` — 新增認證頁面 +- `utils/audit.py` — 審計日誌工具 + +**依賴**: 依賴 Phase 1 | **驗證**: ✅ 能登入、邀請成員、檢視版本歷史 + +Phase 5：審計日誌與版本 Diff +Diff 工具： + +使用 Python difflib 對 HTML 進行行級比較 +前端顯示「並排對比」或「高亮改變」 +支援「回復到此版本」功能 +websites/my-website/ + └─ .audits/ + ├─ 2026-05-20-10-30-00-user1-edit.json + │ { + │ "timestamp": "...", + │ "user": "user1", + │ "action": "edit", + │ "page": "index.html", + │ "diff_type": "html_diff", + │ "diff": [ + │ {"type": "unchanged", "content": "..."}, + │ {"type": "added", "content": "

New Title

"}, + │ {"type": "removed", "content": "

Old Title

"} + │ ], + │ "full_hash": "sha256:abc123..." + │ } + └─ index.json {版本清單} + + +--- + +### **Phase 6️⃣：部署與進階功能（第 6-8 週）** +🚀 自託管選項、進階範本、國際化 + +**步驟：** +1. **部署支援包** — Docker 容器化 + 部署指南 + - 編寫 `Dockerfile` 最佳實踐 + - 提供 `docker-compose.yml` 配置 + - 支援環境變數配置（資料庫、CDN URL） + +2. **進階範本庫** — 20+ 預設網站模板 + - 行業模板（餐廳、工作室、社群、新聞） + - 一鍵部署模板到新專案 + +3. **SEO 最佳化** — 後設資料管理 + - 每頁支援 title、description、og tags + - 自動 sitemap 生成 + - 結構化資料（JSON-LD） + +4. **完整國際化** — i18n 支援 + - 多語言界面（至少：繁體中文、English） + - 前端翻譯系統 + +**相關文件**： +- `Dockerfile`, `docker-compose.yml` — 容器化 +- 新增 `templates/templates/` — 範本庫管理 +- 新增 `utils/seo.py`, `utils/i18n.py` — SEO 和翻譯工具 + +**依賴**: 依賴 Phase 1 | **驗證**: ✅ 可用 Docker 快速啟動，能選擇範本，多語言切換正常 + +--- + +## 🎯 **實施優先級與並行工作** + +| 週次 | 主要任務 | 平行工作 | 完成指標 | +|-----|--------|--------|--------| +| W1-2 | Phase 1：網站設定、檔案管理 | — | 可編輯網站基本資訊 | +| W2-3 | Phase 2：自動導覽列 | 回顧 Phase 1 | 所有頁面有正確導覽列 | +| W3-4 | Phase 3：部落格基礎 | 準備 Phase 4 元素 | 能發佈文章、自動生成列表 | +| W4-5 | Phase 4：評論、RSS、搜尋 | — | RSS 訂閱、評論、搜尋可用 | +| W5-6 | Phase 5：簡易認證、邀請 | 進行 Phase 6 規劃 | 能登入、邀請成員、檢視版本 | +| W6-8 | Phase 6：部署、範本、SEO | 用戶測試 | Docker 快速部署、支援多語言 | + +--- + +## 🤔 **需要你決定的事項** + +1. **部落格存儲方案** + V- 方案 A：純文件系統 (JSON + HTML) — 簡單但搜尋效能差 + - 方案 B：SQLite 資料庫 — 更好的搜尋和篩選 + - 方案 C：混合 — 快取 + 搜尋索引 + +2. **評論審核** + V- 開放所有評論？ + - 需要管理員審核？ + - 支援評論回覆線程？ + +3. **圖片儲存** + V- 本地檔案系統？ + - 外部 CDN（如 Cloudinary）？ + - S3 相容服務？ + +4. **版本控制深度** + - 簡單版本記錄（時間、使用者）？ + V- 完整 diff（顯示改變內容）？ + - Git 整合？ + +--- + +**你對這個計畫有什麼想法？** 需要調整優先級或合併某些階段嗎？ \ No newline at end of file diff --git a/docs/phase1.md b/docs/phase1.md new file mode 100644 index 0000000..5e41f33 --- /dev/null +++ b/docs/phase1.md @@ -0,0 +1,369 @@ + + +## 📋 **Plan: Phase 1 詳細實施方案** + +根據所有決定，以下是完整的 Phase 1 規劃： + +--- + +## **🎯 Phase 1 三大核心模組** + +### **1️⃣ 網站設定模組（Project Settings）** + +**數據結構** — 擴展 `project.json`： +```json +{ + "name": "My Website", + "slug": "my-website", + "description": "社團網站", + "created_at": "2026-05-20T10:00:00", + "updated_at": "2026-05-26T15:30:00", + + "settings": { + "title": "社團官網", + "subtitle": "歡迎來到我們的社團", + "logo_url": "/sites/my-website/media/logo.png", + "favicon_url": "/sites/my-website/media/favicon.ico", + "primary_color": "#007bff", + "secondary_color": "#6c757d", + "description": "關於我們的社團", + "keywords": "社團,網站", + "author": "社團名稱" + }, + + "pages_order": ["index.html", "about.html", "contact.html"], + "navbar_enabled": false, + "blog_enabled": false +} +``` + +**後端 API 端點**： +- `GET /api/projects//settings` — 獲取網站設定 +- `PUT /api/projects//settings` — 更新網站設定 +- `POST /api/projects//settings/logo` — 上傳 Logo（轉向媒體管理） +- `POST /api/projects//settings/favicon` — 上傳 Favicon + +**前端介面（兩個位置）**： + +**位置 A：儀表板** — dashboard.html 新增設定標籤 +```html +
+ + + + +
+ +
+
+ + + + +
+
+``` + +**位置 B：編輯器快速存取** — editor.html 右上方快速菜單 +```html + + +``` + +**依賴**: 無 | **相關改動**: +- main.py — 新增 `/api/projects//settings` 兩個端點 +- dashboard.html — 新增「網站設定」標籤頁 +- my-editor.js — 快速設定面板 + +--- + +### **2️⃣ 檔案管理系統（Media Manager）** + +**本地文件結構** — 圖片存儲在專案下： +``` +websites/my-website/ +├─ project.json +├─ index.html +├─ about.html +├─ media/ +│ ├─ images/ +│ │ ├─ 2026-05/ +│ │ │ ├─ banner.jpg (上傳時間組織) +│ │ │ ├─ banner-thumb.jpg (自動生成縮圖) +│ │ │ └─ thumbnail.png +│ │ └─ 2026-06/ +│ ├─ uploads.json (元數據索引) +│ └─ .gitkeep +``` + +**後端 API 端點**： +- `POST /api/projects//media/upload` — 上傳圖片 + - 接受：jpg, png, gif, webp, svg + - 限制：單檔 2MB，自動生成縮圖 + - 返回：`{filename, url, thumb_url, size, upload_time}` + +- `GET /api/projects//media/list` — 列出所有媒體 + - 返回：`[{filename, url, thumb_url, size, upload_time}, ...]` + +- `DELETE /api/projects//media/` — 刪除媒體 + +**前端介面** — 儀表板媒體庫頁籤： +```html +
+ +
+ 拖放圖片到此或 +
+ + +
+ +
+ +
+

banner.jpg

+

152 KB • 2026-05-20

+
+ + +
+
+
+
+
+``` + +**依賴**: 依賴 1（網站設定先完成） | **相關改動**: +- main.py — 新增 `/api/projects//media/*` 三個端點 +- 新增 utils/media_manager.py — 媒體上傳、縮圖生成、驗證 +- dashboard.html — 新增媒體庫頁籤 +- my-editor.js — 拖拽上傳邏輯、網格展示 + +**技術細節**： +```python +# 縮圖生成邏輯（Pillow） +from PIL import Image +original = Image.open(file) +original.thumbnail((300, 300)) +original.save(thumb_path) + +# 檔名安全化 +import uuid +safe_filename = f"{uuid.uuid4()}_{secure_filename(original_name)}" +``` + +--- + +### **3️⃣ 頁面組織改進（Page Organization）** + +**數據結構** — 在 `project.json` 中新增頁面樹狀結構和排序： +```json +{ + "page_tree": { + "root": [ + {"name": "index.html", "title": "首頁", "order": 0}, + { + "name": "about", + "title": "關於我們", + "order": 1, + "children": [ + {"name": "about.html", "title": "簡介", "order": 0}, + {"name": "team.html", "title": "成員", "order": 1} + ] + }, + {"name": "contact.html", "title": "聯絡", "order": 2} + ] + } +} +``` + +**頁面層級規則** — 按資料夾深度自動決定（如決定 5）： +``` +index.html → Level 0（根） +about.html → Level 0（根） +services/ → Level 1（資料夾） + consulting.html → Level 2（子頁面） +team/operations/ → Level 2（嵌套資料夾） + manager.html → Level 3（子子頁面） +``` + +**後端 API 端點**： +- `GET /api/projects//pages-tree` — 獲取頁面樹狀結構 +- `PUT /api/projects//pages-tree` — 更新頁面順序和層級 +- `POST /api/projects//pages//reorder` — 移動頁面 + +**前端介面** — 編輯器左側面板改進： +```html +
+
+ +
+ 📁 + 根目錄 +
    +
  • + 📄 + 首頁 (index.html) +
    + + + +
    +
    • + +
  • + ▼ + 📁 + services/ + +
    • +
+
+
+ + +
+ + + +
+
+``` + +**排序邏輯**： +- **字母排序**: 遞歸排序每層頁面 +- **修改時間**: 按 `updated_at` 時間戳排序 +- **自訂順序**: 允許拖拽重新排序（存到 `page_tree`） + +**依賴**: 依賴 1、2 | **相關改動**: +- main.py — 新增 `/api/projects//pages-tree` 端點 +- 修改現有 main.py 的頁面掃描邏輯（支援層級） +- editor.html — 新增樹狀面板 +- my-editor.js — 樹狀展示、拖拽邏輯、排序功能 + +**技術細節** — 遞歸掃描資料夾構建層級： +```python +def build_page_tree(project_path, max_depth=3): + """遞歸構建頁面樹狀結構""" + def scan_folder(folder_path, current_depth=0): + if current_depth > max_depth: + return [] + + items = [] + for item in sorted(os.listdir(folder_path)): + if item.startswith('.'): + continue + full_path = os.path.join(folder_path, item) + + if item.endswith('.html'): + # HTML 文件 + title = item.replace('.html', '').replace('-', ' ').title() + items.append({ + "type": "file", + "name": item, + "title": title, + "order": len(items) + }) + elif os.path.isdir(full_path): + # 資料夾 + items.append({ + "type": "folder", + "name": item, + "title": item.replace('-', ' ').title(), + "children": scan_folder(full_path, current_depth + 1), + "order": len(items) + }) + + return items + + return {"root": scan_folder(project_path)} +``` + +--- + +## 📐 **實施步驟（優先級順序）** + +| 步驟 | 任務 | 預計時間 | 依賴 | +|-----|------|--------|------| +| **1.1** | 設計 `project.json` 擴展結構 | 1 小時 | — | +| **1.2** | 後端：網站設定 API (GET/PUT) | 2 小時 | 1.1 | +| **1.3** | 前端：儀表板設定頁籤 | 3 小時 | 1.2 | +| **1.4** | 前端：編輯器快速設定面板 | 2 小時 | 1.2 | +| **2.1** | 建立媒體上傳 API | 3 小時 | — | +| **2.2** | 實現縮圖生成 + 安全驗證 | 2 小時 | 2.1 | +| **2.3** | 前端：媒體庫 UI（網格 + 上傳） | 4 小時 | 2.1 | +| **2.4** | 前端：編輯器集成媒體插入 | 2 小時 | 2.3 | +| **3.1** | 設計頁面樹狀結構數據 | 1 小時 | — | +| **3.2** | 後端：頁面樹狀掃描 + API | 3 小時 | 3.1 | +| **3.3** | 前端：樹狀面板 UI | 4 小時 | 3.2 | +| **3.4** | 前端：拖拽排序邏輯 | 3 小時 | 3.3 | +| **3.5** | 前端：排序按鈕（字母/時間/自訂） | 2 小時 | 3.4 | + +**總計**: 約 33 小時 ≈ **5 工作天** ✅ + +--- + +## 🗂️ **檔案修改清單** + +| 檔案 | 修改類型 | 主要改動 | +|-----|--------|--------| +| main.py | 修改 | 新增 `settings` 相關端點、媒體 API、頁面樹狀 API | +| dashboard.html | 新建/擴展 | 新增 3 個主要標籤頁（設定、頁面、媒體） | +| editor.html | 修改 | 新增快速設定按鈕、樹狀頁面面板 | +| my-editor.js | 擴展 | 加入媒體管理、樹狀邏輯、拖拽排序 | +| utils/media_manager.py | 新建 | 媒體上傳、驗證、縮圖生成 | +| 無需修改 | — | build_editor.py（暫不涉及） | + +--- + +## ✅ **驗收標準** + +### **网站設定模組** +1. ✅ 可在儀表板編輯並儲存網站基本資訊（標題、描述、顏色） +2. ✅ 編輯器快速面板可快速存取設定 +3. ✅ 刷新頁面後設定值保留 + +### **檔案管理系統** +1. ✅ 可拖拽上傳圖片到媒體庫 +2. ✅ 上傳後自動生成縮圖和複製 URL 按鈕 +3. ✅ 可刪除媒體，檔案系統同時刪除 +4. ✅ 在編輯器內可插入媒體庫圖片 + +### **頁面組織改進** +1. ✅ 左側面板以樹狀顯示所有頁面及資料夾結構 +2. ✅ 可按字母/時間/手動排序頁面 +3. ✅ 拖拽頁面重新排序後自動儲存 +4. ✅ 深度超過 3 層的頁面不顯示（避免過度複雜） + +--- + +## 🚀 **建議開發流程** + +**第一天**： +- 開會確認所有決定 ✅（已完成） +- 設計數據結構，建立 `project.json` 擴展 + +**第二天**： +- 實現後端 API（設定、媒體、頁面樹狀） +- 單元測試確保 API 正常 + +**第三天**： +- 儀表板 UI（設定、媒體庫） +- 前端 API 集成 + +**第四天**： +- 編輯器快速面板 + 樹狀頁面面板 +- 拖拽排序邏輯 + +**第五天**： +- 集成測試、bug 修復 +- 本地運行測試 + +--- + +**你對 Phase 1 計畫有任何問題或想要調整嗎？** 是否確認可以開始實施？ \ No newline at end of file