SnowTrace Platform

SnowTrace 是一個全面性的滑雪運動愛好者平台，採用微服務架構，旨在幫助滑雪愛好者規劃行程、找到滑雪夥伴、紀錄滑雪足跡、管理滑雪裝備、追蹤滑雪成就，以及視覺化個人滑雪歷程。

架構概覽

本平台由多個相互關聯的服務組成：

後端服務

• user-core：使用者身份和核心資料服務，作為所有使用者資料的單一真實來源
• resort-services：雪場資訊服務，管理 43 個日本滑雪場的詳細資料
• snowbuddy-matching：智慧雪伴匹配引擎，幫助使用者找到最適合的滑雪夥伴
• trip-planner API（tour）：Next.js Route Handlers + Prisma，為行程規劃器提供 Trip/Day/Item CRUD、Checklist/Packing 勾選與雪場資料整合；依賴 user-core（認證）與 resort-services（雪場資料）

前端應用

• ski-platform：React + TypeScript Web 應用，提供完整的用戶界面和互動體驗
• trip-planner（tour）：Next.js 15 + Tailwind 行程規劃器，主打模板化 Trip 建立、Day/Item 編輯、Checklist/Packing 清單與即時樂觀更新體驗，未來將嵌入 ski-platform

功能特性

🎿 核心功能

• 智能行程規劃

  • AI 對話助手：自然語言創建行程（如「新增苗場2月3到7日」）
  • 支援 43 個日本知名雪場識別（別名系統 + 優先級匹配）
  • 行程管理：建立、查看、編輯、刪除
  • 雪季管理：自動雪季創建和統計
  • 行程狀態追蹤：規劃中、已確認、已完成、已取消

• 滑雪足跡紀錄

  • 雪道紀錄和統計
  • 成就系統：解鎖各類滑雪成就
  • 個人滑雪數據可視化

• 社交互動與智慧媒合

  • 活動動態 Feed：即時查看雪友動態和成就

  • 雪伴公佈欄系統

    • 瀏覽所有公開行程（自動排序：已申請 > 有新申請 > 時間順序）
    • 多維度篩選：按時間（本月/下月/未來 N 月）、雪場、申請狀態
    • 一鍵申請加入行程
    • 申請狀態追蹤：可申請、申請中、已加入、已額滿、已拒絕
    • 取消申請功能（僅 pending 狀態）

  • 雪伴申請管理

    • 行程主人接受/拒絕申請
    • 實時通知系統：導航欄紅色徽章顯示待處理數量
    • 通知下拉選單：直接在選單中處理申請
    • 自動更新機制：每 30 秒刷新通知
    • 點擊通知跳轉至行程詳情

  • 智慧雪伴媒合引擎

    • 多維度匹配算法：技能等級（30%）、地點偏好（25%）、時間可用性（20%）、角色匹配（15%）、知識水平（10%）
    • 候選人智能過濾：排除不符合條件的用戶，提升匹配效率
    • 角色媒合：雪友配對、教練尋找學生、學生尋找教練
    • 知識分數整合：基於 knowledge-engagement 服務的技能檔案
    • 匿名化摘要：保護隱私的前提下展示匹配結果
    • 媒合生命週期管理：請求 → 通知 → 接受/拒絕 → 確認
    • 行為事件追蹤：所有媒合動作回寫至 user-core

  • 單板教學整合（進階媒合）

    • 基於學習行為的智能媒合：利用單板教學 App 同步到 user-core 的資料
    • 5 種進階匹配算法：
      1. 技能等級匹配：基於 experience_level（beginner/intermediate/advanced）
      2. 學習進度匹配：基於已完成課程的 Jaccard 相似度
      3. 練習評分匹配：基於練習平均評分的相似度
      4. 學習興趣匹配：基於搜尋關鍵字和收藏課程的重疊度
      5. 教練學生匹配：為需要幫助的學生推薦合適教練
    • 學習行為追蹤：課程瀏覽、練習完成、搜尋、收藏等事件
    • 教練推薦系統：識別學生困難領域，匹配專長教練
    • 資料來源：user-core BehaviorEvent（source_project: snowboard-teaching）
    • 詳見：specs/snowbuddy-matching/SNOWBOARD_TEACHING_INTEGRATION.md

