eventinvite / README.md
ichieh
更新Readme
7252170
|
Raw History Blame Contribute Delete
7.58 kB
metadata
title: 蛇來蛇去座位表
emoji: 📈
colorFrom: blue
colorTo: yellow
sdk: docker
pinned: false
license: apache-2.0
app_port: 7860
persistent_dir:
  - /data

蛇來蛇去座位表 - 活動座位選擇系統

這是一個專為活動設計的座位選擇系統,讓參與者可以自由選擇想要坐的桌次。系統支援多桌次管理、桌長設定、付款狀態追蹤等功能。

功能特色

參與者功能

  • 即時查看各桌剩餘座位
  • 選擇想要入座的桌次
  • 填寫個人資料(暱稱、Email、FB連結、自我介紹)
  • 點擊參與者名字可查看詳細資訊

管理者功能

  • 管理者後台密碼保護
  • 查看所有參與者資訊
  • 設定/取消桌長身份
  • 標記付款狀態
  • 新增/編輯參與者備註
  • 匯出參與者資料
  • 備份/還原資料庫
  • 與 Google Sheets 同步

技術架構

前端

  • HTML5/CSS3
  • Bootstrap 5.1.3
  • SweetAlert2 (彈窗提示)
  • Bootstrap Icons

後端

  • Python Flask
  • SQLite (暫存資料庫)
  • Flask-SQLAlchemy
  • Google Apps Script (主要資料存儲)

系統架構圖

graph TB
    %% 定義風格
    classDef page fill:#f9f,stroke:#333,stroke-width:2px
    classDef backend fill:#bbf,stroke:#333,stroke-width:2px
    classDef database fill:#ddb,stroke:#333,stroke-width:2px
    classDef api fill:#bfb,stroke:#333,stroke-width:2px

    %% 前端部分
    subgraph Frontend[前端介面]
        A[首頁 index.html]
        B[管理者登入 admin_login.html]
        C[管理面板 admin.html]
        UI[UI 元件<br>Bootstrap 5.1.3<br>SweetAlert2<br>Bootstrap Icons]
    end

    %% 後端部分
    subgraph Backend[後端服務]
        D[Flask App]
        Routes[路由處理<br>/admin<br>/toggle_payment<br>/update_note<br>/backup<br>/restore]
        Auth[認證機制]
    end

    %% 資料存儲
    subgraph Storage[資料暫存]
        E[SQLite 資料庫<br>臨時資料]
        Tables[資料表<br>Participant<br>Table]
    end

    %% Google整合
    subgraph Google[主要資料存儲]
        F[Google Apps Script]
        O[Google Sheets<br>永久資料]
        Sync[資料同步<br>布林值轉換<br>錯誤處理]
    end

    %% 使用者流程
    subgraph UserFlow[使用者流程]
        G[瀏覽座位]
        H[選擇座位]
        I[填寫資料]
        J[完成報名]
    end

    %% 管理者流程
    subgraph AdminFlow[管理者流程]
        K[登入驗證]
        L[查看報名]
        M[管理座位/付款]
        N[同步資料]
    end

    %% 連接關係
    A --> UI
    B --> UI
    C --> UI
    UI --> D
    
    D --> Routes
    Routes --> Auth
    Auth --> E
    
    D --> F
    F --> Sync
    Sync --> O
    
    E --> Tables
    
    G --> H
    H --> I
    I --> J
    J --> D
    
    K --> L
    L --> M
    M --> N
    N --> D

    %% 初始化流程
    Init[系統啟動] --> LoadData[載入資料]
    LoadData --> O
    O --> E

    %% 套用風格
    class A,B,C page
    class D,Routes,Auth backend
    class E,Tables database
    class F,O,Sync api

資料存儲架構

Google Sheets(主要資料存儲)

  • 永久保存所有資料
  • 包含參與者資訊、桌次設定
  • 通過 Google Apps Script 進行存取
  • 支援手動編輯和備份

SQLite(暫存資料庫)

  • 用於應用運行時的資料快取
  • 每次應用啟動時從 Google Sheets 同步
  • 提供高效的資料查詢和修改
  • 應用重啟時會重置

