# MOMO 監控系統 - 專案憲法

**版本：** 1.3
**制定日期：** 2026-01-12
**最後更新：** 2026-01-14

---

## 📜 專案基本原則

本憲法定義了 MOMO 監控系統的開發規範、溝通原則、安全政策及技術標準。所有參與者（開發人員、AI 助手、維護人員）必須遵守以下規範。

---

## 🗣️ 第一章：溝通規範

### 第 1 條：語言使用
- **所有溝通一律使用繁體中文**
- 包含但不限於：
  - 程式碼註解
  - 文檔說明
  - Commit 訊息
  - 錯誤訊息
  - 日誌輸出
  - 使用者介面文字
  - README 和文檔

### 第 2 條：文檔規範
- 所有文檔檔案使用 Markdown 格式（`.md`）
- 檔案名稱使用英文大寫加底線（例：`PROJECT_CONSTITUTION.md`）
- 文檔內容必須包含版本號和最後更新日期
- 重要變更需記錄在 CHANGELOG 中

### 第 3 條：註解規範
- Python 函數必須包含繁體中文 docstring
- 複雜邏輯必須添加行內註解說明
- 註解應說明「為什麼」而非「做什麼」

---

## 🔒 第二章：安全政策

### 第 4 條：敏感資訊管理
- **禁止在程式碼中硬編碼任何敏感資訊**
- 所有憑證、API 金鑰、密碼必須使用環境變數（`.env`）
- `.env` 檔案必須列入 `.gitignore`
- 提供 `.env.example` 作為範本

### 第 5 條：密碼安全
- 所有密碼必須使用 `pbkdf2:sha256` 雜湊儲存
- 禁止使用明文密碼（僅過渡期允許，需發出警告）
- 密碼長度至少 8 個字元，包含英文字母和數字
- 登入失敗 5 次後鎖定帳號 5 分鐘

### 第 6 條：輸入驗證
- **所有使用者輸入必須經過驗證**
- SQL 查詢必須使用參數化查詢或白名單驗證
- 檔案上傳必須驗證副檔名和檔案大小
- 路徑操作必須使用 `safe_join()` 防止路徑遍歷

### 第 7 條：CSRF 防護
- 所有 POST/PUT/DELETE/PATCH 請求必須包含 CSRF token
- HTML 表單使用 hidden input: `<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>`
- AJAX 請求使用 header: `'X-CSRFToken': getCSRFToken()`

### 第 8 條：Session 安全
- Session cookie 必須設定 `HttpOnly=True`
- Session cookie 必須設定 `SameSite=Lax`
- 生產環境必須設定 `Secure=True`（HTTPS）
- Session 有效期設定為 2 小時

---

## 💻 第三章：程式碼規範

