新增即時觀戰房間並整理 README

README.md

@@ -1,49 +1,60 @@
-# 羽球記分板
+# 羽毛球記分板
 
-使用 `Vite + React + TypeScript + Node.js` 製作的羽毛球記分板，支援選隊伍、計分板、歷史戰績、語音播報、PWA 安裝與 Docker / NAS 部署。
+使用 `Vite + React + TypeScript + Node.js` 製作的羽毛球記分板，支援選隊伍、即時記分、歷史戰績、PWA 安裝，以及即時房間觀戰。
 
 ## 功能
 
 - 選隊伍
-  - 可依指定日期從資料庫讀取分組資料。
-  - 若當天沒有資料，可手動輸入 A、B 區名單產生分組。
-  - 每組可直接進入記分板，不需額外再點選這組。
-- 計分板
-  - 設定隊伍彈窗支援逐一選人。
-  - 依選取順序自動成隊：`1、2` 一隊，`3、4` 一隊。
-  - 右側可快速選擇預設隊伍。
-  - 可設定本場幾分獲勝，預設 `21` 分。
-  - 需先指定先攻，之後點擊分數即可直接加分。
-  - 第一分記錄後，右側 `設定隊伍` 會切成 `上一步`。
-  - 可交換上下隊伍位置，也可交換同隊左右球員位置。
-  - `比賽結算` 為防誤觸設計，需長按 `1 秒` 才會觸發。
-  - 比分仍是 `0:0` 時，不會啟動比賽結算長按。
-  - 長按 `比賽結算` 時，按鈕下方會顯示進度條，按鈕本身也會有亮起與下壓的視覺回饋。
-  - 手機長按 `比賽結算` 不會再觸發文字選取。
-  - 連勝會出現特效提示：
-    - `3 連勝`：`大殺特殺`
-    - `4 連勝`：`暴走`
-    - `5 連勝`：`無人能擋`
-    - `6 連勝`：`主宰比賽`
-    - `7 連勝`：`像神一般的`
-    - `8 連勝`：`成為傳說`
+  - 可依指定日期從資料庫載入分組資料。
+  - 若資料庫沒有當天資料，可手動輸入 A、B 區名單產生分組。
+  - 點選分組後可直接進入記分板。
+- 記分板
+  - 隊伍名稱只顯示在最上方與最下方。
+  - 可在設定隊伍面板中逐一選人，也可快速套用預設隊伍。
+  - 先選到的 `1、2` 為一隊，`3、4` 為另一隊。
+  - 可設定本場幾分獲勝，預設為 `21` 分。
+  - 必須先設定先攻，才能開始記分。
+  - 點擊分數直接加分，不提供加一減一按鈕。
+  - 第一分記下後，`設定隊伍` 會切換成 `上一步`。
+  - 可交換上下兩隊位置，也可交換同隊左右站位。
+  - `比賽結算` 需長按 `1 秒` 才會觸發。
+  - 比分 `0:0` 時不允許觸發結算。
+- 語音播報
+  - 可設定是否播報得分者。
+  - 可設定是否播報下一位發球者。
+  - 可調整語速，最高支援到 `10x`。
+  - `RURU` 會以大小寫不敏感方式播報成「嚕嚕」。
+- 動畫提示
+  - 先攻未設定時，`先攻` 文字會有提示動畫。
+  - 選定先攻後，會顯示打勾讓使用者更容易辨識。
+  - 連勝特效：
+    - `3 連勝`：大殺特殺
+    - `4 連勝`：暴走
+    - `5 連勝`：無人能擋
+    - `6 連勝`：主宰比賽
+    - `7 連勝`：像神一般的
+    - `8 連勝`：成為傳說
   - 達到目標分數時會顯示獲勝動畫。
-  - 內建免費瀏覽器 TTS。
-  - 可設定是否播報得分者、是否播報發球者、以及語速。
-  - `RURU` 已支援不分大小寫的發音別名，會念成 `嚕嚕`。
 - 歷史戰績
