# EwoooC (MOMO Pro System) — 核心索引

> **版本**: V12.0 | **目標**: AI 驅動 MOMO 商品監控、業績分析、策略自動化與 AIOps 自愈
> **全域工作流程**（P7/P9/P10、三紅線、委派表、PUA/Loop）見 `~/.claude/CLAUDE.md`

## 治理
- **憲法**: [CONSTITUTION.md](CONSTITUTION.md) — 所有開發必須遵守
- **ADR**: [docs/adr/](docs/adr/)
- **AI 策略師**: `services/openclaw_strategist_service.py` (Gemini 2.0)

## 環境
| 主機 | IP | 角色 |
|------|----|------|
| 110 (Gateway) | `192.168.0.110` | Nginx, Gitea, n8n, Superset |
| 188 (App/AI) | `192.168.0.188` | EwoooC App, DB, Ollama（多專案共存，見 ADR-011） |

## 核心容器（三動一 DB，缺一不可）
| 容器 | 角色 | 啟動入口 |
|------|------|---------|
| `momo-pro-system` | Flask/Gunicorn 主應用 | `app.py`（手動 docker run 歷史債，見 ADR-011） |
| `momo-scheduler` | 13 個排程任務（爬蟲/AI/備份/通知） | `run_scheduler.py` |
| `momo-telegram-bot` | Telegram 互動 + 每日 09:00 推播 | `run_telegram_bot.py`（根目錄副本） |
| `momo-db` | PostgreSQL + pgvector | compose service `momo-postgres` |

## 常用指令
```bash
# 本地開發
source venv/bin/activate && python app.py

# 部署（標準）→ push 即自動部署（Gitea Actions），同時重啟三容器
git push origin main

# 🔍 診斷黃金三句（任何 Telegram/排程異常先跑）
ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"\
  docker ps --format '{{.Names}} | {{.Status}}' | grep momo-; \
  docker exec momo-scheduler env | grep -iE 'TELEGRAM|NVIDIA'; \
  docker logs momo-scheduler --since 1h | grep -E 'Telegram|Error' | tail -10\""

# 🆘 緊急重建單容器（不影響 momo-db 資料）
ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"\
  cd /home/ollama/momo-pro && docker compose up -d --no-deps --force-recreate <service>\""
# ⚠️ 禁用 --remove-orphans（會清掉 momo-db！見 ADR-011）
```

