スケジュールコマンドドキュメント（日本語）

このドキュメントは、システム内のすべてのスケジュールコマンドについて、コンポーネント別に整理して詳細を提供します。

システムコンポーネント概要

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TD
    %% External Data Sources
    BigQuery[(GCP BigQuery)]
    
    %% Core Databases - Aligned horizontally
    subgraph CoreDatabases["コアデータベース"]
        direction LR
        AnalyzerDB[(gb_analyzer)]
        ConsoleDB[(gb_console)]
    end
    
    %% External Services
    Crawler((PLG API))
    Dataset((TV Python API))
    OpenAI[[Open AI]]
    Notification((通知システム))

    %% Define connections with improved formatting
    BigQuery --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>gcp:sync-*</p>
        </div>
    ]
    Step1 --> AnalyzerDB
    
    AnalyzerDB --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>localdb:sync-*</p>
        </div>
    ]
    Step2 --> AnalyzerDB
    
    ConsoleDB --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>plg-api:sending-configs-to-crawler</p>
        </div>
    ]
    Step3 --> Crawler
    
    Crawler --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>plg-api:sync-crawl-failed-from-crawler</p>
        </div>
    ]
    Step4 --> ConsoleDB
    
    AnalyzerDB --- Step5[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
            <p style='margin-top: 8px'>analyzerdb:sync-crawl-success-from-analyzer</p>
        </div>
    ]
    Step5 --> ConsoleDB
    
    ConsoleDB --- Step6[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #ff9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6</span>
            <p style='margin-top: 8px'>dataset:create</p>
        </div>
    ]
    Step6 --> Dataset
    
    Dataset --- Step7[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #ff9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>7</span>
            <p style='margin-top: 8px'>dataset:get-status</p>
        </div>
    ]
    Step7 --> ConsoleDB
    
    AnalyzerDB --- Step8[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #66cccc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>8</span>
            <p style='margin-top: 8px'>specific-viewpoint:process-batches</p>
        </div>
    ]
    Step8 --> OpenAI
    
    OpenAI --- Step9[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #66cccc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>9</span>
            <p style='margin-top: 8px'>specific-viewpoint:check-batch-status</p>
        </div>
    ]
    Step9 --> AnalyzerDB
    
    ConsoleDB --- Step10[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>10</span>
            <p style='margin-top: 8px'>notification:sale-one-month</p>
        </div>
    ]
    Step10 --> Notification

    %% Styling for components
    style BigQuery fill:#d2e3fc,stroke:#3366cc,stroke-width:2px
    style ConsoleDB fill:#e8f5e8,stroke:#2d8f2d,stroke-width:3px,stroke-dasharray: 5 5
    style AnalyzerDB fill:#e8e8f5,stroke:#4d4d99,stroke-width:3px,stroke-dasharray: 5 5
    style OpenAI fill:#fcf3d2,stroke:#cc9900,stroke-width:2px
    style Dataset fill:#fcd9d9,stroke:#cc6666,stroke-width:2px
    style Crawler fill:#fcd9f2,stroke:#cc66cc,stroke-width:2px
    style Notification fill:#d9f2f2,stroke:#66cccc,stroke-width:2px
    
    %% Subgraph styling with database theme
    style CoreDatabases fill:#f0f8ff,stroke:#4682b4,stroke-width:3px,stroke-dasharray: 10 5
    
    %% Transparent connection steps
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3 fill:transparent,stroke:transparent,stroke-width:1px
    style Step4 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5 fill:transparent,stroke:transparent,stroke-width:1px
    style Step6 fill:transparent,stroke:transparent,stroke-width:1px
    style Step7 fill:transparent,stroke:transparent,stroke-width:1px
    style Step8 fill:transparent,stroke:transparent,stroke-width:1px
    style Step9 fill:transparent,stroke:transparent,stroke-width:1px
    style Step10 fill:transparent,stroke:transparent,stroke-width:1px

システムアーキテクチャ

Trend Viewerバックエンドは、複数のデータソースとサービスを統合してトレンド分析機能を提供するLaravelベースのアプリケーションです。システムはリポジトリパターンに従い、様々なソースからの商品とレビューデータをクリーニング、処理、分析するように設計されています。

主要コンポーネント

データベース接続

