速Per Idol - 智能飲食運動管理平台

一個全方位的健康飲食與運動追蹤平台，結合AI智能推薦，幫助用戶實現健康生活目標

📋 目錄

• 專案簡介
• 功能特色
• 技術架構
• 系統需求
• 快速開始
• 詳細安裝
• API文檔
• 資料庫設計
• 故障排除
• 貢獻指南

專案簡介

速Per Idol 是一個現代化的健康管理平台，專為追求健康生活的用戶設計。平台整合了食物營養追蹤、運動管理、智能推薦等功能，通過科學的數據分析幫助用戶達成健康目標。

功能特色

🍽️ 智能飲食管理

• 食物資料庫: 豐富的食物營養數據庫，包含熱量、蛋白質、脂肪、碳水化合物等詳細資訊
• 飲食記錄: 快速記錄每日三餐及宵夜的食物攝取
• 營養分析: 實時計算營養攝取量，提供營養均衡建議
• 個人化推薦: 基於用戶偏好、歷史記錄和健康目標的AI推薦系統

🏃‍♂️ 運動健身追蹤

• 運動計算器: 根據用戶體重和運動強度計算消耗熱量
• 運動記錄: 追蹤各種運動項目的時間和強度
• 目標設定: 設定每日/每週運動目標並追蹤進度

📊 健康數據分析

• 營養圖表: 視覺化呈現營養攝取分布
• 趨勢分析: 長期健康數據追蹤和趨勢分析
• 目標監控: 卡路里和營養目標達成率監控

🎯 智能推薦系統

• 🎯 專屬精選: 基於多維度評分的高精準推薦
• 🏪 餐廳推薦: 根據用戶偏好餐廳的精選美食
• 💪 健康精選: 高蛋白低碳水的營養均衡選擇
• 🌟 探索新品: 推薦用戶未嘗試過的符合偏好美食

技術架構

前端技術棧

技術	版本	說明
Vue.js	3.3.4	漸進式JavaScript框架，提供響應式UI
Pinia	2.1.7	Vue狀態管理庫，處理全局狀態
Vue Router	4.2.5	單頁應用路由管理
Element Plus	2.9.9	基於Vue 3的組件庫
Chart.js	4.4.9	數據視覺化圖表庫
Axios	1.6.2	HTTP客戶端，處理API請求
Vite	6.3.5	現代前端構建工具

後端技術棧

技術	版本	說明
Flask	2.3.2	輕量級Python Web框架
PyMySQL	1.1.0	MySQL數據庫連接器
Flask-SQLAlchemy	3.1.1	ORM對象關係映射
Flask-CORS	4.0.0	跨域資源共享支持
PyJWT	2.8.0	JSON Web Token認證
Gunicorn	21.2.0	WSGI HTTP服務器

架構設計

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Vue.js SPA    │    │   Flask API     │    │   MySQL DB      │
│                 │    │                 │    │                 │
│  • Pinia Store  │◄──►│  • RESTful API  │◄──►│  • 用戶數據     │
│  • Vue Router   │    │  • 智能推薦系統 │    │  • 食物數據庫   │
│  • Element UI   │    │  • 連接池優化   │    │  • 運動數據     │
│  • Chart.js     │    │  • 快取系統     │    │  • 偏好設定     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

核心特性

• 🚀 高性能: 連接池 + LRU快取 + 批量查詢優化
• 🎯 精準推薦: 多維度評分算法，8分門檻確保推薦質量
• 📱 響應式設計: 支持桌面端和移動端
• 🔒 安全認證: JWT token認證機制
• 📊 實時分析: 即時營養數據計算和視覺化

系統需求

基礎環境

• Node.js: >= 16.0.0
• Python: >= 3.8.0
• MySQL: >= 8.0
• Git: 最新版本

快速開始

一鍵自動化啟動（推薦）

# 1. 克隆專案
git clone https://github.com/your-username/super-idol.git
cd super-idol

# 2. 一鍵設置與啟動
cd scripts
node setup.js   # 自動安裝依賴、創建配置文件
node dev.js     # 同時啟動前後端服務

🎉 啟動成功後:

• 前端應用: http://localhost:5173
• 後端API: http://localhost:5000

詳細安裝

1. 數據庫設置

