ewoooc/docs/PROJECT_STRUCTURE.md

MOMO Pro System - 專案結構

最後更新：2026-01-29

---

📁 目錄結構總覽

momo-pro-system/
│
├── 📂 核心應用
│   ├── app.py                    # Flask 主應用 (路由 + 視圖)
│   ├── auth.py                   # 認證與授權模組
│   ├── config.py                 # 環境配置
│   └── scheduler.py              # 爬蟲排程器
│
├── 📂 routes/                    # API 路由模組 (Blueprint)
│   ├── dashboard_routes.py       # 商品看板 API
│   ├── daily_sales_routes.py     # 每日業績 API
│   ├── monthly_routes.py         # 月份總表 API
│   ├── sales_routes.py           # 銷售分析 API
│   ├── ai_routes.py              # AI 文案生成 API
│   ├── user_routes.py            # 用戶管理 API
│   ├── system_routes.py          # 系統設定 API
│   ├── export_routes.py          # 報表匯出 API
│   ├── import_routes.py          # 資料匯入 API
│   ├── edm_routes.py             # EDM 活動 API
│   ├── alert_routes.py           # 告警通知 API
│   ├── bot_api_routes.py         # Bot API (Telegram/LINE)
│   ├── trend_routes.py           # 趨勢爬蟲 API
│   ├── pchome_routes.py          # PChome 爬蟲 API
│   └── price_comparison_routes.py # 價格比較 API
│
├── 📂 services/                  # 業務邏輯層
│   ├── 🤖 AI 服務
│   │   ├── ai_provider.py        # AI 提供者抽象層
│   │   ├── ollama_service.py     # Ollama LLM 服務
│   │   ├── gemini_service.py     # Google Gemini 服務
│   │   └── ai_history_service.py # AI 歷史記錄服務
│   │
│   ├── 🕷️ 爬蟲服務
│   │   ├── momo_crawler.py       # MOMO 商品爬蟲
│   │   ├── pchome_crawler.py     # PChome 爬蟲
│   │   ├── trend_crawler.py      # 趨勢爬蟲 (mybest, cosme)
│   │   ├── mybest_crawler.py     # mybest 爬蟲
│   │   └── cosme_crawler.py      # @cosme 爬蟲
│   │
│   ├── 📧 通知服務
│   │   ├── notification_manager.py  # 通知管理器
│   │   ├── notification_service.py  # 通知發送服務
│   │   ├── telegram_bot_service.py  # Telegram Bot
│   │   └── vendor_email_service.py  # 廠商郵件服務
│   │
│   ├── 📥 匯入服務
│   │   ├── import_service.py     # 資料匯入服務
│   │   └── google_drive_service.py # Google Drive 整合
│   │
│   ├── 👤 用戶服務
│   │   ├── user_service.py       # 用戶管理服務
│   │   ├── password_service.py   # 密碼服務
│   │   └── permission_service.py # 權限服務
│   │
│   └── 🔧 其他服務
│       ├── cache_service.py      # 快取服務
│       ├── price_comparison.py   # 價格比較服務
│       ├── pg_sync_service.py    # PostgreSQL 同步
│       └── exporter.py           # 報表匯出服務
│
├── 📂 database/                  # 資料庫模型
│   ├── manager.py                # 資料庫連線管理
│   ├── models.py                 # 核心模型 (Product, PriceRecord)
│   ├── user_models.py            # 用戶模型 (User, LoginHistory)
│   ├── vendor_models.py          # 廠商模型 (VendorStockout, etc.)
│   ├── ai_models.py              # AI 模型 (AIGenerationHistory, etc.)
│   ├── import_models.py          # 匯入模型 (ImportJob, ImportConfig)
│   ├── permission_models.py      # 權限模型
│   ├── notification_models.py    # 通知模型
│   ├── trend_models.py           # 趨勢模型
│   ├── edm_models.py             # EDM 模型
│   └── vendor_manager.py         # 廠商資料管理器
│
├── 📂 templates/                 # Jinja2 模板
│   ├── base.html                 # 基礎模板
│   ├── components/               # 可重用元件
│   │   ├── _navbar.html          # 導航列
│   │   └── _loading.html         # 載入動畫
│   ├── ai_recommend.html         # AI 推薦頁面
│   ├── ai_history.html           # AI 歷史頁面
│   ├── user_management.html      # 用戶管理頁面
│   ├── price_comparison.html     # 價格比較頁面
│   └── pchome_crawler.html       # PChome 爬蟲頁面
│
├── 📂 根目錄 HTML (主要頁面)
│   ├── dashboard.html            # 商品看板
│   ├── daily_sales.html          # 每日業績
│   ├── sales_analysis.html       # 銷售分析
│   ├── monthly_summary_analysis.html # 月份總表
│   ├── vendor_stockout_*.html    # 廠商缺貨系列頁面
│   ├── edm_dashboard.html        # EDM 活動看板
│   ├── settings.html             # 系統設定
│   ├── system_settings.html      # 系統參數
│   ├── logs.html                 # 系統日誌
│   └── login.html                # 登入頁面
│
├── 📂 static/                    # 靜態資源
│   ├── images/                   # 圖片資源
│   └── css/                      # 樣式表
│
├── 📂 k8s/                       # Kubernetes 配置
│   ├── 00-namespace.yaml         # Namespace
│   ├── 01-secrets.yaml           # Secrets
│   ├── 02-configmap.yaml         # ConfigMap
│   ├── 03-postgres.yaml          # PostgreSQL StatefulSet
│   ├── 04-momo-app.yaml          # Flask 應用 Deployment
│   ├── 05-scheduler.yaml         # 排程器 Deployment
│   ├── 08-google-drive-secret.yaml # Google Drive 認證
│   ├── monitoring/               # 監控配置
│   │   ├── alerting-rules.yaml   # 告警規則
│   │   └── values-prometheus.yaml # Prometheus Helm 配置
│   └── nginx/                    # Nginx 配置
│       ├── monitor.conf          # 監控反向代理
│       └── setup-ssl.sh          # SSL 設定腳本
│
├── 📂 docker/                    # Docker 容器配置
│   ├── prometheus/               # Prometheus 監控
│   ├── grafana/                  # Grafana 儀表板
│   ├── alertmanager/             # 告警管理
│   ├── loki/                     # 日誌收集
│   ├── promtail/                 # 日誌採集
│   ├── postgres/                 # PostgreSQL
│   ├── nginx/                    # Nginx
│   └── nginx-monitor/            # 監控入口
│
├── 📂 n8n-workflows/             # n8n 自動化工作流
│   ├── 01-disk-space-monitor.json
│   ├── 02-ssl-certificate-monitor.json
│   ├── 03-cicd-pipeline-notify.json
│   ├── 04-backup-monitor.json
│   ├── 05-crawler-monitor.json
│   ├── 06-k8s-pod-monitor.json
│   └── ... (共 16 個工作流)
│
├── 📂 deploy/                    # 部署腳本
│   ├── deploy.sh                 # 主部署腳本
│   ├── lib/                      # 部署函式庫
│   └── scripts/                  # 輔助腳本
│
├── 📂 scripts/                   # 維運腳本
│   ├── cicd_auto_repair.sh       # CI/CD 自動修復
│   └── ...
│
├── 📂 docs/                      # 專案文件
│   ├── PRD.md                    # 產品需求書
│   ├── TECH_STACK.md             # 技術架構
│   ├── DATABASE_SCHEMA.md        # 資料庫結構
│   └── ...
│
├── 📂 config/                    # 配置檔案
│   ├── google_credentials.json   # Google OAuth 認證
│   ├── google_token.pickle       # Google Token
│   └── nginx/                    # Nginx 站點配置
│
├── 📂 data/                      # 資料目錄
│   ├── momo_database.db          # SQLite 主資料庫
│   └── scheduler_stats.json      # 排程統計
│
├── 📂 logs/                      # 日誌目錄
│
├── 📄 配置檔案
│   ├── docker-compose.yml        # Docker Compose
│   ├── docker-compose.devops.yml # DevOps 容器
│   ├── Dockerfile                # Docker 映像配置
│   ├── requirements.txt          # Python 依賴
│   ├── .gitlab-ci.yml            # GitLab CI/CD
│   ├── .gitignore                # Git 忽略
│   └── .env.example              # 環境變數範例
│
└── 📄 文件
    ├── CLAUDE.md                 # AI 助手專案記憶
    ├── PROJECT_CONSTITUTION.md   # 專案憲法
    ├── DEPLOY_README.md          # 部署說明
    └── SECURITY_FIX_SUMMARY.md   # 安全修復紀錄