### 第 9 條：檔案上傳
- 僅允許上傳：`.xlsx`, `.xls`, `.csv`
- 檔案大小限制：10 MB
- 使用 `secure_filename_unicode()` 清理檔名（支援中文）
- 檢查路徑遍歷攻擊（`..`, `/`, `\`）

### 第 10 條：SQL 安全
- 表名驗證：僅允許英文字母、數字、底線
- 欄位名驗證：允許中文、英文字母、數字、底線
- 時間戳驗證：嚴格遵守 `YYYY-MM-DD HH:MM:SS` 格式
- 使用 `safe_read_sql()` 進行安全的 SQL 查詢

### 第 11 條：路徑安全
- 所有路徑拼接使用 `safe_join(base, *paths)`
- 檢查 Windows 反斜線、連續點、雙點模式
- 驗證最終路徑在基礎目錄內
- 偵測到攻擊時記錄安全日誌

### 第 12 條：日誌規範
- 使用結構化日誌格式：`[模組] [級別] 訊息 | 詳細資訊`
- 安全事件使用 `[Security]` 標籤
- 記錄所有失敗的驗證嘗試
- 日誌級別：
  - `ERROR`: 系統錯誤
  - `WARNING`: 安全警告、失敗的攻擊嘗試
  - `INFO`: 重要操作成功
  - `DEBUG`: 詳細除錯資訊

---

## 🕷️ 第四章：數據爬取規範

### 第 13 條：爬蟲程式碼穩定性原則
- **爬蟲程式碼屬於核心業務邏輯，修改時必須格外謹慎**
- 任何修改必須經過完整測試，確認不影響現有爬取功能
- 修改前必須備份現有可運作的版本
- 修改後必須驗證所有爬蟲任務正常執行

### 第 14 條：爬蟲選擇器維護
- **CSS 選擇器和 XPath 是脆弱的依賴**
- 修改選擇器前必須：
  1. 記錄修改原因（網站改版、元素變更等）
  2. 測試新選擇器是否正確抓取目標資料
  3. 保留舊選擇器作為註解備份
  4. 記錄網站結構變更日期
- 建議使用多層次選擇器備援（主選擇器 + 備用選擇器）

### 第 15 條：爬蟲錯誤處理
- **所有爬蟲函數必須包含完整的錯誤處理**
- 必須處理的情況：
  1. 網路連線失敗
  2. 頁面載入超時
  3. 元素找不到（選擇器失效）
  4. 資料格式異常
  5. 反爬蟲機制觸發
- 錯誤發生時：
  - 記錄詳細錯誤日誌（包含 URL、選擇器、錯誤訊息）
  - 發送通知給管理員
  - 不中斷其他爬蟲任務
  - 保存最後成功的資料作為備援

### 第 16 條：爬蟲測試要求
- **修改爬蟲程式碼後必須執行完整測試**
- 測試項目：
  1. 單一商品資料爬取
  2. 列表頁面分頁爬取
  3. 多執行緒/並發爬取
  4. 錯誤處理機制
  5. 資料儲存完整性
- 測試環境應模擬生產環境（網路延遲、並發請求）
- 使用測試資料集驗證爬取結果準確性

### 第 17 條：爬蟲依賴管理
- **爬蟲依賴的套件版本必須固定**
- `requirements.txt` 中爬蟲相關套件必須指定版本號：
  - `selenium==4.x.x` （具體版本）
  - `requests==2.x.x`
  - `beautifulsoup4==4.x.x`
- 升級套件前必須：
  1. 在測試環境驗證相容性
  2. 檢查 changelog 確認無破壞性變更
  3. 執行完整爬蟲測試套件
  4. 記錄升級原因和影響

### 第 18 條：網站結構變更應對
- **定期檢查目標網站結構是否變更**
- 建立網站結構監控機制：
  1. 記錄關鍵元素的 HTML 結構
  2. 定期比對結構變化
  3. 發現變更時立即通知
  4. 建立選擇器失效告警
- 保存網站結構快照（HTML samples）供除錯使用

### 第 19 條：爬蟲效能與禮節
- **遵守網站的 robots.txt 規範**
- 設定合理的請求間隔（建議 1-3 秒）
- 使用 User-Agent 識別身份
- 避免在網站高峰時段進行大量爬取
- 實作請求失敗的退避重試機制（Exponential Backoff）

### 第 20 條：資料驗證與清洗
- **爬取的資料必須經過驗證**
- 驗證項目：
  1. 價格範圍合理性（不可為 0 或異常大）
  2. 日期格式正確性
  3. 必填欄位完整性
  4. 資料型別正確性
- 發現異常資料時：
  - 記錄到錯誤日誌
  - 標記為「需人工審核」
  - 不自動儲存到資料庫
  - 發送通知給管理員

### 第 21 條：爬蟲版本控制
- **爬蟲程式碼每次修改必須建立 Git commit**
- Commit 訊息格式：
  - `[Crawler] [網站名稱] 修改描述`
  - 例：`[Crawler] [MOMO] 修復商品價格選擇器失效問題`
- 重大修改應建立分支，測試通過後才合併
- 保留至少最近 3 個可運作版本的備份

### 第 22 條：爬蟲文檔要求
- **每個爬蟲模組必須包含詳細文檔**
- 必須記錄：
  1. 爬取目標（網站 URL、資料類型）
  2. 執行頻率（每小時/每日）
  3. 關鍵選擇器說明
  4. 已知問題和限制
  5. 最後修改日期和原因
  6. 聯絡人/負責人
- 文檔應隨程式碼更新

---

## 🧪 第五章：測試與品質保證

### 第 23 條：測試覆蓋
- 所有安全功能必須有對應的測試
- 測試必須包含正常情況和攻擊情境
- 使用 `test_*.py` 命名測試檔案
- 執行 `./run_security_tests.sh` 必須全部通過

### 第 24 條：安全測試項目
必須測試以下項目：
1. 環境變數與憑證管理
2. SQL 注入防護
3. 路徑遍歷防護
4. 檔案上傳驗證
5. CSRF 防護
6. 登入驗證強化
7. Flask 安全配置

### 第 25 條：爬蟲測試項目
必須測試以下項目：
1. 選擇器有效性測試
2. 資料完整性測試
3. 錯誤處理測試
4. 並發爬取測試
5. 效能壓力測試

### 第 26 條：程式碼審查
- 所有涉及安全的程式碼變更必須經過審查
- 所有涉及爬蟲的程式碼變更必須經過審查
- 檢查是否符合本憲法規範
- 驗證是否通過完整測試
- 確認日誌和錯誤處理完整

---

## 📦 第六章：部署與維運

### 第 27 條：環境管理規範

#### 27.1 環境分層
本系統採用三層環境架構：

1. **開發環境 (Development)**
   - 位置：`/Users/ogt/momo_pro_system` (macOS Local)
   - 用途：程式碼開發、快速測試、UI/UX 調整
   - 運行方式：直接執行 `python app.py`
   - 特性：即時修改、快速迭代

2. **測試環境 (Testing)**
   - 位置：同開發環境
   - 用途：功能測試、安全測試、回歸測試
   - 運行方式：執行測試腳本

3. **正式環境 (Production)**
   - 位置：`/home/ogt/momo_pro_system` (GCP VM)
   - 用途：生產服務、24/7 運行
   - 運行方式：systemd service
   - 網址：`https://momo.wooo.work`

