# Databeat + スプシ + CLI 設計

**日付:** 2026-04-08
**目的:** curumi-ops（Web アプリ）を廃止し、「Databeat + スプシ + CLI」で広告運用業務を完結させる
**ゴール:** 運用者が判断とクライアントコミュニケーションだけに集中できる状態を作る

---

## 背景

### 残る課題

Databeat + スプシで定常業務は回るが、以下の課題がある：

1. **週次レポートの「データ集め」に時間がかかる** — 施策の背景・目標値・アクション履歴等のコンテキストがバラバラに存在
2. **非定型な問い合わせに時間がかかる** — 「直近3ヶ月のCPA推移」「先週CPAが急騰した理由は？」等

### 方針

**定常業務 = スプシで完結。CLI + AI で非定型な補完。**

---

## 現在の仕組み（Databeat + スプシ）

### データの流れ

```
各媒体（Google / Meta / TikTok / Yahoo 等）
  ↓ Databeat が自動収集
BigQuery（perfs-440904）
  ├── rawテーブル（自動生成・カスタマイズ不可）
  │     google_ads_{account_id}/campaign, adgroup, ad, keyword, ...
  │     facebook_ads_{account_id}/campaign, adgroup, ad, ...
  │
  └── 出力フィード（SQL カスタマイズ可）
        output_feed_table_* （約40本の VIEW）
        → 各 VIEW に対応する��プシのシートにデータを自動出力
```

### Databeat の特性

- **BQ の rawテーブルは自動生成。** テーブル構造・カラムは Databeat が決める。カスタマイズ不可
- **出力フィードで SQL をカスタマイズ** → 必要なデータを整形してスプシに抽出。これが現在の運用の基盤
- **出力フィードの限界:** 単一の SQL → 単一のシートへの出力。複数ソースの横断や、施策コンテキストとの突合はできない

### 現在のスプシ構成

```
Google Sheets — 業務の中心
  ├── rawデータシート群（Databeat 出力フィード）  ← 運用者がデータを確認する場所
  ├── プロモーション補足情報      ← KPI目標・クライアント特性（手入力）
  └── アクション履歴              ← 施策記録（手入力）
```

---

## CLI で補うもの

Databeat の出力フィードでは難しい「**複数ソースの横断 + AI 分析**」を CLI が担う。

```
既存（Databeat 出力フィード）:
  BQ rawテーブル → SQL → スプシ（数値の整形・抽出）

CLI が追加するレイヤー:
  BQ（数値） + スプシ（KPI目標・アクション履歴・クライアント特性）
    → AI が横断分析 → レポート下書きをスプシに書き込み
```

**CLI は出力フィードを置き換えない。** 出力フィードはそのまま稼働し続ける。CLI は出力フィードではカバーできない「分析・レポート生成」を追加する位置づけ。

### 全体構成

```
Databeat（SaaS）— データ集約
  ├── 全媒体 → BigQuery rawテーブル（自動生成）
  └── 出力フィード（カスタム SQL）→ スプシにデータ出力（既存・稼働中）

Google Sheets — 業務の中心
  ├── rawデータ（Databeat 出力フィード）  ← 既存のまま
  ├── プロモーション補足情報              ← KPI目標・クライアント特性
  ├── アクション履歴                      ← 施策記録
  └── 週次レポート下書き                  ← CLI が書き込み、運用者が加筆【新規】

adbuddy-cli（TypeScript/Bun）— レポート補助【新規】
  ├── adb report   → BQ + Sheets → AI分析 → スプシに下書き
  └── adb ask      → BQ + Sheets → AI分析 → stdout（将来）
```

### 設計原則

- **既存の仕組み（Databeat 出力フィード + スプシ）を壊さない**。CLI は追加レイヤー
- **定常業務はスプシで完結**。ツールを増やさない。運用者の作業場所を統一
- **データ取得は BigQuery に一本化**。CLI は BQ からデータを読む（出力フィードと同じ rawテーブルを参照）
- **スプシには「Databeat にないもの」だけ追加管理**。対応表や数値データを二重管理しない

---

## Databeat BQ スキーマ（2026-04-08 調査結果）

**BQ プロジェクト:** `perfs-440904`

### データセット構成

```
perfs-440904
  ├── databeat                        ← システム（マスタ + 集約データ）
  ├── udf                             ← ユーザー定義関数
  ├── google_ads_1270800500           ← 媒体名_アカウントID（16アカウント）
  ├── google_ads_1632871505
  ├── ...
  ├── facebook_ads_581009382830044    ← 9アカウント
  └── ...
```

### databeat データセットの核心テーブル

