# MOMO Pro System - 技術架構

> 最後更新：2026-01-29

---

## 🏗️ 整體架構

```mermaid
graph TB
    subgraph "用戶端"
        Browser[🌐 瀏覽器]
        Telegram[📱 Telegram Bot]
        LINE[📱 LINE Bot]
    end

    subgraph "入口層"
        Nginx[🔒 Nginx<br/>SSL + 反向代理]
    end

    subgraph "應用層 (K8s)"
        Flask[🐍 Flask App]
        Scheduler[⏰ 排程器]
    end

    subgraph "AI 服務"
        Ollama[🦙 Ollama<br/>llama3:70b]
        Gemini[✨ Gemini API]
    end

    subgraph "資料層"
        PostgreSQL[(🐘 PostgreSQL)]
        Redis[(📦 Redis Cache)]
    end

    subgraph "外部服務"
        GDrive[📁 Google Drive]
        SMTP[📧 SMTP Server]
        MOMO[🛒 MOMO 電商]
    end

    subgraph "監控層"
        Prometheus[📊 Prometheus]
        Grafana[📈 Grafana]
        Alertmanager[🚨 Alertmanager]
    end

    Browser --> Nginx
    Telegram --> Flask
    LINE --> Flask
    Nginx --> Flask
    Flask --> PostgreSQL
    Flask --> Redis
    Flask --> Ollama
    Flask --> Gemini
    Flask --> GDrive
    Flask --> SMTP
    Scheduler --> MOMO
    Scheduler --> PostgreSQL
    Flask --> Prometheus
    Prometheus --> Grafana
    Prometheus --> Alertmanager
```

---

## 📚 技術棧總覽

| 層級 | 技術 | 版本 | 用途 |
|------|------|------|------|
| **後端框架** | Flask | 2.3+ | Web 應用框架 |
| **ORM** | SQLAlchemy | 2.0+ | 資料庫物件映射 |
| **資料庫** | PostgreSQL | 15 | 主資料庫 (生產環境) |
| **資料庫** | SQLite | 3 | 開發/本地環境 |
| **快取** | Redis | 7.0 | Session + 資料快取 |
| **前端框架** | Bootstrap | 5.3 | UI 元件庫 |
| **圖表** | Chart.js | 4.0 | 資料視覺化 |
| **模板引擎** | Jinja2 | 3.1 | HTML 模板渲染 |
| **容器** | Docker | 24.0 | 容器化部署 |
| **編排** | K3s | 1.34 | Kubernetes 輕量版 |
| **CI/CD** | GitLab CI | - | 持續整合部署 |
| **Registry** | Harbor | 2.10 | 容器映像倉庫 |
| **監控** | Prometheus | 2.51 | 指標收集 |
| **視覺化** | Grafana | 10.0 | 監控儀表板 |
| **日誌** | Loki | 2.9 | 日誌聚合 |
| **AI (本地)** | Ollama | 0.1+ | LLM 推理引擎 |
| **AI (雲端)** | Gemini | 1.5/2.5 | Google AI API |
| **自動化** | n8n | 1.30 | 低代碼工作流 |
| **爬蟲** | Selenium | 4.18 | 網頁自動化 |
| **爬蟲** | BeautifulSoup | 4.12 | HTML 解析 |

---

## 🐍 後端架構

### Flask 應用結構

```
Flask App
├── Blueprints (路由模組)
│   ├── dashboard_routes    # 商品看板
│   ├── daily_sales_routes  # 每日業績
│   ├── ai_routes          # AI 文案
│   ├── user_routes        # 用戶管理
│   └── ...                # 17 個路由模組
│
├── Services (業務邏輯)
│   ├── AI Services        # Ollama + Gemini
│   ├── Crawler Services   # 爬蟲服務
│   ├── Notification       # 通知服務
│   └── ...                # 27 個服務模組
│
└── Database (資料層)
    ├── SQLAlchemy Models  # ORM 模型
    └── Database Manager   # 連線管理
```

### 關鍵依賴 (requirements.txt)

```txt
Flask>=2.3.0
SQLAlchemy>=2.0.0
gunicorn>=21.0.0
psycopg2-binary>=2.9.0
selenium>=4.18.0
beautifulsoup4>=4.12.0
openpyxl>=3.1.0
google-api-python-client>=2.0.0
python-telegram-bot>=20.0
requests>=2.31.0
Pillow>=10.0.0
```

---

## 🎨 前端架構

### 技術選型

| 項目 | 技術 | 說明 |
|------|------|------|
| **CSS 框架** | Bootstrap 5.3 | 響應式 UI 元件 |
| **圖標** | Font Awesome 6 | 圖標庫 |
| **圖表** | Chart.js 4.0 | 折線圖、長條圖 |
| **表格** | DataTables | 分頁、搜尋表格 |
| **日期選擇** | Flatpickr | 日期/時間選擇器 |
| **通知** | Toastr | Toast 通知 |
| **模態框** | Bootstrap Modal | 彈窗對話框 |

### 頁面載入方式

```
Server-Side Rendering (SSR)
├── Jinja2 模板渲染
├── AJAX API 呼叫 (資料更新)
└── 無 SPA 框架
```

---

## 🗄️ 資料庫架構

### 雙資料庫策略