gb_analyzer (BaseModel.phpで'mysql'として設定)
- クリーンで処理されたデータのプライマリデータベース
- BaseModelを継承するモデルで使用
- BigQueryとCrawlerからソースされたクリーンデータを含むテーブル
- Crawlerによって直接入力される't_'プレフィックステーブルを含む
gb_console (BaseConsoleModel.phpで'mysql_console'として設定)
- TV（Trend Viewer）ウェブサイトのビジネスデータベース
- Console名前空間のBaseConsoleModelを継承するモデルで使用
- ウィッシュリストデータ、ユーザーデータ、ビジネスロジックデータを含む

外部サービス統合

BigQuery
- 商品、レビュー、ランキングなどの生データのソース
- スケジュールコマンドを通じてgb_analyzerに同期
- データ整合性を確保するために同期ステータスが追跡される
OpenAI
- レビュー文の特定視点予測に使用
- 大規模データセットを効率的に分析するためのバッチ処理を実装
- AIPromptConfigモデルを通じて設定可能なプロンプト
PLG API（Crawler統合）
- Crawlerシステムとの通信インターフェース
- gb_consoleからCrawlerにサマリーデータを送信
- クロール状態の更新を受信
- クロール設定の作成と更新を管理
TV Python API（Analyzer API）
- データセット操作のインターフェース
- ウィッシュリスト要件に基づいてデータセットを作成
- データセット状態情報を取得
- データ分析のバッチ処理を処理
通知システム
- データ変更と閾値ベースのイベントを処理
- データベースとPusherを通じてユーザーに通知を配信
- ユーザー設定とグループベースの通知ルールを処理

データベース構造

gb_analyzer (BaseModel.phpで'mysql'として設定)
- クリーンで処理されたデータのプライマリデータベース
- BigQueryとCrawlerからソースされたクリーンデータを含むテーブル
- Crawlerによって直接入力される't_'プレフィックステーブルを含む
gb_console (BaseConsoleModel.phpで'mysql_console'として設定)
- TV（Trend Viewer）ウェブサイトのビジネスデータベース
- ウィッシュリストデータ、ユーザーデータ、ビジネスロジックデータを含む

アーキテクチャパターン

リポジトリパターン
- 各モデルには対応するリポジトリインターフェースと実装がある
- ベースリポジトリは共通のデータベース操作を提供：
  - app/Contracts/Interfaces/BaseRepositoryInterface.php
  - app/Contracts/Repositories/BaseRepository.php
- 専門リポジトリはビジネス固有のロジックを実装
- リポジトリはインターフェースを使用して依存性注入とテスト可能性を有効にする
サービス層
- サービスはビジネスロジックをカプセル化
- データに変換と検証を適用
- 複数のリポジトリ間の操作を調整
- 外部APIとの統合を処理
スケジュールタスクのコマンドパターン
- コマンドは機能ドメインによって整理
- 各コマンドはデータパイプラインの特定のタスクを処理
- 共通機能はベースクラスに抽出
- エラーハンドリングとレポートがコマンドに組み込まれている
キューベース処理
- 非同期処理のためにジョブをディスパッチ
- 効率性のためのバッチジョブ処理
- 一時的な障害のための再試行メカニズム
- 進捗追跡とログ記録

主要データモデル

gb_analyzerモデル

Product: コア商品情報
Review: 商品レビュー
ReviewSentence: 分析用のレビューからの個別文
CategoryRanking: カテゴリ内の商品ランキング
SearchQueryRanking: 検索クエリの商品ランキング
BatchJobViewpoint: 視点分析のジョブ
ReviewSentenceSpecificViewpoint: 文と視点の関連付け

gb_consoleモデル

WishlistToGroup: ウィッシュリストをユーザーグループにリンク
SummaryWishlistProduct, SummaryWishlistCategory: クローラー用のサマリーデータ
WishlistDatasetHistory: データセット作成リクエストの履歴
AIPromptConfig: OpenAIプロンプトの設定
WishlistSpecificViewpoint: 分析用の特定視点

エラーハンドリングと監視

ErrorHandleTrait: システム全体で一貫したエラーハンドリングを提供
Slack通知トレイト: 適切なチャンネルにアラートを送信
ジョブ状態追跡: ジョブの進捗を監視・報告
ログ記録: 操作とエラーの詳細なログ記録

データフロー概要

システムのデータフローは、システムコンポーネント概要図に示された番号付きステップに従います：

