實戰開發：基於 Vue 3 與 Laravel 12 的 Cyberpunk O2O 抓寶系統

本文分享一個結合地理位置服務（LBS）與實體核銷（O2O）的遊戲化應用開發心得。專案以賽博朋克視覺為核心，實作從地圖捕捉、背包管理到 QR Code 兌換的完整全端流程。

您可以透過以下 GitHub 連結檢閱本專案的原始碼：https://github.com/BpsEason/pokemon-o2o-demo.git

一、 系統架構與技術棧

本專案採用前後端分離架構，利用 Laravel 12 的高效 API 處理能力與 Vue 3 的響應式介面進行整合。

• 前端：Vue 3 (Composition API)、Vite、Tailwind CSS、Leaflet (地圖交互)、Axios (全域攔截器)。

• 後端：Laravel 12、JWT-auth (認證)、MySQL、Docker 容器化環境。

• 核心邏輯：地圖座標校驗 -> JWT 身份驗證 -> 背包數據持久化 -> QR Code 核銷機制。

二、 前端技術實作

1. Cyberpunk 視覺規範

利用 Tailwind CSS 的自定義配置實現霓虹美學：

• 視覺堆疊：結合 backdrop-blur（毛玻璃）與 drop-shadow（霓虹發光）構建組件層次感。

• 自定義動畫：實作 CSS @keyframes 動畫，如背景掃描線（Scanline）與標記脈動（Pulse）效果，提升遊戲化介面的沉浸感。

2. Leaflet 地圖與 LBS 交互

地圖組件負責處理座標邏輯與標記渲染：

• 動態標記：透過 API 獲取寶物經緯度，並利用 Leaflet 的 L.divIcon 渲染具備 CSS 特效的標記。

• 事件驅動：偵測玩家點擊事件，觸發後端 API 請求，並根據回傳數據即時更新 UI 狀態（成功捕捉/錯誤提示）。

三、 後端 API 與 安全認證

1. Laravel 12 與 JWT 認證

在 Laravel 12 環境下，我們實作了嚴謹的 API 安全機制：

• 身份驗證：利用 JWT 套件管理用戶狀態，所有遊戲核心 API 均受 auth:api 中間件保護。

• 無感刷新 (Silent Refresh)：

  • Axios 攔截器：偵測 401 錯誤。

  • 自動重試：當 Token 過期時，前端自動發起 /api/refresh 請求。成功取得新 Token 後，系統會自動重發先前失敗的請求，確保玩家捕捉過程不因認證過期而中斷。

2. O2O 兌換與數據邏輯

• 關聯設計：使用 User 與 Item 的多對多關聯（Pivot Table）管理背包數據。

• 核銷安全：後端生成具備唯一性的兌換字串。核銷 API 會嚴格檢查 redeemed_at 欄位，確保寶物僅能被實體核銷一次。

四、 開發挑戰與優化

1. 並行請求處理：為解決多個 API 同時觸發 Token 刷新的競爭條件，在 Axios 攔截器中建立請求佇列，確保重新認證過程的單一性。

2. Docker 部署優化：針對 Demo 場景，優化 .gitignore 配置以保留關鍵環境設定，並透過 Laravel 的 Migration 與 Seeder 機制快速建構初始測試數據。

五、 總結

本專案透過 Laravel 12 與 Vue 3 的整合，解決了認證管理、即時地圖交互與 O2O 商務邏輯等核心問題。這不僅是一次全端技術的實踐，也驗證了遊戲化機制在數位化行銷中的應用潛力。