nudoragon/vvveb-cms
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
vvveb-cms/docs/phase1.md
nudoragon e9ac2ae1a8 更新計畫
2026-05-26 03:02:53 +08:00

12 KiB
Raw Permalink Blame History

📋 Plan: Phase 1 詳細實施方案

根據所有決定，以下是完整的 Phase 1 規劃：

🎯 Phase 1 三大核心模組

1️⃣ 網站設定模組（Project Settings）

數據結構 — 擴展 project.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 新增設定標籤

<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 右上方快速菜單

<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> — 刪除媒體

前端介面 — 儀表板媒體庫頁籤：

<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 — 拖拽上傳邏輯、網格展示

技術細節：

# 縮圖生成邏輯（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 中新增頁面樹狀結構和排序：

{
  "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 — 移動頁面

前端介面 — 編輯器左側面板改進：

<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 — 樹狀展示、拖拽邏輯、排序功能

技術細節 — 遞歸掃描資料夾構建層級：

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

Reference in New Issue View Git Blame Copy Permalink