---

📊 專案統計

項目	數量
Python 檔案	~100+
HTML 模板	~35
API 路由模組	17
服務模組	27
資料庫模型	16
K8s 配置	10
n8n 工作流	16
總程式碼行數	~28,000+

---

🔗 模組依賴關係

graph TB
    subgraph "前端層"
        HTML[HTML 模板]
        JS[JavaScript]
    end

    subgraph "路由層 (routes/)"
        Routes[API Routes]
    end

    subgraph "服務層 (services/)"
        AI[AI 服務]
        Crawler[爬蟲服務]
        Notify[通知服務]
        Import[匯入服務]
        User[用戶服務]
    end

    subgraph "資料層 (database/)"
        Models[資料模型]
        Manager[連線管理]
    end

    subgraph "資料庫"
        PG[(PostgreSQL)]
        SQLite[(SQLite)]
    end

    HTML --> Routes
    JS --> Routes
    Routes --> AI
    Routes --> Crawler
    Routes --> Notify
    Routes --> Import
    Routes --> User
    AI --> Models
    Crawler --> Models
    Notify --> Models
    Import --> Models
    User --> Models
    Models --> Manager
    Manager --> PG
    Manager --> SQLite

---

📁 主要目錄說明

/routes - API 路由層

所有 REST API 端點定義，採用 Flask Blueprint 架構。

/services - 業務邏輯層

核心業務邏輯，包含 AI、爬蟲、通知、匯入等服務。

/database - 資料存取層

SQLAlchemy ORM 模型與資料庫管理。

/templates - 視圖模板

Jinja2 HTML 模板，用於 Server-Side Rendering。

/k8s - Kubernetes 配置

K3s 部署配置，包含 Deployment、Service、ConfigMap 等。

/n8n-workflows - 自動化工作流

n8n 低代碼自動化工作流 JSON 定義。