- 建立 Gitea Actions CD pipeline (.gitea/workflows/cd.yaml) - 部署模式: rsync Python 檔案至 188 → docker restart (volume mount) - Dockerfile/requirements 變動時自動重建 Docker image - 部署通知: Telegram (開始/成功/失敗) - 健康檢查: https://mo.wooo.work/health (最多 5 次重試) - 同步最新 CLAUDE.md / ADR-008 / memory (2026-04-19) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ogt
502
docs/API_DOCUMENTATION.md
Normal file
502
docs/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,502 @@
|
||||
# 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 | 伺服器錯誤 |
|
||||
Reference in New Issue
Block a user