10 KiB
10 KiB
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 # 環境變數範例
│
└── 📄 文件
├── AGENTS.md # Codex 專案入口與工作規則
├── CLAUDE.md # 舊工作流相容轉址頁
├── 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 定義。