ewoooc/CONSTITUTION.md

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

> 本文件定義專案開發的核心準則與不可違反的規範
> **建立日期**: 2026-01-12
> **當前版本**: V10.63 (Warm dashboard cache after AI pick regeneration)
> **最後更新**: 2026-05-01

---

## 🗣️ 第零章：溝通與語法原則
### 第 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」的價格記錄
- **理由**: 爬蟲可能跳過某些日期，必須容錯處理
- **實作方式**:
  ```python
  # 取得今日之前的最後一筆價格
  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 直接構造
  ```python
  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 條：前端 V2 視覺基準（絕對禁止違反）
- ✅ **正式基準**: 前端相關視覺呈現風格與 UI/UX，以 `MOMO Pro/` 新版原型為主要依據。
- ✅ **設計語言**: 米色工作台背景、暖墨文字、焦糖橘 accent、細線框、克制陰影、側邊欄 + 頂部工具列。
- ✅ **資料字體**: 數字、商品 ID、時間、價格與表格欄位標籤優先使用等寬字體。
- ✅ **漲價**: 使用新版 token 的 danger 色系（紅色）。
- ✅ **降價**: 使用新版 token 的 success 色系（綠色）。
- ❌ **禁止**: 新增頁面或更版頁面回到舊紫藍漸層主題、彩色表頭、厚重 KPI 卡片或五彩按鈕風格。
- **依據**: `MOMO Pro/HANDOFF.md`、`MOMO Pro/design-tokens.css`、`docs/guides/frontend_upgrade_roadmap.md`

### 第 12 條：響應式設計（強制要求）
- ✅ **正確**: 所有頁面必須支援手機版（< 768px）
- ✅ **正確**: 既有 Flask/Jinja 頁面可沿用 Bootstrap 5.3.3，但新版 UI 優先使用 V2 tokens 與新版 shell 規範。
- ✅ **正確**: 表格與圖表必須支援橫向滾動（手機版）
- ❌ **禁止**: 僅針對桌面版設計

### 第 13 條：互動體驗（強制要求）
- ✅ **正確**: 所有按鈕、導覽項、表格列與可點擊卡片必須有 hover / active 狀態。
- ✅ **正確**: 使用 V2 token 的 transition，保持快速、安靜、克制。
- ❌ **禁止**: 靜態無互動的 UI 元素

### 第 14 條：字體與可讀性（強制要求）
- ✅ **正確**: 主要文字使用新版暖墨色 token，避免純黑造成刺眼。
- ✅ **正確**: 表格表頭使用米色 paper 底 + 等寬小字標籤；活動 hero 等深色區塊才使用反白文字。
- ❌ **禁止**: 使用純黑色 `#000`（刺眼）
- ❌ **禁止**: 使用低對比度顏色組合

### 第 14.1 條：真實資料與真實頁面（絕對禁止違反）
- ✅ **正確**: 所有新版頁面內容必須接正式後端資料、既有 route/service/API 或明確可追溯的資料來源。
- ✅ **正確**: 尚未完成串接的功能，應顯示真實空狀態、錯誤狀態或「尚未提供資料來源」的可診斷訊息。
- ❌ **禁止**: 使用 mock data、假商品、假 KPI、假排程、假使用者、假頁面或純展示用 placeholder 冒充已完成。
- ❌ **禁止**: 為了符合原型畫面而改寫或捏造業務數字。

---

## 第五章：系統架構規範

### 第 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()` 輸出日誌

### 第 18.1 條：健康檢查與監控目標（強制要求）
- ✅ **正確**: Docker healthcheck、CD health check、Blackbox HTTP 監控必須打 `/health`，不可打 Dashboard 首頁 `/` 作為可用性探測。
- ✅ **正確**: Gunicorn runtime 必須保留可併發回應輕量 health check 的 worker 設定，例如 `gthread` + `GUNICORN_THREADS`。
- ❌ **禁止**: 用會觸發大量 DB 查詢或模板渲染的頁面作為探測目標，避免監控流量本身造成 worker starvation。

---

## 第六章：版本管理規範

### 第 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` 標記 ✅
- ✅ **正確**: 記錄修改的檔案與行數
- ❌ **禁止**: 完成任務但不更新文件

---

## 第六之一章：模組化治理規範

### 第 21.1 條：模組分層與大檔治理（強制要求）
- ✅ **正確**：新功能必須先放入對應層級：`routes/` 只處理 HTTP/Blueprint glue，`services/` 放商業邏輯與外部 API client，`database/` 放 ORM/DB access，`utils/` 放無狀態共用工具，`templates/` 放 UI。
- ✅ **正確**：`app.py` 只保留 Flask 初始化、Blueprint 註冊、啟動自檢、版本與全域設定；禁止新增 route、長函式或商業邏輯。
- ✅ **正確**：現有超過 800 行的 Python 檔案視為拆分技術債，只能做 bugfix / 安全修補 / 搭橋式抽離；新增功能前應優先抽 shared service 或子模組。
- ✅ **正確**：新增或修改導致 Python 檔案超過 600 行時，必須先評估拆模組；超過 800 行必須更新 `docs/memory/code_modularization_inventory_20260430.md` 與對應測試，並寫出拆分計畫。
- ❌ **禁止**：把可共用邏輯藏在 route、template helper 或單一巨檔內，造成其他模組只能複製貼上。
- **依據**：ADR-017、`docs/guides/modularization_governance.md`

---

## 第七章：程式碼品質規範

### 第 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 查詢
- **範例**:
  ```python
  # ✅ 正確
  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（統帥批准，加入第十三、十四章）