## 📋 **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 計畫有任何問題或想要調整嗎？** 是否確認可以開始實施？