badminton-scoreboard/README.md

# 羽毛球記分板

以 `Vite + React + TypeScript + Node.js` 製作的羽毛球記分板，提供選隊伍、記分板、歷史戰績三個主要頁面，並可搭配 Docker 部署到 NAS。

## 功能

- 選隊伍頁
  - 可依指定日期從資料庫讀取分組資料
  - 若當天沒有資料，可手動輸入 A、B 區名單建立分組
  - 成功載入後會在畫面底部顯示 1 秒浮動提示
  - 對戰名單直接點 `進入記分板` 就會帶入該組
  - 分組卡片標題改成左右緊湊排列，減少手機版高度
- 記分板頁
  - 從所選組別進入記分板
  - 設定隊伍彈窗支援兩種方式
  - 左側逐一選人，依順序 `1、2` 為上方隊伍，`3、4` 為下方隊伍
  - 右側快速套用預設隊伍
  - 可設定幾分獲勝，預設 `21`
  - 必須先設定先攻，之後點分數即可直接加分
  - 第一分後 `設定隊伍` 會改成 `上一步`
  - 支援上下交換兩隊位置、左右交換隊內站位
- 歷史戰績頁
  - 直接從資料庫 `history` 表讀取列表
  - 點擊任一筆可開啟得分紀錄彈窗
  - 彈窗右上角提供 `X` 關閉按鈕，手機更容易操作
  - 每筆資料可單獨刪除

## 本機開發

### Port

- Client: `3501`
- Server: `8788`

### 安裝

```bash
npm install
```

### 啟動開發模式

```bash
npm run dev
```

啟動後可從以下位置開啟：

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

### 驗證

```bash
npm run lint
npm run build
```

## 環境變數

請在專案根目錄建立 `.env`，至少包含以下欄位：

```env
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_password
DB_DATABASE=badminton
DB_TABLE=match_results
DB_HISTORY_TABLE=history
PORT=8788
```

## Docker / NAS 部署

目前部署設計如下：

- 對外入口：`3501`
- App 內部服務：`8788`
- 由 Nginx 負責 SSL 與反向代理

### 啟動

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

正式部署後入口會是：

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

## SSL 憑證目錄

Docker Compose 會掛載 NAS 的憑證目錄：

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

目前 Nginx 會使用這個目錄下的檔案產生 `fullchain.pem`，因此之後若你更新 SSL，只要更新這個資料夾內的憑證即可，再重新啟動容器讓設定重載。

預設使用的檔名為：

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

## 歷史戰績寫入格式

`history` 表使用的資料欄位如下：

- `id`
- `time`
- `dayOfWeek`
- `score`
- `winScore`
- `type`
  - `0`：雙打
  - `1`：單打
- `players`
  - 依照 `1 ~ 4` 編號順序儲存
- `team`
  - `1、2` 為一隊
  - `3、4` 為一隊
- `scoreList`
  - 格式：`[round, 發球者編號, 連勝次數, 得分隊伍(0 或 1)]`

## Git 中文紀錄

專案已設定 git 使用 UTF-8：

```bash
git config i18n.commitEncoding utf-8
git config i18n.logOutputEncoding utf-8
git config core.quotepath false
```

之後 commit 訊息與 log 可直接使用中文。