ewoooc/docs/API_DOCUMENTATION.md

# MOMO Pro System - API 文件

> 最後更新：2026-01-29

---

## 📌 概述

### Base URL
- **生產環境**: `https://mo.wooo.work`
- **開發環境**: `http://localhost:5000`

### 認證方式
- **Session Cookie**: 透過 `/login` 取得
- **Bot API Token**: Header `Authorization: Bearer <token>`

### 回應格式
```json
{
    "success": true,
    "data": { ... },
    "message": "操作成功"
}
```

### 錯誤回應
```json
{
    "success": false,
    "error": "錯誤訊息",
    "code": "ERROR_CODE"
}
```

---

## 🔐 認證 API

### 登入
```http
POST /login
Content-Type: application/x-www-form-urlencoded
```

| 參數 | 類型 | 必填 | 說明 |
|------|------|------|------|
| username | string | ✓ | 帳號 |
| password | string | ✓ | 密碼 |

**回應**: 302 Redirect 或 401

### 登出
```http
GET /logout
```

### 修改密碼
```http
POST /api/user/change_password
Content-Type: application/json
```

```json
{
    "current_password": "舊密碼",
    "new_password": "新密碼"
}
```

---

## 📊 商品看板 API

### 取得商品列表
```http
GET /api/products
```

| 參數 | 類型 | 說明 |
|------|------|------|
| page | int | 頁碼 (default: 1) |
| per_page | int | 每頁筆數 (default: 50) |
| category | string | 分類篩選 |
| filter | string | 狀態篩選 (all/increase/decrease/delisted) |
| q | string | 搜尋關鍵字 |
| sort_by | string | 排序欄位 |
| order | string | 排序方向 (asc/desc) |

**回應**:
```json
{
    "items": [...],
    "total": 5576,
    "page": 1,
    "per_page": 50,
    "total_pages": 112
}
```

### 取得商品價格歷史
```http
GET /api/history/{product_id}
```

**回應**:
```json
[
    {"t": "2026-01-29 14:00", "p": 3280},
    {"t": "2026-01-28 14:00", "p": 3180}
]
```

### 手動執行爬蟲
```http
POST /api/run_task
```

### 發送價格通知
```http
POST /api/trigger_momo_notification
```

---

## 📈 業績分析 API

### 取得每日業績
```http
GET /api/daily_sales
```

| 參數 | 類型 | 說明 |
|------|------|------|
| date | string | 日期 (YYYY-MM-DD) |
| pm | string | PM 篩選 |
| brand | string | 品牌篩選 |

### 取得月份總表
```http
GET /api/monthly_summary
```

| 參數 | 類型 | 說明 |
|------|------|------|
| year | int | 年份 |
| month | int | 月份 |

### 取得銷售趨勢
```http
GET /api/sales/trend
```

| 參數 | 類型 | 說明 |
|------|------|------|
| start_date | string | 開始日期 |
| end_date | string | 結束日期 |
| dimension | string | 維度 (brand/pm/category) |

---

## 📦 廠商缺貨 API

### 匯入缺貨資料
```http
POST /api/vendor/stockout/import
Content-Type: multipart/form-data
```

| 參數 | 類型 | 說明 |
|------|------|------|
| file | file | Excel 檔案 |

### 取得缺貨列表
```http
GET /api/vendor/stockout
```

| 參數 | 類型 | 說明 |
|------|------|------|
| batch_id | string | 批次篩選 |
| vendor_code | string | 廠商篩選 |
| status | string | 狀態篩選 |

### 發送通知郵件
```http
POST /api/vendor/stockout/send
Content-Type: application/json
```

```json
{
    "stockout_ids": [1, 2, 3]
}
```

### 廠商清單 CRUD

```http
GET /api/vendor/list                      # 取得廠商列表
POST /api/vendor/list                     # 新增廠商
PUT /api/vendor/list/{vendor_id}          # 更新廠商
DELETE /api/vendor/list/{vendor_id}       # 刪除廠商
```

### 廠商郵件 CRUD

```http
GET /api/vendor/{vendor_id}/emails        # 取得郵件列表
POST /api/vendor/{vendor_id}/emails       # 新增郵件
DELETE /api/vendor/email/{email_id}       # 刪除郵件
```

---

## 🤖 AI API

### 生成文案
```http
POST /api/ai/generate
Content-Type: application/json
```

```json
{
    "product_name": "商品名稱",
    "style": "吸睛",
    "keywords": ["保濕", "抗老"],
    "provider": "ollama"
}
```

