dashboard

ダッシュボード

マルチアカウントのダッシュボード作成を専門としています。Account → Campaign → AdSet → Ad の階層で、広告アカウントの統計情報を表示します。

---

タスク

1. アカウントの概要 — すべてのアクティブなアカウントの一覧表
2. キャンペーンの詳細 — キャンペーンレベルまで展開
3. AdSet の詳細 — 広告セットレベルまで展開
4. Ads の詳細 — 広告レベルまでの完全なダッシュボード
5. WhatsApp の指標 — WhatsApp キャンペーンの CPQL、Quality Rate
6. カスタム期間 — 任意の日付範囲

---

ワークフロー

ステップ 1：リクエストパラメーターの解析

ユーザーのリクエストから、以下を特定します。

パラメーター	選択肢	デフォルト
期間	today、yesterday、7d、30d、custom	yesterday
アカウント	すべて／名前を指定	すべて
レベル	account、campaign、adset、ad	campaign

重要：期間が明示されていない場合は、yesterday（昨日）を使用してください。

期間を示すキーワード：

• 「今日」、「today」 → today
• 「昨日」、「yesterday」 → yesterday
• 「7 日間」、「1 週間」、「7d」 → last_7d
• 「30 日間」、「1 か月」、「30d」 → last_30d
• 「YYYY-MM-DD — YYYY-MM-DD」 → custom {"since": "...", "until": "..."}

レベルを示すキーワード：

• 「アカウントのみ」、「account」 → レベル account
• 「AdSet 付き」、「adset」 → レベル adset
• 「完全」、「詳細」、「すべてのレベル」、「ads」 → レベル ad
• 指定なし → レベル campaign（デフォルト）

アカウントを示すキーワード：

• アカウント名（例：「Profimed」、「Бас дент」） → このアカウントのみ
• 指定なし → すべてのアクティブなアカウント

---

ステップ 2：設定の読み込み

1. Прочитай .claude/ads-agent/config/ad_accounts.md
2. Извлеки список аккаунтов со статусом "активен"
3. Для каждого аккаунта запомни:
   - name (Название)
   - account_id (Account ID)
   - page_id (Page ID)
   - brief_path (путь к брифу)

4. Прочитай бриф каждого аккаунта (briefs/{name}.md)
5. Извлеки target CPL для каждой кампании из таблицы "Активные кампании/направления":
   | Направление | Campaign ID | Цель CPL | ...

セクションの解析：

## Аккаунт N: {name}

- **Account ID**: act_XXX  ← извлечь
- **Page ID**: XXX         ← извлечь
- **Название**: XXX
- **Статус**: активен      ← фильтровать только "активен"

---

ステップ 3：MCP 経由でデータを取得

Account レベルの場合：

# Для каждого аккаунта параллельно
for account in accounts:
    insights = get_insights(
        object_id=account.account_id,
        time_range=period,
        level="account"
    )

Campaign レベルの場合（必要に応じて）：

# 1. Получить список кампаний
campaigns = get_campaigns(
    account_id=account_id,
    status_filter="ACTIVE",
    limit=50
)

# 2. Получить insights на уровне кампаний
campaign_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="campaign"
)

AdSet レベルの場合（必要に応じて）：

# 1. Получить список adsets
adsets = get_adsets(account_id=account_id, campaign_id=campaign_id)

# 2. Получить insights на уровне adset
adset_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="adset"
)

# 3. Получить daily_budget для каждого adset
for adset in adsets:
    details = get_adset_details(adset_id=adset.id)
    daily_budget = details.daily_budget / 100  # центы → доллары

Ad レベルの場合（必要に応じて）：

# 1. Получить список ads
ads = get_ads(account_id=account_id, adset_id=adset_id)

# 2. Получить insights на уровне ad
ad_insights = get_insights(
    object_id=account_id,
    time_range=period,
    level="ad"
)

---

ステップ 4：指標の計算

基本指標（API から取得）

指標	API フィールド	説明
spend	spend	費用（$）
impressions	impressions	インプレッション数
clicks	clicks	クリック数

actions からリード数を集計

def count_leads(actions):
    leads = 0
    messagingLeads = 0
    qualityLeads = 0

    for action in actions:
        action_type = action.get("action_type", "")
        value = int(action.get("value", 0))

        if action_type == "onsite_conversion.total_messaging_connection":
            messagingLeads = value
            leads += value
        elif action_type == "onsite_conversion.messaging_user_depth_2_message_send":
            qualityLeads = value
        elif action_type in ["offsite_conversion.fb_pixel_lead", "onsite_conversion.lead_grouped"]:
            leads += value

    return leads, messagingLeads, qualityLeads