#### 27.2 環境同步原則

**嚴格禁止**：
- ❌ 直接在正式環境修改程式碼
- ❌ 跳過測試直接部署到正式環境
- ❌ 混用不同環境的資料庫
- ❌ 將 `.env` 檔案上傳到 Git

**必須遵守**：
- ✅ 所有修改必須在開發環境完成
- ✅ 完整測試通過後才能部署
- ✅ 部署前必須備份正式環境
- ✅ 部署後必須驗證功能正常
- ✅ 監控 24 小時確保穩定

#### 27.3 標準部署流程

參照 `DEPLOYMENT_WORKFLOW.md` 文檔，嚴格遵守以下流程：

```
開發 → 測試 → 備份 → 部署 → 驗證 → 監控
```

**階段性檢查**：
1. **開發階段**：程式碼符合規範、Git commit 完成
2. **測試階段**：功能測試、安全測試、爬蟲測試通過
3. **部署前**：備份正式環境、確認修改檔案清單
4. **部署中**：使用標準部署腳本或手動部署
5. **部署後**：服務狀態正常、功能驗證通過
6. **監控期**：持續監控 24 小時

#### 27.4 部署方法選擇

**方法 A：完整部署**（推薦用於大改動）
```bash
cd /Users/ogt/momo_pro_system
./deploy_scripts/deploy_to_gcp.sh
```
適用於：
- Python 程式碼修改
- 依賴套件更新
- 配置檔案變更
- 資料庫結構變更

**方法 B：快速更新**（用於小改動）
```bash
gcloud compute scp --zone=asia-east1-a 修改的檔案 momo-server:~/momo_pro_system/
```
適用於：
- HTML/CSS/JS 檔案修改
- 模板檔案更新
- 靜態資源更新

**重要**：
- HTML/CSS/JS 修改：不需重啟服務（Flask 自動重載模板）
- Python 檔案修改：必須重啟服務
- 配置檔案修改：必須重啟服務

### 第 28 條：變更前強制備份原則 ⚠️

**重要性：最高優先級**

**核心原則**：
- **所有涉及嚴重影響的變更、修改操作，變更前必須先進行完整備份**
- **備份完成並確認無誤後，才可進行變更**
- 違反此原則的變更操作視為嚴重違規

**適用範圍**：
以下操作在執行前必須完整備份：

1. **資料庫相關**
   - 資料庫結構變更（ALTER TABLE, DROP, CREATE）
   - 大量資料修改或刪除（UPDATE, DELETE 影響 >100 筆）
   - 資料庫升級或遷移
   - 索引重建或優化

2. **系統配置**
   - 系統配置檔案修改（config.py, .env）
   - Nginx/Apache 配置變更
   - Systemd service 配置修改
   - 排程任務（crontab, scheduler）變更

3. **核心程式碼**
   - 爬蟲核心邏輯修改
   - 資料庫連線和 ORM 修改
   - 認證和安全模組修改
   - API 端點的破壞性變更

4. **部署操作**
   - 生產環境程式碼更新
   - Python 依賴套件升級
   - 系統套件升級（Python, Node.js 等）
   - 伺服器遷移或重啟