BigQueryからAnalyzer DB（ステップ1）：
- コマンド: gcp:sync-* (products, reviews, review_sentences)
- プロセス: BigQueryから生データを抽出してAnalyzerデータベースにインポート
- 実装: BaseBigQuerySyncCommandがデータを取得し、専門ジョブによってバッチで処理
- 頻度: 30分ごと、日次の欠損データ同期
- 主要機能: 大規模データセットを処理するための効率的なチャンク化システム
LocalDB内部処理（ステップ2）:
- コマンド: localdb:sync-* (product-category-rankings, product-search-query-rankings)
- プロセス: 't_'プレフィックステーブル（Crawlerによって入力）をAnalyzer DBのクリーンフォーマットに内部処理
- 実装: 生データを分析用の正規化構造に変換
- 頻度: 5分ごと
- 主要機能: 下流システム用のデータ検証と変換
Console DBからCrawler（ステップ3）:
- コマンド: plg-api:sending-configs-to-crawler
- プロセス: Console DBからのウィッシュリストとサマリーデータをPLG API経由でCrawlerに送信
- 実装: SendToCrawlerが作成/更新操作用の設定データを準備
- 頻度: 5分ごと
- 主要機能: ビジネスルールに基づく動的設定生成
Crawler失敗状態からConsole DB（ステップ4）:
- コマンド: plg-api:sync-crawl-failed-from-crawler
- プロセス: Crawler APIから失敗したクロール情報を取得してConsole DBに記録
- 実装: 説明責任のために失敗詳細で追跡レコードを更新
- 頻度: 30分ごと
- 主要機能: 失敗したクロール操作のエラー追跡と診断
Analyzer成功クロールからConsole DB（ステップ5）:
- コマンド: analyzerdb:sync-crawl-success-from-analyzer
- プロセス: 成功したクロールデータを検証してConsole DBの状態を更新
- 実装: データ整合性のためのクロスデータベース検証プロセス
- 頻度: 5分ごと
- 主要機能: 運用データベースとビジネスデータベース間の状態同期
Console DBからデータセット作成（ステップ6）:
- コマンド: dataset:create
- プロセス: TV Python API経由でウィッシュリストデータをデータセットに処理
- 実装: CreateDatasetが商品、カテゴリ、視点データを準備
- 頻度: 30分ごと
- 主要機能: 分析システム用の包括的データパッケージング
データセット状態更新からConsole DB（ステップ7）:
- コマンド: dataset:get-status
- プロセス: TV Python APIからデータセット処理状態を取得してConsole DBに記録
- 実装: データセット生成の状態追跡と監視
- 頻度: 5分ごと
- 主要機能: 非同期ジョブ監視と状態管理
Analyzer DBからOpenAI処理（ステップ8）:
- コマンド: specific-viewpoint:process-batches
- プロセス: レビュー文と視点定義を分析のためにOpenAIに送信
- 実装: PromptConfigServiceからのプロンプトを使用したCreateBatchJobLogCommand
- 頻度: 5分ごと
- 主要機能: 顧客フィードバックのAI駆動分類
OpenAI結果からAnalyzer DB（ステップ9）:
- コマンド: specific-viewpoint:check-batch-status
- プロセス: OpenAIから分類結果を取得してAnalyzer DBに保存
- 実装: バッチ結果を処理して視点関連付けを作成
- 頻度: 5分ごと
- 主要機能: AI分析結果の構造化抽出と保存
Console DBから通知システム（ステップ10）:
- コマンド: notification:sale-one-month
- プロセス: 売上データの変更がPusherサービスを通じて通知をトリガー
- 実装: 閾値ベースの通知生成と配信
- 頻度: 日次
- 主要機能: 重要なビジネス指標変更のリアルタイムアラート

この相互接続されたデータフローにより、複数のソースからのデータを組み合わせ、専門サービスを通じて処理し、エンドユーザーに価値のある洞察を提供する包括的なトレンド分析システムが可能になります。

コンポーネントドキュメント