-- 創建數據庫
CREATE DATABASE super_idol CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 創建用戶（可選）
CREATE USER 'super_idol_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON super_idol.* TO 'super_idol_user'@'localhost';
FLUSH PRIVILEGES;

2. 後端設置

# 進入後端目錄
cd super-idol/backend

# 創建虛擬環境
python -m venv .venv

# 激活虛擬環境
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

# 創建環境配置文件
cp .env.example .env
# 編輯 .env 文件，配置數據庫連接信息

3. 前端設置

# 進入前端目錄
cd super-idol/frontend

# 安裝依賴
npm install

4. 啟動服務

# 啟動後端 (在 backend 目錄下)
python app.py

# 啟動前端 (在 frontend 目錄下)
npm run dev

API文檔

食物管理

方法	端點	說明	參數
GET	/api/food/	搜索食物	name, priceMin, priceMax, calMin, calMax, type, restaurant
GET	/api/food/recommend	智能推薦	user_id
POST	/api/food/record	新增飲食記錄	user_id, food_id, mealtime, quantity, date
GET	/api/food/record	獲取飲食記錄	user_id, start_date, end_date, mealtime
PUT	/api/food/record/{record_id}	更新飲食記錄	user_id, mealtime, quantity, date
DELETE	/api/food/record/{record_id}	刪除飲食記錄	user_id

收藏管理

方法	端點	說明	參數
GET	/api/food/favorites	獲取收藏清單	user_id
POST	/api/food/favorites	新增收藏	user_id, food_id
DELETE	/api/food/favorites	移除收藏	user_id, food_id

運動相關

方法	端點	說明	參數
GET	/api/food/exercise/calculator	運動熱量計算	calories, weight

示例請求

// 獲取智能推薦
const response = await axios.get('/api/food/recommend?user_id=23');

// 新增飲食記錄
const foodRecord = await axios.post('/api/food/record', {
  user_id: 23,
  food_id: 1,
  mealtime: '早餐',
  quantity: 1,
  date: '2024-01-15'
});

// 搜索食物
const foods = await axios.get('/api/food/', {
  params: {
    name: '雞肉',
    priceMax: 200,
    calMax: 500
  }
});

資料庫設計

核心數據表

-- 用戶表
Users (UserID, Username, Password, Email, Budget, WeekCalorieLimit, ...)

-- 食物表
Food (FoodID, Name, Calories, Price, Food_Type, Protein, Fat, Carb, ...)

-- 餐廳表  
Restaurant (RestaurantID, Name, Location, ...)

-- 飲食記錄表
Food_Records (RecordID, UserID, FoodID, MealTime, Quantity, Date, ...)

-- 收藏表
My_Favorite (FavoriteID, UserID, FoodID, CreatedAt)

-- 偏好表
Food_Preference (PreferenceID, UserID, Food_Type)
Restaurant_Preference (PreferenceID, UserID, RestaurantID)

關聯關係

• 用戶 ↔ 飲食記錄 (一對多)
• 用戶 ↔ 收藏 (一對多)
• 用戶 ↔ 偏好設定 (一對多)
• 食物 ↔ 餐廳 (多對一)

故障排除

常見問題

1. CORS 跨域錯誤

# 解決方案: 確認後端CORS設置
curl http://localhost:5000/api/test-cors

2. 數據庫連接失敗

# 檢查MySQL服務狀態
# Windows
net start mysql
# Linux/macOS
sudo systemctl status mysql

# 測試數據庫連接
mysql -u root -p -h localhost

3. 端口衝突

# 查看端口使用情況
# Windows
netstat -an | findstr :5000
netstat -an | findstr :5173

# 修改配置文件中的端口設置

4. 依賴安裝失敗

# 清除快取重新安裝
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

# Python依賴問題
pip cache purge
pip install -r requirements.txt --force-reinstall

編輯指南

1. Fork 本倉庫
2. Clone 到本地: git clone https://github.com/your-username/super-idol.git
3. 創建分支: git checkout -b feature/amazing-feature
4. 提交更改: git commit -m 'feat: 新增驚人功能'
5. 推送分支: git push origin feature/amazing-feature
6. 提交 Pull Request

代碼提交規範

feat: 新功能
fix: 修復bug
docs: 文檔更新
style: 代碼格式調整
refactor: 代碼重構
test: 測試相關
chore: 構建過程或輔助工具的變動

---

Made with ❤️ by Super Idol Team