jiantw83/Kokorone
1
0
Fork 0
Code Pull Requests Actions Releases Activity

feat: 完成 A 群組 — 專案骨架與可重啟的服務

Browse Source 
- packages/shared：TypeScript 專案參考建置鏈路、統一日誌模組（Asia/Taipei 格式）
- apps/api：最小 NestJS 服務，GET /health
- apps/web：最小 Next.js（App Router + Tailwind v4）首頁，套用品牌色票與亮暗模式
- scripts/dev-restart.mjs：讀 .dev-pids 以 process group 訊號安全停止舊行程、背景啟動 api/web 並輪詢健康檢查
- scripts/smoke：npm run smoke -- <群組代號> 冒煙測試框架，A 群組測試涵蓋 /health 與首頁內容
- 本機 port 3000 被既有服務佔用，web 開發埠改為 3100（已記錄於 todo.md）

npm run restart && npm run smoke -- A 皆通過（A-V）。
This commit is contained in:
Jeffery
2026-08-13 09:18:40 +08:00
parent 80b1383406
commit ae9c44dde7
29 changed files with 8991 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
todo.md
+10 -8
View File
@@ -111,14 +111,16 @@ flowchart TB
### A. 專案骨架與可重啟的服務
- [ ] **A-1 建立 monorepo 根目錄（XS）**：於 `/home/h3285/jsc/jiantw83/Kokorone` 建立 `package.json`（npm workspaces：`apps/*`、`packages/*`）、`.gitignore`、`.editorconfig`、`README.md`（一句話說明專案），執行 `git init` 並完成首次 commit。驗收：根目錄 `npm run` 可列出腳本、`git log` 有一筆提交。依據：技術選型「單一 monorepo 三端共用邏輯」；因本機無 pnpm，先用 npm workspaces 並在 README 註記 R-1 會遷移。
- [ ] **A-2 TypeScript 基礎設定（XS）**：建立根 `tsconfig.base.json`（`strict: true`），各 workspace 以 `extends` 繼承；建立 `packages/shared` 空套件並匯出一個型別驗證編譯鏈路。驗收：`npx tsc -b` 零錯誤。依據：技術選型「TypeScript：三端共用型別」。
- [ ] **A-3 統一日誌模組（S）**：於 `packages/shared/src/log.ts` 實作 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息` 格式輸出（時區 Asia/Taipei，等級限 INF/WRN/ERR/TRC/DBG，一行一則），api 與 web 的伺服端輸出一律走此模組。驗收：啟動 api 時輸出符合格式的啟動訊息。
- [ ] **A-4 建立 apps/api 最小 NestJS 服務（S）**：實作 `GET /health` 回 `{ status: 'ok', version, uptime }`，連接埠讀 `PORT`（預設 3001）。驗收：`curl localhost:3001/health` 回 200 且含 `status: ok`。依據：技術選型「後端 NestJS + Socket.IO」。
- [ ] **A-5 建立 apps/web 最小 Next.js 頁面（S）**：App Router + Tailwind，首頁顯示「心音 Kokorone」標題與心跳波形 SVG，套用色票 心動粉 `#FF7E9D`／暮空紫 `#8C7AE6`／晨霧白 `#FFF8FA`／夜空藍黑 `#1A1430`／墨字 `#3A3242`，並以 CSS 變數實作亮／暗模式（暗色模式為一級公民）。驗收：`http://localhost:3000` 顯示標題與波形，切換系統深色模式配色正確。依據：主視覺與資產§色彩、§視覺母題。
- [ ] **A-6 重啟與健康檢查機制（M）**：實作 `scripts/dev-restart.mjs`——讀 `.dev-pids` 停掉舊行程 → 背景啟動 api 與 web → 輪詢 `GET /health` 與 web 首頁直到皆回 200（逾時 60 秒則以非零狀態結束並輸出 ERR log）；`package.json` 加上 `npm run restart` 指向它。驗收：連續執行兩次 `npm run restart` 不會殘留重複行程且皆成功。依據：使用者要求「每完成一個階段就重新啟動服務」。
- [ ] **A-7 冒煙測試框架（M）**：實作 `scripts/smoke/run.mjs`，以 `npm run smoke -- <群組代號>` 執行 `scripts/smoke/<群組代號>.mjs`；建立 `scripts/smoke/A.mjs`（檢查 `/health` 回 200、web 首頁含「心音」字樣），失敗以非零狀態結束。驗收：`npm run smoke -- A` 全綠。
- [ ] **A-V 階段驗證（XS）**：執行 `npm run restart && npm run smoke -- A`，兩者皆通過才算本階段完成；失敗則修到通過為止，不得跳到 B。
- [x] **A-1 建立 monorepo 根目錄（XS）**：於 `/home/h3285/jsc/jiantw83/Kokorone` 建立 `package.json`（npm workspaces：`apps/*`、`packages/*`）、`.gitignore`、`.editorconfig`、`README.md`（一句話說明專案），執行 `git init` 並完成首次 commit。驗收：根目錄 `npm run` 可列出腳本、`git log` 有一筆提交。依據：技術選型「單一 monorepo 三端共用邏輯」；因本機無 pnpm，先用 npm workspaces 並在 README 註記 R-1 會遷移。
- [x] **A-2 TypeScript 基礎設定（XS）**：建立根 `tsconfig.base.json`（`strict: true`），各 workspace 以 `extends` 繼承；建立 `packages/shared` 空套件並匯出一個型別驗證編譯鏈路。驗收：`npx tsc -b` 零錯誤。依據：技術選型「TypeScript：三端共用型別」。
- [x] **A-3 統一日誌模組（S）**：於 `packages/shared/src/log.ts` 實作 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息` 格式輸出（時區 Asia/Taipei，等級限 INF/WRN/ERR/TRC/DBG，一行一則），api 與 web 的伺服端輸出一律走此模組。驗收：啟動 api 時輸出符合格式的啟動訊息。
- [x] **A-4 建立 apps/api 最小 NestJS 服務（S）**：實作 `GET /health` 回 `{ status: 'ok', version, uptime }`，連接埠讀 `PORT`（預設 3001）。驗收：`curl localhost:3001/health` 回 200 且含 `status: ok`。依據：技術選型「後端 NestJS + Socket.IO」。
- [x] **A-5 建立 apps/web 最小 Next.js 頁面（S）**：App Router + Tailwind，首頁顯示「心音 Kokorone」標題與心跳波形 SVG，套用色票 心動粉 `#FF7E9D`／暮空紫 `#8C7AE6`／晨霧白 `#FFF8FA`／夜空藍黑 `#1A1430`／墨字 `#3A3242`，並以 CSS 變數實作亮／暗模式（暗色模式為一級公民）。驗收：`http://localhost:3000` 顯示標題與波形，切換系統深色模式配色正確。依據：主視覺與資產§色彩、§視覺母題。
- [x] **A-6 重啟與健康檢查機制（M）**：實作 `scripts/dev-restart.mjs`——讀 `.dev-pids` 停掉舊行程 → 背景啟動 api 與 web → 輪詢 `GET /health` 與 web 首頁直到皆回 200（逾時 60 秒則以非零狀態結束並輸出 ERR log）；`package.json` 加上 `npm run restart` 指向它。驗收：連續執行兩次 `npm run restart` 不會殘留重複行程且皆成功。依據：使用者要求「每完成一個階段就重新啟動服務」。
- [x] **A-7 冒煙測試框架（M）**：實作 `scripts/smoke/run.mjs`，以 `npm run smoke -- <群組代號>` 執行 `scripts/smoke/<群組代號>.mjs`；建立 `scripts/smoke/A.mjs`（檢查 `/health` 回 200、web 首頁含「心音」字樣），失敗以非零狀態結束。驗收：`npm run smoke -- A` 全綠。
- [x] **A-V 階段驗證（XS）**：執行 `npm run restart && npm run smoke -- A`，兩者皆通過才算本階段完成；失敗則修到通過為止，不得跳到 B。
> **實作記錄（A 群組）**：本機 port 3000 已被既有非本專案服務佔用，web 開發埠改為 **3100**（`PORT_WEB`，可覆寫），api 維持 **3001**（`PORT_API`）。後續所有群組提及 `localhost:3000` 之處一律改讀 `localhost:3100`。
### B. 資料層與核心領域模型