setup_guide.md

# LINE Bot + FastAPI + Supabase 設定指南

## 🚀 快速開始

### 1. 必要的 API Keys 和設定

您需要準備以下 API Keys 和設定：

#### LINE Developers Console
1. 前往 [LINE Developers Console](https://developers.line.biz/)
2. 建立新的 Provider 和 Messaging API Channel
3. 取得以下資訊：
   - `Channel Access Token` (長期)
   - `Channel Secret`

#### Supabase
1. 前往 [Supabase](https://supabase.com/)
2. 建立新專案
3. 取得以下資訊：
   - `Project URL`
   - `Anon/Public Key`

#### OpenRouter (可選)
1. 前往 [OpenRouter](https://openrouter.ai/)
2. 註冊帳號並取得 `API Key` (用於進階 NLP 功能)
3. 選擇適合的模型 (預設: anthropic/claude-3-haiku)

### 2. Hugging Face Spaces 環境變數設定

在 Hugging Face Spaces 的 Settings 中設定以下環境變數：

```
LINE_CHANNEL_ACCESS_TOKEN=你的_LINE_Channel_Access_Token
LINE_CHANNEL_SECRET=你的_LINE_Channel_Secret
SUPABASE_URL=你的_Supabase_專案_URL
SUPABASE_KEY=你的_Supabase_Anon_Key
OPENROUTER_API_KEY=你的_OpenRouter_API_Key (可選)
OPENROUTER_MODEL=anthropic/claude-3-haiku (可選)
DEBUG=False
LOG_LEVEL=INFO
```

### 3. Supabase 資料庫設定

在 Supabase Dashboard 的 SQL Editor 中執行以下 SQL：

```sql
-- 建立用戶表
CREATE TABLE IF NOT EXISTS users (
    user_id VARCHAR(255) PRIMARY KEY,
    name VARCHAR(255),
    email VARCHAR(255),
    display_name VARCHAR(255),
    picture_url TEXT,
    status_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 建立商品表
CREATE TABLE IF NOT EXISTS products (
    product_id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10,2) NOT NULL,
    stock INTEGER DEFAULT 0,
    category VARCHAR(100),
    image_url TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 建立訂單表
CREATE TABLE IF NOT EXISTS orders (
    order_id VARCHAR(255) PRIMARY KEY,
    user_id VARCHAR(255) REFERENCES users(user_id),
    total_amount DECIMAL(10,2) NOT NULL,
    status VARCHAR(50) DEFAULT 'pending',
    shipping_address TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 建立訂單項目表
CREATE TABLE IF NOT EXISTS order_items (
    id SERIAL PRIMARY KEY,
    order_id VARCHAR(255) REFERENCES orders(order_id),
    product_id INTEGER REFERENCES products(product_id),
    quantity INTEGER NOT NULL,
    unit_price DECIMAL(10,2) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 建立訊息記錄表
CREATE TABLE IF NOT EXISTS line_messages (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255),
    message TEXT NOT NULL,
    message_type VARCHAR(50) DEFAULT 'text',
    timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    processed BOOLEAN DEFAULT FALSE
);

-- 建立用戶會話表
CREATE TABLE IF NOT EXISTS user_sessions (
    id SERIAL PRIMARY KEY,
    user_id VARCHAR(255) REFERENCES users(user_id),
    session_data JSONB,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

-- 插入範例商品資料
INSERT INTO products (name, description, price, stock, category) VALUES
('iPhone 15 Pro', '最新款 iPhone，配備 A17 Pro 晶片', 35900, 50, '手機'),
('MacBook Air M2', '輕薄筆記型電腦，搭載 M2 晶片', 37900, 30, '筆電'),
('AirPods Pro', '主動降噪無線耳機', 7490, 100, '耳機');
```

### 4. LINE Bot Webhook 設定

1. 部署到 Hugging Face Spaces 後，取得您的應用程式 URL
2. 在 LINE Developers Console 中設定 Webhook URL：
   ```
   https://你的用戶名-你的空間名稱.hf.space/webhook
   ```
3. 啟用 Webhook 和 Auto-reply messages

### 5. 測試功能

部署完成後，您可以測試以下功能：

#### 用戶查詢
- "查詢用戶 張三"
- "找用戶名叫王小明的資料"

#### 商品查詢
- "查詢商品 iPhone"
- "有什麼手機商品"
- "價格 1000 到 5000 的商品"

#### 訂單查詢
- "查詢訂單 ORD001"
- "我的訂單狀態如何"

#### 統計分析
- "統計用戶數量"
- "總共有多少筆訂單"

#### 說明功能
- "幫助"
- "說明"

## 🔧 本地開發

如果要在本地開發：

1. 複製專案
2. 建立 `.env` 檔案（參考 `.env.example`）
3. 安裝依賴：`pip install -r requirements.txt`
4. 執行：`python -m uvicorn backend.main:app --reload --port 7860`
5. 使用 ngrok 建立公開 URL 用於 LINE Webhook 測試

## 📝 架構說明

- **FastAPI**: Web 框架和 API 端點
- **Pydantic**: 資料驗證和序列化
- **LINE Bot SDK**: 處理 LINE 訊息
- **Supabase**: PostgreSQL 資料庫
- **NLP Service**: 自然語言處理和意圖識別
- **Database Service**: 資料庫操作抽象層

## 🚨 注意事項

1. 確保所有環境變數都正確設定
2. Supabase 資料表必須先建立
3. LINE Bot Webhook URL 必須是 HTTPS
4. 測試時注意 LINE 訊息的回應時間限制（30秒）