補上歷史戰績列表與 NAS 部署說明

README.md

@@ -1,36 +1,30 @@
 # badminton-scoreboard
 
-羽毛球記分板專案，使用 `Vite + React + TypeScript` 建立前端，搭配 `Express + MySQL` 提供分組讀取與戰績寫入 API。
+羽毛球記分板專案，使用 `Vite + React + TypeScript` 建立前端，搭配 `Express + MySQL` 提供分組讀取、歷史戰績列表與戰績寫入 API。
 
-## 目前功能
+## 功能
 
-- 選擇日期後從 DB 讀取隊伍與分組資料
-- 若指定日期沒有資料，可手動輸入名單並產生配對
+- 指定日期後從 DB 讀取隊伍與分組資料
+- 若該日期沒有資料，可手動輸入名單並產生配對
 - 從指定組別選 2 隊帶入記分板
 - 記分板支援先攻設定、點擊分數直接加分、上一步回退
-- 支援上下換隊、左右交換隊員位置
+- 支援上下交換隊伍、左右交換隊員位置
 - 比賽結算後可選擇是否上傳戰績到 `history` 資料表
+- 歷史戰績頁直接從 DB 顯示列表，點擊可查看得分過程
 
-## 開發環境 Port
+## 開發 Port
 
 - Client: `3501`
 - Server API: `8788`
 
-Vite 前端會開在：
+本機開發模式：
 
-```text
-http://localhost:3501
-```
+- 前端：`http://localhost:3501`
+- API：`http://localhost:8788`
 
-API 會開在：
+## 本機開發
 
-```text
-http://localhost:8788
-```
-
-## 啟動方式
-
-先安裝套件：
+安裝套件：
 
 ```bash
 npm install
@@ -42,7 +36,7 @@ npm install
 npm run dev
 ```
 
-這個指令會同時啟動：
+這會同時啟動：
 
 - Vite client on `3501`
 - Node server on `8788`
@@ -64,13 +58,13 @@ DB_HISTORY_TABLE=history
 SERVER_PORT=8788
 ```
 
-## 資料表說明
+## 資料表
 
 ### `badminton`
 
 - `time`: 日期，格式 `YYYYMMDD`
-- `personnel`: 人員清單，格式例如 `[[1,"A區成員"],[0,"B區成員"]]`
-- `battlecombination`: 分組資料，格式例如 `{"0":[["A","B"]],"1":[...],"2":[...]}`
+- `personnel`: 人員清單，例如 `[[1,"A區成員"],[0,"B區成員"]]`
+- `battlecombination`: 分組資料，例如 `{"0":[["A","B"]],"1":[...],"2":[...]}`
 
 ### `history`
 
@@ -90,12 +84,12 @@ SERVER_PORT=8788
 [round, starter, winCount, winner]
 ```
 
-對應意義：
+欄位意義：
 
 - `round`: 第幾球
 - `starter`: 發球者編號，依記分板 `1~4`
-- `winCount`: 連續得分次數
-- `winner`: 該球由哪一隊得分，`0` 代表上方隊伍，`1` 代表下方隊伍
+- `winCount`: 該隊目前連續得分次數
+- `winner`: 哪一隊得分，`0` 代表上方隊伍，`1` 代表下方隊伍
 
 ## 建置
 
@@ -103,7 +97,7 @@ SERVER_PORT=8788
 npm run build
 ```
 
-## Docker
+## Docker 單次啟動
 
 建置映像：
 
@@ -128,10 +122,39 @@ docker run -d \
   badminton-scoreboard
 ```
 
-容器啟動後可透過：
+## NAS 部署
 
-```text
-http://localhost:8788
+這個專案現在已經補上 [docker-compose.yml](./docker-compose.yml)，所以在 NAS 上可以直接使用：
+
+```bash
+sudo docker compose up -d --build
 ```
 
-提供 API 與建置後的前端頁面。
+但前提是你要先在 NAS 的專案目錄準備好 `.env`，至少要有：
+
+```env
+DB_HOST=192.168.0.15
+DB_PORT=3307
+DB_USER=jianmiau
+DB_PASSWORD=你的密碼
+DB_DATABASE=badminton
+DB_TABLE=badminton
+DB_HISTORY_TABLE=history
+```
+
+部署後會對外提供：
+
+```text
+http://NAS_IP:8788
+```
+
+## NAS 部署注意事項
+
+- 這個專案在正式部署時沒有獨立的 `3501` 前端埠，前端建置後由 Node server 一起從 `8788` 提供。
+- 如果 NAS 上已經有其他服務佔用 `8788`，要先改 `docker-compose.yml` 的左側對外埠。
+- 指令要完整寫成 `sudo docker compose up -d --build`，不是 `--buil`。
+- 第一次部署前，建議先確認 NAS 已安裝 Docker / Container Manager，且帳號可執行 `sudo docker compose`。
+
+## Git 記錄
+
+這個專案後續提交我會使用中文 commit 訊息，並已將本地 repo 的 git 中文編碼輸出設定好，方便直接看中文 log。