AdCompass 要求定義書

バージョン 3.1 | 2026年4月6日 | ドラフト

📱 モックアップ: https://adcompass-mockup.pages.dev（PW: adcompass2026）

変更履歴

バージョン日付変更内容
1.02026-04-01初版作成
2.02026-04-04アーキテクチャ詳細（§7）追加、サービス一覧・費用感（§9）追加、画面一覧をモックアップ反映（§8）、4/1-4/3のIA変更（台本一覧ページ追加等）を反映。4/4モックアップ改修反映: 競合設定を1UI統合、台本生成本数プルダウン化・動画尺フリー入力・追加生成機能、レポート承認フロー（入稿待ち→保存済み→公開済み）、レポート入稿アーキテクチャ追加、運営管理画面をPOC向け3メニューに簡素化、ノウハウ管理追加、テスト期間中プラン・支払い非表示、生成上限テナント単位管理
2.12026-04-05技術スタック確定（Python FastAPI + Next.js）、フェーズ別アーキテクチャ（Phase 1手動入稿/Phase 2 Bedrock自動化）、SES→SendGrid変更、不整合修正11件
3.02026-04-06エンジニアレビュー反映。Cognito→Auth0、Lambda廃止、BE言語Go想定（TBD）、DB直入れ方式、管理画面WYSIWYG化、テナント分離をアプリケーションレベルのみに、データ保持・監査ログを将来検討に、プロンプトキャッシュ削除、Phase 2（AI自動化）を将来検討として分離
3.12026-04-06インフラ構成確定。セキュリティ観点でDBをprivate subnetに置く方針→フロント含め全てAWS（ECS Fargate + CloudFront）に統一。Vercel不要に。RLSは不採用（アプリケーションレベルのtenant_idフィルタで十分）

1. プロダクト概要

1.1 サービス概要

アドコンパスは、動画広告の競合分析・自社分析・台本生成をワンストップで提供するSaaS型Webサービスである。広告代理店およびブランド企業を対象とし、AI（Claude）を活用して動画広告の分析レポートと台本を生成する。

1.2 ビジネス目標

1.3 MVPスコープ

MVPには以下を含む。

※ Stripe決済は将来フェーズで実装。Phase 1ではテスト期間として手動請求。

2. ユーザーと権限体系

2.1 ユーザーロール

本サービスは「運営側（自社）」と「利用企業側（クライアント）」の2軸で構成される。

2.1.1 運営側ロール

ロール権限用途
スーパー管理者全機能・全クライアントのデータにアクセス可能。プラン設定・クレジット付与・アカウント作成/停止経営層・事業責任者
運営オペレーター全クライアントの利用状況・分析結果の閲覧。手動でのクレジット調整・レポート再実行運用チーム

2.1.2 クライアント側ロール

ロール権限用途
企業管理者自社の全データにアクセス可能。ユーザー招待/削除、広告アカウント接続管理、プラン・支払い管理クライアント企業の責任者
一般ユーザー分析実行・台本生成・レポート閲覧のみ。管理系機能にはアクセス不可クライアント企業の担当者

2.2 マルチテナント構造

運営管理画面（全クライアント横断）
  └── クライアント企業A（テナント）
  │     ├── 企業管理者ユーザー × N
  │     ├── 一般ユーザー × N
  │     ├── 広告アカウント接続 × N
  │     ├── クレジット残量
  │     └── 分析結果・台本データ
  └── クライアント企業B（テナント）
        ├── ...

2.3 認証方式

MVPで以下の全てに対応する。

SSOはクライアントBのような上場企業の導入時にセキュリティ要件として必須となる想定。

3. 機能要求

3.1 広告アカウント接続

FR-3.1.1 Meta広告APIの接続

FR-3.1.2 接続管理

3.2 競合分析

FR-3.2.1 競合設定

FR-3.2.2 定期実行

FR-3.2.3 分析対象

FR-3.2.4 分析内容

3.3 自社分析

