# EwoooC 專案歷史紀錄 (History Logs)

## 📌 重大里程碑
- **2026-04-29**: ADR-018 四 AI Agent 自動化控制面立案，Hermes / NemoTron / OpenClaw / ElephantAlpha 的告警、自癒、記憶與 HITL 邊界完成文件化。
- **2026-04-29**: ADR-017 Phase 3f 模組化收尾立案，啟動 DB metadata、路由雙註冊、cache、scheduler、模板與死碼清理六線收斂。
- **2026-04-18**: 專案正式正名為 **EwoooC**，AI 治理架構 Phase 4 結案（V10.3）。
- **2026-02-13**: WOOO AIOps SaaS 核心模組完成。
- **2026-01-24**: 曾嘗試遷移至 K3s（後於 04-18 審計確認回歸 Docker Compose）。
- **2026-01-12**: 專案啟動，MOMO 監控系統初版。

---

## 📅 詳細更新日誌 (考古存檔)

### 2026-04-29：ADR-017 Phase 3f 模組化收尾啟動
- **DB metadata 救急**: `database/manager.py` 改為顯式載入 permission / AI / autoheal / import / vendor / realtime_sales ORM，PostgreSQL 初始化透過 process-local guard + advisory lock 執行 `Base.metadata.create_all()`，避免新環境漏表與一般流量重複碰 DDL。
- **realtime_sales_monthly 補 ORM**: 新增 `database/realtime_sales_models.py`，並同步 `docker/postgres/init/01-init.sql` 欄位，避免 fresh volume 先建出窄表後造成匯入欄位靜默遺失。
- **啟動自檢**: `app.py` 啟動時檢查 34 張 expected metadata tables，缺表直接 fail fast，防止「看似啟動成功但 create_all 漏表」。
- **路線校正**: 12-Agent 盤點確認 3f-1 需先處理 API shadow 與 `system_bp` prefix 分裂，3f-3 需先補 EventRouter 同步告警 facade，再改 scheduler 裸 `except`。

