ewoooc/CONSTITUTION.md

EwoooC（原 MOMO Pro System）- 專案憲法 (CONSTITUTION)

本文件定義專案開發的核心準則與不可違反的規範 建立日期: 2026-01-12 當前版本: V10.2 (治理與安全重疊整合版) 最後更新: 2026-04-18

---

🗣️ 第零章：溝通與語法原則

第 0.1 條：語言使用

• 所有溝通一律使用繁體中文。包含：程式碼註解、文檔說明、Commit 訊息、錯誤訊息、日誌輸出、使用者介面文字。

第 0.2 條：文檔規範

• 所有文檔使用 Markdown 格式。
• 檔案名稱優先使用英文大寫加底線（例：CONSTITUTION.md）。
• 重要變更需記錄在 CLAUDE.md 或 walkthrough.md 中。

---

📜 憲法總綱

本專案憲法旨在確保系統的穩定性、一致性與可維護性。所有開發者（包括 AI 助手）在進行任何程式碼修改前，必須詳細閱讀並嚴格遵守本憲法的所有條款。

---

第一章：資料庫與模型層規範

第 1 條：商品 ID 命名規範（絕對禁止違反）

• ✅ 正確: 使用 product.i_code 作為商品唯一識別碼
• ❌ 禁止: 使用 product.momo_id（此屬性不存在）
• 理由: Product 模型定義為 i_code = Column(String(50), unique=True)
• 影響範圍: 所有查詢、API、前端顯示

第 2 條：時間戳處理規範（絕對禁止違反）

• ✅ 正確: 使用 datetime.now(TAIPEI_TZ).replace(tzinfo=None)
• ❌ 禁止: 直接使用 datetime.now() 或保留 tzinfo
• 理由: SQLite 不支援時區感知的 datetime，資料庫存儲必須為 naive datetime
• 影響範圍: 所有涉及時間比對的查詢（價格變動、統計計算）

第 3 條：價格變動邏輯（絕對禁止違反）

• ✅ 正確: 比對「今日最新價格」與「今日之前的最後一筆價格」
• ❌ 禁止: 僅查詢「昨天 00:00-23:59」的價格記錄
• 理由: 爬蟲可能跳過某些日期，必須容錯處理
• 實作方式:

  # 取得今日之前的最後一筆價格
  yesterday_prices_subq = session.query(
      PriceRecord.product_id,
      func.max(PriceRecord.id).label('max_id')
  ).filter(
      PriceRecord.product_id.in_(product_ids),
      PriceRecord.timestamp < today_start  # 不限定昨天
  ).group_by(PriceRecord.product_id).subquery()
  

第 4 條：查詢效能優化（強制要求）

• ✅ 正確: 使用批次查詢（如 yesterday_prices_map）
• ❌ 禁止: N+1 查詢模式（在迴圈內執行單筆查詢）
• 理由: 商品數量可達數千筆，N+1 查詢會導致嚴重效能問題
• 影響範圍: 儀表板、API、統計計算

---

第二章：爬蟲與資料採集規範

第 5 條：商品圖片 URL 構造（絕對禁止違反）

• ✅ 正確: 使用 CDN 直接構造

  image_url = f"https://m.momoshop.com.tw/moscdn/goods/{i_code}_m.webp"
  

• ❌ 禁止: 使用複雜的 DOM 查詢（8+ CSS 選擇器）
• 理由: CDN URL 格式固定且穩定，DOM 查詢速度慢且易失效
• 效能提升: 速度提升 20-30%

第 6 條：爬蟲頻率與禮貌性（強制要求）

• ✅ 正確: 每次請求間隔至少 1 秒
• ❌ 禁止: 高頻率無間隔爬取
• 理由: 避免被 MOMO 封鎖 IP

第 7 條：錯誤處理與重試機制（強制要求）

• ✅ 正確: 所有爬蟲函式必須使用 try-except 包裹
• ✅ 正確: 記錄失敗原因至日誌系統
• ❌ 禁止: 靜默失敗（吞掉例外）

---

第三章：API 設計規範

第 8 條：API 邏輯一致性（絕對禁止違反）

