code-standards

🌍 多語言支援

• 五種語言: 繁體中文、簡體中文、英文、日文、韓文
• 語言持久化: 自動記住使用者選擇的語言設定
• 即時切換: 無需重新載入頁面即可切換語言

📊 資料分析與展示

• 詳細統計顯示: 查看所有角色和載具的完整能力值
• 地形特化分析: 道路、地形、水面三種地形的專門數值
• 視覺化統計: 彩色進度條和動態圖表顯示相對強度

🔍 篩選與搜索

• 多維度排序: 依據速度、加速度、重量、操控性進行排序
• 即時搜索: 快速搜索角色和載具
• 高級篩選: 複合條件篩選和範圍選擇
• 排序記憶: 自動記住使用者的篩選偏好

💾 資料持久化

• 本地儲存: 用戶組合和偏好自動儲存到 localStorage
• 即時同步: 資料變更即時反映到 UI
• 跨設備同步: 支援未來雲端同步功能
• 備份恢復: 支援資料備份和恢復

🌙 暗色模式與主題

• 完整暗色模式: 所有組件都支援暗色主題
• 一鍵切換: 透過頭部按鈕快速切換亮色/暗色主題
• 自動持久化: 主題偏好自動儲存到本地
• 平滑過渡: 主題切換時有流暢的過渡動畫
• 優化對比度: 暗色模式下確保文字清晰可讀
• 系統適配: 支援 prefers-color-scheme 媒體查詢

核心技術

• Framework: Next.js 16.0.10 (App Router)
• UI Library: React 18.3.1
• 狀態管理: Jotai 2.16.0 + 本地持久化
• 樣式框架: Tailwind CSS 3.4.19
• 開發語言: TypeScript 5.9.3
• 套件管理: pnpm

多國語系

• i18n Framework: react-i18next 15.7.4
• 語言檢測: i18next-browser-languagedetector 8.2.0
• SSR 支援: 完整的伺服器端渲染國際化
• 語言持久化: localStorage + 智能語言檢測

```

src/

├── app/ # Next.js App Router

│ ├── admin/ # 資料同步頁面

│ │ └── page.tsx # 同步管理介面

│ ├── api/ # API 路由

│ │ └── sync-data/ # 資料同步端點

│ │ └── route.ts # Google Sheets 同步 API

│ ├── globals.css # 全域樣式

│ ├── layout.tsx # 根版面配置

│ └── page.tsx # 首頁

├── components/ # React 組件庫

│ ├── CharacterCard.tsx # 角色卡片組件

│ ├── VehicleCard.tsx # 載具卡片組件

│ ├── CombinationCard.tsx # 組合卡片組件

│ ├── RecommendationCard.tsx # 推薦卡片組件

│ ├── RecommendationsPage.tsx # 推薦頁面

│ ├── StatBar.tsx # 統計條組件

│ ├── CustomSelect.tsx # 自定義下拉選單

│ ├── LanguageSelector.tsx # 語言選擇器

│ ├── ClientOnlyWrapper.tsx # 客戶端包裝組件

│ ├── LayoutContent.tsx # 版面內容組件

│ ├── SearchModal.tsx # 搜索模態框

│ ├── SearchButton.tsx # 搜索按鈕

│ ├── PageControls.tsx # 頁面控制元件

│ ├── CombinationSelector.tsx # 組合選擇器

│ ├── DebugDataLoading.tsx # 偵錯元件

│ └── TestPersistence.tsx # 持久化測試元件

├── hooks/ # 自定義 Hooks

│ ├── useClientMounted.ts # 客戶端掛載檢查

│ ├── useMarioKartData.ts # 瑪利歐賽車資料管理

│ ├── useMarioKartStore.ts # Jotai 狀態管理

│ └── useLanguagePersistence.ts # 語言持久化管理

├── i18n/ # 國際化系統

│ ├── config.ts # i18next 配置

│ └── locales/ # 語言文件

│ ├── zh-TW.json # 繁體中文

│ ├── zh-CN.json # 簡體中文

│ ├── en.json # 英文

│ ├── ja.json # 日文

│ └── ko.json # 韓文

├── providers/ # Context Providers

│ └── JotaiProvider.tsx # Jotai Provider 配置

├── store/ # 狀態管理

│ ├── atoms.ts # Jotai atoms 定義

│ └── combinations.ts # 組合狀態管理

├── utils/ # 工具函數

│ └── csvParser.ts # CSV 解析和資料處理

├── types/ # TypeScript 類型定義

│ └── index.ts # 應用程式類型定義

└── constants/ # 應用程式常數

└── index.ts # 通用常數

```

