wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f11b0cc732badef544016d56a3571d0fca4fd5e3
ewoooc/PROJECT_CONSTITUTION.md

18 KiB
Raw Blame History

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：完整部署（推薦用於大改動）

cd /Users/ogt/momo_pro_system
./deploy_scripts/deploy_to_gcp.sh

適用於：

  • Python 程式碼修改
  • 依賴套件更新
  • 配置檔案變更
  • 資料庫結構變更

方法 B：快速更新（用於小改動）

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): 初版發布，定義核心規範
Reference in New Issue View Git Blame Copy Permalink