--- 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 (主要資料存儲) ## 系統架構圖 ```mermaid 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 元件
Bootstrap 5.1.3
SweetAlert2
Bootstrap Icons] end %% 後端部分 subgraph Backend[後端服務] D[Flask App] Routes[路由處理
/admin
/toggle_payment
/update_note
/backup
/restore] Auth[認證機制] end %% 資料存儲 subgraph Storage[資料暫存] E[SQLite 資料庫
臨時資料] Tables[資料表
Participant
Table] end %% Google整合 subgraph Google[主要資料存儲] F[Google Apps Script] O[Google Sheets
永久資料] Sync[資料同步
布林值轉換
錯誤處理] 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. 安裝依賴: ```bash pip install -r requirements.txt ``` 2. 設定環境變數: ```bash export ADMIN_PASSWORD=your_password export SETTINGS_SCRIPT_URL=your_script_url ``` 3. 啟動應用: ```bash 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