系統需求

• Node.js 18.0 或更高版本
• pnpm 8.0 或更高版本

1. 複製專案

```bash

git clone https://github.com/Ponpon55837/MarioKartWorldParams.git

cd MarioKartWorldParams

```

2. 安裝依賴

```bash

pnpm install

```

3. 開發模式

```bash

pnpm dev

```

應用程式將在 http://localhost:3000 啟動

4. 建置生產版本

```bash

pnpm build

```

5. 啟動生產伺服器

```bash

pnpm start

```

6. 程式碼檢查

```bash

pnpm lint

```

應用程式從 public/mario-kart-data.csv public/mario-kart-data.json 讀取瑪利歐賽車資料，包含：

角色統計

• 基本能力: 速度、加速度、重量、操控性
• 地形特化: 道路、地形、水面各地形的專門數值
• 顯示數值: 遊戲中顯示的簡化數值

載具統計

• 相同統計類別: 與角色相同的能力值結構
• 載具類型: 卡丁車、機車、ATV 等分類
• 特殊屬性: 載具獨有的特性參數

組合計算

• 自動計算: 角色 + 載具 + 3 點遊戲加成
• 最大值: 理論最大值 20 (10+7+3)
• 百分比: 相對於最大值的百分比顯示

1. 語言設定

• 點擊右上角的語言選擇器切換語言
• 支援繁體中文、簡體中文、英文、日文、韓文
• 語言設定會自動儲存，重新載入後保持選擇

2. 瀏覽和篩選

• 使用頁面頂部的控制項切換角色/載具/組合頁面
• 利用篩選控制項根據不同統計類型排序
• 使用搜索功能快速找到特定角色或載具

3. 建立組合

• 在組合頁面點擊「新增組合」按鈕
• 選擇角色和載具建立新組合
• 查看組合的詳細統計資料和能力值

4. 推薦系統

• 切換到推薦頁面查看推薦組合
• 選擇不同地形查看特化推薦
• 根據排名和評分選擇最適合的組合

5. 資料分析

• 利用顏色編碼快速識別能力值優劣
• 查看詳細的統計條形圖和數值
• 比較不同組合的能力值差異

推薦組合計算

```typescript

綜合評分 = 速度 × 40% + 操控性 × 30% + 加速度 × 20% - 重量 × 10%

```

地形特化系統

• 道路 🏁: 平坦賽道，注重速度和操控性平衡
• 地形 🏔️: 越野賽道，更注重加速度和重量穩定性
• 水面 🌊: 水上賽道，需要特殊的操控技巧

多樣性控制

• 每個地形最多推薦 3 種相同載具
• 確保推薦結果的多樣性和實用性
• 避免推薦清單過度集中於少數載具

本地開發

```bash

# 開啟開發伺服器

pnpm dev

# 開啟開發者工具

# Jotai DevTools 會自動啟用

```

雙系統 Agent Skills 整合

本專案採用了軟路由共享機制，讓 OpenCode 和 GitHub Copilot 兩個 AI 系統共享同一套技能庫，避免重複維護。

#### 🔄 軟路由共享機制

```

.github/skills/ # GitHub Copilot Agent Skills

│ ├── code-standards -> ../../.opencode/skills/code-standards

│ ├── git-workflow -> ../../.opencode/skills/git-workflow

│ ├── i18n-workflow -> ../../.opencode/skills/i18n-workflow

│ ├── react-best-practices -> ../../.opencode/skills/react-best-practices

│ ├── web-design-guidelines -> ../../.opencode/skills/web-design-guidelines

│ └── readme-maintenance/ # 新技能：README 維護指南

│

.opencode/skills/ # OpenCode Agent Skills

│ ├── code-standards/

│ ├── git-workflow/

│ ├── i18n-workflow/

│ ├── react-best-practices/

│ ├── web-design-guidelines/

│ └── readme-maintenance -> ../../.github/skills/readme-maintenance

```