コンポーネント	説明	リンク
BigQuery同期	Google BigQueryからローカルデータベースへのデータ同期。定期同期、状態更新、欠損データ復旧を実装してデータ整合性を確保。	ドキュメントを見る
ローカルDB同期	ローカルデータベースの一貫性維持とCrawlerからの't_'プレフィックステーブルの処理コマンド（localdb:sync-product-category-rankings, localdb:sync-product-search-query-rankings）。データ整合性と生クローラーデータからクリーンアプリケーションデータへの適切な変換を確保。	ドキュメントを見る
Crawler統合	ウィッシュリストサマリーデータをCrawlerに送信（plg-api:sending-configs-to-crawler）し、失敗したクロール同期を処理（plg-api:sync-crawl-failed-from-crawler）するコマンド。クロール設定の作成と更新を管理し、状態更新を処理。	ドキュメントを見る
AnalyzerDB統合	Crawlerからの成功したクロールデータをgb_consoleに同期するコマンド（analyzerdb:sync-crawl-success-from-analyzer）。't_'プレフィックステーブルからのデータを検証・処理し、それに応じてビジネスデータを更新。	ドキュメントを見る
データセット	TV Python API経由でのデータセット生成（dataset:create）と状態監視（dataset:get-status）のコマンド。ウィッシュリストグループ、商品、カテゴリデータを処理して分析データセットを作成し、その処理状態を監視。	ドキュメントを見る
特定視点	OpenAIでレビュー文を処理（specific-viewpoint:process-batches）し、バッチ状態をチェック（specific-viewpoint:check-batch-status）するコマンド。効率性のためのバッチ処理とAIPromptConfigモデルを通じた設定可能なプロンプトを使用。	ドキュメントを見る
通知	ユーザーへのシステム通知の管理と送信コマンド（notification:send）。売上アラートやシステム更新を含む様々な通知タイプを処理。	ドキュメントを見る

頻度概要

timeline
    title コマンドスケジュールタイムライン
    section 高頻度
        5分ごと<br>(例：08.00) : update bigquery-status
                                       : localdb sync-product-category-rankings
                                       : localdb sync-product-search-query-rankings
                                       : plg-api sending-configs-to-crawler --mode=create --data-type=*
                                       : plg-api sending-configs-to-crawler --mode=update --data-type=*
                                       : analyzerdb sync-crawl-success-from-analyzer --data-type=*
                                       : dataset get-status
                                       : specific-viewpoint process-batches
                                       : specific-viewpoint check-batch-status
    section 中頻度
        30分ごと<br>(例：08.30) : gcp sync-products
                                        : gcp sync-reviews
                                        : gcp sync-review_sentences
                                        : plg-api sync-crawl-failed-from-crawler --data-type=*
                                        : dataset create
    section 低頻度
        日次<br>(例：00.00) : gcp sync-products --missed
                              : gcp sync-reviews --missed
                              : notification sale-one-month

DataType値に関する注記:

*は以下のデータタイプを表します：
- SummaryProduct ('product'): 商品サマリーデータ
- SummaryProductReview ('reviews'): 商品レビューデータ
- SummaryCategory ('category_ranking_group'): カテゴリランキングデータ
- SummarySearchQuery ('sq_ranking_group'): 検索クエリランキングデータ

実装詳細

リポジトリパターン実装

システムはデータアクセスのためのリポジトリパターンを実装：

インターフェース: app/Contracts/Interfaces/でリポジトリ操作の契約を定義
- ベースインターフェース: BaseRepositoryInterface.php
- Analyzerインターフェース: app/Contracts/Interfaces/Analyzer/
- Consoleインターフェース: app/Contracts/Interfaces/Console/
実装: app/Contracts/Repositories/で具体的な機能を提供
- ベースリポジトリ: BaseRepository.php
- Analyzerリポジトリ: app/Contracts/Repositories/Analyzer/
- Consoleリポジトリ: app/Contracts/Repositories/Console/
モデル: データ構造と関係を定義：
- gb_analyzerモデルはapp/Models/BaseModel.phpを継承
- gb_consoleモデルはapp/Models/Console/BaseConsoleModel.phpを継承

スケジュールタスクのコマンドパターン

コマンドは機能ドメインによって整理され、各コマンドはデータパイプラインの特定のタスクを処理：

ベースコマンドクラス: 関連コマンドの共有機能を提供
- 例: BaseBigQuerySyncCommand.phpは共通のBigQuery同期ロジックを提供
専門コマンド: 特定のビジネスロジックを実装
- 例: 特定のデータタイプ用のSyncProduct.php, SyncReview.php
エラーハンドリング: ErrorHandleTraitによる組み込みエラーハンドリング
- コマンド全体で一貫したログ記録と通知
- 重要な問題のアラート用Slack統合

キューベース処理

システムは効率的な処理のためにLaravelのキューシステムを使用：

ジョブディスパッチ: コマンドは非同期処理のためにジョブを作成・ディスパッチ
バッチ処理: ジョブは効率性のためにチャンク化されバッチで処理
再試行メカニズム: ジョブは一時的な障害を処理するための再試行ロジックを実装
監視: ジョブ状態追跡と詳細なログ記録

Backend Documentation