ewoooc/docs/APP_REFACTOR_PLAN.md

app.py 重構計畫

文件資訊

• 建立日期: 2026-01-18
• 目標檔案: app.py (7,253 行)
• 目標: 模組化拆分，提高可維護性

---

一、現況分析

1.1 檔案規模

• 總行數: 7,253 行
• 路由數量: 49 個
• 函數數量: 約 70 個

1.2 最大函數 (需優先拆分)

排名	函數名稱	行數	所屬模組建議
1	sales_analysis()	1,020 行	sales_routes.py
2	get_monthly_summary_data()	388 行	monthly_routes.py
3	import_excel()	288 行	import_routes.py
4	get_sales_table_data()	267 行	sales_routes.py
5	export_top_detail()	256 行	sales_routes.py
6	get_top_detail()	252 行	sales_routes.py
7	edm_dashboard()	244 行	edm_routes.py
8	index()	190 行	dashboard_routes.py

1.3 現有路由分類

頁面路由 (12個):
├── / (首頁/商品看板)
├── /settings (設定)
├── /system_settings (系統設定)
├── /brand_assets (品牌資源)
├── /edm (EDM 儀表板)
├── /festival (節慶儀表板)
├── /abc_analysis/detail (ABC 分析詳情)
├── /logs (系統日誌)
├── /monthly_summary_analysis (月結分析)
├── /sales_analysis (業績分析)
├── /growth_analysis (成長分析)
└── /daily_sales (當日業績)

