# 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 ` ### 回應格式 ```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 | 伺服器錯誤 |