TCGToolWS

專為 Weiss Schwarz (WS) 玩家打造的現代化卡片瀏覽與牌組管理工具。

📖 目錄

• 專案簡介
• 主要功能
• 系統架構
• 快速開始
  • 環境變數設定
  • 安裝與執行
• 開發規範
• 貢獻
• 免責聲明

專案簡介

TCGToolWS 是一個基於 Vue 構建的網站，旨在提供流暢的 Weiss Schwarz 卡片查詢體驗。透過響應式設計，無論是在桌面電腦還是行動裝置上，都能輕鬆管理您的牌組與瀏覽最新的卡片系列。

✨ 主要功能

• 卡片瀏覽: 快速檢索與瀏覽 WS 全系列卡片資料。
• 牌組管理: 直觀的介面讓您輕鬆組建、編輯與儲存牌組。
• 全局搜索: 強大的索引功能，支援跨系列關鍵字搜尋。
• 響應式 UI: 基於 Vuetify 3 的 Material Design 設計，適配各種螢幕尺寸。

系統架構

本專案採用 Serverless (無伺服器) 架構：

類別	技術 / 套件	說明
核心架構	Cloudflare Workers	(核心) Serverless 運算環境，處理 API 與後端邏輯
後端框架	Hono	處理 API 路由
資料庫	Cloudflare D1	基於邊緣運算的 Serverless SQL 資料庫
部署工具	Wrangler	Cloudflare 專用 CLI，用於本地開發與部署
前端框架	Vue 3	使用 Composition API 與 <script setup> 語法
建構工具	Vite	極速的開發伺服器與打包工具
UI 框架	Vuetify 3	強大的 Vue UI 元件庫
狀態管理	Pinia	直觀且輕量的狀態管理庫
路由管理	Vue Router	處理 SPA 頁面導航
程式碼品質	ESLint + Prettier	確保程式碼風格一致性與品質

快速開始

環境變數設定

在啟動專案前，請先在根目錄建立 .env 檔案（可複製 .env.dev 作為模板）。

關鍵變數說明：

變數名稱	描述	範例 / 備註
VITE_IMAGE_BASE_URL	(核心) 卡片圖片的來源路徑	見下方圖片來源詳細說明
VITE_BLUR_IMAGE_BASE_URL	(核心) 卡片縮圖的來源路徑	見下方圖片來源詳細說明
JWT_SECRET	JWT 簽名密鑰	必填 (開發環境可填任意字串)
BREVO_API_KEY	Brevo 郵件服務 API Key	用於發送系統郵件
FRONTEND_URL	前端部署網址	用於生成郵件內的連結
AFDIAN_PUBLIC_KEY	愛發電支付公鑰	處理贊助與支付邏輯

關於圖片來源的設定

您可以選擇以下兩種方式之一來設定圖片來源：

1. 使用URL (推薦)

   直接連結圖片庫，無需下載大量檔案。

   VITE_IMAGE_BASE_URL=https://media.githubusercontent.com/media/U-CLIMAX/ws-image-data/main/ws-image-data
   VITE_BLUR_IMAGE_BASE_URL=https://media.githubusercontent.com/media/U-CLIMAX/ws-image-data/main/ws-blur-image-data

2. 使用本地圖片

   • 第一步：執行腳本下載圖片

     npm run setup-img

   • 第二步：修改環境變數

     VITE_IMAGE_BASE_URL=ws-image-data
     VITE_BLUR_IMAGE_BASE_URL=ws-blur-image-data

開發環境資料庫設定

若要在本地環境進行登入與權限測試，請依序執行以下步驟：

1. 初始化本地資料庫

   npm run db:init

2. 建立測試管理員帳號 執行以下指令將預設 Admin 帳號寫入本地 D1 資料庫：

   npx wrangler d1 execute ws-account-db --local --command="INSERT INTO users (id, email, hashed_password, salt, role) VALUES ('f892bf9e-f8c3-4c87-9a9a-1c3bc38547c0', '[email protected]', '9d7edc1be25e6ea2227d9b916fb0c0eb8f8d4dd01b3fc06fdb022941aa0b1a27', 'c26f314e-4570-47c1-abb1-712bd7964fb9', 0);"

3. 登入資訊 完成上述步驟後，您可以使用以下資訊登入：

   • Email: [email protected]
   • Password: 12345678

Important

雖然是測試帳號，但後端仍需要 JWT_SECRET 來簽發登入 Token。請確保您的 .env 檔案中包含該變數（開發環境可設為任意值，如 dev_secret），否則登入將會失敗。

安裝與執行

請確保您的環境已安裝 Node.js (建議 v20+)。

1. 安裝相依套件

   npm install

2. 建立搜尋索引 (初次執行必備)

   npm run build:index

3. 啟動開發伺服器

   npm run dev

   開啟瀏覽器訪問顯示的 Local URL (預設為 http://localhost:5173)。

4. 建構生產版本

   npm run build

開發規範

為了維護程式碼品質，請遵守以下規範：

• 元件風格: 全面使用 Vue 3 <script setup> 單一檔案元件 (SFC)。

• 函式風格:

  • 統一使用 箭頭函式 (Arrow Functions) 定義方法。
  • 例：const handleClick = () => { ... } 而非 function handleClick() { ... }。

• 路徑引用: 使用 @ 作為 src/ 目錄的別名 (例: import Foo from '@/components/Foo.vue')。

• 格式化與檢查: 提交程式碼前，請務必執行以下指令確保通過檢查：

  # 格式化程式碼 (Prettier)
  npm run format
  
  # 語法檢查與自動修正 (ESLint)
  npm run lint

貢獻

歡迎提交 Pull Request 或 Issue！ 在提交 PR 前，請確保：

1. 已執行 npm run format 與 npm run lint。
2. 新功能需附上簡單的測試或截圖說明。

免責聲明

本專案為非官方粉絲製作工具，與 Bushiroad 無任何關聯。 卡片圖片與資料版權歸 Bushiroad 及各相關版權方所有。 本專案僅供學習與交流使用，請勿用於商業用途。