ewoooc/DEPLOYMENT_WORKFLOW.md

# MOMO 監控系統 - 開發測試部署流程

**版本：** 1.0
**制定日期：** 2026-01-13
**最後更新：** 2026-01-13

---

## 🏗️ 環境架構

### 環境分層

| 環境 | 位置 | 用途 | 網址 | 運行方式 |
|------|------|------|------|----------|
| **開發環境 (Dev)** | `/Users/ogt/momo_pro_system` | 本地開發、程式碼修改 | `http://127.0.0.1:80` | 直接運行 `python app.py` |
| **測試環境 (Test)** | 同開發環境 | 功能測試、安全測試 | 同開發環境 | 執行測試腳本 |

### 環境特性

#### 開發環境 (macOS Local)
- **系統**：macOS (Darwin)
- **Python**：pyenv 管理的 Python 3.11.7
- **資料庫**：本地 SQLite
- **用途**：
  - 程式碼開發
  - 快速測試
  - UI/UX 調整
  - 新功能實驗

#### 正式環境 (GCP VM)
- **系統**：Ubuntu 22.04 LTS
- **Python**：系統 Python 或 venv
- **服務管理**：systemd (`momo.service`)
- **反向代理**：可能使用 nginx
- **域名**：DuckDNS (momo.wooo.work)
- **用途**：
  - 生產服務
  - 24/7 運行
  - 爬蟲任務排程
  - 使用者訪問

---

## 📋 完整開發部署流程

### 階段 1：需求與規劃

```mermaid
graph LR
    A[需求確認] --> B[功能設計]
    B --> C[技術評估]
    C --> D[風險評估]
    D --> E[制定計劃]
```

**檢查清單**：
- [ ] 需求文檔完整
- [ ] 技術方案可行
- [ ] 評估對現有功能的影響
- [ ] 確認是否需要爬蟲修改（若是，參照憲法第四章）
- [ ] 確認是否影響安全（若是，參照憲法第二章）

---

### 階段 2：本地開發 (Dev)

#### 2.1 環境準備

```bash
# 確保在開發環境
cd /Users/ogt/momo_pro_system

# 確認虛擬環境
source venv/bin/activate

# 確認依賴最新
pip list
```

#### 2.2 程式碼開發

```bash
# 1. 創建功能分支（重大修改）
git checkout -b feature/功能名稱

# 2. 開發程式碼
# - 遵守憲法第三章程式碼規範
# - 使用繁體中文註解
# - 添加錯誤處理
# - 記錄詳細日誌

# 3. 本地測試
python app.py
# 訪問 http://127.0.0.1:80 測試功能
```

**開發規範**：
- ✅ 所有註解使用繁體中文
- ✅ 所有輸入經過驗證
- ✅ 使用 `safe_join()` 處理路徑
- ✅ POST 請求包含 CSRF token
- ✅ 敏感資訊使用環境變數
- ✅ 完整的錯誤處理和日誌

#### 2.3 Git 提交

```bash
# 查看修改
git status
git diff

# 提交修改
git add 相關檔案
git commit -m "[模組] 繁體中文描述"

# 範例：
# git commit -m "[UI] 為廠商缺貨系統所有子頁面添加返回主頁按鈕"
# git commit -m "[Crawler] [MOMO] 修復商品價格選擇器失效"
# git commit -m "[Security] 強化檔案上傳驗證"
```

---

### 階段 3：本地測試 (Test)

#### 3.1 功能測試

```bash
# 手動測試
python app.py
# 1. 測試新功能正常運作
# 2. 測試現有功能未受影響
# 3. 測試邊界情況
# 4. 測試錯誤處理
```

#### 3.2 安全測試（如涉及安全）

```bash
# 執行完整安全測試套件
./run_security_tests.sh

# 或個別測試
python test_sql_security.py
python test_path_traversal.py
python test_file_upload.py
```

**必須通過**：
- ✅ 所有安全測試通過
- ✅ 無新增安全漏洞
- ✅ 日誌記錄完整

#### 3.3 爬蟲測試（如涉及爬蟲）

```bash
# 執行爬蟲測試
python test_crawler_specific.py

# 測試項目：
# 1. 選擇器有效性
# 2. 資料完整性
# 3. 錯誤處理
# 4. 效能測試
```

**必須通過**：
- ✅ 選擇器正確抓取資料
- ✅ 資料格式正確
- ✅ 錯誤處理完整
- ✅ 執行時間合理

#### 3.4 回歸測試

```bash
# 確認現有功能未受影響
# 1. 測試主要功能流程
# 2. 測試業績分析
# 3. 測試爬蟲任務
# 4. 測試廠商缺貨系統
# 5. 測試 Google Drive 自動匯入
```

