Refine scoreboard flow and update ports

README.md

@@ -1,39 +1,111 @@
-# 羽毛球記分板
+# badminton-scoreboard
 
-使用 `Vite + React + TypeScript` 初始化的前端專案，作為羽毛球記分板與賽事畫面的開發基底。
+羽毛球記分板專案，使用 `Vite + React + TypeScript` 建立前端，搭配 `Express + MySQL` 提供分組讀取與戰績寫入 API。
 
-## 技術堆疊
+## 目前功能
 
-- Vite
-- React
-- TypeScript
-- ESLint
-- Docker / Nginx 靜態部署
+- 選擇日期後從 DB 讀取隊伍與分組資料
+- 若指定日期沒有資料，可手動輸入名單並產生配對
+- 從指定組別選 2 隊帶入記分板
+- 記分板支援先攻設定、點擊分數直接加分、上一步回退
+- 支援上下換隊、左右交換隊員位置
+- 比賽結算後可選擇是否上傳戰績到 `history` 資料表
 
-## 開發指令
+## 開發環境 Port
+
+- Client: `3501`
+- Server API: `8788`
+
+Vite 前端會開在：
+
+```text
+http://localhost:3501
+```
+
+API 會開在：
+
+```text
+http://localhost:8788
+```
+
+## 啟動方式
+
+先安裝套件：
 
 ```bash
 npm install
+```
+
+啟動開發模式：
+
+```bash
 npm run dev
 ```
 
-本機開發預設網址：
+這個指令會同時啟動：
+
+- Vite client on `3501`
+- Node server on `8788`
+
+其中後端已使用 `node --watch`，修改 `server/server.mjs` 會自動重啟。
+
+## 環境變數
+
+可參考 [.env.example](./.env.example)：
+
+```env
+DB_HOST=192.168.0.15
+DB_PORT=3307
+DB_USER=jianmiau
+DB_PASSWORD=your-password
+DB_DATABASE=badminton
+DB_TABLE=badminton
+DB_HISTORY_TABLE=history
+SERVER_PORT=8788
+```
+
+## 資料表說明
+
+### `badminton`
+
+- `time`: 日期，格式 `YYYYMMDD`
+- `personnel`: 人員清單，格式例如 `[[1,"A區成員"],[0,"B區成員"]]`
+- `battlecombination`: 分組資料，格式例如 `{"0":[["A","B"]],"1":[...],"2":[...]}`
+
+### `history`
+
+- `id`
+- `time`
+- `dayOfWeek`
+- `score`
+- `winScore`
+- `type`
+- `players`
+- `team`
+- `scoreList`
+
+其中 `scoreList` 格式為：
 
 ```text
-http://localhost:5173
+[round, starter, winCount, winner]
 ```
 
+對應意義：
+
+- `round`: 第幾球
+- `starter`: 發球者編號，依記分板 `1~4`
+- `winCount`: 連續得分次數
+- `winner`: 該球由哪一隊得分，`0` 代表上方隊伍，`1` 代表下方隊伍
+
 ## 建置
 
 ```bash
 npm run build
 ```
 
-建置完成後，輸出會在 `dist/`。
+## Docker
 
-## Docker 打包
-
-建立映像：
+建置映像：
 
 ```bash
 docker build -t badminton-scoreboard .
@@ -42,19 +114,24 @@ docker build -t badminton-scoreboard .
 啟動容器：
 
 ```bash
-docker run -d -p 8080:80 --name badminton-scoreboard badminton-scoreboard
+docker run -d \
+  --name badminton-scoreboard \
+  -p 8788:8788 \
+  -e PORT=8788 \
+  -e DB_HOST=192.168.0.15 \
+  -e DB_PORT=3307 \
+  -e DB_USER=jianmiau \
+  -e DB_PASSWORD=your-password \
+  -e DB_DATABASE=badminton \
+  -e DB_TABLE=badminton \
+  -e DB_HISTORY_TABLE=history \
+  badminton-scoreboard
 ```
 
-啟動後可由以下網址檢視：
+容器啟動後可透過：
 
 ```text
-http://localhost:8080
+http://localhost:8788
 ```
 
-## 後續可擴充功能
-
-- 單打 / 雙打模式
-- 發球權切換
-- 局數統計
-- 比賽計時
-- 賽程與場地管理
+提供 API 與建置後的前端頁面。