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