badminton-scoreboard/README.md

# badminton-scoreboard

羽毛球記分板系統，使用 `Vite + React + TypeScript` 建立前端，搭配 `Express + MySQL` 提供資料讀寫 API。

目前專案包含三個主要頁面：

- `選隊伍`：可依指定日期從 DB 載入隊伍資料，若沒有資料可改用手動配對
- `記分板`：支援先攻設定、直接點分數記分、上一步回退、上下換隊、左右換位
- `歷史戰績`：直接從 DB 的 `history` 表讀取戰績列表，點開可看得分紀錄，也能直接刪除單筆紀錄

## 目前記分板流程

- 進入記分板前，先從選隊伍頁面選定「第幾組」
- 點 `設定隊伍` 後會打開雙欄彈窗
- 左邊可一個一個選球員，依照順序自動成隊：
  - 第 1、2 位成上方隊伍
  - 第 3、4 位成下方隊伍
- 右邊可直接快速選預設好的隊伍
- 可設定 `幾分獲勝`，預設是 `21`
- 確認配隊後會直接帶入記分板並重設本場狀態
- 開始記分後，`設定隊伍` 會改成 `上一步`

## 手機版設計方向

- 以手機完整顯示為優先
- 記分板主畫面盡量避免整頁上下滑動
- 設定隊伍彈窗會優先壓縮內容高度
- 若名單較多，改為彈窗內局部捲動，不影響整頁閱讀

## 歷史戰績功能

- 歷史列表直接從 DB 的 `history` 表讀取
- 點列表卡片可查看得分過程
- 每筆列表右側都有 `刪除此筆` 按鈕
- 刪除前會跳出確認視窗
- 刪除成功後列表會即時更新

## Port 設定

### 本機開發

- Client：`3501`
- Server API：`8788`

啟動後：

- 前端：`http://localhost:3501`
- API：`http://localhost:8788`

### Docker / NAS 部署

- 對外入口：`3501`
- Node app 內部 port：`8788`

正式部署時，外部會走 Nginx SSL 入口，使用 `3501`；`8788` 只提供容器內部反向代理使用。

## 本機開發

安裝套件：

```bash
npm install
```

啟動開發環境：

```bash
npm run dev
```

會同時啟動：

- Vite client on `3501`
- Node server on `8788`

## 建置與檢查

```bash
npm run build
```

```bash
npm run lint
```

## `.env` 範例

請參考 [.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
NGINX_SERVER_NAME=_
SSL_CERT_FILE_NAME=RSA-cert.pem
SSL_CHAIN_FILE_NAME=RSA-chain.pem
SSL_KEY_FILE_NAME=RSA-privkey.pem
```

## 資料表格式

### `badminton`

- `time`：日期鍵值，格式 `YYYYMMDD`
- `personnel`：球員名單 JSON
- `battlecombination`：各組配對 JSON

### `history`

- `id`
- `time`
- `dayOfWeek`
- `score`
- `winScore`
- `type`
- `players`
- `team`
- `scoreList`

`scoreList` 格式：

```text
[round, starter, winCount, winner]
```

說明：

- `round`：第幾球
- `starter`：發球者編號
- `winCount`：連勝次數
- `winner`：`0` 代表上方隊伍得分，`1` 代表下方隊伍得分

## Docker 建置

單獨建置 Node app：

```bash
docker build -t badminton-scoreboard .
```

## NAS 部署

專案已提供 [docker-compose.yml](./docker-compose.yml)。

服務包含：

1. `badminton-scoreboard`
Node app，內部使用 `8788`

2. `badminton-scoreboard-web`
Nginx SSL 入口，對外使用 `3501`

在 NAS 專案目錄執行：

```bash
sudo docker compose up -d --build
```

## SSL 憑證掛載

SSL 憑證目錄固定使用：

```text
/volume1/homes/JianMiau/www/certificate/
```

預設檔名：

- `RSA-cert.pem`
- `RSA-chain.pem`
- `RSA-privkey.pem`

Nginx 會自動組合：

- `RSA-cert.pem` + `RSA-chain.pem` => fullchain
- `RSA-privkey.pem` => private key

之後只要更新：

```text
/volume1/homes/JianMiau/www/certificate/
```

容器內的 Nginx 就會重新載入，不需要重建 image。

## NAS 對外入口

部署完成後可由：

```text
https://你的網域或IP:3501
```

進入系統。

## Git 中文設定

目前 repo 已設定：

- `i18n.commitEncoding=utf-8`
- `i18n.logOutputEncoding=utf-8`
- `core.quotepath=false`

之後使用中文 commit 訊息與 `git log` 會比較正常。