• 裝備管理

  • 個人裝備庫：建立、編輯、刪除裝備資訊
  • 裝備分類：單板、固定器、雪靴、頭盔、雪鏡等
  • 狀態管理：使用中、待售、已售出
  • 裝備檢查紀錄：紀錄保養和檢查歷史
  • 維護提醒：自動提醒裝備保養時間
  • 二手市場：發布/搜尋待售裝備，聯繫賣家

• 滑雪征服地圖

  • 日本滑雪區域地圖視覺化
  • 顯示已去過的雪場區域
  • 個人滑雪足跡展示

• 雪場資訊

  • 43 個日本雪場資料庫
  • 雪場詳情查詢
  • 雪況統計和設施資訊

🤖 AI 對話助手特性

• 自然語言理解

  • 支援多種表達方式（如「去二世谷」、「二世谷 12月20日 5天」）
  • 智能缺失資訊補全（多輪對話）
  • 意圖識別：建立行程、查看行程、刪除行程、閒聊

• 雪場識別系統

  • 別名配置（如「二世谷」、「Niseko」、「新雪谷」）
  • 優先級匹配（熱門雪場優先）
  • 模糊匹配和建議（Levenshtein 距離）

• 對話狀態管理

  • 連續行程創建支援
  • 上下文保持和累積資料
  • 錯誤處理和友好提示

🤝 雪伴公佈欄特性

• 行程瀏覽和篩選

  • 瀏覽所有公開行程
  • 按時間篩選：本月、下月、未來 N 個月
  • 按雪場篩選：43 個雪場智能過濾
  • 按狀態篩選：可申請、申請中、已加入、已額滿、已拒絕

• 雪伴申請系統

  • 一鍵申請加入公開行程
  • 申請狀態實時追蹤（pending、accepted、declined）
  • 取消申請功能（僅 pending 狀態）
  • 行程主人接受/拒絕申請

• 實時通知系統

  • 導航欄通知鈴鐺：顯示待處理申請數量紅色徽章
  • 自動更新機制：每 30 秒自動刷新
  • 通知下拉選單：直接在下拉選單中接受/拒絕申請
  • 點擊通知可跳轉至行程詳情

🎒 裝備管理特性

• 個人裝備庫

  • 建立裝備：名稱、品牌、類別（單板/固定器/雪靴/頭盔/雪鏡/其他）
  • 用途標記：個人使用 / 教學用
  • 狀態管理：使用中、待售、已售出
  • 裝備過濾：按狀態、用途快速篩選

• 裝備檢查與維護

  • 檢查紀錄：紀錄每次保養和檢查的詳細資訊
  • 檢查歷史：查看裝備完整的維護時間軸
  • 維護提醒：自動提醒裝備保養到期時間
  • 提醒管理：查看和取消維護提醒

• 二手市場

  • 發布待售：設定售價（支援多種貨幣）
  • 搜尋裝備：按類別、價格範圍搜尋
  • 聯繫賣家：站內訊息聯繫功能
  • 交易管理：追蹤待售裝備狀態

🗾 滑雪征服地圖特性

• 視覺化地圖

  • 日本滑雪區域互動地圖
  • 顯示已征服的雪場區域
  • 區域點擊查看詳情

• 足跡統計

  • 已去過的雪場數量統計
  • 區域覆蓋率展示
  • 個人滑雪足跡視覺化

🏂 單板教學系統（獨立應用）

位置: specs/單板教學/
技術棧: Next.js 15 + React 19 + Supabase + Tailwind CSS

滑雪板教學內容管理系統，基於 CASI 認證教學框架，專為雪場使用設計。

核心特色

• 雪場優化設計

  • 手機優先 UI：觸控目標 ≥44px（WCAG 標準）
  • 戴手套操作：大按鈕、大觸控區
  • 強光下閱讀：高對比深色主題
  • 弱網環境：自動重試機制、錯誤邊界
  • 震動回饋：Android 觸覺反饋
  • 省電模式：支援 prefers-reduced-motion

• Alpine Velocity 美學系統

  • 速度感設計：斜切角邊緣、速度光暈、3 層光影
  • 字體系統：Bebas Neue（Display）+ Space Mono（Body）
  • 動畫效果：滾動斜向滑入、脈動光暈、點擊回饋
  • Snow Mode：頂部環境光暈、文字陰影強化
  • 評分：9.6/10（Frontend Design Skill）

