ewoooc/routes

路由模組重構說明

概述

此目錄包含從 app.py 中分離出來的路由模組，採用 Flask Blueprint 架構。 這樣的模組化設計使得代碼更易於維護、測試和擴展。

模組清單

模組	狀態	說明	路由
system_routes.py	✅ 獨立	系統管理	/settings, /logs, /health, /metrics, /api/backup 等
edm_routes.py	✅ 獨立	EDM 儀表板	/edm, /festival
monthly_routes.py	✅ 獨立	月結分析	/monthly_summary_analysis, /api/monthly_summary_data
dashboard_routes.py	✅ 獨立	首頁看板	/, /brand_assets
daily_sales_routes.py	✅ 獨立	當日業績	/daily_sales, /daily_sales/export*
api_routes.py	✅ 已獨立	通用 API	/api/run_task, /api/history/* 等
export_routes.py	✅ 已獨立	匯出功能	/api/export/*
import_routes.py	✅ 已獨立	匯入功能	/api/import_excel, /api/import/monthly_summary
sales_routes.py	⚡ 延遲導入	業績分析	/sales_analysis, /growth_analysis, /api/sales_analysis/*

啟用模組

方法一：修改 config.py（推薦）

在 config.py 中設定 USE_MODULAR_ROUTES：

USE_MODULAR_ROUTES = {
    'system': True,      # 啟用 system_routes
    'edm': True,         # 啟用 edm_routes
    'monthly': True,     # 啟用 monthly_routes
    'dashboard': True,   # 啟用 dashboard_routes
    'daily_sales': True, # 啟用 daily_sales_routes
    'api': False,        # api_routes 有依賴，暫不啟用
    'export': False,     # export_routes 有依賴，暫不啟用
    'import': False,     # import_routes 有依賴，暫不啟用
    'sales': False,      # sales_routes 有依賴，暫不啟用
}

方法二：環境變數

可透過環境變數覆蓋設定（待實作）。

運作原理

1. Blueprint 註冊：routes/__init__.py 中的 register_blueprints() 函數根據 USE_MODULAR_ROUTES 設定決定是否註冊各模組的 Blueprint。

2. 重複路由清理：app.py 底部的 cleanup_duplicate_routes() 函數會在所有路由定義完成後，移除與已啟用 Blueprint 重複的路由。

3. 優先順序：Blueprint 中的路由優先於 app.py 中的同名路由。

模組依賴說明

完全獨立模組

• system_routes.py
• edm_routes.py
• monthly_routes.py
• dashboard_routes.py - 提供 get_consolidated_data, get_dashboard_stats
• daily_sales_routes.py

這些模組不依賴 app.py 中的任何函數或變數。

已獨立化的模組（使用 services 或其他獨立模組）

• api_routes.py：
  • 使用 services/task_runner.py 中的 run_momo_task_with_notification
  • 使用 routes/dashboard_routes.py 中的 get_dashboard_stats
• export_routes.py：
  • 使用 routes/dashboard_routes.py 中的 get_consolidated_data
  • 使用 services/cache_service.py 中的快取變數
• import_routes.py：
  • 使用 services/cache_service.py 中的 _SALES_DF_CACHE, _SALES_PROCESSED_CACHE

延遲導入模組

• sales_routes.py：
  • growth_analysis() 已完全獨立
  • 其他 API 函數使用延遲導入從 app.py 取得（函數邏輯複雜，暫不遷移）

開發指南

新增路由模組

1. 在 routes/ 目錄建立新的 Python 檔案
2. 定義 Blueprint：

   from flask import Blueprint
   my_bp = Blueprint('my_module', __name__)
   

3. 在 routes/__init__.py 中加入註冊邏輯
4. 在 config.py 的 USE_MODULAR_ROUTES 中加入控制項

從 app.py 遷移路由

1. 複製路由函數到對應模組
2. 將 @app.route 改為 @blueprint_name.route
3. 確認所有導入正確
4. 測試模組可正常導入：python -c "from routes.xxx import xxx_bp"
5. 在 MODULAR_ENDPOINTS 中記錄端點名稱

測試

測試模組是否正常運作：

# 測試所有模組導入
python -c "
from routes.system_routes import system_bp
from routes.edm_routes import edm_bp
from routes.monthly_routes import monthly_bp
from routes.dashboard_routes import dashboard_bp
from routes.daily_sales_routes import daily_sales_bp
print('All independent modules imported successfully!')
"

# 測試完整應用（啟用所有獨立模組）
python -c "
import config
config.USE_MODULAR_ROUTES = {
    'system': True, 'edm': True, 'monthly': True,
    'dashboard': True, 'daily_sales': True,
    'api': False, 'export': False, 'import': False, 'sales': False
}
import app
print(f'Total routes: {len(list(app.app.url_map.iter_rules()))}')
"

已知問題

模板 url_for 端點名稱問題

當啟用模組化路由時，端點名稱會從 'index' 變為 'dashboard.index'。 這會導致模板中的 url_for('index') 調用失敗。

影響範圍：

• index.html 中的 url_for('index', ...)
• edm_dashboard.html 中的 url_for('edm_dashboard', ...)

解決方案（需在啟用模組前執行）：

1. 在模板中使用完整的端點名稱，如 url_for('dashboard.index', ...)
2. 或在 app.py 中加入端點別名

注意：目前預設所有模組皆禁用（USE_MODULAR_ROUTES 全為 False）， 因此不會影響正常使用。此問題只會在手動啟用模組後出現。

變更歷史

• 2026-01-18：
  • 初始版本，建立 9 個路由模組，5 個獨立模組可直接啟用
  • 修復 url_for 端點名稱問題，新增 register_endpoint_aliases() 函數
  • 處理有依賴的模組 (api, export, import)，使用獨立 services 模組
  • 新增 services/task_runner.py 封裝爬蟲任務執行邏輯
  • 所有 9 個模組已啟用並通過測試