5. **資料處理**
   - Excel 匯入覆蓋現有資料
   - 批次資料清理或轉換
   - 歷史資料歸檔或刪除

**備份要求**：

**必須備份的內容**：
- 完整資料庫檔案（momo.db 或 PostgreSQL dump）
- 所有程式碼檔案（Git commit + 檔案副本）
- 配置檔案（config.py, .env, nginx.conf 等）
- 重要的資料檔案（Excel, CSV 等）

**備份驗證**：
- 檢查備份檔案完整性（檔案大小、MD5 校驗）
- 確認備份可讀取（嘗試開啟資料庫）
- 記錄備份時間和檔案位置
- 確保備份檔案有足夠的磁碟空間

**備份命名規範**：
```
資料庫：momo_backup_YYYYMMDD_HHMMSS.db
程式碼：momo_code_backup_YYYYMMDD_HHMMSS.tar.gz
配置：config_backup_YYYYMMDD_HHMMSS.tar.gz
```

**復原計畫**：
- 每次重大變更必須準備復原步驟文件
- 測試復原流程的可行性
- 記錄復原所需時間
- 確保有回滾機制

**違規處理**：
- 未備份就執行重大變更：視為一級違規
- 備份不完整或無法復原：視為二級違規
- 必須立即停止變更，進行損害評估
- 記錄事件並更新操作規範

**例外情況**：
僅以下情況可豁免備份要求：
- 純前端 HTML/CSS/JS 修改（不影響資料）
- 日誌檔案查看（唯讀操作）
- 系統監控和狀態查詢
- 測試環境的實驗性變更

### 第 29 條：環境配置
- 開發環境使用 `.env`
- 生產環境使用環境變數注入
- 不同環境使用不同的 `SECRET_KEY`
- 定期輪換敏感憑證

### 第 30 條：備份策略
- 資料庫每日自動備份
- 備份檔案加密保存
- 保留最近 7 天備份
- 使用 `safe_join()` 處理備份路徑

### 第 31 條：更新流程
1. **評估變更影響**（是否需要備份，參照第 28 條）
2. **完整備份**（若屬於重大變更，必須先備份）
3. 更新程式碼
4. 執行完整測試套件（安全測試 + 爬蟲測試）
5. 檢查安全日誌
6. 重啟服務
7. 驗證功能正常（包含爬蟲任務）
8. 監控 24 小時確保穩定
9. 確認備份可刪除或歸檔

---

## 🚨 第七章：事件處理

### 第 32 條：安全事件
發現安全漏洞時：
1. 立即記錄詳細資訊
2. 評估風險等級（Critical/High/Medium/Low）
3. 優先處理 Critical 和 High 級別
4. 修復後執行完整測試
5. 更新 `SECURITY_FIX_SUMMARY.md`

### 第 33 條：爬蟲異常事件
發現爬蟲異常時：
1. 記錄詳細錯誤資訊（URL、選擇器、錯誤訊息）
2. 檢查是否為網站結構變更
3. 若為選擇器失效，立即修復並測試
4. 發送通知給管理員
5. 記錄在爬蟲維護日誌中

### 第 34 條：錯誤處理
- 所有錯誤必須妥善處理，不得暴露敏感資訊
- 使用者看到的錯誤訊息應簡潔明確
- 詳細錯誤資訊記錄在日誌中
- 開發環境可顯示詳細錯誤，生產環境僅顯示通用訊息

---

## 🔧 第八章：開發工具與依賴

### 第 35 條：Python 依賴
核心依賴套件（見 `requirements.txt`）：
- Flask (Web 框架)
- Flask-WTF (CSRF 防護)
- SQLAlchemy (ORM)
- pandas (資料處理)
- selenium (網頁自動化)
- werkzeug (安全工具)

### 第 36 條：版本控制
- 使用 Git 進行版本控制
- Commit 訊息使用繁體中文
- Commit 格式：`[模組] 簡短描述`
- 例：`[Security] 修復路徑遍歷漏洞`
- 例：`[Crawler] [MOMO] 更新商品價格選擇器`

### 第 37 條：開發環境
- Python 3.8+
- 使用虛擬環境 (venv)
- IDE 建議：VSCode, PyCharm
- 測試環境與生產環境分離
- 爬蟲測試使用獨立環境

---

## 📊 第九章：監控與維護

### 第 38 條：系統監控
- 定期檢查安全日誌
- 監控登入失敗次數
- 追蹤異常 API 請求
- 定期執行安全測試