FR-3.3.1 分析対象の選択

FR-3.3.2 デフォルト分析枠

FR-3.3.3 分析内容

FR-3.3.4 重量課金（追加クレジット）

3.4 台本生成

FR-3.4.1 生成条件の指定

FR-3.4.2 生成方式

FR-3.4.3 台本の出力内容

FR-3.4.4 重量課金

FR-3.4.5 台本の追加生成

3.5 レポート出力

FR-3.5.1 出力形式

FR-3.5.2 データ保持

FR-3.5.3 レポート承認フロー

3.6 通知

FR-3.6.1 対応チャネル

FR-3.6.2 レポート生成時の通知

FR-3.6.3 設定

4. 課金・決済

4.1 料金体系

4.1.1 月額基本料金

4.1.2 初期費用

4.1.3 追加クレジット

4.1.4 ボリュームディスカウント

4.2 Stripe決済

FR-4.2.1 決済手段

FR-4.2.2 サブスクリプション管理

FR-4.2.3 追加クレジット購入

4.3 運営側の課金管理

FR-4.3.1 運営管理画面での課金操作

FR-4.3.2 請求管理

FR-4.3.3 テスト期間中の制限

5. 運営管理画面

5.1 ダッシュボード → POCフェーズでは廃止

5.2 テナント管理

5.3 分析ジョブ管理 → POC後に実装予定（Coming Soon）

5.4 原価管理 → POC後に実装予定

5.5 レポート承認管理（新規）

5.6 ノウハウ管理（新規）

5.7 レポート入稿アーキテクチャ（新規）

入稿方式

セクション構成

  1. 分析サマリー（総評テキスト）
  2. 自社分析コメント（3観点分析の所見）
  3. 競合分析コメント（収集結果と学習ポイント）
  4. 台本メモ（社内用。お客様には非表示）

POCフェーズでの管理画面構成（3メニューのみ）

  1. レポート管理（承認フロー） — §5.5
  2. ノウハウ管理 — §5.6
  3. テナント一覧 — §5.2

6. 非機能要求

6.1 パフォーマンス

6.2 可用性

6.3 セキュリティ

6.4 スケーラビリティ

6.5 データ保持

将来検討。 以下の方針は負債になりやすいため、Phase 1では厳密な保持ポリシーを定めず、運用しながら決定する。

7. システムアーキテクチャ

7.1 フェーズ別アーキテクチャ概要

本システムは2フェーズで構築する。Phase 1で完全なプロダクト（認証・閲覧・管理の一通り）を実装し、AI分析はローカルのClaude Codeで手動実行→DB直入れで運用する。Phase 2でAI分析の自動化を検討する。

セキュリティ上、DBはprivate subnetに配置しパブリックアクセスを禁止する。この方針によりフロントエンド（Next.js）もバックエンド（Go API）もAWS上のECS Fargateに統一し、VPC内でDBと通信する構成とする。

Phase 1: 完全なプロダクト（手動AI分析）

┌─────────────────────────────────────────────────────────┐
│  ローカル（運営チーム）                                     │
│  Claude Code → AI分析実行 → DB直入れ（VPN or 踏み台経由）  │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│  CloudFront (CDN)                                       │
└────────────────┬────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────────────┐
│                      AWS VPC                             │
│                                                          │
│  Public Subnet                                           │
│  ┌────────────────────────────────────────────────────┐  │
│  │ ECS Fargate                                        │  │
│  │ ├── Next.js（フロント + 管理画面 WYSIWYG）          │  │
│  │ └── Go API（CRUD / SendGrid通知）                  │  │
│  └──────────────────────┬─────────────────────────────┘  │
│                          │ Security Group                 │
│  Private Subnet          ▼                                │
│  ┌────────────────────────────────────────────────────┐  │
│  │ RDS PostgreSQL                                     │  │
│  │ （外部からアクセス不可）                              │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  S3（画像・動画ストレージ）                                │
└─────────────────────────────────────────────────────────┘
         │              │
         ▼              ▼
