更新計畫

2026-05-26 03:02:53 +08:00
parent 9be9d5d924
commit e9ac2ae1a8
2 changed files with 666 additions and 1 deletions
--- a/docs/phase1.md
+++ 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/<slug>/settings` — 獲取網站設定
+- `PUT /api/projects/<slug>/settings` — 更新網站設定
+- `POST /api/projects/<slug>/settings/logo` — 上傳 Logo（轉向媒體管理）
+- `POST /api/projects/<slug>/settings/favicon` — 上傳 Favicon
+
+**前端介面（兩個位置）**：
+
+**位置 A：儀表板** — dashboard.html 新增設定標籤
+```html
+<div class="nav-tabs">
+  <button class="tab-btn active">概覽</button>
+  <button class="tab-btn">🔧 網站設定</button>
+  <button class="tab-btn">📄 頁面管理</button>
+  <button class="tab-btn">🖼️ 媒體庫</button>
+</div>
+
+<div class="settings-panel">
+  <form id="settingsForm">
+    <input type="text" id="title" placeholder="網站標題" />
+    <textarea id="description" placeholder="網站描述"></textarea>
+    <input type="color" id="primaryColor" />
+    <button type="submit">💾 儲存設定</button>
+  </form>
+</div>
+```
+
+**位置 B：編輯器快速存取** — editor.html 右上方快速菜單
+```html
+<button class="quick-settings-btn" title="快速設定">⚙️</button>
+<!-- 點擊時展開小面板（不離開編輯器） -->
+```
+
+**依賴**: 無 | **相關改動**:
+- main.py — 新增 `/api/projects/<slug>/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/<slug>/media/upload` — 上傳圖片
+  - 接受：jpg, png, gif, webp, svg
+  - 限制：單檔 2MB，自動生成縮圖
+  - 返回：`{filename, url, thumb_url, size, upload_time}`
+
+- `GET /api/projects/<slug>/media/list` — 列出所有媒體
+  - 返回：`[{filename, url, thumb_url, size, upload_time}, ...]`
+
+- `DELETE /api/projects/<slug>/media/<filename>` — 刪除媒體
+
+**前端介面** — 儀表板媒體庫頁籤：
+```html
+<div class="media-manager">
+  <!-- 拖拽上傳區 -->
+  <div class="upload-dropzone" id="dropZone">
+    拖放圖片到此或 <button>點擊上傳</button>
+  </div>
+  
+  <!-- 媒體網格 -->
+  <div class="media-grid" id="mediaGrid">
+    <!-- 動態生成媒體卡片 -->
+    <div class="media-card">
+      <img src="banner-thumb.jpg" />
+      <div class="card-info">
+        <p class="filename">banner.jpg</p>
+        <p class="size">152 KB • 2026-05-20</p>
+        <div class="card-actions">
+          <button class="copy-url" title="複製連結">📋</button>
+          <button class="delete-btn" title="刪除">🗑️</button>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+**依賴**: 依賴 1（網站設定先完成） | **相關改動**:
+- main.py — 新增 `/api/projects/<slug>/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/<slug>/pages-tree` — 獲取頁面樹狀結構
+- `PUT /api/projects/<slug>/pages-tree` — 更新頁面順序和層級
+- `POST /api/projects/<slug>/pages/<page_path>/reorder` — 移動頁面
+
+**前端介面** — 編輯器左側面板改進：
+```html
+<div class="pages-panel">
+  <div class="pages-tree" id="pagesTree">
+    <!-- 遞歸樹狀展示 -->
+    <div class="tree-item root-folder">
+      <span class="folder-icon">📁</span>
+      <span class="folder-name">根目錄</span>
+      <ul class="tree-children">
+        <li class="tree-item page">
+          <span class="page-icon">📄</span>
+          <span class="page-name">首頁 (index.html)</span>
+          <div class="page-actions">
+            <button class="edit-page">✏️</button>
+            <button class="duplicate-page">📋</button>
+            <button class="delete-page">🗑️</button>
+          </div>
+        </li>
+        
+        <li class="tree-item folder">
+          <span class="folder-toggle">▼</span>
+          <span class="folder-icon">📁</span>
+          <span class="folder-name">services/</span>
+          <ul class="tree-children" style="display:none">
+            <li class="tree-item page">
+              <span class="page-icon">📄</span>
+              <span class="page-name">consulting.html</span>
+            </li>
+          </ul>
+        </li>
+      </ul>
+    </div>
+  </div>
+  
+  <!-- 拖拽排序控制 -->
+  <div class="sort-controls">
+    <button id="sortAlpha">按字母排序 A-Z</button>
+    <button id="sortRecent">按修改時間</button>
+    <button id="sortCustom">自訂順序</button>
+  </div>
+</div>
+```
+
+**排序邏輯**：
+- **字母排序**: 遞歸排序每層頁面
+- **修改時間**: 按 `updated_at` 時間戳排序
+- **自訂順序**: 允許拖拽重新排序（存到 `page_tree`）
+
+**依賴**: 依賴 1、2 | **相關改動**:
+- main.py — 新增 `/api/projects/<slug>/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 計畫有任何問題或想要調整嗎？** 是否確認可以開始實施？