### 第 39 條：爬蟲監控
- 監控爬蟲執行成功率
- 追蹤選擇器失效次數
- 檢查資料品質（異常值、缺失值）
- 監控爬取耗時變化
- 定期檢查目標網站結構

### 第 40 條：效能監控
- 資料庫查詢效能
- API 回應時間
- 記憶體使用量
- 磁碟空間
- 爬蟲執行效率

---

## 📋 第十章：憲法修訂

### 第 41 條：修訂流程
- 本憲法可隨專案需求修訂
- 修訂需說明原因和影響範圍
- 更新版本號和修訂日期
- 記錄在文檔歷史中

### 第 42 條：解釋權
- 本憲法條款如有疑義，以最新版本為準
- 技術決策以穩定性和安全性優先
- 爬蟲修改以不影響現有功能為原則
- 使用者體驗和效能次之

---

## 📚 附錄：快速檢查清單

### ✅ 新功能開發檢查
- [ ] 程式碼和註解使用繁體中文
- [ ] 無硬編碼敏感資訊
- [ ] 所有輸入經過驗證
- [ ] POST 請求包含 CSRF token
- [ ] 路徑操作使用 `safe_join()`
- [ ] 檔案上傳經過驗證
- [ ] 錯誤處理完整
- [ ] 日誌記錄完整
- [ ] 通過安全測試
- [ ] 更新相關文檔

### ⚠️ 重大變更前備份檢查
- [ ] 評估變更影響範圍（資料庫/配置/核心程式碼/部署）
- [ ] 確認符合第 28 條適用範圍
- [ ] 完整備份資料庫檔案
- [ ] 備份所有程式碼（Git commit + 檔案副本）
- [ ] 備份配置檔案
- [ ] 驗證備份檔案完整性（檔案大小、可讀取）
- [ ] 記錄備份時間和位置
- [ ] 準備復原計畫文件
- [ ] 測試復原流程可行性
- [ ] 確保有回滾機制

### 🔒 安全審查檢查
- [ ] SQL 查詢使用參數化或白名單
- [ ] 無明文密碼
- [ ] Session 配置正確
- [ ] CSRF 防護啟用
- [ ] 路徑遍歷防護
- [ ] 檔案上傳限制
- [ ] 登入失敗鎖定
- [ ] 敏感操作有日誌

### 🕷️ 爬蟲修改檢查
- [ ] 備份現有可運作版本
- [ ] 記錄修改原因和網站變更資訊
- [ ] 保留舊選擇器作為註解
- [ ] 測試新選擇器正確性
- [ ] 執行單一商品爬取測試
- [ ] 執行列表頁面爬取測試
- [ ] 驗證資料完整性和格式
- [ ] 檢查錯誤處理機制
- [ ] 更新爬蟲文檔
- [ ] 記錄在維護日誌中
- [ ] 建立 Git commit
- [ ] 監控 24 小時確保穩定

---

## 🎯 結語

本憲法旨在確保 MOMO 監控系統的安全性、穩定性、可維護性和一致性。所有參與者應：

1. **遵守規範**：嚴格遵守本憲法所有條款
2. **持續改進**：隨著專案發展適時修訂
3. **穩定優先**：爬蟲修改以不影響現有功能為原則
4. **安全第一**：任何決策以安全為最高優先
5. **謹慎測試**：修改後必須完整測試並監控
6. **文檔完整**：保持文檔與程式碼同步更新

**核心原則：**
- **安全不是功能，而是基礎**
- **爬蟲是核心業務，修改需格外謹慎**
- **測試是品質的保證，不可省略**

---

**版本歷史：**
- v1.3 (2026-01-14): 新增第六章第 28 條「變更前強制備份原則」⚠️，明確規定所有涉及嚴重影響的變更操作前必須完整備份，定義適用範圍、備份要求、驗證流程、復原計畫及違規處理機制
- v1.2 (2026-01-13): 擴充第六章第 27 條「環境管理規範」，明確定義開發/測試/正式三層環境架構、環境同步原則、標準部署流程，並新增 `DEPLOYMENT_WORKFLOW.md` 完整部署文檔
- v1.1 (2026-01-12): 新增第四章「數據爬取規範」（第 13-22 條），定義爬蟲程式碼穩定性、選擇器維護、錯誤處理、測試要求等 10 項規範
- v1.0 (2026-01-12): 初版發布，定義核心規範