┌──────────────┐ ┌──────────────────┐
│ Auth0        │ │ SendGrid         │
│ 認証基盤      │ │ メール通知        │
└──────────────┘ └──────────────────┘

Phase 1のポイント:

Phase 2（将来検討）: AI分析の自動化

Phase 1の運用結果を踏まえて設計する。以下は検討候補。

検討候補:

Phase 2で決定すべきこと:

7.2 技術スタック

レイヤー技術備考
フロントエンドNext.js (React / TypeScript)ECS Fargate + CloudFrontで配信
バックエンドGo（想定・TBD）ECS Fargate。パイプライン（Python）とは分離。Phase 1実装開始時に最終決定
AIパイプラインPythonPhase 1: ローカルClaude Codeで手動実行。Phase 2: 自動化方式を将来検討
データベースRDS PostgreSQLprivate subnetに配置。マルチテナント（tenant_idによるアプリケーションレベル分離）
ファイルストレージS3動画、フレーム画像、レポート
認証Auth0SSO (SAML 2.0 / OIDC) + OAuth対応。エンタープライズ対応
メール通知SendGridレポート公開通知、エラー通知
CDNCloudFrontフロントエンド配信 + S3オリジン
コンテナECS FargateNext.js + Go APIをホスティング
決済Stripeサブスクリプション + 従量課金（将来フェーズ）
画像生成GCP Imagenコンテ画像
スクレイピングApify競合広告収集（Meta広告ライブラリ、TikTok）

7.3 設計方針

AWS統一のセキュアなインフラ

Phase 1: 完全なプロダクト + 手動AI分析

Phase 2（将来検討）: AI自動化

7.4 AI / モデル構成

Phase 1（手動実行）

Phase 2（将来検討）

Phase 1の運用データを元に、以下を検討する。

工程モデル候補備考
データ取得・前処理コードのみ（AI不使用）Meta API、Apify等のAPI呼び出し
フレーム分析Sonnet画像理解＋分析判断
考察・台本生成Opus最高品質のクリエイティブ出力
コンテ画像生成GCP Imagen背景画像生成 + Pillowで日本語テロップ合成

7.5 コスト最適化施策（将来検討）

※ プロンプトキャッシュは問題が起きやすいため不採用。

8. 画面一覧

8.1 クライアント向け画面

#画面名ファイル名概要備考
C-01ログインindex.htmlメール/パスワード、Google OAuth、SSO
C-02ダッシュボードdashboard.html最新の分析結果サマリー、通知、クレジット残量、次回定期分析タイミング
C-03レポート一覧reports.html過去のレポート一覧・検索
C-04レポート作成report-create.html分析対象の選択、期間指定、競合指示（フリーテキスト）、台本生成条件を統合旧「競合設定」画面を統合
C-05レポート詳細report-detail.htmlタブ構成: 概要（訴求別配信割合）→自社分析→競合分析→台本。台本の追加生成もここから旧「台本一覧」画面を統合
C-06台本生成（report-create.html内）参照データ選択、方向性入力、本数プルダウン（1〜10本）、動画尺フリー入力
C-07広告アカウント設定ad-accounts.htmlMeta広告アカウントの接続・管理
C-08ユーザー管理users.htmlユーザーの招待・削除・ロール変更（企業管理者のみ）
C-09設定settings.html通知設定（メール・Slack・ダッシュボード）、Slack Webhook設定
C-09旧台本一覧scripts.html生成済み台本のレポート別グループ表示レポート詳細の「台本」タブに統合
C-11旧プラン・支払いbilling.html現在のプラン、クレジット残量、追加購入、支払い履歴テスト期間中は非表示

8.2 運営管理画面

POCフェーズで実装する画面（3メニュー）

