インストール方法

1. 動作要件

2. ファイル配置

1. kunugi_geo_Ver0.1.zip をダウンロードします。
2. ZIP を解凍すると下記のファイル群が直接展開されます（ZIP の中に system/ のような上位ディレクトリは含まれていません）。
   これらをまるごと、クヌギGEO を公開したいディレクトリへ配置してください。配置先のディレクトリ名は任意です。

   例 1（ドメイン直下に公開）：https://example.com/ を起点にする場合 → ドキュメントルート（/var/www/example.com/public_html/ など）に直接展開。

   例 2（サブディレクトリに公開）：https://example.com/kunugi-geo/ として公開する場合 → /var/www/example.com/public_html/kunugi-geo/ を作成し、その中に展開。

3. 展開後のディレクトリ構成（抜粋）。以降のドキュメント中の data/・api/・cron/ などのパスは、すべてこの配置ディレクトリを起点とした相対パスとして表記しています。

   index.php          ← ブラウザで開く起点
   matrix.php
   settings.php
   .htaccess          ← Apache 用：書換え＋Basic 認証
   LICENSE            ← MIT 本文（再配布時、内容を別の場所に転記しても可）
   admin/             ← システム管理画面群
   api/               ← REST API & ブートストラップ
                        ※ bootstrap.php / auth_helpers.php / routes.php /
                           ga4_handlers.php / catalog_handlers.php は
                           .htaccess で HTTP からの直接アクセスを禁止
   auth/              ← ログイン・初回設定
   backup/            ← DB バックアップ格納（.htaccess で HTTP 直接アクセス禁止）
   cron/              ← CLI で動かす自動実行スクリプト（.htaccess で HTTP 直接アクセス禁止）
   css/, js/, img/    ← 静的アセット
   img/custom/        ← アップロードロゴ等の配置先
                        （.htaccess で .php / .phtml / .phar / .cgi 等の
                          スクリプト実行を無効化）
   data/              ← SQLite DB / 認証鍵 / ログ（書込み権限が必要・
                        .htaccess で HTTP 直接アクセス禁止）
   data/products/     ← プロダクトごとの DB ファイル（自動生成・data/ の禁止に内包）
   includes/          ← 内部 require 専用（.htaccess で HTTP 直接アクセス禁止）
   manage/            ← プロダクト管理者向け画面群
   products/          ← レポート画面群
   templates/         ← レイアウト共有
   vendor/chartjs/    ← Chart.js v4（MIT・LICENSE 同梱）
   

3. ディレクトリ権限

SQLite DB を含む data/ 配下は Web サーバプロセス（Apache/Nginx）が読み書きできる必要があります。共用サーバなどでは 755 / 644 程度から始め、書き込めなければ 775 / 664 へ緩めてください。

下表のパスは、いずれもクヌギGEO を配置したディレクトリ直下の相対表記です。

4. Basic 認証の設定（必須級）

同梱の .htaccess 末尾に以下のような記述があります。ご自身のサーバの htpasswd ファイル絶対パスへ書き換えて有効化してください。

AuthUserFile "/path/to/htpasswd/.htpasswd"
AuthName "Member Site"
AuthType BASIC
require valid-user

1. 適当な場所（例: /etc/apache2/htpasswd/kunugi_geo）に htpasswd ファイルを作成。

   htpasswd -c /etc/apache2/htpasswd/kunugi_geo your_user

2. .htaccess の AuthUserFile をそのファイルパスに書き換える。
3. ブラウザで配置先 URL（例: https://<サーバ>/）を開き、Basic 認証ダイアログが出るかを確認。
4. パスワード入力後にクヌギGEO のログイン画面に進めることを確認。

5. 初回ブラウザアクセスと初期管理者の登録

1. 配置先 URL（例: https://<サーバ>/）にアクセス → Basic 認証 → クヌギGEO のログイン画面。
2. ログイン画面で admin / admin でログインを試みると、自動的に「初期管理者情報」画面（auth/initial_setup.php）に飛びます。
3. 「管理者ログイン ID（メール形式）」と「管理者パスワード（4 文字以上）」を入力 → 「登録して続行」を押下。
4. 以後はそのメールアドレス＋パスワードで auth/login.php（配置先 URL からの相対）でログインします。パスワード再発行メールも、このアドレス宛に送信されます。

6. DataForSEO API の登録

1. DataForSEO のアカウント登録ページでアカウント作成（個人メール: $1 / ビジネスメール: $5 のテストクレジット付与）。
2. 本格運用する場合は最低 $50 をデポジット（入金）。クレジットカード等で入金できます。
3. クヌギGEO の 「システム → DataForSEO API 管理」にログイン名（メール）と API パスワードを入力 → 「API 設定を保存」。
4. 同画面で「残高を表示」を押し、現在の残高が取得できれば連携 OK。
5. 必要に応じて実行プラン（Live / Priority / Standard）と各 LLM のモデルを選択して保存。
6. キーワード × 軸の組み合わせから月額・年額コストを試算する DataForSEO 料金シミュレーション も用意しています。