**回應**:
```json
{
    "content": "生成的文案內容",
    "model": "llama3:70b",
    "duration": 5.2,
    "input_tokens": 120,
    "output_tokens": 85
}
```

### 取得熱門推薦
```http
GET /api/ai/trending
```

| 參數 | 類型 | 說明 |
|------|------|------|
| source | string | 來源 (mybest/cosme/youtube) |
| category | string | 分類 |

### 網路搜尋 (Gemini)
```http
POST /api/ai/search
Content-Type: application/json
```

```json
{
    "query": "搜尋關鍵字"
}
```

### AI 歷史記錄

```http
GET /api/ai/history                       # 取得歷史列表
GET /api/ai/history/{id}                  # 取得單筆記錄
PUT /api/ai/history/{id}/favorite         # 切換收藏
DELETE /api/ai/history/{id}               # 刪除記錄
```

### AI 使用統計
```http
GET /api/ai/usage/stats
```

| 參數 | 類型 | 說明 |
|------|------|------|
| start_date | string | 開始日期 |
| end_date | string | 結束日期 |

---

## 👤 用戶管理 API

### 取得用戶列表 (Admin)
```http
GET /api/users
```

### 新增用戶 (Admin)
```http
POST /api/users
Content-Type: application/json
```

```json
{
    "username": "帳號",
    "email": "郵箱",
    "password": "密碼",
    "role": "user",
    "display_name": "顯示名稱"
}
```

### 更新用戶 (Admin)
```http
PUT /api/users/{user_id}
```

### 刪除用戶 (Admin)
```http
DELETE /api/users/{user_id}
```

### 重設密碼 (Admin)
```http
POST /api/users/{user_id}/reset_password
```

### 取得登入歷史
```http
GET /api/users/login_history
```

---

## ⚙️ 系統 API

### 取得系統狀態
```http
GET /api/system/status
```

**回應**:
```json
{
    "cpu_percent": 25.5,
    "memory_percent": 68.2,
    "disk_percent": 45.0,
    "uptime": "5 days"
}
```

### 取得爬蟲狀態
```http
GET /api/system/crawler/status
```

### 系統清理
```http
POST /api/system/cleanup
```

### K8s Pod 重啟
```http
POST /api/system/k8s/restart
Content-Type: application/json
```

```json
{
    "deployment": "momo-app"
}
```

### 健康檢查
```http
GET /health
```

**回應**: `200 OK`

### Prometheus 指標
```http
GET /metrics
```

---

## 📥 匯入 API

### 列出 Google Drive 檔案
```http
GET /api/import/drive/files
```

### 匯入 Drive 檔案
```http
POST /api/import/drive/import
Content-Type: application/json
```

```json
{
    "file_id": "Google Drive 檔案 ID",
    "job_type": "daily_sales"
}
```

### 取得匯入進度
```http
GET /api/import/jobs/{job_id}
```

---

## 📤 匯出 API

### 匯出商品報表
```http
GET /api/export/excel/all
GET /api/export/excel/changes
GET /api/export/excel/delisted
```

### 匯出業績報表
```http
GET /api/export/daily_sales
```

| 參數 | 類型 | 說明 |
|------|------|------|
| date | string | 日期 |
| format | string | 格式 (excel/csv) |

---

## 🔔 通知 API

### 發送 Telegram 通知
```http
POST /api/notification/telegram
Content-Type: application/json
```

```json
{
    "message": "通知內容"
}
```

### 渲染通知模板 (供 n8n 呼叫)
```http
POST /api/notification/render
Content-Type: application/json
```

```json
{
    "code": "disk_warning",
    "variables": {
        "usage_percent": 85
    }
}
```

### 取得通知模板
```http
GET /api/notification/templates
GET /api/notification/templates/{code}
PUT /api/notification/templates/{code}
```

---

## 🤖 Bot API

### Telegram Webhook
```http
POST /api/bot/telegram/webhook
```

### Bot 指令處理
```http
POST /api/bot/command
Content-Type: application/json
```

```json
{
    "command": "/sales",
    "args": ["today"]
}
```

---

## 📝 錯誤代碼

| 代碼 | HTTP | 說明 |
|------|------|------|
| AUTH_REQUIRED | 401 | 需要登入 |
| AUTH_FAILED | 401 | 登入失敗 |
| PERMISSION_DENIED | 403 | 權限不足 |
| NOT_FOUND | 404 | 資源不存在 |
| VALIDATION_ERROR | 400 | 參數驗證錯誤 |
| RATE_LIMITED | 429 | 請求過於頻繁 |
| SERVER_ERROR | 500 | 伺服器錯誤 |