File size: 7,577 Bytes
702617f
1714d7d
702617f
 
 
 
 
 
45e08b1
 
702617f
 
7252170
2a06b2a
3dde316
2a06b2a
3dde316
2a06b2a
3dde316
 
 
 
 
2a06b2a
3dde316
 
 
 
 
 
 
 
 
2a06b2a
3dde316
2a06b2a
3dde316
 
 
 
 
2a06b2a
3dde316
 
7252170
3dde316
7252170
0e8b1df
3dde316
 
 
 
7252170
 
 
 
 
 
 
 
 
 
 
 
3dde316
 
7252170
 
 
 
 
3dde316
 
7252170
 
 
 
3dde316
 
7252170
 
 
 
 
3dde316
 
7252170
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3dde316
7252170
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3dde316
 
7252170
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
3dde316
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
0e8b1df
 
 
3dde316
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
7252170
 
 
 
3dde316
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2a06b2a
7252170
 
 
 
 
 
 
 
 
 
 
 
 
2a06b2a
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
---
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