### 2026-04-29：AI 自動化閉環與四 Agent 控制面
- **ADR-018 立案**: 正式把 ElephantAlpha 納入 Hermes / NemoTron / OpenClaw 之外的 L3 Orchestrator，形成四 AI Agent 自動化控制面。
- **通知鏈補強**: EventRouter 補 AI 失敗降級、Telegram file queue、成功後 replay、去重冷卻與 silence 檢查。
- **自癒安全回看**: AutoHeal 保護 `momo-db` / `momo-postgres`，DB/DNS 無法安全修復時降級為 alert / wait retry。
- **記憶閉環**: raw `ai_insights` insert 路徑補 embedding enqueue；OpenClaw learning 支援 stale reset 與 missing embedding backfill。
- **L2 action 落地**: `flag_for_human_review`、`route_to_km`、`mark_for_relearn` 改為可審計 OpenClaw memory 寫入。
- **可觀測性落地**: `/metrics` 匯出 EventRouter dispatch/latency、safe action、Telegram replay、AutoHeal action/duration 指標。
- **Smoke Dashboard**: 新增 `/ai_automation_smoke` 與 `/api/ai-automation/smoke`，提供四 Agent 閉環 read-only 快檢。
- **Smoke 趨勢保存**: Smoke API 追加 JSONL 精簡紀錄，dashboard 顯示最近 OK / Warning / Critical 趨勢。
- **Smoke 趨勢管理**: Dashboard 增加 JSONL 匯出、清理與每日摘要，清理範圍限定 smoke history 檔。
- **Smoke 每日摘要推播**: 新增 Telegram 手動推播 API 與 momo-scheduler 每日 09:10 摘要任務，只讀 smoke history。
- **Grafana AI 觀測**: 新增 `MOMO AI Automation Overview` provisioning dashboard，覆蓋 EventRouter、safe action、replay、AutoHeal Prometheus 指標。
- **Grafana 線上載入與 scrape 修復**: 188 active Grafana 載入 4 dashboards；active Prometheus 補 `momo-app` scrape job，並修復 gunicorn preload LocalProxy boot crash。
- **CD 健康檢查強化**: Gitea Actions health check 改為 internal container health + external URL 雙檢查，降低 rebuild 後短暫 502 誤判。
- **CD Sync reload 修復**: rsync 後明確 restart 三容器，避免 bind-mounted Python 檔案更新但 gunicorn/scheduler/bot process 未 reload。
- **CD Gunicorn 掛載強化**: `momo-app` 補 `./gunicorn.conf.py:/app/gunicorn.conf.py:ro`，避免容器 restart 後回吃 image 內舊 gunicorn 設定。
- **Metrics schema drift 降噪**: `/metrics` 的 `realtime_sales_monthly` 總筆數改用 raw `COUNT(*)`，避免 ORM 欄位 drift 造成 Prometheus scrape warning。
- **CD Rebuild 切換強化**: rebuild 模式改成先 build 成功、再短暫 stop/rm/recreate 三應用容器，避免 no-cache build 長時間 502。
- **ElephantAlpha NIM fallback 強化**: production 帳號呼叫 Ultra 253B 會 404，預設改用可呼叫的 Nemotron Super 49B v1.5，並加入 70B / 8B fallback。
- **DatabaseManager 連線池收斂**: PostgreSQL 每 worker pool 收斂為 `pool_size=2/max_overflow=3`，並以 cache 重用 engine/session。
- **Ollama embedding API 遷移**: embedding client 優先使用官方 `/api/embed`，舊節點才 fallback `/api/embeddings`，降低 deprecated endpoint 與 timeout 風險。
- **Scheduler 例外記錄強化**: 清除 `scheduler.py` 靜默 `except/pass`，Chrome 清理、EDM optional 欄位、備份 insight/Telegram 失敗均保留 log。
- **AI metrics baseline 觀測**: `/metrics` 在尚無 AI 自動化事件時仍輸出 `momo_ai_*` zero-baseline series，避免 app 重啟後 Grafana/Prometheus 看不到 metric names。
- **ElephantAlpha transient fallback**: NVIDIA NIM primary model timeout、connection error、429 與 5xx 會嘗試下一個 fallback model，400 等非暫時性請求錯誤不重試。
- **模組化治理守門**: 盤點 15 個超過 800 行 Python 大檔，新增 `docs/guides/modularization_governance.md` 與 `tests/test_modularization_governance.py`，防止未分類巨檔再長出來。
- **Legacy 5888 入口清理**: 刪除 `tests/main_test.py` standalone Flask 死碼，測試與自動匯入文件改用 Port 80 `/auto_import` 入口。
- **OpenClaw Bot 第一刀拆分**: Telegram API send/retry/file upload helper 移到 `services/openclaw_bot/telegram_api.py`，`routes/openclaw_bot_routes.py` 往 thin Blueprint 收斂。
- **EDM Dashboard endpoint 修復**: 部署後健康檢查抓到活動看板排序連結少 `edm.` blueprint 前綴，修正模板 endpoint 推導並補 5 個活動頁排序連結回歸測試。
- **Monitoring exporter 修復**: Prometheus 已能 scrape `momo-app` V10.24，但 target 檢查發現 `blackbox-exporter` 未啟動、`cadvisor` 因 host `8080` 衝突未進入 monitoring DNS；改為 cAdvisor internal-only 並補 monitoring compose 守門測試。
- **Active blackbox target 降噪**: 線上 Nginx 與 curl 驗證目前有效 MOMO 入口為 `https://mo.wooo.work`；`momo.wooo.work` 逾時、`wooo.work` DNS 不解析，先從 active UAT blackbox targets 移除，避免舊域名噪音誤導告警。
- **action_plans schema drift 修復**: CodeReview pipeline 寫入 action plan 時發現線上表只有 NemoTron Group B 欄位；啟動期 PostgreSQL metadata repair 會補 `action_type` / `description` / `priority` / `metadata_json` 與 index，恢復 AI code review action plan 閉環。
- **Gitea runner label 隔離**: EWOOOC CD workflow 改用 `ewoooc-host`；110 的 `/home/wooo/act-runner` runner config 必須只宣告 `ewoooc-host`，避免 user-level runner 混接 AWOOOI workflow。
- **CD sync hot reload**: 一般 Python/模板同步不再 `restart momo-app`，改為 `docker kill -s HUP momo-pro-system` 讓 Gunicorn 熱重載 workers，只重啟 scheduler / telegram-bot；Gunicorn 關閉 `preload_app`，確保 HUP 後 workers 會 import 新版 app code。
- **OpenClaw Bot 第二刀拆分**: Inline Keyboard builders 移到 `services/openclaw_bot/menu_keyboards.py`，透過 `configure_menu_keyboards()` 注入 `latest_date/_GOALS/TAIPEI_TZ`，route 檔下降到 5,240 行並補選單回歸測試。
- **CD sync mount drift guard**: 發現舊 app 容器未掛載 `app.py/config.py` 時，rsync 後服務檔已更新但 `/health` 版本仍卡 image 內舊檔；CD sync 會檢查 mount，僅 drift 時一次性 recreate momo-app，其餘維持 HUP 熱重載。
- **CD 單檔 bind mount inode 修復**: `app.py/config.py` 單檔 bind mount 會被 rsync/tar 的 inode replacement 卡住舊檔，CD rsync 改用 `--inplace`，避免 HUP reload 後仍讀到舊版本。
- **Frontend V2 視覺基準立案**: `MOMO Pro/` prototype 與 `docs/guides/frontend_upgrade_roadmap.md` 成為前端更版依據，AGENTS/CONSTITUTION 改以米色工作台、暖墨文字、焦糖橘 accent 與新版 shell 規範作為後續 UI 基準。
- **Frontend V2 Phase 0 assets**: 新增 `static/css/ewoooc-tokens.css`、`static/css/ewoooc-shell.css`、`templates/ewoooc_base.html` 與 `_ewoooc_shell.html`，先建立可重用 shell，不替換既有頁面；憲章補「真實資料與真實頁面」紅線，禁止假資料冒充完成。
- **Dashboard V2 feature flag**: `/` 預設仍走既有 `dashboard.html`，`/?ui=v2` 才渲染 `dashboard_v2.html`；新版頁沿用既有 dashboard 真實資料與篩選/排序參數，不建立 mock 商品或假 KPI。
- **Frontend V2 static mount**: `momo-app` 補 `./web/static:/app/web/static:ro`，確保 Flask `url_for('static', filename='css/ewoooc-*.css')` 會從實際 `STATIC_DIR=/app/web/static` 讀到 V2 CSS；保留 `./static:/app/static:ro` 供 local-dev Nginx/舊資產相容。
- **EDM Dashboard V2 feature flag**: 五個活動看板入口預設仍走既有 `edm_dashboard.html`，加上 `?ui=v2` 才渲染 `edm_dashboard_v2.html`；新版頁沿用既有活動真實 `grouped_items/slot_stats/scheduler_stats`。