• ✅ 正確: API 的資料處理邏輯必須與儀表板完全一致
• ❌ 禁止: API 與前端使用不同的計算邏輯
• 理由: 避免前後端資料不一致，造成使用者困惑
• 實例: /api/price_change_details 必須使用與 get_consolidated_data() 相同的價格比對邏輯

第 9 條：API 錯誤處理（強制要求）

• ✅ 正確: 所有 API 必須使用 try-except-finally 結構
• ✅ 正確: 錯誤時返回 JSON 格式: {'products': []}, 500
• ✅ 正確: 記錄詳細錯誤日誌: sys_log.error()
• ❌ 禁止: 返回 HTML 錯誤頁面或純文字錯誤

第 10 條：API 效能優化（強制要求）

• ✅ 正確: 使用批次查詢與預先計算
• ❌ 禁止: 在迴圈中執行資料庫查詢
• 實例: 建立 yesterday_prices_map 一次性查詢所有商品的歷史價格

---

第四章：前端 UI/UX 規範

第 11 條：設計系統色彩（絕對禁止違反）

• ✅ 主題色: 紫色漸變 #667eea → #764ba2
• ✅ 漲價: 紅色 #dc3545 / #ff6b6b
• ✅ 降價: 綠色 #28a745 / #51cf66
• ❌ 禁止: 使用其他顏色作為主題色（除非整體改版）
• 理由: 保持與 Daily Sales 頁面視覺一致性

第 12 條：響應式設計（強制要求）

• ✅ 正確: 所有頁面必須支援手機版（< 768px）
• ✅ 正確: 使用 Bootstrap 5.3.3 的響應式網格系統
• ✅ 正確: 表格與圖表必須支援橫向滾動（手機版）
• ❌ 禁止: 僅針對桌面版設計

第 13 條：互動體驗（強制要求）

• ✅ 正確: 所有按鈕必須有 hover 效果（陰影、位移、顏色變化）
• ✅ 正確: 所有卡片必須有 hover 動畫
• ✅ 正確: 使用 transition: all 0.3s ease 實現平滑過渡
• ❌ 禁止: 靜態無互動的 UI 元素

第 14 條：字體與可讀性（強制要求）

• ✅ 正確: 主要文字顏色 #2c3e50（深灰）
• ✅ 正確: 表格表頭使用白色文字 #fff
• ❌ 禁止: 使用純黑色 #000（刺眼）
• ❌ 禁止: 使用低對比度顏色組合

---

第五章：系統架構規範

第 15 條：服務端口（絕對禁止違反）

• ✅ 正確: Flask 使用 Port 80
• ❌ 禁止: 使用 5888 或其他端口（已廢棄）
• 配置位置: config.py 的 PUBLIC_URL

第 16 條：資料庫路徑（絕對禁止違反）

• ✅ 正確: data/momo_database.db
• ❌ 禁止: 更改資料庫位置或名稱
• 配置位置: config.py 的 DATABASE_PATH

第 17 條：時區設定（絕對禁止違反）

• ✅ 正確: 使用 TAIPEI_TZ = pytz.timezone('Asia/Taipei')
• ❌ 禁止: 使用 UTC 或其他時區
• 理由: 所有業務邏輯基於台北時間

第 18 條：日誌系統（強制要求）

• ✅ 正確: 使用 sys_log.info() / sys_log.error() 記錄關鍵操作
• ✅ 正確: 日誌格式必須包含 [模組] [功能] 狀態 | 詳細資訊
• ❌ 禁止: 使用 print() 輸出日誌

---

第六章：版本管理規範

第 19 條：版本號更新（強制要求）

• ✅ 正確: 每次功能更新必須修改 app.py 的 SYSTEM_VERSION
• ✅ 格式: V主版本.次版本 (例如: V9.4)
• ❌ 禁止: 修改功能但不更新版本號

第 20 條：備份系統（強制要求）

• ✅ 正確: 重大更新前必須執行 python backup_system.py
• ✅ 排除目錄: ['backups', '__pycache__', '.git', '.idea', '.vscode', 'bin', 'bin 2']
• ❌ 禁止: 跳過備份直接上線

第 21 條：TODO 文件維護（強制要求）