#画面名ファイル名概要
A-01レポート管理（トップ）admin/index.html入稿待ち/保存済み/公開済みの3タブ。レポート承認フローのハブ
A-02テナント一覧admin/tenants.html検索・フィルタ付きのテナント一覧
A-03テナント詳細admin/tenant-detail.htmlユーザー、広告アカウント、プラン、クレジット残量、生成上限設定（数値入力）、利用履歴
A-11レポート詳細・編集admin/report-review.htmlWYSIWYGエディタ＋お客様プレビュー。「保存」「公開」ボタン
A-12ノウハウ管理admin/knowledge.htmlMarkdownエディタ風ナレッジベース。記事一覧+編集画面

POC後に実装予定の画面

#画面名ファイル名概要ステータス
A-01旧運営ダッシュボード—全テナントの利用状況サマリー、収益、原価廃止（レポート管理に置換）
A-04プラン・価格設定admin/plans.htmlテナントごとの月額・特別価格・初期費用の設定POC後
A-05クレジット管理admin/credits.htmlテナントへのクレジット手動付与・調整テナント詳細に統合
A-06ジョブ管理admin/jobs.html分析・台本生成ジョブの一覧、ステータス、エラーログPOC後（Coming Soon）
A-07定期実行設定admin/schedules.html競合分析の実行スケジュール管理POC後
A-08原価レポートadmin/costs.htmlテナント別・月次の原価内訳、APIトークン消費推移POC後
A-09請求管理admin/billing.htmlStripe連携の請求一覧、未払い検知POC後
A-10監査ログadmin/audit.htmlログイン履歴、重要操作の記録POC後（Coming Soon）

8.3 モックアップ

9. 外部サービス一覧と費用

9.1 会社クレジットカード登録が必要なサービス

#サービス用途月額費用（100アカウント時）登録時に必要な情報優先度
1AWSインフラ全般（ECS Fargate, RDS, S3, CloudFront）¥10,000〜30,000法人メール、クレカ、電話番号Phase 1
2Auth0認証基盤（SSO/OIDC対応）無料〜$23/月（Free〜Essentials）メール、クレカPhase 1
3Apify競合広告スクレイピング（Meta広告ライブラリ、TikTok）¥7,000〜22,000（$49〜149）メール、クレカPhase 1
4GCPImagen画像生成（コンテ画像）¥3,000〜7,000Googleアカウント、クレカ、請求先住所Phase 1
5Stripeクライアント向け決済基盤3.6%+¥40/決済（固定費なし）法人情報（登記、代表者、口座）、本人確認書類将来フェーズ

9.2 クレカ不要のサービス

#サービス用途費用備考
6Meta for Developers広告API（OAuth認証、データ取得）無料法人ビジネスマネージャーに紐付け直し推奨
7SendGridメール通知（レポート公開通知等）無料〜$20/月（Free〜Essentials）メール、ドメイン認証
8Slack AppWebhook通知無料Incoming Webhookのみ

9.3 AWSサービス内訳

AWSサービス用途月額費用（100アカウント時）
ECS FargateNext.js + Go APIホスティング¥3,000〜10,000
RDS PostgreSQLメインDB（private subnet）¥2,000〜15,000（db.t4g.micro〜medium）
S3フロント静的ファイル + 画像・動画ストレージ¥500〜3,000
CloudFrontCDN（フロントエンド配信 + S3オリジン）¥500〜2,000
VPC / Security Groupネットワーク分離ほぼ無料

9.4 月額コスト概算（Phase 1 / 100アカウント時）

カテゴリ月額
AWSインフラ（ECS + RDS + S3 + CloudFront）¥10,000〜30,000
Auth0¥0〜3,500
Apify¥7,000〜22,000
GCP（Imagen）¥3,000〜7,000
SendGrid¥0〜3,000
合計¥20,000〜65,500
1アカウントあたり原価¥200〜655

※ Phase 1ではAI分析はローカルClaude Code（MAXプラン $200/月）で実行。上記に含まず。

※ Phase 2のAI自動化コスト（E2B / ECS等）は将来検討。