---

### 階段 4：部署前準備

#### 4.1 程式碼檢查

**檢查清單**：
- [ ] 所有測試通過
- [ ] 程式碼遵守規範
- [ ] 註解完整清晰
- [ ] 無硬編碼敏感資訊
- [ ] 日誌記錄完整
- [ ] Git commit 完成
- [ ] 文檔更新完成

#### 4.2 確認修改檔案清單

```bash
# 查看本次修改的所有檔案
git status
git diff --name-only

# 列出修改清單，確認需要部署的檔案
# 範例：
# - sales_analysis.html
# - vendor_stockout_list.html
# - vendor_stockout_import.html
# - vendor_stockout_send_email.html
# - vendor_stockout_history.html
```

#### 4.3 備份正式環境

```bash
# 連接到 GCP VM
gcloud compute ssh momo-server --zone=asia-east1-a

# 在 VM 上執行備份
cd /home/ogt/momo_pro_system
./deploy_scripts/backup.sh
# 或手動備份
tar -czf backup_$(date +%Y%m%d_%H%M%S).tar.gz \
    --exclude='venv' \
    --exclude='__pycache__' \
    --exclude='*.log' \
    .
```

---

### 階段 5：部署到正式環境

#### 方法 A：完整部署（推薦用於大改動）

```bash
# 在本地執行
cd /Users/ogt/momo_pro_system

# 使用部署腳本自動上傳

# 腳本會：
# 1. 檢查 gcloud 登入狀態
# 2. 檢查 VM 狀態
# 3. 上傳所有檔案（排除 venv、__pycache__、logs）
# 4. 提示後續步驟
```

**然後連接到 VM**：

```bash
# 連接到 VM
gcloud compute ssh momo-server --zone=asia-east1-a

# 在 VM 上執行
cd ~/momo_pro_system

# 安裝/更新依賴（如有新依賴）
source venv/bin/activate
pip install -r requirements.txt

# 重啟服務
sudo systemctl restart momo.service

# 檢查服務狀態
sudo systemctl status momo.service

# 查看日誌
sudo journalctl -u momo.service -f
```

#### 方法 B：快速更新（用於小改動，僅 HTML/CSS/JS）

```bash
# 在本地執行
cd /Users/ogt/momo_pro_system

# 僅上傳修改的檔案
gcloud compute scp --zone=asia-east1-a \
    sales_analysis.html \
    vendor_stockout_list.html \
    vendor_stockout_import.html \
    vendor_stockout_send_email.html \
    vendor_stockout_history.html \
    momo-server:~/momo_pro_system/

# HTML 模板檔案不需要重啟服務
# Flask 會自動重新載入模板
```

**注意**：
- HTML/CSS/JS 檔案：不需重啟服務
- Python 檔案（.py）：需要重啟服務
- 配置檔案（.env）：需要重啟服務
- 依賴更新（requirements.txt）：需要重新安裝並重啟

---

### 階段 6：部署後驗證

#### 6.1 服務狀態檢查

```bash
# 在 GCP VM 上執行
sudo systemctl status momo.service

# 查看最近的日誌
sudo journalctl -u momo.service -n 100

# 檢查是否有錯誤
sudo journalctl -u momo.service -p err -n 50
```

#### 6.2 功能驗證

```bash
# 測試網站訪問
curl -I https://momo.wooo.work

# 測試特定功能頁面
curl -I https://momo.wooo.work/vendor-stockout/send-email
curl -I https://momo.wooo.work/vendor-stockout/history
```

**手動驗證**：
- [ ] 訪問 https://momo.wooo.work
- [ ] 測試修改的功能
- [ ] 確認新功能正常運作
- [ ] 確認現有功能未受影響
- [ ] 檢查是否有 JavaScript 錯誤（瀏覽器 Console）
- [ ] 測試在不同瀏覽器（Chrome, Safari）

#### 6.3 監控檢查

```bash
# 監控系統日誌（持續 10 分鐘）
tail -f /home/ogt/momo_pro_system/logs/system.log

# 檢查是否有錯誤或異常
```

**監控項目**：
- [ ] 無錯誤訊息
- [ ] 爬蟲任務正常執行
- [ ] 資料庫操作正常
- [ ] 記憶體使用正常
- [ ] CPU 使用正常

#### 6.4 24 小時監控

**重要**：部署後必須監控 24 小時
- 定期檢查日誌
- 確認排程任務正常執行
- 確認通知正常發送
- 監控系統資源使用

---

## 🔄 回滾流程

### 何時需要回滾

- ❌ 部署後發現嚴重錯誤
- ❌ 核心功能失效
- ❌ 爬蟲完全失敗
- ❌ 系統崩潰或無法啟動
- ❌ 資料庫損壞

