273 lines
10 KiB
Markdown
273 lines
10 KiB
Markdown
# 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+ |
|
||
|
||
---
|
||
|
||
## 🔗 模組依賴關係
|
||
|
||
```mermaid
|
||
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 定義。
|