LINEBOT_OPERATION_GUIDE.md

# LineBot 操作指南

## 🤖 系統概述

本 LineBot 系統整合了 Pydantic AI 框架，提供智能商品查詢、聊天和業務查詢功能。系統設計考慮了 LINE 群組使用場景，避免不必要的 AI token 消耗。

## 📱 用戶操作指南

### 基本指令

#### 1. 聊天模式
```
/chat 你好！今天天氣如何？
/chat 推薦一些好用的功能
```
- **用途**：一般對話、問候、非業務相關問題
- **適用場景**：群組聊天、客戶服務
- **AI 服務**：使用 Groq 進行自然對話

#### 2. 商品查詢模式
```
/search iPhone 15 Pro
/search 價格 1000-5000
/search 庫存不足的商品
```
- **用途**：傳統的商品搜尋和業務查詢
- **適用場景**：明確的商品查詢需求
- **查詢範圍**：商品、訂單、庫存、客戶資料

#### 3. 幫助指令
```
/help
幫助
說明
```
- **用途**：顯示系統使用說明
- **回應**：完整的功能介紹和使用範例

### 智能模式（無前綴）

#### 商品推薦查詢
```
是否有推薦貓砂？
有什麼狗糧推薦？
推薦一些寵物用品
```
- **特點**：自動識別推薦意圖
- **回應**：智能推薦相關商品，包含庫存資訊
- **優勢**：更自然的對話方式

#### 庫存查詢
```
查詢iPhone庫存
寵物用品還有多少？
低庫存商品有哪些？
```
- **特點**：自動識別庫存查詢意圖
- **回應**：詳細的庫存狀態和警告提醒

#### 一般對話
```
你好！
今天天氣如何？
謝謝你的幫助
```
- **特點**：自動識別為聊天意圖
- **回應**：友善的對話回應

## 🏢 管理員操作指南

### 系統監控

#### 1. 健康檢查
```bash
curl http://localhost:7860/health
```
**回應內容**：
- 系統狀態
- 資料庫連線狀態
- 資料庫連線資訊

#### 2. 路由統計
在 LINE 中輸入：`統計` 或 `stats`

**統計內容**：
- 各模式使用次數和百分比
- Groq 服務狀態
- Pydantic AI 服務狀態

### API 端點管理

#### 1. 直接聊天 API
```bash
curl -X POST "http://localhost:7860/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "今天天氣如何？",
    "user_id": "admin_user"
  }'
```

#### 2. 直接搜尋 API
```bash
curl -X POST "http://localhost:7860/search" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "iPhone 15",
    "user_id": "admin_user"
  }'
```

#### 3. 商品查詢 API
```bash
curl -X POST "http://localhost:7860/product-query" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "是否有推薦貓砂？",
    "user_id": "admin_user"
  }'
```

#### 4. 智能路由 API
```bash
curl -X POST "http://localhost:7860/route" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "有什麼狗糧推薦？",
    "user_id": "admin_user"
  }'
```

### 系統配置

#### 環境變數檢查
```bash
# 檢查必要的環境變數
echo $GROQ_API_KEY
echo $DB_HOST
echo $LINE_CHANNEL_ACCESS_TOKEN
```

#### 服務狀態檢查
```python
# 在 Python 中檢查服務狀態
from backend.services.pydantic_ai_service import ProductQueryService
from backend.services.groq_service import GroqService

product_service = ProductQueryService()
groq_service = GroqService()

print(f"Pydantic AI 可用: {product_service.is_available()}")
print(f"Groq 服務可用: {groq_service.is_available()}")
```

## 🔧 故障排除

### 常見問題

#### 1. 商品查詢沒有結果
**可能原因**：
- 資料庫中沒有相關商品
- 關鍵字匹配不準確
- 商品被標記為已刪除

**解決方案**：
- 檢查資料庫商品資料
- 嘗試使用不同的關鍵字
- 使用 `/search` 進行傳統查詢

#### 2. Pydantic AI 服務不可用
**錯誤訊息**：「商品查詢服務暫時無法使用」

**解決方案**：
- 檢查 `GROQ_API_KEY` 環境變數
- 確認 Groq API 配額
- 系統會自動降級到傳統搜尋

#### 3. 資料庫連線失敗
**錯誤訊息**：「資料庫連線測試失敗」

**解決方案**：
- 檢查資料庫連線參數
- 確認資料庫服務運行狀態
- 檢查網路連線

### 日誌查看

#### 應用程式日誌
```bash
# 查看即時日誌
tail -f app.log

# 搜尋特定錯誤
grep "ERROR" app.log
grep "商品查詢錯誤" app.log
```

#### 特定功能日誌
```bash
# Pydantic AI 相關
grep "Pydantic AI" app.log

# 路由統計
grep "智能路由" app.log

# 資料庫查詢
grep "資料庫" app.log
```

## 📊 效能監控

### API 回應時間
- **聊天模式**：通常 1-3 秒
- **商品查詢**：通常 2-5 秒
- **智能路由**：通常 1-4 秒

### 資源使用
- **記憶體**：約 200-500MB
- **CPU**：低負載時 < 10%
- **網路**：主要是 API 調用

### Token 使用監控
- 監控 Groq API 使用量
- 設定使用量警告
- 考慮實施使用限制

## 🚀 部署指南

### 開發環境
```bash
# 1. 安裝依賴
pip install -r requirements.txt

# 2. 設定環境變數
cp .env.example .env
# 編輯 .env 文件

# 3. 運行測試
python test_pydantic_ai_integration.py

# 4. 啟動服務
uvicorn backend.main:app --host 0.0.0.0 --port 7860
```

### 生產環境
```bash
# 使用 Docker
docker build -t linebot-pydantic .
docker run -p 7860:7860 --env-file .env linebot-pydantic

# 或使用 Docker Compose
docker-compose up -d
```

### LINE Webhook 設定
1. 在 LINE Developers Console 設定 Webhook URL
2. URL 格式：`https://your-domain.com/webhook`
3. 確認 SSL 憑證有效

## 📋 維護檢查清單

### 每日檢查
- [ ] 系統健康狀態
- [ ] API 回應時間
- [ ] 錯誤日誌
- [ ] Groq API 使用量

### 每週檢查
- [ ] 路由統計分析
- [ ] 資料庫效能
- [ ] 商品資料更新
- [ ] 用戶回饋收集

### 每月檢查
- [ ] 系統效能評估
- [ ] 功能使用分析
- [ ] 安全性檢查
- [ ] 備份驗證

## 📞 支援聯絡

### 技術問題
- 檢查日誌文件
- 參考故障排除指南
- 聯絡系統管理員

### 功能建議
- 記錄用戶需求
- 評估實施可行性
- 規劃功能更新

---

**版本**：v1.0  
**更新日期**：2025-01-12  
**維護團隊**：開發團隊