前台功能

• 課程系統
  • 課程列表：搜尋、分類篩選、收藏
  • 課程詳情：問題/目標/練習方法/做對做錯訊號
  • 練習紀錄：紀錄每次練習心得（需登入）
  • 付費方案：7天/30天/年費訂閱
  • 意見回報：Bug/課程許願/功能許願

後台數據分析

• Dashboard 面板

  • 💡 快速洞察：自動分析數據給出建議
  • 🔍 內容缺口：搜尋無結果 TOP 10
  • 📊 課程來源：首頁/搜尋/分類/相關課程佔比
  • 🔥 熱門課程/搜尋：了解用戶需求

• 追蹤事件

  • view_lesson：瀏覽課程（含來源）
  • search_keyword：搜尋關鍵字
  • search_no_result：搜尋無結果（發現內容缺口）
  • scroll_depth：滾動深度（判斷內容長度）
  • practice_start/complete：練習完成率和有效度

• 管理功能

• 用戶管理：搜尋用戶、手動開通訂閱

Trip Planner（tour）整合說明

角色定位

• 服務邊界：負責 Trip/Day/Item/Checklist/Packing 的整體生命週期，其他服務僅透過 API 消費資料或提供輔助資訊（例如 resort-services 提供雪場資料）。
• 資料依賴：
  • Trip Planner 採 Prisma/PostgreSQL 儲存，Trip 內會引用 user-core 的 user_id，並綁定 resort-services 的 resort_id
  • 與 user-core 的 POST /users/{user_id}/ski-preferences API 整合，行程建立/更新即時同步使用者偏好雪場
  • 與 snowbuddy-matching 的 /matching/searches + /matching/searches/{id} 串接，Trip Header 顯示 AI 推薦雪友
• 部署型態：Next.js 15 App Router + Route Handlers，既是前端 UI 也是後端 API；可獨立部署於 Vercel / Zeabur / Docker。

環境變數與 Prisma DB 需求

在 tour/.env（或環境變數）設定：

DATABASE_URL=postgresql://snowtrace_trip:snowtrace_trip@localhost:5450/trip_planner
NODE_ENV=development
RESORT_API_BASE_URL=http://localhost:8000
USER_CORE_API_URL=http://localhost:8001
SNOWBUDDY_API_URL=http://localhost:8002

• DATABASE_URL：必要。Prisma 會依此連接資料庫並建立 Trip/Day/Item/ChecklistItem/PackingItem 五張表。
• 建議獨立資料庫（trip_planner），避免與 user-core 共用 schema。
• 本地初始化流程：
  1. cd tour
  2. npm install
  3. npx prisma migrate dev
  4. npm run dev

docker-compose 服務建議

Trip Planner 預計以兩個服務加入 docker-compose.yml：

trip-planner-db:
  image: postgres:15-alpine
  environment:
    - POSTGRES_USER=snowtrace_trip
    - POSTGRES_PASSWORD=snowtrace_trip
    - POSTGRES_DB=trip_planner
  volumes:
    - trip_planner_data:/var/lib/postgresql/data/

trip-planner:
  build:
    context: ./tour
    dockerfile: Dockerfile
  environment:
    - DATABASE_URL=postgresql://snowtrace_trip:snowtrace_trip@trip-planner-db:5432/trip_planner
    - RESORT_API_BASE_URL=http://resort-api:8000
    - USER_CORE_API_URL=http://user-core:8001
    - SNOWBUDDY_API_URL=http://snowbuddy-matching:8002
  ports:
    - "3010:3000"
  depends_on:
    - trip-planner-db
    - resort-api
    - user-core

• 可以與既有 db、frontend 服務並行啟動，對其他服務僅為 read-only 消費者。

• 若僅需本地前端 UI，可跳過 Docker，直接使用 npm run dev，但仍需 PostgreSQL。

  • 回報管理：查看/篩選用戶回報
  • 課程分析：熱門/有效度/健康度/熱力圖
  • 付費分析：轉換率、方案分布、漏斗

User Core 整合（Phase 3）

• 錯誤監控和性能追蹤
• 配置管理系統
• CASI 技能同步機制
• 生產環境部署：Zeabur + Supabase

