🏎️ 瑪利歐賽車世界參數工具 (Mario Kart World Parameters)

一個功能豐富的 React/Next.js 應用程式，用於分析和比較瑪利歐賽車角色與載具統計資料，提供智能推薦系統和高性能的使用者體驗。

🌟 功能特色

🌍 多語言支援

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

📊 資料分析與展示

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

🔍 篩選與搜索

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

💾 資料持久化

本地儲存: 用戶組合和偏好自動儲存到 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. 複製專案

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

2. 安裝依賴

pnpm install

3. 開發模式

pnpm dev

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

4. 建置生產版本

pnpm build

5. 啟動生產伺服器

pnpm start

6. 程式碼檢查

pnpm lint

📊 資料格式

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

角色統計

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

載具統計

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

組合計算

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

🎮 使用方式

1. 語言設定

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

2. 瀏覽和篩選

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

3. 建立組合

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

4. 推薦系統

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

5. 資料分析

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

🎯 特色功能詳解

地形特化系統

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

多樣性控制

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

🔧 開發指南

本地開發

# 開啟開發伺服器
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 分支命名與工作流程規範
- 標準化的分支命名格式 (<type>/<name>/<description>)
- 分支類型: 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 使用者：

# 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-workflow/           # Git 規範
    ├── code-standards/         # 程式碼標準
    ├── i18n-workflow/         # 多語言流程
    ├── react-best-practices/   # React 效能最佳化
    ├── web-design-guidelines/   # UI/UX 最佳實踐
    └── readme-maintenance/ -> ../../.github/skills/readme-maintenance

.github/skills/                # GitHub Copilot 技能
├── git-workflow -> ../../.opencode/skills/git-workflow
├── code-standards -> ../../.opencode/skills/code-standards
├── 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/README.md - AI 啟動時必讀
- 包含最關鍵的操作規範
- 防止在 main 分支上直接修改
- 強制執行 Git 工作流程
.opencode/config.yaml - 專案行為配置
- 定義 AI 的自動檢查規則
- 設定 skills 自動載入時機
- 配置檔案修改前後的檢查流程
.opencode/hooks/pre-modify.sh - 自動檢查腳本
- 在修改任何檔案前自動執行
- 驗證目前不在 main 分支
- 確保分支命名符合規範

Skills 文件說明

每個 skill 都包含：

功能說明和使用時機
詳細的開發規範和範例
最佳實踐和注意事項
常見問題解答
相關參考資源

開發者可以直接閱讀這些檔案來了解專案規範，或者讓 OpenCode AI 自動參考這些 skills 來協助開發。

🔒 防錯機制

本專案實施以下防錯措施：

✅ 禁止在 main 分支直接修改檔案
✅ 強制使用功能分支開發
✅ 自動檢查分支命名規範
✅ Commit message 必須使用繁體中文
✅ 推送前必須經過使用者確認
✅ 修改後必須進行測試

🚨 已知問題

開發環境警告

TypeScript 5.8.3 版本超出官方支援範圍 (>=4.7.4 <5.5.0)
jotai-devtools 將在未來版本中移除自動 tree-shaking
某些 pnpm 快取檔案可能導致編譯警告

解決方案

# 清除快取
rm -rf .next
pnpm dev

# 重設 pnpm 快取
pnpm store prune

🤝 貢獻指南

歡迎貢獻程式碼、回報問題或建議新功能！

🎨 設計特色

視覺設計

現代化界面: 清潔、簡潔的設計風格
彩色編碼: 直觀的顏色系統表示不同能力值
動畫效果: 流暢的過渡和互動效果
圖標系統: 豐富的表情符號和圖標

使用者體驗

直觀操作: 簡單易懂的操作流程
即時反饋: 操作後立即顯示結果
錯誤處理: 友好的錯誤提示和處理
載入狀態: 清晰的載入指示器

🔐 安全性

資料安全

本地儲存: 所有資料僅存於用戶本地
無伺服器: 純前端應用，無後端資料收集
隱私保護: 不收集任何個人資訊
開源透明: 程式碼完全開源，可供審核

📄 授權

此專案採用 MIT 授權條款 - 詳見 LICENSE 檔案

🙏 致謝

感謝 Nintendo 提供瑪利歐賽車系列遊戲
感謝 React 和 Next.js 社群的開源貢獻
感謝 Jotai 團隊提供優秀的狀態管理方案
感謝 Tailwind CSS 團隊提供強大的樣式框架
感謝任天堂玩家社群分享的資料內容
感謝所有測試用戶的回饋和建議

⭐ 如果此專案對你有幫助，請給我們一個 star！

🐛 發現問題？請在 Issues 中回報

💡 有好的建議？歡迎在 Discussions 中分享

🚀 想要貢獻？查看我們的貢獻指南

📋 查看發展藍圖？參考我們的 Roadmap

🚀 需要部署協助？查看部署指南

Name		Name	Last commit message	Last commit date
Latest commit History 139 Commits
.githooks		.githooks
.github		.github
.opencode		.opencode
openspec		openspec
public		public
src		src
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
.vercelignore		.vercelignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
next-env.d.ts		next-env.d.ts
next.config.js		next.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

License

Ponpon55837/MarioKartWorldParams

Folders and files

Latest commit

History

Repository files navigation