---
id: max-engine
name: MAX (Meta Ads eXpert) 広告自動化エンジン
category: クライアント案件
status: Phase 3完了・運用中
priority: ★★★
updated: 2026-04-13
client: 株式会社上間（上間沖縄天ぷら店）
spec: ~/Desktop/MAX/PROGRESS.md
---

## 📝 概要

Meta Marketing APIを用いた広告運用の自動化エンジン。データ取得→KPI分析→ベンチマーク評価→AIインサイト→改善提案→オーディエンス分析→メールレポート配信を統合するローカル実行型Python+Vueシステム。最終目標はLevel 4（完全自動運用＋自己改善）。

## 📊 ステータス

- **Day 1 (2026-04-12)** にPhase 0〜3を一気に完了
- 毎朝7:00 JSTに日次バッチが自動稼働中（launchd: `com.max.daily`）
- メールレポートが `Y.uema@uemabento.com` に毎日自動配信
- 次はPhase 4（ML提案 Lv3）— データ30日分蓄積待ち（あと11日）

## 🏗 アーキテクチャ

```
Meta Marketing API v25.0
  ↓
Python エンジン (src/max/)
  ├ ingest: データ取得（Insights + Demographics + Hourly + Platform）
  ├ analyze: KPI算出 + 異常検知 + ベンチマーク + AIインサイト + 改善提案 + 予算シミュレーション + オーディエンス
  ├ ledger: Decision Ledger（予測↔実績記録）
  ├ improve: Self-Healer（リトライ + BUCスロットリング + DLQ）
  ├ notify: HTMLメールレポート（上間ブランドカラー）+ Gmail SMTP
  └ api: FastAPI 15エンドポイント
  ↓
SQLite (data/max.db, schema v2, 14テーブル)
  ↓
Vue 3 + Vite + Chart.js ダッシュボード (frontend/)
```

## 📁 リソース

| 項目 | パス |
|---|---|
| 作業ディレクトリ | `~/Desktop/MAX/` |
| プロジェクト指示書 | `~/Desktop/MAX/CLAUDE.md` |
| 進捗台帳（全詳細） | `~/Desktop/MAX/PROGRESS.md` |
| 仕様書群 | `~/Desktop/MAX/specs/` |
| Phase 0手順書 | `~/Desktop/MAX/docs/phase0_setup_guide.md` |
| DB | `~/Desktop/MAX/data/max.db` |
| 日次バッチ | `~/Desktop/MAX/run_daily.sh` |
| launchd | `~/Library/LaunchAgents/com.max.daily.plist` |

## 🔧 主要コマンド

```bash
cd ~/Desktop/MAX/src
python3 -m max.cli status          # DB状態確認
python3 -m max.cli ingest --daily  # データ取得
python3 -m max.cli report --daily  # レポート送信
python3 -m max.cli serve --port 8000  # APIサーバー
cd ~/Desktop/MAX/frontend && npm run dev  # ダッシュボード
```

## 📈 広告アカウント

| 項目 | 値 |
|---|---|
| アカウント | act_903304605483746（上間沖縄天ぷら店） |
| 通貨 | JPY |
| キャンペーン | 3件（魚天ぷらシズル×2、沖縄そば×1） |
| 主要オーディエンス | 35-44歳男女 |
| 主要配信面 | Instagram ストーリーズ (44%) |
| CTR | 4.25%（業界平均の2倍以上） |
| CPC | ¥17（業界平均¥50-100の1/3） |

## 🔜 次回作業

1. **Phase 4: ML提案 (Lv3)** — LightGBMでCPA予測→予算配分最適化提案→人間が承認
   - 前提: 30日分データ蓄積（2026-04-23頃達成見込み）
2. **Advanced Access申請** — 15日間1,500 APIコール達成後
3. **追加アカウント接続** — 残り2-4件
4. **トークン再発行** — 2026年6月頃（60日有効期限）

## 📦 配布・展開

### Wiki保存済みファイル
```
~/projects-wiki/specs/max-engine/
├── 00_setup_playbook.md    ← Claude Code用の自動構築指示書
├── 01_client_config.yaml   ← クライアント固有設定（これだけ書き換える）
├── 02_human_steps.md       ← 人間操作5ステップの手順書
├── CLAUDE.md               ← プロジェクト指示書
└── PROGRESS.md             ← 進捗台帳（全詳細）
```

### 配布用zipパッケージ
```bash
cd ~/Desktop/MAX && bash package_for_distribution.sh
```
→ `~/Desktop/MAX_distribution_YYYYMMDD.zip` (136KB) が生成される
→ .env/DB/logs/node_modules は除外済み（機密安全）
→ メール添付・AirDrop・クラウドストレージで共有可能

### 新規クライアント展開手順
1. zipを解凍（または `~/Desktop/MAX/` をコピー）
2. `playbook/01_client_config.yaml` を新クライアント用に書き換え
3. Claude Codeで `playbook/00_setup_playbook.md` を読み込ませる
4. 指示に従い5箇所のブラウザ操作を完了
5. 自動運用開始

### 対応業種（ベンチマーク プリセット）
飲食 / 小売 / 美容 / 不動産 / 医療 / EC（6業種）

## ⚠️ リスク

- Development TierのAPIレート制限（Advanced Access申請準備中）
- アクセストークン60日期限（2026年6月頃）
- ML学習にはデータ量が必要（現在19日/最低30日）