• ✅ 正確: 完成功能後更新 TODO_NEXT_STEPS.txt 標記 ✅
• ✅ 正確: 記錄修改的檔案與行數
• ❌ 禁止: 完成任務但不更新文件

---

第七章：程式碼品質規範

第 22 條：命名規範（強制要求）

• ✅ 函式名稱: 使用 snake_case (例如: get_price_change_details)
• ✅ 類別名稱: 使用 PascalCase (例如: PriceRecord)
• ✅ 變數名稱: 使用有意義的描述性名稱
• ❌ 禁止: 使用 a, b, temp, data 等無意義名稱

第 23 條：註解規範（強制要求）

• ✅ 正確: 在複雜邏輯前加上中文註解說明「為什麼」
• ✅ 正確: 修復 Bug 時標註 V-Fix:
• ✅ 正確: 新增功能時標註 V-New:
• ❌ 禁止: 完全不寫註解或寫無意義註解

第 24 條：DRY 原則（強制要求）

• ✅ 正確: 重複邏輯必須抽取為函式
• ❌ 禁止: 複製貼上相同程式碼超過 2 次
• 實例: get_consolidated_data() 封裝了通用的資料查詢邏輯

---

第八章：測試與除錯規範

第 25 條：修改前測試（強制要求）

• ✅ 正確: 修改程式碼前，先了解現有功能的行為
• ✅ 正確: 修改後必須測試相關功能是否正常
• ❌ 禁止: 修改後直接提交，未經測試

第 26 條：錯誤修復流程（強制要求）

1. 閱讀錯誤日誌 (logs/system.log)
2. 定位問題程式碼位置
3. 理解根本原因（不是表面症狀）
4. 修復問題並添加註解
5. 測試修復是否有效
6. 檢查是否有相同問題的其他地方

第 27 條：日誌檢查（強制要求）

• ✅ 正確: 修改 API 後檢查日誌是否有錯誤
• ✅ 正確: 使用 tail -f logs/system.log 即時監控
• ❌ 禁止: 盲目修改不看日誌

---

第九章：效能優化規範

第 28 條：資料庫查詢優化（強制要求）

• ✅ 正確: 使用 subquery 與 JOIN 減少查詢次數
• ✅ 正確: 使用 options(joinedload()) 預載關聯資料
• ❌ 禁止: 在迴圈中執行查詢（N+1 問題）

第 29 條：前端效能優化（強制要求）

• ✅ 正確: 圖表使用 CDN 載入 Chart.js
• ✅ 正確: 大表格使用分頁或虛擬滾動
• ❌ 禁止: 一次渲染超過 1000 筆資料

第 30 條：快取策略（建議執行）

• ✅ 建議: 對不常變動的資料實作快取（5-10 分鐘）
• ✅ 建議: 使用 get_consolidated_data() 的結果快取
• ⚠️ 注意: 快取必須有過期機制

---

第十章：安全性規範

第 31 條：敏感資訊保護（絕對禁止違反）

• ✅ 正確: 所有 API Token、密碼存放於 config.py
• ❌ 禁止: 硬編碼敏感資訊於程式碼中
• ❌ 禁止: 提交 config.py 至公開 Git 倉庫

第 32 條：SQL 注入防護（絕對禁止違反）

• ✅ 正確: 使用 SQLAlchemy ORM 的參數化查詢
• ❌ 禁止: 使用字串拼接建構 SQL 查詢
• 範例:

  # ✅ 正確
  session.query(Product).filter(Product.i_code == user_input)
  
  # ❌ 禁止
  session.execute(f"SELECT * FROM products WHERE i_code = '{user_input}'")
  

第 33 條：XSS 防護（強制要求）

• ✅ 正確: Jinja2 模板自動跳脫 HTML
• ✅ 正確: JavaScript 中使用 textContent 而非 innerHTML
• ❌ 禁止: 直接插入未驗證的使用者輸入

---

第十一章：部署與維運規範

第 34 條：伺服器啟動（強制要求）

• ✅ 正確: 使用 nohup python3 app.py > /dev/null 2>&1 & 背景執行
• ✅ 正確: 部署前檢查 Port 80 是否已被佔用
• ❌ 禁止: 直接執行 python3 app.py（關閉終端機會停止服務）