詳見：specs/單板教學/README.md, specs/單板教學/PHASE3_COMPLETE.md

🔐 技術特性

• 統一認證系統：所有服務使用 user-core 的集中式認證
• 使用者身份管理與個人資料
• 行為事件紀錄與分析
• 安全的 API 端點保護（Bearer Token / X-User-Id）

技術架構

後端

• 微服務架構：採用 Python + FastAPI 開發
• 統一認證：共享認證模組，環境感知的安全機制
• 容器化：使用 Docker 和 Docker Compose 進行部署
• 資料庫：PostgreSQL 用於使用者資料，Redis 用於快取和非同步任務
• API 標準：開放 API 規範，提供完整的 REST API
• 測試驅動開發：95+ 測試涵蓋所有核心功能

前端

• 框架：React 18 + TypeScript
• 狀態管理：Redux Toolkit
• 路由：React Router v6
• 樣式：Tailwind CSS
• 構建工具：Vite
• API 通信：Axios

快速開始

前置需求

• Docker
• Docker Compose
• Node.js 18+ (僅前端開發)

部署步驟

後端服務

1. 克隆此儲存庫：

   git clone https://github.com/James3014/snow-project.git
   cd snow-project

2. 啟動服務：

   docker-compose up --build

3. 服務將在以下端點運行：

   • User Core API: http://localhost:8001
   • Resort API: http://localhost:8000
   • Snowbuddy Matching API: http://localhost:8002
   • API 文件: http://localhost:8000/docs (Resort API)

前端應用

1. 進入前端目錄：

   cd platform/frontend/ski-platform

2. 安裝依賴：

   npm install

3. 啟動開發伺服器：

   npm run dev

4. 應用將在 http://localhost:5173 運行

5. 構建生產版本：

   npm run build

服務說明

User Core Service (user-core)

• 處理所有使用者身份和個人資料
• 提供認證 API (/auth/login, /auth/validate)
• 管理使用者行為事件紀錄
• 提供其他服務所需的使用者資料

Resort Services API (resort-api)

• 提供雪場資訊查詢（公開端點）
• 管理 43 個日本滑雪場的靜態資料
• 受保護：滑雪足跡紀錄需要認證
• 支援分頁查詢（limit/offset）

Snowbuddy Matching Service (snowbuddy-matching)

• 全部需要認證：所有匹配和配對端點
• 實現非同步雪伴搜尋功能
• 執行基於技能、地點和時間偏好的匹配算法
• 處理雪伴邀請和接受流程

Frontend Platform (ski-platform)

• React + TypeScript Web 應用
• AI 對話助手界面
• 行程規劃和管理介面
• 滑雪足跡紀錄介面
• 成就系統和社交動態
• 響應式設計，支援桌面和移動端

開發進度

後端服務

• ✅ user-core: 功能完整 (100%) - 含認證 API 和完整測試套件
• ✅ resort-services: 功能完整 (100%) - API 完整實作含認證
• ✅ snowbuddy-matching: 功能完整 (100%) - 智能匹配引擎含認證
• ✅ 統一認證架構: 完整 (100%) - 所有服務使用集中式認證

前端應用

• ✅ 使用者認證: 登入、註冊、個人資料管理 (100%)
• ✅ 行程規劃系統: 完整 CRUD + AI 助手 (100%)
  • ✅ AI 對話助手
  • ✅ 雪場識別（43 個雪場）
  • ✅ 自然語言行程創建
  • ✅ 行程編輯和刪除
  • ✅ 雪季自動管理
• ✅ 滑雪足跡紀錄: 雪道紀錄和統計 (100%)
• ✅ 成就系統: 成就解鎖和展示 (100%)
• ✅ 社交動態: Activity Feed (100%)
• ✅ 雪伴系統: 雪伴公佈欄、申請管理、實時通知 (100%)
• ✅ 裝備管理: 裝備庫、檢查紀錄、維護提醒、二手市場 (100%)
• ✅ 滑雪征服地圖: 日本區域地圖視覺化 (100%)
• ✅ 雪場資訊: 43 個雪場詳情查詢 (100%)

未來規劃

• 🟡 coach-scheduling: 教練預約系統 - 規劃完成，待實作
• 🔵 knowledge-engagement: 知識社群系統 - 規劃階段

