トップ／レポート／拡張レポート／拡張レポートの作り方

拡張レポートの作り方

このページでできること

独自の拡張レポートを PHP ファイル 1 つで追加する手順を理解できます。
docblock の @llmo-extended-report 系タグの仕様、自動検出の挙動、ON/OFF 制御の仕組みを把握できます。
認証・権限の付け方、共通ヘルパ（PDO・GA4 など）の利用方法を確認できます。

クヌギGEO の拡張レポートは、products/extended_reports/ に PHP ファイルを置くだけで自動検出され、サイドバーに追加される仕組みです。データベース変更は不要、プログラムビルドも不要、ファイルを置くだけで機能を増やせます。

仕組みの全体像
STEP 1. PHP ファイルを作成
STEP 2. docblock の各タグの意味
STEP 3. ファイルを設置するだけで自動検出
STEP 4. 表示 ON/OFF はプロダクトごとに切替
認証・権限の付け方
データの取り出し方（共通ヘルパ）
サイドバーへの並び順
サンプルとして読むべきファイル

仕組みの全体像

products/extended_reports/<your_key>.php を新規作成。
ファイル先頭の docblock に @llmo-extended-report マーカーと @report-title 等を書く。
サーバへアップロードすると、次回ページ読込時に拡張レポート表示設定の一覧と各プロダクトのサイドバーに自動で現れる。
不要になったらファイルを削除すればサイドバーから消える（DB のオーバーライド行は残るが影響なし）。

STEP 1. PHP ファイルを作成

テンプレートとして以下をコピーして、my_custom_report 部分を自分のレポート用識別子に書き換えてください。

<?php
/**
 * @llmo-extended-report
 * @report-key my_custom_report
 * @report-title 私のカスタムレポート
 * @report-description GA4 と AI ブランド言及の独自集計を行います
 * @report-default-enabled true
 */
declare(strict_types=1);
require __DIR__ . '/../../includes/auth_web.php';
$pageTitle = '私のカスタムレポート — クヌギGEO';
$headerProductNav = 'extended_report';
$navActive = 'extended:my_custom_report';
require __DIR__ . '/../../templates/page_open.php';
?>
      <h1>私のカスタムレポート</h1>
      <p class="llmo-hint">ここに本文や JS を書く</p>
<?php
require __DIR__ . '/../../templates/layout_app_close.php';
require __DIR__ . '/../../templates/html_close.php';

3 つのセクションが必要です。

docblock：自動検出のメタ情報（タイトル・key・既定 ON/OFF など）。
ヘッダー部：auth_web.php でログイン必須化、page_open.php でレイアウト読込。
フッター部：layout_app_close.php + html_close.php で締める。

STEP 2. docblock の各タグの意味

タグ	必須	意味
`@llmo-extended-report`	必須	このファイルを「拡張レポート」として認識させるマーカー。値は不要（このタグが無いファイルは検出対象外）。
`@report-key`	任意	URL／DB の識別子。英数字・アンダースコア・ハイフンのみ。先頭は英字で始める必要があります。省略時はファイル名（拡張子なし）が自動採用されます。
`@report-title`	必須	サイドバー／設定画面で表示するタイトル。空のままだと一覧から除外されます。
`@report-description`	任意	拡張レポート表示設定画面のリスト項目に表示する補足説明。
`@report-default-enabled`	任意	`true` / `false` / `1` / `0` / `yes` / `no` / `on` から指定。既存プロダクトで明示保存されていない場合の既定値。省略時は `false`（追加時は手動で ON にする運用）。
`@report-icon`	任意	サイドバーに表示するアイコン名（将来拡張用。現在は使用していません）。

STEP 3. ファイルを設置するだけで自動検出

FTP / SCP / Git pull などで products/extended_reports/ 配下にアップロードしてください。
キャッシュは無く、次回ページ読込時から即座に検出されてサイドバーに現れます（条件：そのプロダクトで ON になっていること）。
@report-default-enabled true なら、まだ ON/OFF 操作されていないプロダクトでも追加直後から表示されます（false なら、システム管理者が手動で ON にするまで非表示）。
ファイル先頭 4 KB のみを読んで docblock を解析するため、ファイルが大きくても検出のオーバーヘッドはほぼゼロです。
同じ @report-key が重複した場合は、最初に検出されたファイル 1 件のみが採用されます（重複は警告も出ません）。