7. GA4 連携（OAuth）の準備

本機能は GA4 流入レポート・GA4 × AI 言及相関を使う場合のみ必要です。詳細手順は GA4 連携（OAuth） を参照。

1. Google Cloud Console でプロジェクトを作成し、Google Analytics Data API を有効化。
2. OAuth 同意画面を作成（テスト 段階で構いません。本ツール利用者の Google アカウントを「テストユーザー」に登録）。
3. OAuth クライアント ID（種別: ウェブ アプリケーション）を作成。承認済みのリダイレクト URI にはクヌギGEO 画面で表示される URI（配置先に応じて https://<サーバ>/api/ga4_callback.php など）を登録。
4. クヌギGEO の 「システム → GA4 連携」 画面でクライアント ID／シークレットを保存。
5. 各プロダクトの 「プロダクト管理 → GA4 連携・設定」で GA4 プロパティ ID（数字のみ）を入力 → 「Google で認証」。

8. プロダクトとキーワードの登録

1. 「システム → プロダクト管理」でプロダクトを 1 件以上作成（自社サービス、商品ライン等）。
2. 画面上部の「プロダクト」セレクトで対象プロダクトを選択。
3. 「プロダクト管理 → キーワード登録」でキーワード（最大 2000 件）と自社／競合ブランド、調査軸（順位 / AI Overview / AI Mode / 各 LLM）を登録。
4. 「プロダクト管理 → 手動での調査実行」で初回のスナップショットを取得。

9. cron による自動調査の設定

毎日同じ時刻に「すべてのプロダクトの本日未取得分」を自動取得するには、サーバの cron に以下を登録してください。

# crontab -e の例（毎日 4:00 に実行 / 配置先が /var/www/example.com/public_html/ の場合）
0 4 * * * /usr/bin/php /var/www/example.com/public_html/cron/run_survey.php --product=all --mode=missingToday >> /var/www/example.com/public_html/data/cron.log 2>&1

• --product=<ID> で単一プロダクトを指定／--product=all（または --all-products）で全プロダクト。
• --mode=missingToday（既定）は本日未取得・エラーのみ／--mode=all は全件再取得（コストがフルにかかります）。
• 「プロダクト管理 → 調査実行管理」で曜日スケジュールを設定すると、その日対象外の軸は cron でも自動でスキップされます。
• 同時多重起動防止のため、ロックファイル（data/cron_survey.lock）を取得します。前回が異常終了した時のみ --no-lock を付けて回避してください。

エックスサーバー（Xserver）での Cron 設定例

本ツールの動作確認環境（Xserver / PHP 8.3.30）での具体的な手順です。GUI から登録できるので、crontab -e を直接編集する必要はありません。

1. Xserver サーバーパネル にログイン。
2. 「アカウント」セクションの 「Cron 設定」 をクリック。
3. 初回のみ、上部の「Cron 結果の通知アドレス」にエラー通知用メールアドレスを設定して保存（推奨）。
4. 「Cron 追加」タブを開き、以下のとおり入力。

   欄	入力例
   分	0（毎時 0 分に実行）
   時	4（深夜 4 時に実行）
   日 / 月 / 曜日	すべて *（毎日）
   コマンド	下のコード参照

5. 「確認画面へ進む」→「追加する」で登録完了。

cd /home/<サーバーID>/<ドメイン>/public_html && /usr/bin/php8.3 /home/<サーバーID>/<ドメイン>/public_html/cron/run_survey.php --product=all --mode=missingToday >> /home/<サーバーID>/<ドメイン>/public_html/data/cron.log 2>&1

サブディレクトリ（例 /public_html/kunugi-geo/）に配置している場合は、cd 先と /cron/・/data/ の親パスを実際の配置先に合わせて差し替えてください。

• <サーバーID> は契約時に決まる ID（例 xs132374）。<ドメイン> は配置先の独自ドメイン（例 example.com）。
• PHP のフルパスは /usr/bin/php8.3（Xserver の PHP 8.3 系 CLI）。詳細はサーバーパネルの「サーバー情報 → コマンドパス一覧」で確認できます。
• cd でスクリプトのあるディレクトリに移動してから実行することで、require __DIR__ . '/...' 等の相対 require が確実に解決されます。
• 結果メールが不要な場合は末尾を > /dev/null 2>&1 に変更してください（ログだけで十分なら、この例のとおり cron.log へ追記する方が運用しやすいです）。
• 「Cron 結果の通知アドレス」を設定していると、標準出力に何か出力されるたびにメールが届きます。エラー時のみ通知を受け取りたい場合は、コマンド末尾を >> data/cron.log 2>&1 ではなく > /dev/null 2>/dev/null に変更し、ログはアプリ内の cron 実行ログ 画面から確認する運用にしてください。

10. よくあるトラブルと対処法