※ 定価33,000円/月に対して原価率 0.6〜2.0%（AI分析コスト除く）。目標の10%以下を達成。

10. 制約事項・前提条件

10.1 制約

10.2 前提条件

10.3 開発体制

10.4 リスク

リスク影響対策
Claude API料金の値上げ原価率の悪化クレジット制でユーザーへの転嫁が可能な設計。モデルルーティング等の最適化余地を残す
競合サービスの出現シェア喪失先行者優位の確立。広告運用プロのノウハウが組み込まれた品質で差別化
大量アカウント導入時のインフラ負荷サービス品質低下SQSによるジョブキューイング、スケールアウト設計
Meta広告APIの仕様変更データ取得不能API変更の監視、柔軟なデータ取得層の設計

11. フェーズ計画

Phase 1: 完全なプロダクト（手動AI分析）

目的: 認証〜閲覧〜管理の一通りが動く完全なプロダクトを構築し、実顧客でPMF検証する。

実装範囲:

実装しない範囲:

運用フロー:

  1. ユーザーがレポート作成リクエスト
  2. 運営がローカルのClaude Codeで分析実行（既存v12パイプラインの延長）
  3. 分析結果をDB直入れ（ローカルClaude Codeスクリプトから直接DB接続）
  4. 管理画面（WYSIWYGエディタ）でレビュー・編集→公開→SendGridでお客様にメール通知

初期クライアント: ロットネスト社（3〜5アカウント）でのトライアル

Phase 2（将来検討）: AI自動化

目的: AI分析を自動化し、運営の手動オペレーションを排除する。

Phase 1の運用結果を踏まえて設計する。パイプラインの動きもPhase 1の結果次第で変わる可能性がある。

検討候補:

Phase 3（将来構想）: スケール

12. 用語定義

用語定義
テナント本サービスを契約する1つの企業単位
アカウントテナント内で接続されたMeta広告アカウント
ユーザーテナント内でサービスにログインする個人
クレジットデフォルト枠を超えて分析・生成を行うための追加利用権
ジョブ1回の分析実行または台本生成のバッチ処理単位
フレーム分析動画を画像に分解し、各フレームのクリエイティブ内容を分析すること
訴求タイプ動画の主な訴求軸の分類（価格訴求、機能訴求、感情訴求等）

13. 決定済み事項

#項目決定内容
1インフラ方針AWS統一（DBをprivate subnetに配置するセキュリティ要件のため）
2フロントエンドNext.js on ECS Fargate + CloudFront
3バックエンドGo（想定）on ECS Fargate（同一VPC内でDBと通信）
4DBRDS PostgreSQL（private subnet、パブリックアクセス禁止）
5ファイルストレージS3
6CDNCloudFront
7認証基盤Auth0（Cognitoは開発コスト・キャッチアップコストが高いため不採用）
8メール通知SendGrid
9Phase 1の範囲認証〜閲覧〜管理の一通りが動く完全なプロダクト。AI分析はローカルClaude Codeで手動→DB直入れ
10Phase 2の位置づけ将来検討。Phase 1の運用結果を踏まえて設計
11テナント分離アプリケーションレベルのみ（tenant_idフィルタ）。RLSは不採用
12Lambda不採用（state管理が困難）
13プロンプトキャッシュ不採用（問題が起きやすい）
14管理画面エディタWYSIWYGエディタ
15データ投入方式ローカルClaude Code → DB直入れ（VPNまたは踏み台経由）

14. 未決定事項

#項目選択肢決定期限
1バックエンド言語Go（想定） / Next.js API Routes / Python (FastAPI)Phase 1実装開始時
2Phase 1開発タイムライン2週間〜2ヶ月エンジニアレビュー後
3DB設計マルチテナントのテーブル設計（共有スキーマ+tenant_id）Phase 1実装開始時
4Phase 2 AI実行基盤E2B / ECS+Docker / Claude Code sub-agentPhase 1運用後