🎯 優勢：

• ✅ 單一維護點：修改一次，兩個系統同步更新
• ✅ 無縫整合：兩個 AI 系統都能存取完整的技能庫
• ✅ 自動同步：透過符號連結實現即時同步
• ✅ 節省時間：避免重複維護相同內容

#### 🛠️ 可用的 Skills

專案自訂 Skills：

• git-workflow: Git 分支命名與工作流程規範

- 標準化的分支命名格式 (//)

- 分支類型: feat, fix, refactor, docs, style, test, chore

- Git 工作流程最佳實踐

- 支援中文 commit message 規範

• code-standards: Next.js App Router 與 TypeScript 編碼規範

- Next.js 16 App Router 規範

- TypeScript 嚴格模式與型別定義

- Jotai 狀態管理規範（優先使用 atoms，避免 props drilling）

- Tailwind CSS 樣式規範

- 開發測試流程與強制性驗證步驟

• i18n-workflow: 多語言國際化開發流程

- 五語言支援 (繁中、簡中、英、日、韓)

- i18next 使用方式

- 翻譯檔案管理流程

- 語言持久化實現

• readme-maintenance: README.md 維護與文檔同步指南 🆕

- 技術棧版本自動同步檢查

- 專案結構變更更新流程

- 功能變更文檔化規範

- 雙系統技能整合驗證

- 自動化檢查腳本範本

Vercel Labs Skills：

• react-best-practices: React 與 Next.js 性能優化指南 (來自 Vercel Engineering)

- 40+ 條規則，涵蓋 8 大類別，按影響程度分級

- 消除 Waterfalls (關鍵): 非同步操作優化、Promise.all()、Suspense 邊界

- Bundle Size 優化 (關鍵): 避免 barrel imports、動態匯入、延遲載入

- 伺服器端效能 (高): React.cache()、LRU 快取、平行資料獲取

- 客戶端資料獲取 (中高): SWR、事件監聽器去重

- Re-render 優化 (中): memo、衍生狀態、transitions

- 渲染效能 (中): SVG 優化、content-visibility、靜態 JSX

- JavaScript 效能 (低中): 快取優化、Set/Map 查找、迴圈優化

- 進階模式 (低): useLatest、事件處理器 refs

• web-design-guidelines: Web 介面設計最佳實踐檢查

- 100+ 條 UI/UX 規則，用於審查前端程式碼

- 無障礙性: aria-labels、語義化 HTML、鍵盤處理

- 焦點狀態: 可見的焦點、focus-visible 模式

- 表單: autocomplete、驗證、錯誤處理

- 動畫: prefers-reduced-motion、compositor-friendly transforms

- 排版: 彎引號、省略號、tabular-nums

- 圖片: 尺寸、延遲載入、alt 文字

- 效能: 虛擬化、避免 layout thrashing、preconnect

- 導航與狀態: URL 反映狀態、深度連結

- 深色模式與主題: color-scheme、theme-color meta

- 觸控與互動: touch-action、tap-highlight

- 本地化與 i18n: Intl.DateTimeFormat、Intl.NumberFormat

#### 🎯 如何使用 Agent Skills

OpenCode AI 使用者：

```bash

# OpenCode 會自動載入專案中的 skills

# 在對話中提及相關主題時，AI 會自動參考對應的 skill

```

GitHub Copilot 使用者：

• GitHub Copilot 會自動偵測 .github/skills/ 目錄中的技能
• 在相關開發任務中，Copilot 會自動載入對應的技能指南
• 支援 VS Code、Copilot CLI 和 GitHub.com 中的 agent 模式

#### 📁 雙系統配置結構

```

.opencode/ # OpenCode 配置

├── README.md # AI 助手必讀檔案

├── config.yaml # 專案配置規則

├── hooks/

│ └── pre-modify.sh # 檔案修改前檢查

└── skills/

├── git