API 路由 (37個):
├── 系統 API (3個): /health, /metrics, /api/logs
├── 分類管理 API (4個): /api/categories/*
├── 匯出 API (11個): /api/export/*
├── 任務觸發 API (6個): /api/run_*, /api/trigger_*
├── 匯入 API (2個): /api/import_excel, /api/import/monthly_summary
├── 備份 API (2個): /api/backup, /api/backup/download/*
├── 業績分析 API (5個): /api/sales_analysis/*
├── 月結分析 API (1個): /api/monthly_summary_data
├── 其他 API (3個): /api/test_url, /api/history/*, /api/price_change_details
└── 當日業績匯出 (2個): /daily_sales/export*

---

二、重構架構設計

2.1 目標目錄結構

momo_pro_system/
├── app.py                    # 主應用程式 (精簡後約 500 行)
├── config.py                 # 配置檔 (保持不變)
├── auth.py                   # 認證模組 (保持不變)
│
├── routes/                   # 🆕 路由模組目錄
│   ├── __init__.py          # Blueprint 註冊中心
│   ├── dashboard_routes.py  # 商品看板 (首頁)
│   ├── sales_routes.py      # 業績分析相關
│   ├── daily_sales_routes.py # 當日業績相關
│   ├── monthly_routes.py    # 月結分析相關
│   ├── edm_routes.py        # EDM 儀表板
│   ├── export_routes.py     # 匯出功能
│   ├── import_routes.py     # 匯入功能
│   ├── system_routes.py     # 系統管理 (設定、日誌、備份)
│   └── api_routes.py        # 通用 API (健康檢查、任務觸發等)
│
├── services/                 # 服務層 (現有)
│   ├── __init__.py
│   ├── cache_service.py     # 🆕 快取服務 (從 app.py 抽出)
│   ├── sales_service.py     # 🆕 業績計算服務
│   ├── dashboard_service.py # 🆕 看板數據服務
│   └── ... (現有服務)
│
├── utils/                    # 工具函數 (現有)
│   ├── __init__.py
│   ├── validators.py        # 🆕 驗證函數 (從 app.py 抽出)
│   ├── formatters.py        # 🆕 格式化函數
│   └── ... (現有工具)
│
├── database/                 # 資料庫層 (保持不變)
├── vendor_routes.py          # 廠商缺貨路由 (已存在)
└── auto_import_routes.py     # 自動匯入路由 (已存在)

2.2 模組劃分詳情

模組 1: routes/dashboard_routes.py (~400 行)

# 包含路由:
- GET /                      # index() - 商品看板首頁
- GET /brand_assets          # brand_assets()

# 包含函數:
- get_consolidated_data()    # 153 行
- get_full_dashboard_data()  # 148 行
- get_dashboard_stats()      # 16 行

模組 2: routes/sales_routes.py (~2,000 行)

# 包含路由:
- GET /sales_analysis                    # sales_analysis() - 1,020 行
- GET /api/sales_analysis/table_data     # get_sales_table_data() - 267 行
- GET /api/sales_analysis/table_data_pandas
- GET /api/sales_analysis/top_detail     # get_top_detail() - 252 行
- GET /api/sales_analysis/export_top_detail
- GET /api/sales_analysis/yoy_comparison

# 包含函數:
- _get_filtered_sales_data()

模組 3: routes/daily_sales_routes.py (~800 行)

# 包含路由:
- GET /daily_sales           # daily_sales() - 161 行
- GET /daily_sales/export    # export_daily_sales_category()
- GET /daily_sales/export_marketing
- GET /growth_analysis       # growth_analysis()

# 包含函數:
- preprocess_daily_sales_data()
- calculate_daily_kpis()
- calculate_dod()
- calculate_wow()
- prepare_daily_charts()
- prepare_category_summary()
- prepare_marketing_summary()
- get_taiwan_holiday()
- prepare_calendar_data()

模組 4: routes/monthly_routes.py (~500 行)

# 包含路由:
- GET /monthly_summary_analysis
- GET /api/monthly_summary_data  # 388 行
- POST /api/import/monthly_summary

模組 5: routes/edm_routes.py (~400 行)

# 包含路由:
- GET /edm                   # edm_dashboard() - 244 行
- GET /festival              # festival_dashboard() - 148 行

模組 6: routes/export_routes.py (~800 行)

# 包含路由:
- GET /api/export/all_categories
- GET /api/export/excel/all
- GET /api/export/excel/changes
- GET /api/export/excel/delisted
- GET /api/export/price_changes   # 156 行
- GET /api/export/low_prices
- GET /api/export/changes
- GET /api/export/excel/abc       # 175 行
- GET /api/export/excel/vendor    # 135 行
- GET /api/export/excel/seasonality_detail

模組 7: routes/import_routes.py (~350 行)

# 包含路由:
- POST /api/import_excel     # import_excel() - 288 行

模組 8: routes/system_routes.py (~400 行)

# 包含路由:
- GET /settings
- GET /system_settings
- GET /logs
- GET /api/logs
- POST /api/backup
- GET /api/backup/download/<path:filename>
- POST /api/categories (CRUD)
- POST /api/test_url

# 包含函數:
- load_categories()
- save_categories()
- load_scheduler_stats()

模組 9: routes/api_routes.py (~300 行)

# 包含路由:
- GET /health
- GET /metrics
- POST /api/run_task
- POST /api/run_edm_task
- POST /api/run_festival_task
- POST /api/trigger_momo_notification
- POST /api/trigger_edm_notification
- POST /api/test_notification
- GET /api/history/<int:product_id>
- GET /api/price_change_details
- GET /abc_analysis/detail

# 包含函數:
- track_query_time()

---

三、重構執行步驟

階段 1: 準備工作 (風險: 低)

1. ✅ 完整備份現有程式碼
2. 建立 routes/ 目錄結構
3. 建立 routes/__init__.py Blueprint 註冊中心

階段 2: 抽取共用模組 (風險: 低)

1. 建立 services/cache_service.py - 抽取快取相關變數和函數
2. 建立 utils/validators.py - 抽取驗證函數
3. 建立 utils/formatters.py - 抽取格式化函數

階段 3: 拆分路由模組 (風險: 中)

執行順序 (由簡單到複雜):

順序	模組	路由數	複雜度	依賴關係
1	system_routes.py	8	低	無外部依賴
2	api_routes.py	10	低	scheduler
3	export_routes.py	10	中	DatabaseManager, Exporter
4	import_routes.py	1	中	DatabaseManager
5	edm_routes.py	2	中	DatabaseManager
6	monthly_routes.py	3	中	DatabaseManager
7	dashboard_routes.py	2	高	cache_service, DatabaseManager
8	daily_sales_routes.py	4	高	多個輔助函數
9	sales_routes.py	6	高	cache_service, 複雜邏輯

階段 4: 整合測試 (風險: 低)

1. 本機測試所有路由
2. UAT 環境部署測試
3. 回歸測試所有功能

---

四、安全措施

4.1 備份策略

# 重構前完整備份
cp -r /Users/ogt/momo_pro_system /Users/ogt/momo_pro_system_backup_$(date +%Y%m%d_%H%M%S)

# 資料庫備份
cp /Users/ogt/momo_pro_system/data/momo_database.db /Users/ogt/momo_pro_system/backups/

4.2 漸進式部署

1. 每拆分一個模組後立即測試
2. 使用 feature flag 控制新舊路由切換
3. 保留原始 app.py 直到所有模組穩定

4.3 回滾方案

# 如發生嚴重問題，立即回滾
cp /Users/ogt/momo_pro_system_backup_YYYYMMDD/app.py /Users/ogt/momo_pro_system/app.py
rm -rf /Users/ogt/momo_pro_system/routes/
# 重新部署

---

五、預期效益

5.1 程式碼品質

指標	重構前	重構後
app.py 行數	7,253	~500
最大函數行數	1,020	~200
模組數量	1	10
可測試性	低	高

5.2 維護性改善

• 問題定位: 從搜尋 7000 行 → 搜尋 300-800 行
• 功能擴展: 只需修改相關模組
• 團隊協作: 可並行開發不同模組
• 部署風險: 可單獨部署/回滾特定模組

---

六、時程規劃

階段	工作項目	預估工作量
1	準備工作 + 共用模組	1-2 小時
2	system_routes + api_routes	2-3 小時
3	export_routes + import_routes	2-3 小時
4	edm_routes + monthly_routes	2-3 小時
5	dashboard_routes	2-3 小時
6	daily_sales_routes	3-4 小時
7	sales_routes (最複雜)	4-5 小時
8	整合測試 + 修復	2-3 小時
總計		18-26 小時

---

七、注意事項

7.1 已知問題需修復

1. datetime 重複導入: 多處函數內有 from datetime import datetime，需統一移除
2. 快取變數: _SALES_DF_CACHE 等全域變數需移至 cache_service.py
3. 循環依賴: 拆分時需注意模組間的 import 順序

7.2 不動的部分

• config.py - 配置檔保持不變
• auth.py - 認證模組保持不變
• vendor_routes.py - 已是 Blueprint，保持不變
• auto_import_routes.py - 已是 Blueprint，保持不變
• database/ 目錄 - 資料庫層保持不變
• services/ 目錄 - 現有服務保持不變

---

八、執行確認

重構開始前，請確認：

• 已完成完整備份
• 已確認 UAT 環境可正常運作
• 已預留足夠時間進行測試
• 已準備好回滾方案

---

文件結束