派生指標

基本指標（常に表示）：

cpl = spend / leads if leads > 0 else None
ctr = (clicks / impressions) * 100 if impressions > 0 else 0
cpm = (spend / impressions) * 1000 if impressions > 0 else 0

# План-факт (ОБЯЗАТЕЛЬНО для кампаний)
target_cpl = brief.campaigns[campaign_id].target_cpl  # из брифа
cpl_diff = ((cpl - target_cpl) / target_cpl) * 100 if target_cpl and cpl else None  # % отклонения

WhatsApp 指標（messagingLeads > 0 の場合に表示）：

cpql = spend / qualityLeads if qualityLeads > 0 else None
qualityRate = (qualityLeads / messagingLeads) * 100 if messagingLeads > 0 else 0

---

ステップ 5：階層の上位レベルへの集計

# Ad → AdSet
adset.spend = sum(ad.spend for ad in adset.ads)
adset.leads = sum(ad.leads for ad in adset.ads)
# ... остальные метрики

# AdSet → Campaign
campaign.spend = sum(adset.spend for adset in campaign.adsets)
campaign.leads = sum(adset.leads for adset in campaign.adsets)
campaign.daily_budget = sum(adset.daily_budget for adset in campaign.adsets if adset.status == "ACTIVE")
# ... остальные метрики

# Campaign → Account
account.spend = sum(campaign.spend for campaign in account.campaigns)
account.leads = sum(campaign.leads for campaign in account.campaigns)
# ... остальные метрики

---

ステップ 6：出力の作成

リクエストされた詳細レベルに応じて表を出力します。

---

表の形式

ダッシュボードの見出し

# Dashboard
📅 Период: {since} — {until}

または、1 日分の場合：

# Dashboard
📅 Период: {date}

---

アカウントの概要（Account レベル）

## Сводка по аккаунтам

| Аккаунт | Spend | Leads | CPL | CTR | CPM | Статус |
|---------|------:|------:|----:|----:|----:|--------|
| Бас дент | $450.00 | 120 | $3.75 | 1.2% | $8.50 | ✅ |
| Profimed | $320.00 | 85 | $3.76 | 1.1% | $9.20 | ✅ |
| **ВСЕГО** | **$770.00** | **205** | **$3.76** | **1.15%** | **$8.85** | — |

書式：

• Spend：${value:,.2f}（例：$1,234.56）
• Leads：整数
• CPL：${value:.2f}
• CTR：{value:.1f}%
• CPM：${value:.2f}
• ステータス：アクティブな場合は ✅

---

キャンペーン（Campaign レベル）

アカウントごとに個別の表を出力します。

## {Account Name} — Кампании

| Кампания | Spend | Leads | CPL | Target | Δ% | Budget | Статус |
|----------|------:|------:|----:|-------:|---:|-------:|--------|
| Импланты | $250.00 | 65 | $3.85 | $4.00 | -4% | $40 | ACTIVE |
| Виниры | $200.00 | 55 | $3.64 | $5.00 | -27% | $30 | ACTIVE |
| **ИТОГО** | **$450.00** | **120** | **$3.75** | — | — | **$70** | — |

Δ%（計画対実績）の書式：

• 負の値（CPL < Target）＝良好。そのまま -4% と表示
• 正の値（CPL > Target）＝不良。+15% と表示
• target がない場合、またはリード数が 0 の場合は — と表示

---

AdSets（AdSet レベル）

各キャンペーンの下に表示します。

### AdSets — {Campaign Name}

| AdSet | Spend | Leads | CPL | CTR | Budget | Статус |
|-------|------:|------:|----:|----:|-------:|--------|
| 30-45_astana | $150.00 | 40 | $3.75 | 1.4% | $25 | ACTIVE |
| 25-35_almaty | $100.00 | 25 | $4.00 | 1.1% | $15 | ACTIVE |

---

Ads（Ad レベル）

各 AdSet の下に表示します。

#### Ads — {AdSet Name}

| Ad | Spend | Leads | CPL | CTR | Статус |
|----|------:|------:|----:|----:|--------|
| video_1_kitchen | $80.00 | 22 | $3.64 | 1.5% | ACTIVE |
| video_2_doctor | $70.00 | 18 | $3.89 | 1.3% | ACTIVE |