| テーブル/VIEW | 用途 | CLI での使い方 |
|-------------|------|----------------------|
| `databeat_attribute` | Promotion × Account の N:M マッピング | プロモーション一覧・アカウント特定 |
| `campaign_summary_report` | 日次 × Promotion × Campaign の集約データ | レポートのメインデータソース |
| `campaign_summary` (VIEW) | 上記 + 属性 + 予算 + 目標達成率 | `adb report` のメインクエリ先 |
| `databeat_period_attribute` | 月次予算・目標設定 | 現状未入力（0.0）。スプシで代替 |
| `output_feed_table_*` (VIEW) | Databeat → スプシ自動連携用 | CLI では使わない（Databeat の機能） |

### Databeat のプロモーション構造

Databeat は BQ 上に「プロモーション」概念を持ち、媒体アカウントとの N:M マッピングを `databeat_attribute` テーブルで管理している。

```
databeat.databeat_attribute:
  PromotionId (UUID)     → プロモーション単位の一意キー
  PromotionName          → "ブラス様_全体", "ルナビューティー様_池袋" 等
  AccountId (UUID)       → Databeat 内部アカウントID
  AccountName            → "ブラス様_結婚式場", "ルナドクター様_美容事業_Google"
  ServiceName            → "Google Ads" / "Facebook Ads" / "TikTok Ads" 等
  ServiceAccountId       → 媒体のアカウントID（BQ データセット名に対応）
```

実データ例：

```
Promotion「ブラス様_全体」
  ├── ブラス様_結婚式場（Google Ads: 215-710-0762）
  ├── ブラス様_Meta（Facebook Ads: 660386785372414）
  └── ブラス様_TikTok（TikTok Ads: 7545389763659235329）

Promotion「ルナビューティー様_池袋」  ─┐
Promotion「ルナビューティー様_指名」   ├── 同一 Google Ads アカウント（127-080-0500）
Promotion「ルナビューティー様_ハイコックス」 ─┘
```

**スプシに対応表を手作りする必要はない。** Databeat が自動管理。

### 個別アカウントデータセットのテーブル（Google Ads の例）

24テーブル。日次パーティション（MONTH）。

| テーブル | 粒度 | 用途 |
|---------|------|------|
| `campaign` | 日次 × キャンペーン | 基本分析（メイン） |
| `adgroup` | 日次 × 広告グループ | グループ別ドリルダウン |
| `ad` / `ad_asset` | 日次 × 広告 | クリエイティブ比較 |
| `keyword` | 日次 × キーワード | KW分析 + 品質スコア |
| `search_query` | 日次 × 検索語句 | 検索意図の変化検出 |
| `campaign_hourly` | 時間帯別 | 時間帯シフト分析 |
| `age_range` / `gender` | デモグラ | ターゲット層分析 |
| `geo` | 地域別 | エリア分析 |
| `final_url` | LP別 | LP×CVR比較 |
| `campaign_conversion` | CV詳細 | CV種別内訳 |

campaign テーブルの主要カラム：

```
Date, CampaignId, CampaignName, CampaignStatus, BiddingStrategyType
ExternalCustomerId, AccountDescriptiveName
Impressions, Clicks, Cost, Conversions, ConversionValue
CostPerConversion, Ctr, AverageCpc, SearchImpressionShare
```

---

## スプシ テンプレート設計

**スプシは「Databeat にないもの」だけを管理する。** 既存の rawデータシート（Databeat 連携）はそのまま。

### シート1: プロモーション補足情報

Databeat の PromotionId に紐づくビジネスコンテキスト。

| 列 | 内容 | 記入例 |
|----|------|--------|
| promotion_id | **主キー。** Databeat の PromotionId（UUID） | `45eaa4a4-71bc-44ce-...` |
| プロモーション名 | 表示用（正は Databeat） | ブラス様_全体 |
| CPA目標 | 目標CPA | ¥3,000 |
| CV目標 | 月間目標CV数 | 100件 |
| 月予算 | 月間予算上限 | ¥500,000 |
| クライアント特性メモ | CPA重視、ブランド重視等 | CPA重視。LP改修中 |

### シート2: アクション履歴

| 列 | 内容 |
|----|------|
| 日付 | 施策実施日 |
| promotion_id | Databeat の PromotionId |
| 施策内容 | LP変更、入札変更、クリエイティブ追加等 |
| 意図 | なぜその施策を行ったか |
| 結果メモ | 施策後の所感・数値変化 |

### シート3: 週次レポート下書き

CLI が書き込む先。運用者が加筆修正してクライアントに出す。

| 列 | 内容 |
|----|------|
| draft_id | **一意キー。** `{promotion_id}_{period_start}` 形式 |
| 生成日 | CLI 実行日時 |
| promotion_id | Databeat の PromotionId |
| プロモーション名 | 表示用（Databeat から自動補完） |
| 期間 | 対象週 |
| 数値サマリ | 主要KPIの今週/先週/前週比/目標達成率 |
| 変動分析 | AI が生成した変動要因の仮説 |
| 改善提案 | AI が生成した次のアクション案 |
| 運用者コメント | 運用者が加筆する欄（空欄で出力） |
| ステータス | `draft` / `edited` / `sent` |