### 2026-05-01：Frontend V2 營運頁推進
- **Vendor Stockout V2 production default**: `/vendor-stockout` 預設渲染 `vendor_stockout_index_v2.html`，`?ui=legacy` 才回舊頁；統計來自正式 `VendorStockout/VendorList/VendorEmail/EmailSendLog` 查詢，不建立假資料。
- **Vendor Stockout List V2 production default**: `/vendor-stockout/list` 預設渲染 `vendor_stockout_list_v2.html`，`?ui=legacy` 才回舊頁；清單、批次、搜尋、分頁與狀態統計都從正式 `VendorStockout` 查詢組裝，並移除重複的 `web/templates/vendor_stockout_index_v2.html`。
- **Vendor query service extraction**: Vendor V2 首頁統計與缺貨清單 query 移到 `services/vendor_stockout_query_service.py`，`routes/vendor_routes.py` 由約 1,821 行降至 1,675 行，回到 request parsing + template rendering，避免巨型 Blueprint 繼續承接資料組裝邏輯。
- **Vendor stockout API query extraction**: `/vendor-stockout/api/stockout/list` 與 `/vendor-stockout/api/stockout/batches` 的 query/serialization 移入同一個 `services/vendor_stockout_query_service.py`，保留既有 JSON shape，`routes/vendor_routes.py` 再降至約 1,565 行。
- **Vendor management query extraction**: `/vendor-stockout/api/vendor/list` 與 `/vendor-stockout/api/vendor/<vendor_code>` 的 query/serialization 移入 `services/vendor_stockout_query_service.py`，保留既有 JSON shape，`routes/vendor_routes.py` 再降至約 1,485 行。
- **Health-safe monitoring runtime**: 健康檢查失敗盤點確認 Blackbox 打 Dashboard 首頁 `/` 會觸發重型查詢並和 `/health` 搶 worker；188 與 110 active blackbox 均改打 `/health`，Gunicorn 預設改為 `gthread` + `GUNICORN_THREADS=4`，CD 也會在 monitoring target 變更時重新載入 Prometheus/blackbox。