最新更新

2025-12-03 - 雪場 Logo 系統完成

• ✅ 43 個雪場 Logo 完整整合
  • 所有日本雪場 logo 統一尺寸 1024x1024
  • 白色背景容器設計，適配深色介面
  • ResortList、ResortDetail、ResortCard 組件優化
  • 圓角設計、陰影效果、響應式佈局

2025-12-02 - Glacial Futurism 設計系統 & 品牌重塑

• ✅ SnowTrace 品牌重塑
  • 平台名稱從 DIYSKI 更新為 SnowTrace
  • 全面繁體中文化
  • Glacial Futurism 視覺設計系統
• ✅ 系統架構優化
  • trip_planning_service 模組化拆分
  • TypeScript 類型錯誤修復
  • 錯誤邊界和重試機制
  • Lazy loading 路由優化

2025-11-15 - 雪伴功能優化 & 繁體中文完善

• ✅ 雪伴申請系統優化
  • 修復取消申請 400 錯誤：已拒絕的申請不再顯示「移除紀錄」按鈕
  • 修復通知鈴鐺功能：紅色數字徽章自動顯示待處理申請數量
  • 添加自動更新機制：每 30 秒自動刷新通知數量
  • 首次載入時自動獲取待處理申請
• ✅ 繁體中文完善
  • 全面檢查並修復系統中的簡體字
  • 修復範圍：使用者界面、組件註釋、AI 功能相關檔案
  • 確保所有文字統一使用繁體中文

2025-11-11 - AI 助手增強 & 刪除功能

• ✅ 修復雪場識別 Bug: 解決 API 分頁問題，現在可識別所有 43 個雪場
• ✅ AI 對話刪除功能: 新增 DELETE_TRIP 意圖識別和處理
  • 支援「刪除苗場行程」、「刪除第1個行程」等多種表達
  • 智能匹配待刪除行程（按雪場、日期、編號）
  • 確認對話框防止誤刪
• ✅ 行程詳情刪除按鈕: 在行程詳情頁面添加實體刪除按鈕
  • 紅色警告樣式的刪除按鈕
  • 模態確認對話框
  • 刪除中載入動畫
  • 刪除成功自動返回
• ✅ 對話狀態修復: 修復行程建立後無法繼續操作的問題

2025-11-05 - 統一認證系統

• ✅ 🔐 統一認證架構: 完整的認證系統跨所有服務
  • User-core 認證 API (/auth/login, /auth/validate)
  • 共享認證模組 (shared/auth.py)
  • 環境感知安全機制（開發/生產模式）
  • Bearer Token 和 X-User-Id 支援
• ✅ 95+ 測試: 完整的單元、契約、整合、認證測試
• ✅ 遷移工具: user-core legacy data migration script
• ✅ Makefile: 開發便利工具
• ✅ 完整文檔: 所有服務都有 spec, plan, tasks + 認證指南

📊 測試覆蓋率

• user-core: 65 tests ✅
• resort-services: 9 tests (含 4 個認證測試) ✅
• snowbuddy-matching: 14 tests (含 6 個認證測試) ✅
• 後端總計: 95+ tests 全部通過 ✅
• ski-platform (前端): 21+ 測試套件（AI 助手核心功能）✅

📚 文檔

• 實作總結 - 完整的實作細節
• 認證架構指南 - 統一認證說明
• AI 對話助手文檔 - AI 功能說明（如果存在）

資料庫支援的雪場

系統目前支援 43 個日本知名滑雪場，涵蓋：

熱門地區

• 北海道: 二世谷、留壽都、富良野、Tomamu、手稻、Kiroro、Sahoro 等
• 長野: 白馬、志賀高原、野澤溫泉、輕井澤、白樺湖等
• 新潟: 苗場、神樂、妙高赤倉、GALA 湯澤等
• 其他: 猪苗代、安比高原、藏王等

AI 助手支援多種雪場名稱變體（中文、日文、英文），並能智能識別用戶意圖。

貢獻

歡迎提交 Issues 和 Pull Requests 來改善此專案。

開發指南

1. Fork 此專案
2. 創建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交變更 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 開啟 Pull Request

授權

此專案採用 MIT 授權。