STEP 4. 表示 ON/OFF はプロダクトごとに切替可能

システム管理者はシステム → 拡張レポート表示設定でプロダクト × レポートのマトリクスから一括切替できます。
状態は product_extended_reports テーブル（product_id, report_key, enabled）に保存されます。
明示的に保存されていないセルは @report-default-enabled の値が採用されます（テーブルに行が無い状態）。
「個別」と表示されているプロダクトは保存済み（オーバーライド適用中）、「既定」と表示されているプロダクトは未保存（docblock の値で動作中）です。

認証・権限の付け方

拡張レポートは require __DIR__ . '/../../includes/auth_web.php'; によりログイン必須が自動的に強制されます。

システム管理者（admin）のみ・プロダクト管理者以上のみに制限したい場合は、ファイル冒頭で以下のように追記してください。

require __DIR__ . '/../../includes/auth_web.php';
llmo_web_require_role($pdo, ['admin']);                         // システム管理者（admin）のみ
// または
llmo_web_require_role($pdo, ['admin', 'product_manager']);      // システム管理者（admin）+ プロダクト管理者（product_manager）

ロールが許可されていないユーザーがアクセスすると、403 が返却されます。

データの取り出し方（共通ヘルパ）

拡張レポート PHP の中から、以下の共通ヘルパが利用できます（api/bootstrap.php 経由ですべて require 済み）。

システム DB（`app.db`）

$pdo：システム DB に接続済みの PDO インスタンス。users / products / product_keywords / product_ga4 などにアクセスできます。
$currentUser：ログイン中のユーザー情報。
$currentUserRole：admin / product_manager / viewer。

プロダクト DB（`product_<id>.db`）

llmo_attach_product_db($pdo, $productId)：当該プロダクトの survey_snapshots を pdb.survey_snapshots として ATTACH。
llmo_detach_product_db($pdo)：使い終わったら明示的に detach（任意。同一接続内で別プロダクトを attach し直すと自動 detach されます）。

// 例: 当該プロダクトのスナップショット件数を取得
llmo_attach_product_db($pdo, $productId);
$count = (int) $pdo->query('SELECT COUNT(*) FROM pdb.survey_snapshots')->fetchColumn();

拡張レポート ON/OFF 状態の参照

llmo_extended_reports_effective($pdo, $productId)：そのプロダクトで ON になっている拡張レポートの [key => bool] マップを取得。
llmo_extended_reports_enabled_for_product($pdo, $productId)：ON のレポートメタ情報の配列。

GA4 関連

api/ga4_handlers.php の llmo_ga4_* 系関数（プロダクトの認証・トークン更新・データ取得）。
フロント側からは、既存の API（api/matrix.php, api/ga4.php, api/snapshot.php 等）を fetch() で呼び出して再利用するのがもっとも簡単です。同じ API を「サマリー」「マトリクス」「拡張レポート」が共有しているため、データの整合性も自動的に取れます。

サイドバーへの並び順

拡張レポートは llmo_extended_reports_discover() 関数によって 「タイトル昇順 → key 昇順」で並べられます。表示順を制御したい場合は、@report-title の先頭に番号やプレフィックスを付けてください。

@report-title 01. GA4 × AI 相関
@report-title 02. ページ別 言及分析
@report-title 03. 競合シェア推移

サンプルとして読むべきファイル

実物のソースが最良の教材です

クヌギGEO に同梱されている products/extended_reports/ga4_brand_correlation.php（→ ドキュメント上の解説は GA4 × AIブランド言及相関）が、最も完成された実装サンプルです。

docblock の書き方
front-end JS（fetch + Chart.js）でのデータ可視化
共通 API（api/matrix.php / api/ga4.php）の組み合わせ方
診断パネル（データが空のときの原因表示）の実装パターン

これらをほぼそのまま流用すれば、独自の集計軸を持つ拡張レポートを 1〜2 時間で作成できます。