Spaces:
Sleeping
Sleeping
|
Download README.md from fromnowoncoding/eventinvite: direct link, hf CLI and curl.
- Browser
- Download file 7.58 kB
-
https://huggingface.co/spaces/fromnowoncoding/eventinvite/resolve/main/README.md
- Command line
-
hf download hf://spaces/fromnowoncoding/eventinvite/README.md
-
curl -L -o README.md https://huggingface.co/spaces/fromnowoncoding/eventinvite/resolve/main/README.md
7.58 kB
| 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 元件<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. 安裝依賴: | |
| ```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 | |