---

WhatsApp 指標（任意）

いずれかのアカウントで messagingLeads > 0 の場合は、セクションを追加します。

## WhatsApp Quality

| Аккаунт | Msg Leads | Quality Leads | CPQL | Quality Rate |
|---------|----------:|--------------:|-----:|-------------:|
| Profimed | 85 | 42 | $7.62 | 49.4% |

---

エラー処理

⚠️ Аккаунт {name}: ошибка доступа — пропущен

ℹ️ {name}: нет данных за выбранный период

---

リクエスト例

期間を指定しないダッシュボード

リクエスト：「ダッシュボードを表示」または /dashboard

解析結果：

• 期間：yesterday（デフォルト）
• アカウント：すべて
• レベル：campaign（デフォルト）

実行内容：

1. ad_accounts.md を読み込み、アクティブなアカウントを確認します
2. 各アカウントのブリーフを読み込み、キャンペーンの target CPL を確認します
3. 各アカウントで get_insights を実行します（level="campaign"、time_range="yesterday"）
4. Target 列と Δ% 列を含む表を作成します

---

Базовый дашборд

Запрос: "Покажи дашборд за вчера"

Парсинг:

• Период: yesterday
• Аккаунты: все
• Уровень: campaign (по умолчанию)

Действия:

1. Читаю ad_accounts.md → 2 активных аккаунта
2. get_insights(act_805414428109857, "yesterday", "campaign")
3. get_insights(act_1106872004544227, "yesterday", "campaign")
4. Формирую сводную таблицу + таблицы кампаний для каждого аккаунта

---

Конкретный аккаунт с кампаниями

Запрос: "Дашборд Profimed за 7 дней с кампаниями"

Парсинг:

• Период: last_7d
• Аккаунты: Profimed (act_1106872004544227)
• Уровень: campaign

Действия:

1. Читаю ad_accounts.md → нахожу Profimed
2. get_campaigns(act_1106872004544227, "ACTIVE")
3. get_insights(act_1106872004544227, "last_7d", "campaign")
4. Формирую таблицу аккаунта + таблицу кампаний

---

Полный дашборд

Запрос: "Полный дашборд за месяц"

Парсинг:

• Период: last_30d
• Аккаунты: все
• Уровень: ad

Действия:

1. Читаю ad_accounts.md → все активные
2. Для каждого аккаунта:
   • get_campaigns() → список кампаний
   • get_adsets() → списки adsets по кампаниям
   • get_ads() → списки ads по adsets
   • get_insights(level="ad") → метрики по ads
   • get_adset_details() → бюджеты
3. Формирую полную иерархию таблиц

---

Custom период

Запрос: "Дашборд с 2026-01-10 по 2026-01-20"

Парсинг:

• Период: {"since": "2026-01-10", "until": "2026-01-20"}
• Аккаунты: все
• Уровень: campaign (по умолчанию)

---

Чек-лист

• Прочитан ad_accounts.md
• Определены параметры (период, аккаунты, уровень)
• Получены insights для нужного уровня
• Рассчитаны производные метрики (CPL, CTR, CPM)
• Проверены WhatsApp метрики (если есть messagingLeads)
• Сформированы таблицы по шаблонам
• Добавлена строка ИТОГО для групп

---

MCP команды

Чтение данных

# Список аккаунтов (если нужно проверить доступ)
get_ad_accounts(limit=10)

# Кампании аккаунта
get_campaigns(account_id, status_filter="ACTIVE", limit=50)

# AdSets аккаунта или кампании
get_adsets(account_id, campaign_id=None, limit=50)

# Ads аккаунта или adset
get_ads(account_id, adset_id=None, limit=50)

# Метрики за период
get_insights(
    object_id,           # account_id или конкретный ID
    time_range,          # "yesterday" или {"since": "...", "until": "..."}
    level="account"      # account | campaign | adset | ad
)

# Детали adset (для бюджета)
get_adset_details(adset_id)

Доступные периоды

Значение	Описание
today	Сегодня
yesterday	Вчера
last_3d	Последние 3 дня
last_7d	Последние 7 дней
last_14d	Последние 14 дней
last_30d	Последние 30 дней
this_month	Текущий месяц
last_month	Прошлый месяц
{"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"}	Custom