### 回滾步驟

```bash
# 1. 連接到 GCP VM
gcloud compute ssh momo-server --zone=asia-east1-a

# 2. 停止服務
sudo systemctl stop momo.service

# 3. 還原備份
cd /home/ogt/momo_pro_system
mv momo_pro_system momo_pro_system_failed
tar -xzf backup_20260113_HHMMSS.tar.gz

# 4. 重啟服務
sudo systemctl start momo.service

# 5. 驗證服務恢復
sudo systemctl status momo.service
curl -I https://momo.wooo.work

# 6. 記錄問題
# 在本地環境修復問題，重新測試後再次部署
```

---

## 📝 部署檢查清單總表

### 部署前檢查（Pre-Deployment）

- [ ] 功能開發完成
- [ ] 本地測試通過
- [ ] 安全測試通過（如涉及）
- [ ] 爬蟲測試通過（如涉及）
- [ ] 回歸測試通過
- [ ] 程式碼遵守規範
- [ ] Git commit 完成
- [ ] 文檔更新完成
- [ ] 正式環境已備份

### 部署中檢查（During Deployment）

- [ ] 檔案上傳成功
- [ ] 依賴安裝成功（如需要）
- [ ] 服務重啟成功（如需要）
- [ ] 無錯誤訊息

### 部署後檢查（Post-Deployment）

- [ ] 服務狀態正常
- [ ] 網站可以訪問
- [ ] 新功能正常運作
- [ ] 現有功能未受影響
- [ ] 日誌無異常
- [ ] 排程任務正常
- [ ] 監控 24 小時
- [ ] 更新部署日誌

---

## 🔧 常用命令速查

### 本地開發

```bash
# 啟動開發環境
cd /Users/ogt/momo_pro_system
source venv/bin/activate
python app.py

# 執行測試
./run_security_tests.sh
python test_specific.py

# Git 操作
git status
git add .
git commit -m "[模組] 描述"
git push
```

## 📊 環境差異注意事項

### 路徑差異

| 項目 | 開發環境 | 正式環境 |
|------|----------|----------|
| 專案路徑 | `/Users/ogt/momo_pro_system` | `/home/ogt/momo_pro_system` |
| Python | `/Users/ogt/.pyenv/versions/3.11.7/bin/python` | `/home/ogt/momo_pro_system/venv/bin/python` |
| 資料庫 | `data/momo_database.db` | `data/momo_database.db` |
| 日誌 | `logs/` | `logs/` |

### 服務運行差異

| 項目 | 開發環境 | 正式環境 |
|------|----------|----------|
| 運行方式 | 直接 `python app.py` | systemd service |
| Port | 80 | 80 |
| 網址 | `http://127.0.0.1:80` | `https://momo.wooo.work` |
| 自動重啟 | 否 | 是（systemd） |
| 日誌管理 | 檔案 | systemd journal + 檔案 |

### 注意事項

1. **程式碼差異**：
   - 開發環境和正式環境的程式碼必須保持同步
   - 避免在正式環境直接修改程式碼
   - 所有修改必須經過開發→測試→部署流程

2. **資料庫差異**：
   - 開發環境和正式環境使用不同的資料庫
   - 不要混用資料庫檔案
   - 測試時使用測試資料，避免污染正式資料

3. **環境變數**：
   - `.env` 檔案在兩個環境中可能不同
   - 確保正式環境的憑證正確配置
   - 不要將 `.env` 上傳到 Git

---

## 🎯 最佳實踐

### DO ✅

- ✅ 小步提交，頻繁部署
- ✅ 每次部署前備份
- ✅ 完整測試後再部署
- ✅ 部署後立即驗證
- ✅ 監控 24 小時
- ✅ 記錄部署日誌
- ✅ 遵守憲法規範

### DON'T ❌

- ❌ 直接在正式環境改程式碼
- ❌ 跳過測試直接部署
- ❌ 部署後不驗證
- ❌ 不備份就部署
- ❌ 在高峰時段部署重大更新
- ❌ 同時部署多個大改動

---

## 📈 持續改進

### 定期檢視

- 每月檢視部署流程效率
- 收集部署中遇到的問題
- 優化自動化腳本
- 更新文檔

### 自動化目標

未來可考慮的自動化：
- [ ] CI/CD 流程（GitHub Actions）
- [ ] 自動化測試流程
- [ ] 自動化部署腳本
- [ ] 自動化回滾機制
- [ ] 部署通知（Telegram/Line）

---

**版本歷史**：
- v1.0 (2026-01-13): 初版發布，定義完整開發測試部署流程