### 2026-04-28~29：Phase 3e 重構大戰 + daily_sales cache 隱形 bug 根除
- **app.py 縮減 -10.8%**: 7,386 → 6,590 行，11 commits 全綠零 502。
- **抽 Blueprint**: `/api/categories` → `category_routes.py` (8fce73b)；`/api/test_url` + `/brand_assets` → `misc_routes.py` (e676840)。
- **揭發 4 個改進版死碼**: refactor-specialist 28 條雙重 URL 等價性矩陣指出 `/growth_analysis`、`/daily_sales`、`/api/export/excel/abc`、`/api/run_task` 在 routes/*.py 已重構但因 Flask first-registered-wins 規則被 app.py 同 URL `@app.route` shadow 從未生效。本輪先啟用 daily_sales (8fefea0)，餘三條待後續。
- **daily_sales cache 機制重構** (ADR-016): 「匯入 15323 筆但業績頁面看不到」隱形 bug 根因 = gunicorn 4 worker 各持獨立 module-level dict。先嘗試 N-POST broadcast hack 命中率僅 9.4%（debugger + web-researcher + migration-engineer 三方共識）；改用 DB fingerprint (`MAX(snapshot_date), COUNT(*)`) 雙閘失效 (3971fd4)，強一致無浪費。
- **clear_cache endpoint 加 `@login_required`**: 修 critic HIGH-3，外部 POST 無 auth 回 400（CSRF + login 雙重攔截）。
- **hook 9 PoC 強化** (136e65b): vuln-verifier 對 `.claude/hooks/momo-prod-guard.js` 跑 9 條 PoC 8 條繞過 → 補強 heredoc / writable CTE / multi-statement / pg_read_file / COPY FROM PROGRAM / `/run/secrets` / `/proc/*/environ` 全擋。
- **12 Agent 並行作戰實踐**: 8 完成 + 4 rate-limited；學到 critic 必須先於 fullstack-engineer 完成（feedback_agent_dispatch_order.md）。
- **殘留 HIGH-2 技術債**: app.py 仍 43 處 `_SALES_PROCESSED_CACHE`（sales_analysis 等獨立 cache）待後續抽 `services/cache_manager.py`。

### 2026-04-28：AI 引擎穩定性與 CI/CD 幽靈容器大規模修復
- **幽靈容器排除**: 發現 `docker-compose.yml` 漏掛載 `routes` 目錄，導致 Telegram Bot 長期執行舊代碼。
- **埠位衝突修復**: 移除 `depends_on: postgres` 以解決與 orphan `momo-db` 的 5432 埠位競爭問題。
- **CI/CD 強化**: `cd.yaml` 引入 `--no-cache` 與 `docker compose restart` 以應對快取損壞與容器識別問題。
- **AI 備援優化**: 放寬 Ollama 健康檢查至 10s，請求超時至 180s，修復 Gemini 429 速率限制與 MCP 404 報錯。
- **網站 502 修復**: 手動恢復因容器重建中斷的 110-188 SSH 隧道。

### 2026-02-13：重開機服務修復與 Clawdbot 整合
- 更新 `system_startup.sh` v2.0，移除 Harbor 相關邏輯。
- 重新設計 Monitor 首頁，移除不存在的服務連結。
- 實作 Ollama Server 端的 `Clawdbot` 整合腳本。

### 2026-02-09：域名健康監控與服務修復
- 新增 `domain-health-monitor.sh`，每 5 分鐘自動巡檢。
- 修復 n8n Task Runner 403 錯誤。

### 2026-02-07：CI/CD Dashboard 與 Registry 遷移
- 完全移除 Harbor，改用輕量級 Docker Registry。
- 開發 CI/CD Dashboard 頁面 (`/cicd`)。

### 2026-01-28：核心問題修復
- **502 Bad Gateway**: 發現 Docker 網路棧故障，新增自動重啟機制。
- **OOM 問題**: 修復業績匯入進程因記憶體消耗過大被 SIGKILL 的問題。
- **Ollama 監控**: 實作 AI 服務器健康專項監控。

---

## 🛠️ 過往技術爭議與決策 (ADR 前身)
- **資料流向**: 確立 `daily_sales_snapshot` 為 SOT，同步至 `realtime_sales_monthly`。
- **快取機制**: 使用 `FileLock` 解決 Gunicorn 多 Worker 重建快取競爭。
- **時區處理**: 強制使用 `Asia/Taipei` 並於 SQLite 存儲 naive datetime。

---
*詳細原始紀錄請參閱 Git Commit History 或 110 主機備份目錄。*