**再実行時の挙動:**

- `draft` → 上書き（upsert）。まだ人間が触っていないので安全
- `edited` or `sent` → 上書きしない。`_v2` で新規追加
- なし → 新規追加（append）

---

## adbuddy-cli 設計

### コマンド体系

```bash
adb report "ブラス様_全体" --period last-week
# → campaign_summary から全アカウント集約データを取得してレポート

adb report --all --period last-week
# → 全プロモーションのレポートを一括生成

adb ask "ブラス様のCPAが先週急に上がった理由は？"
# → BQ + Sheets を横断して自然言語で問い合わせ（将来）
```

### 内部アーキテクチャ

```
CLI エントリポイント
  ├── data/bigquery.ts    — BigQuery への接続・クエリ実行
  ├── data/sheets.ts      — Google Sheets の読み書き
  ├── ai/analyze.ts       — Claude API でデータ分析・レポート生成
  └── commands/
      ├── report.ts       — レポート下書き生成 → スプシ書き込み
      ├── ask.ts          — 自然言語での問い合わせ
      └── query.ts        — データ取得
```

### `report` コマンドの処理フロー

```
1. PromotionName（or PromotionId）で databeat_attribute からプロモーションを特定
2. campaign_summary VIEW から当該 PromotionId の対象期間データを取得（全媒体集約済み）
3. スプシのプロモーション補足情報から KPI目標・クライアント特性を取得
4. スプシのアクション履歴から promotion_id の直近施策を取得
5. 上記をすべて Claude に渡し、プロモーション単位のレポート下書きを生成
6. スプシの「週次レポート下書き」シートに書き込み
```

### データソースの使い分け

| 用途 | データソース |
|------|------------|
| `adb report`（レポート） | `campaign_summary` VIEW のみ（プロモーション×キャンペーン粒度で十分） |
| `adb ask`（深掘り分析） | 質問内容に応じて個別データセット（adgroup, keyword, search_query 等）まで深掘り |

### 技術スタック

| 要素 | 技術 |
|------|------|
| ランタイム | Bun |
| 言語 | TypeScript |
| BigQuery | `@google-cloud/bigquery` |
| Sheets | `googleapis` |
| AI | `@anthropic-ai/sdk`（Claude API、Opus） |
| CLI フレームワーク | 最小限（引数パースのみ） |

---

## curumi-ops の廃止

実運用に入っていないため、移行計画は不要。

| 機能 | 判断 | 移行先 |
|------|------|--------|
| 広告データ同期（Google/Meta） | **廃止** | Databeat |
| campaign_assignments（紐付け） | **廃止** | Databeat の `databeat_attribute` |
| 会社・商材管理 | **廃止** | スプシのプロモーション補足情報 |
| 週次レポート生成 | **CLI に置き換え** | `adb report` |
| タイムライン | **廃止** | スプシのアクション履歴 |
| Marp スライド生成 | **凍結** | 必要になったら CLI サブコマンドで復活 |
| Share of Model / ナレッジ管理 | **凍結** | 不要であれば廃止 |

**即時実行可能:**

- Cloudflare Worker を停止（外部利用者なし）
- cron ジョブを停止（既に無効化済み）
- リポジトリはアーカイブ（削除はしない。設計資産の参照用に残す）
- Turso DB は当面維持（参照用。不要になったら削除）

---

## Phase 計画

**Phase 0: スプシ テンプレート整備**

- プロモーション補足情報・アクション履歴・レポート下書きシートのテンプレートを作成
- Databeat の `databeat_attribute` から PromotionId/PromotionName を取得してセット

**Phase 1: BigQuery 接続** ✅ データ粒度調査完了（2026-04-08）

- GCP 認証の設定
- `campaign_summary` VIEW からのデータ取得が動く状態にする
- `databeat_attribute` からプロモーション一覧を取得できる状態にする

**Phase 2: Sheets 接続**

- CLI がスプシのプロモーション補足情報・アクション履歴を読み書きできる状態にする

**Phase 3: レポート下書き生成**

- `campaign_summary` VIEW + スプシ（KPI目標・アクション履歴）を Claude に渡してレポート下書きを生成
- `adb report` → スプシに書き込み

**Phase 4: 運用定着と改善**

- プロンプトの改善（レポート品質の向上）
- cron での定期実行
- `adb ask` の実装

---

## やらないこと

- Web UI（スプシで十分）
- 広告データの独自同期（Databeat に任せる）
- 媒体への書き込み操作
- レポートの自動送信（人間が確認してから出す）

> **運用自動化（google-ads-ops / Meta）** は別ドキュメント: `docs/strategy/2026-04-08-automation-roadmap.md`