wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: AI 治理完備 V10.3 — 技術債清零 + DB 備份機制 + 備份 AI 監控
Some checks are pending
CD Pipeline / deploy (push) Waiting to run
Details

Browse Source 
技術債清零 (2026-04-19):
- migrations/010: ai_insights 補 decay_exempt/avg_quality/status/ai_model/feedback 欄位
- migrations/011: embedding_retry_queue 持久化表 (ADR-009)
- migrations/012: backup_log 備份記錄表
- services/openclaw_learning_service: 記憶體 Queue → DB retry queue，時間衰減 RAG
- services/nemoton_dispatcher_service: 三個 tool 強制雙寫 ai_insights (_sink_insight_to_km)
- services/import_service: Excel 前置欄位防禦（商品名稱類 + 業績金額類）
- services/ollama_service: generate_embedding 新增 EMBEDDING_HOST env，embedding 永遠走 192.168.0.111
- SYSTEM_VERSION: V9.4 → V10.3

DB 備份機制:
- scripts/pg_backup.sh: host-level pg_dump 備份腳本，cron 每日 02:00，保留 7 天，Telegram 通知
- services/db_backup_service.py: Python 備份 service，寫入 backup_log
- scheduler: run_db_backup_task (02:00) + run_backup_monitor_task (每 6h AI Agent 監控)
- Dockerfile: 加入 postgresql-client

文件:
- CLAUDE.md: 環境架構依 ADR-008 實地重寫，含完整 SSH/Docker 部署 SOP
- PROJECT_CONSTITUTION.md: 內容已整合入 CLAUDE.md，刪除重複檔案

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ogt
2026-04-19 02:03:45 +08:00
parent 30e4485142
commit 676c711e7a
10 changed files with 494 additions and 5884 deletions
Download Patch File Download Diff File Expand all files Collapse all files

599
PROJECT_CONSTITUTION.md
View File

@@ -1,599 +0,0 @@
# 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
```
適用於：
- 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): 初版發布，定義核心規範