| 環境 | 資料庫 | 用途 |
|------|--------|------|
| 開發 | SQLite | 本地快速開發 |
| 生產 | PostgreSQL | UAT + 正式環境 |

### 連線管理

```python
# database/manager.py
- 支援 SQLite 和 PostgreSQL 切換
- 連線池管理
- Session 生命週期管理
```

### 資料庫備份

- **頻率**: 每日自動備份
- **保留**: 最近 7 天
- **工具**: pg_dump + cron

---

## 🚀 部署架構

### K3s Kubernetes 環境

```yaml
Namespace: momo
├── Deployment: momo-app (Flask)
│   ├── Replicas: 1
│   ├── Resources: 512Mi-4Gi / 200m-2000m
│   └── Image: harbor.wooo.work/wooo/momo-pro-system
│
├── Deployment: momo-scheduler (爬蟲)
│   ├── Replicas: 1
│   └── Resources: 256Mi-2Gi / 100m-1000m
│
├── StatefulSet: momo-postgres
│   ├── Storage: 10Gi PVC
│   └── Resources: 256Mi-1Gi / 100m-500m
│
└── Services
    ├── momo-app: ClusterIP
    └── momo-postgres: ClusterIP
```

### 流量路徑

```
用戶 → mo.wooo.work:443
     → VM Nginx (SSL)
     → K8s ClusterIP 10.43.238.49:80
     → momo-app Pod
```

---

## 🔄 CI/CD 流程

```mermaid
graph LR
    A[Git Push] --> B[GitLab CI]
    B --> C{Test}
    C -->|Pass| D[Build Image]
    C -->|Fail| E[Auto Repair]
    D --> F[Push to Harbor]
    F --> G[K8s Rollout]
    G --> H[Health Check]
    E --> C
```

### Pipeline 階段

| 階段 | 動作 | 自動修復 |
|------|------|---------|
| test | pytest 單元測試 | 系統診斷 |
| build | Docker 映像構建 | Harbor 重啟、磁碟清理 |
| deploy | K8s 滾動更新 | Pod 重啟、Secret 重建 |

---

## 🤖 AI 服務架構

### 雙 AI 提供者

| 提供者 | 模型 | 用途 | 計費 |
|--------|------|------|------|
| **Ollama** | llama3:70b | 文案生成、推薦 | 免費 (自建) |
| **Gemini** | gemini-1.5-flash | 網路搜尋、產品分析 | 按 Token |

### AI 服務切換邏輯

```python
class AIProvider:
    def generate(self, prompt):
        if self.provider == 'ollama':
            return self.ollama_service.generate(prompt)
        else:
            return self.gemini_service.generate(prompt)
```

### Ollama 伺服器

- **位置**: 192.168.0.188:11434
- **模型**: llama3:70b-instruct-q2_K
- **監控**: n8n 健康檢查 (每 5 分鐘)

---

## 📊 監控系統

### 監控堆疊

```
Prometheus (指標收集)
    ├── Node Exporter (主機指標)
    ├── cAdvisor (容器指標)
    ├── Postgres Exporter (DB 指標)
    └── Blackbox Exporter (外部探測)
         │
         ▼
    Alertmanager (告警路由)
         │
         ▼
    Telegram / LINE (通知)
         │
         ▼
    Grafana (視覺化儀表板)
```

### 告警規則

| 規則 | 條件 | 動作 |
|------|------|------|
| Pod OOMKilled | Pod 記憶體不足 | Telegram 告警 |
| 高重啟率 | 5 分鐘內重啟 > 3 次 | Telegram 告警 |
| 磁碟空間 | 使用率 > 80% | 自動清理 |
| SSL 到期 | 30 天內到期 | 每日提醒 |

---

## 🔒 安全架構

### 認證與授權

| 項目 | 實作 |
|------|------|
| 用戶認證 | Flask-Login + Session |
| 密碼儲存 | bcrypt 雜湊 |
| CSRF 防護 | Flask-WTF Token |
| 權限控制 | RBAC (admin/manager/user) |

### 網路安全

| 項目 | 實作 |
|------|------|
| HTTPS | Let's Encrypt SSL |
| 端口限制 | 僅開放 22, 80, 443 |
| 內部服務 | 僅綁定 127.0.0.1 |

---

## 📁 外部整合

| 服務 | 用途 | 整合方式 |
|------|------|---------|
| **Google Drive** | 檔案匯入 | OAuth 2.0 API |
| **SMTP** | 郵件發送 | smtplib |
| **Telegram** | 通知 + Bot | Bot API |
| **LINE** | 通知 | Messaging API |
| **MOMO** | 商品爬蟲 | Selenium |
| **mybest** | 趨勢爬蟲 | BeautifulSoup |

---

## ⚙️ 環境變數

```bash
# 資料庫
DATABASE_URL=postgresql://user:pass@host:5432/db
SQLALCHEMY_DATABASE_URI=...

# AI 服務
OLLAMA_HOST=http://192.168.0.188:11434
OLLAMA_MODEL=llama3:70b-instruct-q2_K
GEMINI_API_KEY=AIzaSy...

# 通知
TELEGRAM_BOT_TOKEN=807564...
TELEGRAM_CHAT_ID=561907...

# Google
GOOGLE_DRIVE_FOLDER_ID=...
```