資料同步機制

  1. 應用啟動時:

    • 從 Google Sheets 讀取所有資料
    • 初始化 SQLite 資料庫
    • 建立資料表結構
  2. 資料修改時:

    • 先更新 SQLite 資料庫
    • 立即同步到 Google Sheets
    • 確保資料一致性
  3. 錯誤處理:

    • 同步失敗時提供錯誤提示
    • 支援手動重新同步
    • 記錄同步錯誤日誌

主要功能流程

  1. 一般使用者流程

    • 瀏覽活動座位表
    • 選擇想要的座位
    • 填寫個人資料(暱稱、Email、FB連結、自我介紹)
    • 完成報名
  2. 管理者流程

    • 登入管理面板
    • 查看所有報名資料
    • 管理座位分配
    • 與 Google Sheets 同步資料
  3. 資料同步流程

    • 後端 Flask 應用程式處理請求
    • 透過 Google Apps Script 進行資料同步
    • 資料存儲於 SQLite 資料庫和 Google Sheets

部署資訊

本系統部署在 Hugging Face Spaces 平台,使用持久化存儲來保存資料。

環境變數設定

  • ADMIN_PASSWORD: 管理者密碼
  • SETTINGS_SCRIPT_URL: Google Apps Script 網址(用於同步設定)

本地開發

  1. 安裝依賴:
pip install -r requirements.txt
  1. 設定環境變數:
export ADMIN_PASSWORD=your_password
export SETTINGS_SCRIPT_URL=your_script_url
  1. 啟動應用:
python app.py

應用將在 http://localhost:7860 運行

資料庫結構

Table 資料表

  • id: 桌次 ID
  • name: 桌次名稱
  • capacity: 座位容量
  • participants: 關聯到 Participant 資料表

Participant 資料表

  • id: 參與者 ID
  • nickname: 暱稱
  • email: 電子郵件
  • fb_link: Facebook 連結
  • introduction: 自我介紹
  • table_id: 所屬桌次
  • seat_number: 座位號碼
  • is_table_leader: 是否為桌長
  • created_at: 建立時間
  • has_paid: 付款狀態
  • note: 管理者備註

資料備份

系統提供兩種備份機制:

  1. 資料庫備份:完整備份所有資料
  2. Google Sheets 同步:即時同步重要設定

注意事項

  1. 請定期備份資料庫
  2. 管理者密碼請妥善保管
  3. 建議定期檢查 Google Sheets 同步狀態

授權資訊

本專案採用 MIT 授權條款。

開發 Debug 記錄

前端顯示

  1. 圓形桌位顯示溢出

    • 問題:參與者超過 5 人時,名字會溢出圓形區域
    • 解決:改用長方形設計,並根據參與者數量自動調整大小
  2. 參與者資訊顯示優化

    • 問題:自我介紹和備註內容過長時影響版面
    • 解決:實作文字截斷和彈出式詳細資訊視窗

Google Sheets 同步

  1. 跨域請求問題

    • 問題:無法直接從前端呼叫 Google Apps Script
    • 解決:透過後端 API 轉發請求,並處理回應
  2. 布林值同步問題

    • 問題:付款狀態和桌長狀態在 Google Sheets 同步時出現異常
    • 解決:統一使用 'TRUE'/'FALSE' 字串值在 Google Sheets 中儲存,並在應用程式中正確轉換為布林值

安全性問題

  1. 管理者密碼保護
    • 問題:需要保護管理者頁面的存取
    • 解決:使用環境變數和 session 機制,實作管理者登入功能

使用者體驗

  1. 座位選擇流程

    • 問題:原本點擊整個圓桌來選擇不夠直覺
    • 解決:新增獨立的選擇按鈕,並提供視覺回饋
  2. 錯誤處理優化

    • 問題:系統錯誤訊息不夠友善
    • 解決:使用 SweetAlert2 提供更好的錯誤提示
  3. 付款狀態更新問題

    • 問題:更新單一參與者的付款狀態時會影響到其他參與者
    • 解決:修正資料同步邏輯,確保只更新指定參與者的狀態

資料格式處理

  1. 布林值格式統一
    • 問題:布林值在不同系統間的格式不一致(Python布林值、Google Sheets字串、JavaScript布林值)
    • 解決:
      • Google Sheets:使用 'TRUE'/'FALSE' 字串
      • Python:使用 ==True 或 =='TRUE' 進行比較
      • JavaScript:使用 === true 或 === 'TRUE' 進行比較

Hosted on 🤗 Hugging Face Spaces