## CI/CD
| 項目 | 說明 |
|------|------|
| Gitea Repo | `http://192.168.0.110:3001/wooo/ewoooc` (Public) |
| CD Pipeline | `.gitea/workflows/cd.yaml` |
| 部署模式 | sync（Python 變動 ~30s）/ rebuild（Dockerfile 變動） |
| 健康檢查 | `https://mo.wooo.work/health` |
| Runner | `wooo-runner`（user-level，服務所有 wooo/* repo） |
| 通知 | Telegram（部署開始/成功/失敗） |
| 參考 | ADR-010 |

## 文檔索引
| 類型 | 路徑 |
|------|------|
| 部署 SOP | [docs/guides/deployment_sop.md](docs/guides/deployment_sop.md) |
| DevOps 手冊 | [docs/guides/devops_handbook.md](docs/guides/devops_handbook.md) |
| Google Drive | [docs/guides/google_drive_setup.md](docs/guides/google_drive_setup.md) |
| 歷史日誌 | [docs/memory/history_logs.md](docs/memory/history_logs.md) |
| 憑證對照表 | [docs/memory/credentials_passbook.md](docs/memory/credentials_passbook.md) |
| AIOps 存檔 | [docs/external/aiops_saas.md](docs/external/aiops_saas.md) |
| 跨專案隔離（**必讀**）| [docs/adr/ADR-011-cross-project-resource-isolation.md](docs/adr/ADR-011-cross-project-resource-isolation.md)
* **ADR-011: Docker --remove-orphans 危險停用決策**（避免 Gitea Action 刪除非 Compose 管理的容器，如資料庫）
* **ADR-012: Elephant Alpha 模型整合**（三智能體核心決策大腦，具備防爆走護欄與 Telegram 稽核通知）
* **ADR-013: AIOps 自動修復服務**（實作 `AutoHealService` 處理容器異常關閉與效能瓶頸，通過 SSH Jump Executor 在跳板機隔離操作機制）
* **ADR-014: Autonomous Code Repair**（結合 Elephant Alpha 進行系統錯誤日誌Traceback掃描，自動觸發 110 主機上 Aider 自動化執行程式碼修復，並依賴 Git + Gitea CI/CD 回滾防線進行安全發布）
* **ADR-015: Telegram Bot Menu 復活**（OpenClawAwoooI_Bot 三專案共用、cmd:/menu:/await: callback prefix）
* **ADR-016: daily_sales cache fingerprint**（gunicorn 多 worker cache 失效改 DB MAX/COUNT 指紋；棄用 N-POST 9.4% 命中 hack；3971fd4 已落地） |
* **ADR-017: Phase 3f 模組化收尾**（DB metadata、路由雙註冊、cache、scheduler、模板與死碼清理收斂路線圖） |
| **PPT 簡報系統 V2（ADR-014）** | [docs/adr/ADR-014-ppt-report-system-v2.md](docs/adr/ADR-014-ppt-report-system-v2.md) |

## PPT 簡報系統（9 種，V2）
| 類型 | 頁數 | Telegram 指令 | 核心圖表 |
|------|------|-------------|---------|
| daily 日報 | 4 | `cmd:ppt:daily` | 近7日業績柱狀圖 |
| weekly 週報 | 5 | `cmd:ppt:weekly` | 7日走勢+TOP10 |
| monthly 月報 | 5 | `cmd:ppt:monthly` | 品類橫條+TOP10 |
| strategy 策略 | 5 | `cmd:ppt:strategy [範圍]` | 策略矩陣分佈+行動清單 |
| competitor 競品 | 4 | `cmd:ppt:competitor [範圍]` | 橫條圖+比較表 |
| promo 促銷 | 5 | `await:promo_range` | 雙層KPI+雙柱業績對比 |
| **growth** 成長趨勢 | **6** | `cmd:ppt:growth` | 月營收+MoM+AOV+毛利率 |
| **vendor** 廠商業績 | **5** | `cmd:ppt:vendor [YYYY/MM]` | TOP20廠商2024/2025對比 |
| **bcg** 品牌矩陣 | **5** | `cmd:ppt:bcg [YYYY/MM]` | BCG象限表+區域分佈 |

---

## momo 安全架構（bypassPermissions）

本專案採用 `permissions.defaultMode: "bypassPermissions"` + Hook 自動政策替代人工確認對話框。
安全防線由 [.claude/hooks/](.claude/hooks/) 的 Hook 自動執行，覆蓋範圍：

| Hook | 觸發點 | 防護內容 |
|------|--------|---------|
| `momo-prod-guard.js` | PreToolUse | 阻擋 --remove-orphans、force push、遠端 docker rm momo-db、生產 SSH 稽核 |
| `commit-quality.js` | PreToolUse | 阻擋 hardcoded Token/API Key（含 Telegram/Gemini/Gitea 模式）|
| `large-file-warner.js` | PreToolUse | >2MB 阻擋讀取，>500KB 警告 |
| `mcp-health.js` | PreToolUse | MCP 伺服器 cooldown 保護 |
| `audit-log.js` | PostToolUse | 所有 Bash 指令稽核，自動 redact Token |
| `suggest-compact.js` | PostToolUse | 50 次工具呼叫後建議 /compact |
| `cost-tracker.js` | Stop | Token 用量與成本追蹤 |
| `session-summary.js` | Stop | 對話快照存檔 |

全域 Hook（`~/.claude/hooks/`）同時生效：`branch-protection.js`（main 分支保護已透過 `.claude/hooks/branch-protection.local.json` 設為僅保護 `production`）。