wooo/ewoooc

Fork 0

Files

OoO 72fa166729

CD Pipeline / deploy (push) Successful in 1m46s

Details

fix(ai): 遷移 Ollama embedding 至 api embed

2026-04-30 10:24:15 +08:00

20 KiB

Raw Blame History

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

本文件定義專案開發的核心準則與不可違反的規範 建立日期: 2026-01-12 當前版本: V10.17 (Ollama embedding /api/embed 強化版) 最後更新: 2026-04-30

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

第 0.1 條：語言使用

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

第 0.2 條：文檔規範

所有文檔使用 Markdown 格式。
檔案名稱優先使用英文大寫加底線（例：CONSTITUTION.md）。
重要變更需記錄在對應正式文件中：入口變更寫 AGENTS.md，架構決策寫 ADR，長期專案知識寫 docs/memory/README.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 條：錯誤修復流程（強制要求）

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

第 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-29 修訂）

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

Hermes（採集層）: 192.168.0.111 Ollama，負責 embedding、去重、品質分數計算。成本 = $0
NemoTron（處理層）: NVIDIA NIM Llama 3.1 8B，負責 tool calling 邏輯路由與 DB 寫入。限額 80 次/天
OpenClaw / Gemini（應用層）: 負責最終 PPT 生成、洞察報告對外輸出。成本最高，最後動用
ElephantAlpha（編排層）: 負責跨 Agent orchestration、HITL、AutoHeal bridge 與受控執行計畫，不可繞過安全入口
❌ 禁止：讓 OpenClaw 做 Hermes 層的苦力工作（高算力浪費）
❌ 禁止：讓 Hermes 直接生成對外報告（品質不足）
❌ 禁止：讓 ElephantAlpha 直接繞過 EventRouter / AutoHeal / ADR-011 執行高風險副作用

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

✅ 正確：所有 AI 產出（PPT 洞察、競品分析、對話記錄、Agent action、自癒紀錄）必須雙寫 PostgreSQL ai_insights + pgvector embedding
❌ 禁止：只寫 DB 不寫 KM（RAG 無法語意搜尋）
❌ 禁止：只寫 KM 不寫 DB（精確 period/sku 查詢無法命中）
理由：DB 是精準命中，KM 是語意搜尋，兩者互補缺一不可（ADR-007）
入口：store_insight() 或 raw insert + enqueue_insight_embedding() → 同步寫 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 缺 API key、HTTP 429、timeout、network/HTTP error 或 0 tool call 時，立刻 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）

第 45.1 條：AI 自動化安全閉環（絕對禁止違反）

✅ 正確：EventRouter 是告警、降級、去重、通知 replay 與 L2 safe action 的入口
✅ 正確：AutoHeal 是自癒副作用入口，失敗時必須安全降級為 alert / log / file queue
✅ 正確：L2 safe action 必須可審計、可回放、低副作用
✅ 正確：AI 自動化觀測變更需同步 /metrics、Smoke dashboard 與 Grafana provisioning，避免告警閉環變成黑盒
❌ 禁止：自動 restart / stop / recreate momo-db 或 momo-postgres
❌ 禁止：AI 分析失敗導致 Telegram 告警完全不送出
依據：ADR-012、ADR-013、ADR-018

第十四章：Codex 工作規則（2026-04-29 修訂）

第 46 條：正式規範來源必須精簡且唯一（絕對禁止違反）

入口：AGENTS.md — Codex 專案工作入口與讀取順序
紅線：CONSTITUTION.md — 不可違反規則
ADR：docs/adr/ADR-XXX-*.md — 架構決策，只增不刪
Memory：docs/memory/README.md + 單篇 memory — 跨 session 的高重用記憶
SOT：docs/AI_INTELLIGENCE_MODULE_SOT.md — 當前架構事實
❌ 禁止：讓多份文件同時扮演正式入口，造成規則重複與 token 浪費

第 47 條：Session 開始採最小必要讀取（強制要求）

每次 Codex Session 開始必做：
1. 讀 AGENTS.md
2. 讀 CONSTITUTION.md 的相關章節
3. 讀 docs/adr/README.md，僅打開命中的 ADR
4. 讀 docs/memory/README.md，僅打開命中的 memory

第 48 條：Session 結束沉澱採最小必要更新（強制要求）

每次 Session 結束前必做 checklist：
□ 有新架構決策？→ 新建 ADR-XXX.md + 更新 docs/adr/README.md
□ 有長期有效的專案知識？→ 新增或更新 docs/memory/*.md + docs/memory/README.md
□ 有 SOT 變更？→ 更新 AI_INTELLIGENCE_MODULE_SOT.md
□ 有硬性紅線變更？→ 更新 CONSTITUTION.md
□ 有入口或工作方式變更？→ 更新 AGENTS.md

第 49 條：本專案不以本地 Skills 作為正式治理層（強制要求）

✅ 正確：重複流程優先寫成 docs/guides/*.md、腳本、測試或 ADR
✅ 正確：AI 自動化重複流程以 docs/guides/ai_automation_session_sop.md 維護
❌ 禁止：把 .claude/skills、私有 agent 腳本、外部平台工作流當成本專案正式規範來源

第 50 條：角色派工以 AGENTS 入口為準（強制要求）

✅ 正確：預設派工與角色選路以 AGENTS.md 的一頁式 dispatch 表為準
✅ 正確：角色詳細說明以 docs/guides/codex_agent_roles.md 為準
❌ 禁止：把歷史上的私有 agent 腳本、舊 onboarding 或散落文件當成更高優先級的派工真相

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

✅ 本憲法範圍：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（統帥批准，加入第十三、十四章）

20 KiB Raw Blame History Unescape Escape