-  - 直接從資料庫 `history` 表讀取列表。
-  - 點擊單筆戰績可開啟得分紀錄彈窗。
-  - 彈窗支援右上角 `X` 關閉按鈕。
-  - 每筆資料可直接刪除，刪除前會跳一次確認提示。
+  - 比賽結算後可選擇是否上傳戰績到資料庫。
+  - 歷史戰績列表直接從資料庫 `history` 表讀取。
+  - 可點開查看每球得分紀錄。
+  - 手機上彈窗有 `X` 可快速關閉。
+  - 每筆戰績可刪除，刪除前會確認一次。
+- 即時房間 / 觀戰
+  - 只要帶入隊伍進入記分板，就會自動建立一個房間。
+  - 記分板右側會顯示房號。
+  - `房間列表` 只顯示房號、隊伍、目標分數與最後更新時間，不顯示比分。
+  - 觀戰者進入房間後可即時看到比分，不能操作。
+  - 觀戰同步使用 `SSE + 輪詢備援`，降低漏分風險。
+  - 房主重整、離開記分板或換隊伍時，未結束房間會自動清掉。
+  - 達到目標分數後房間會標記結束，觀戰者會看到獲勝彈窗，按確定後返回房間列表。
 - PWA
   - 可加入手機主畫面，像 App 一樣開啟。
-  - 支援 `manifest`、`service worker`、主畫面 icon。
-  - 網頁 favicon 與 PWA icon 已改用 `ICON.png` 產生的 PNG 圖示。
-  - 偵測到新版本時，畫面底部會顯示更新提示，可一鍵重新整理套用新版。
-  - 前端會定期輪詢 `/api/version`，只要重新部署並重建 app container，就能偵測到新版本。
+  - 支援自訂網站 icon / PWA icon。
+  - 新版本部署後會顯示更新提示，可直接重新整理套用新版。
 
-## 執行環境
+## 開發環境
 
 ### Port
 
@@ -56,18 +67,18 @@
 npm install
 ```
 
-### 開發模式
+### 啟動開發模式
 
 ```bash
 npm run dev
 ```
 
-啟動後會同時開兩個服務：
+啟動後：
 
 - 前端：`http://localhost:3501`
 - API：`http://localhost:8788`
 
-### 檢查
+### 建置與檢查
 
 ```bash
 npm run lint
@@ -91,24 +102,24 @@ PORT=8788
 
 ## Docker / NAS 部署
 
-正式部署時目前是雙容器架構：
+正式部署時：
 
-- App 內部服務：`8788`
-- Nginx SSL 對外入口：`3501`
+- App 內部服務 port：`8788`
+- 對外 HTTPS 入口：`3501`
 
-啟動指令：
+部署指令：
 
 ```bash
 sudo docker compose up -d --build
 ```
 
-部署完成後，對外入口：
+部署完成後，對外入口為：
 
 ```text
 https://你的網域或 NAS IP:3501
 ```
 
-每次執行 `sudo docker compose up -d --build` 重建 app container 時，後端都會帶新的容器啟動版號；前端輪詢發現版號不同後，就會跳出更新提示。
+每次執行 `sudo docker compose up -d --build`，容器都會更新啟動版號，已安裝 PWA 的裝置會在偵測到新版本後顯示更新提示。
 
 ## SSL 憑證目錄
 
@@ -118,17 +129,17 @@ Docker Compose 會直接掛載 NAS 上的憑證目錄：
 /volume1/homes/JianMiau/www/certificate/
 ```
 
-目前預設使用這三個檔名：
+預設使用以下檔案：
 
 - `RSA-cert.pem`
 - `RSA-chain.pem`
 - `RSA-privkey.pem`
 
-更新憑證時，只要更新上述目錄內的檔案，再重新啟動容器即可。
+之後只要更新這個資料夾內的憑證檔即可，不需要重建 image。
 
-## history 資料表格式
+## 資料表格式
 
-`history` 表目前使用以下欄位：
+### `history`
 
 - `id`
 - `time`
@@ -139,16 +150,25 @@ Docker Compose 會直接掛載 NAS 上的憑證目錄：
   - `0`：雙打
   - `1`：單打
 - `players`
-  - 依 `1 ~ 4` 順序排序的玩家名稱
+  - 依 `1 ~ 4` 編號排序的玩家陣列
 - `team`
-  - `1、2` 一隊
-  - `3、4` 一隊
+  - `1、2` 為一隊
+  - `3、4` 為一隊
 - `scoreList`
   - 格式：`[round, 發球者編號, 連勝次數, 得分隊伍(0 或 1)]`
 
-## Git 中文顯示
+## PWA 圖示
 
-若要讓 commit 與 log 正常顯示中文，可設定：
+目前網站 icon 與 PWA icon 來源為：
+
+- `public/favicon.png`
+- `public/apple-touch-icon.png`
+- `public/pwa-192.png`
+- `public/pwa-512.png`
+
+## Git 中文設定
+
+建議設定 git 使用 UTF-8，避免中文 commit 或 log 顯示異常：
 
 ```bash
 git config i18n.commitEncoding utf-8