第 35 條：伺服器重啟（強制要求）

• ✅ 正確步驟:
  1. pkill -9 -f "python3 app.py" (停止舊程序)
  2. sleep 2 (等待端口釋放)
  3. nohup python3 app.py > /dev/null 2>&1 & (啟動新程序)
  4. ps aux | grep "[p]ython3 app.py" (確認運行)

第 36 條：日誌輪替（建議執行）

• ✅ 建議: 定期清理過大的日誌檔案 (> 100MB)
• ✅ 建議: 使用 logrotate 自動管理日誌

---

第十二章：協作開發規範

第 37 條：Git Commit 規範（強制要求）

• ✅ 正確格式: [版本號] 功能描述 | 修改的檔案
• 範例: [V9.4] 修正彈窗無資料問題 | app.py, dashboard.html
• ❌ 禁止: fix, update, 修改 等無意義訊息

第 38 條：程式碼審查（強制要求）

• ✅ 正確: 重大修改前與 AI 助手討論方案
• ✅ 正確: 提供清晰的需求描述與預期結果
• ❌ 禁止: 直接要求 AI 「修改成...」而不解釋原因

第 39 條：憲法修訂（特別規定）

• ✅ 修訂權限: 僅限專案負責人（統帥）
• ✅ 修訂流程: 提出修訂 → 討論評估 → 更新文件 → 通知全員
• ⚠️ 重要: 本憲法不可輕易修改，除非有重大架構變更

---

第十三章：AI 三 Agent 自主學習架構規範（2026-04-18 加入）

第 40 條：三 Agent 分工架構（絕對禁止違反）

• Hermes（採集層）: 192.168.0.111 Ollama，負責 embedding、去重、品質分數計算。成本 = $0
• NemoTron（處理層）: NVIDIA NIM Llama 3.1 8B，負責 tool calling 邏輯路由與 DB 寫入。限額 80 次/天
• OpenClaw / Gemini（應用層）: 負責最終 PPT 生成、洞察報告對外輸出。成本最高，最後動用
• ❌ 禁止：讓 OpenClaw 做 Hermes 層的苦力工作（高算力浪費）
• ❌ 禁止：讓 Hermes 直接生成對外報告（品質不足）

第 41 條：AI 學習數據雙寫（絕對禁止違反）

• ✅ 正確：所有 AI 產出（PPT 洞察、競品分析、對話記錄）必須雙寫 PostgreSQL ai_insights + pgvector embedding
• ❌ 禁止：只寫 DB 不寫 KM（RAG 無法語意搜尋）
• ❌ 禁止：只寫 KM 不寫 DB（精確 period/sku 查詢無法命中）
• 理由：DB 是精準命中，KM 是語意搜尋，兩者互補缺一不可（ADR-007）
• 入口：NemoTron store_insight tool call → 同步寫 DB → 異步排隊給 Hermes 做 embedding

第 42 條：KM 向量庫技術選型（絕對禁止違反）

• ✅ 唯一選擇：pgvector（與現有 PostgreSQL 192.168.0.188 同一 DB）
• ❌ 禁止：引入 ChromaDB、Qdrant 等獨立向量庫
• 理由：混合查詢（WHERE 結構化 + ORDER BY embedding <-> 語意）只有 pgvector 能一條 SQL 搞定（ADR-002）

第 43 條：Embedding 本地化（強制要求）

• ✅ 正確：使用 bge-m3（或 nomic-embed-text）掛載在 Hermes 主機 192.168.0.111 Ollama
• ❌ 禁止：呼叫外部 Embedding API（成本與隱私雙重問題）
• 維度：1024 dim（vector(1024) 欄位）（ADR-003）

第 44 條：NemoTron 配額 Fallback 機制（強制要求）

• ✅ 正確：當 NIM 回傳 HTTP 429 時，立刻 fallback 至 _hermes_rule_fallback() rule-based 派發
• ❌ 禁止：配額耗盡時讓告警管線中斷
• 標記：降級模式告警須帶 🟡 前綴，讓統帥識別（ADR-004）

第 45 條：KM 品質分數時間衰減（強制要求）

• ✅ 公式：effective_score = base_score × e^(-decay_rate × days_passed)
• decay_rate：0.005（預設）；decay_exempt=True 用於結構性/憲法類知識
• 理由：確保 RAG 優先抓取最新、最適用的洞察，避免歷史偏誤（ADR-005）

---

第十四章：Claude Code 官方遊戲規則（2026-04-18 加入）

第 46 條：記憶架構四層必須完整（絕對禁止違反）

• Memory：~/.claude/projects/.../memory/*.md — 跨 Session 持久記憶
• ADR：docs/adr/ADR-XXX-*.md — 架構決策，只增不刪
• SOT：docs/AI_INTELLIGENCE_MODULE_SOT.md — 當前架構事實
• Skills：.claude/skills/*.py — 執行 SOP checklist
• ❌ 禁止：任何一層缺失，都會導致後續 Session 失憶或決策矛盾

第 47 條：Session 開始 SOP（強制要求）

每次 Claude Session 開始必做：
1. 讀 CLAUDE.md 第零章（元憲法）
2. 讀 memory/MEMORY.md 索引
3. 讀 docs/adr/README.md 索引
4. 才開始執行任務

第 48 條：Session 結束沉澱 SOP（強制要求）

每次 Session 結束前必做 checklist：
□ 有架構決策？→ 新建 ADR-XXX.md + 更新索引
□ 有統帥偏好？→ 更新 memory/user_profile.md
□ 有技術債？→ 更新 memory/project_tech_debt_backlog.md
□ 有 SOT 變更？→ 更新 AI_INTELLIGENCE_MODULE_SOT.md
□ 有憲法新條款？→ 更新 CONSTITUTION.md + CLAUDE.md
□ 更新 memory/MEMORY.md 索引

第 49 條：專案範圍邊界（絕對禁止違反）

• ✅ 本憲法範圍：momo-pro-system（EwoooC）唯一
• ❌ 禁止：將 AWOOOI / WOOO AIOps SaaS 的決策混入本文件
• ❌ 禁止：跨專案邊界做架構決策

---

附錄 A：常見錯誤與解決方案

錯誤 1: 'Product' object has no attribute 'momo_id'

• 原因: 使用錯誤的屬性名稱
• 解決: 改用 product.i_code

錯誤 2: API 返回空資料

• 原因: 價格比對邏輯錯誤（只查昨天）
• 解決: 使用「今日之前最後一筆」邏輯

錯誤 3: 時間戳比對失敗

• 原因: 時區感知 datetime 與 naive datetime 混用
• 解決: 使用 .replace(tzinfo=None) 統一為 naive

錯誤 4: 彈窗顯示「無資料」

• 原因: API 邏輯與前端不一致
• 解決: 確保使用相同的 yesterday_prices_map 查詢

---

附錄 B：關鍵檔案索引

檔案路徑	用途	禁止修改項目
config.py	系統配置	DATABASE_PATH, PUBLIC_URL
database/models.py	資料模型	Product.i_code 定義
app.py	主程式	SYSTEM_VERSION, TAIPEI_TZ
dashboard.html	商品看板	主題色系、響應式設計
daily_sales.html	業績看板	行事曆邏輯、圖表配置
scheduler.py	排程爬蟲	商品圖 CDN URL 構造
backup_system.py	備份系統	排除目錄清單

---

附錄 C：版本更新檢查清單

每次發布新版本前，必須確認以下項目：

• SYSTEM_VERSION 已更新
• 相關功能已測試正常運作
• 日誌無錯誤訊息
• TODO_NEXT_STEPS.txt 已更新
• 已執行系統備份
• API 邏輯與前端一致
• 響應式設計正常（手機版測試）
• 資料庫查詢效能正常（無 N+1 問題）

---

結語

本憲法的目的是維護專案的長期穩定性與開發效率。所有開發者（包括 AI 助手）在遇到與憲法條款衝突的需求時，應優先遵守憲法，並與專案負責人討論是否需要修訂憲法。

記住: 一個穩定運行的系統，遠比一個功能豐富但 Bug 頻出的系統更有價值。

---

專案憲法版本: 2.0 生效日期: 2026-01-12 最後審核: 2026-04-18（統帥批准，加入第十三、十四章）