特定視点概要

説明

特定視点オペレーションコンポーネントは、OpenAIのAI機能を使用して、あらかじめ定義された視点に従ってレビュー文を分類するための処理と分析を管理します。このコンポーネントは、アナライザーデータベース（gb_analyzer）から商品レビュー文を処理し、コンソールデータベース（gb_console）で定義された特定の視点と関連付けます。バッチ処理を通じて、大量のレビューデータを効率的に処理し、トレンド分析とパターン認識のためのカスタマイズ可能な視点カテゴリに基づいた顧客フィードバックの構造化分析を可能にします。

システム概要図

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TD
    %% External services
    OpenAI[[OpenAI API]]
    
    %% Commands
    ProcessCommand[specific-viewpoint:process-batches]
    StatusCommand[specific-viewpoint:check-batch-status]
    
    %% Database tables grouped by database
    subgraph ConsoleDB["<div style='width: 300px'>コンソールデータベース (gb_console)</div>"]
        direction LR
        WishlistSpecificVP[(wl_spec_vps)]
        WishlistCatVPDetail[(wl_cat_vp_details)]
    end
    
    subgraph AnalyzerDB["<div style='width: 300px'>アナライザーデータベース (gb_analyzer)</div>"]
        direction TB
        ReviewSentences[(review_sentences)]
        BatchJobs[(batch_jobs_vps)]
        BatchJobLogs[(batch_jobs_vp_logs)]
        ReviewSentenceVP[(review_sentences_wl_spec_vp)]
    end
    
    subgraph Commands["スケジュールされたコマンド"]
        ProcessCommand
        StatusCommand
    end
    
    %% Process Command Steps (1A to 5A)
    subgraph ProcessSteps["プロセスコマンドステップ"]
        direction LR
        ProcessCmdStep1A[
            <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'>1A</span>
                <p style='margin-top: 8px'>保留中バッチの取得</p>
            </div>
        ]
        ProcessCmdStep2A[
            <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'>2A</span>
                <p style='margin-top: 8px'>レビュー文の取得</p>
            </div>
        ]
        ProcessCmdStep3A[
            <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'>3A</span>
                <p style='margin-top: 8px'>視点定義の取得</p>
            </div>
        ]
        ProcessCmdStep4A[
            <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'>4A</span>
                <p style='margin-top: 8px'>バッチリクエスト送信</p>
            </div>
        ]
        ProcessCmdStep5A[
            <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'>5A</span>
                <p style='margin-top: 8px'>ログレコード作成</p>
            </div>
        ]
        
        ProcessCmdStep1A --> ProcessCmdStep2A
        ProcessCmdStep2A --> ProcessCmdStep3A
        ProcessCmdStep3A --> ProcessCmdStep4A
        ProcessCmdStep4A --> ProcessCmdStep5A
    end
    
    %% Status Command Steps (1B to 5B)
    subgraph StatusSteps["ステータスコマンドステップ"]
        direction LR
        StatusCmdStep1B[
            <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'>1B</span>
                <p style='margin-top: 8px'>保留中ログの取得</p>
            </div>
        ]
        StatusCmdStep2B[
            <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'>2B</span>
                <p style='margin-top: 8px'>ステータス確認</p>
            </div>
        ]
        StatusCmdStep3B[
            <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'>3B</span>
                <p style='margin-top: 8px'>結果ダウンロード</p>
            </div>
        ]
        StatusCmdStep4B[
            <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'>4B</span>
                <p style='margin-top: 8px'>結果保存</p>
            </div>
        ]
        StatusCmdStep5B[
            <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'>5B</span>
                <p style='margin-top: 8px'>ステータス更新</p>
            </div>
        ]
        
        StatusCmdStep1B --> StatusCmdStep2B
        StatusCmdStep2B --> StatusCmdStep3B
        StatusCmdStep3B --> StatusCmdStep4B
        StatusCmdStep4B --> StatusCmdStep5B
    end
    
    %% Connections from commands to step groups
    ProcessCommand --> ProcessSteps
    StatusCommand --> StatusSteps
    
    %% Connections from steps to databases/services
    ProcessCmdStep1A -.-> BatchJobs
    ProcessCmdStep2A -.-> ReviewSentences
    ProcessCmdStep3A -.-> WishlistSpecificVP
    ProcessCmdStep4A -.-> OpenAI
    ProcessCmdStep5A -.-> BatchJobLogs
    
    StatusCmdStep1B -.-> BatchJobLogs
    StatusCmdStep2B -.-> OpenAI
    StatusCmdStep3B -.-> OpenAI
    StatusCmdStep4B -.-> ReviewSentenceVP
    StatusCmdStep5B -.-> BatchJobLogs
    
    %% Database styles
    style ConsoleDB fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style AnalyzerDB fill:#d9d9f2,stroke:#6666cc,stroke-width:2px
    
    %% Table styles
    classDef consoleTable fill:#e6ffe6,stroke:#339933,stroke-width:1px
    classDef analyzerTable fill:#e6e6ff,stroke:#6666cc,stroke-width:1px
    
    %% Apply table styles
    class WishlistSpecificVP,WishlistCatVPDetail consoleTable
    class ReviewSentences,BatchJobs,BatchJobLogs,ReviewSentenceVP analyzerTable
    
    %% Other styles
    style OpenAI fill:#fcf3d2,stroke:#cc9900,stroke-width:2px
    style ProcessCommand fill:#d9f2d9
    style StatusCommand fill:#d9f2d9
    style Commands fill:#f9f9f9
    style ProcessSteps fill:#f0f8ff,stroke:#6699cc,stroke-width:1px
    style StatusSteps fill:#f0fff0,stroke:#99cc66,stroke-width:1px
    
    %% Transparent connection steps
    style ProcessCmdStep1A fill:transparent,stroke:transparent,stroke-width:1px
    style ProcessCmdStep2A fill:transparent,stroke:transparent,stroke-width:1px
    style ProcessCmdStep3A fill:transparent,stroke:transparent,stroke-width:1px
    style ProcessCmdStep4A fill:transparent,stroke:transparent,stroke-width:1px
    style ProcessCmdStep5A fill:transparent,stroke:transparent,stroke-width:1px
    style StatusCmdStep1B fill:transparent,stroke:transparent,stroke-width:1px
    style StatusCmdStep2B fill:transparent,stroke:transparent,stroke-width:1px
    style StatusCmdStep3B fill:transparent,stroke:transparent,stroke-width:1px
    style StatusCmdStep4B fill:transparent,stroke:transparent,stroke-width:1px
    style StatusCmdStep5B fill:transparent,stroke:transparent,stroke-width:1px

詳細データフロー依存関係

特定視点オペレーションコンポーネントは、図の番号付きステップに合わせた2つの主要プロセスによる双方向データフローに従います：

バッチ作成と処理（ステップ1A-5A）

1A. 保留中バッチの取得: specific-viewpoint:process-batchesコマンドはバッチジョブを特定します：

保留中のログ作成ステータスを持つジョブをbatch_jobs_vpsテーブルから照会
オプションの--log-creation-statusパラメータに基づいてフィルタリングを適用
レコード取得にはBatchJobViewpointRepositoryInterfaceを使用
効率的な処理のためにジョブをチャンクにグループ化

2A. レビュー文の取得: 各バッチジョブに対して、システムは関連データを取得します：

未処理のレビュー文をreview_sentencesテーブルから収集
バッチジョブで指定された商品IDでフィルタリング
設定（specific_viewpointbatch_processing.max_processing_sentences）から最大制限を適用
ページネーションをサポートするために最後に処理されたレビュー文IDを追跡

3A. 視点定義の取得: システムは視点設定を読み込みます：

特定視点定義をwl_spec_vpsテーブルから取得
カテゴリ視点詳細をwl_cat_vp_detailsテーブルから読み込み
これらの定義を使用してAIプロンプトを構造化
入力データの完全性と正確性を検証

4A. バッチリクエスト送信: データが構造化されOpenAIに送信されます：

OpenAIとの通信にはViewpointClassifyProcessingInterfaceを使用
レビュー文と視点定義を含むプロンプトを準備
バッチ処理リクエストをOpenAI APIに送信
将来の参照用にOpenAIバッチIDを保存

5A. ログレコード作成: リクエスト成功時、システムは操作を記録します：

batch_jobs_vp_logsテーブルに新しいレコードを作成
OpenAIバッチID、文数、処理メタデータを保存
初期ステータスを「保留中」に設定
データの一貫性を確保するためにトランザクションを使用
重複処理を防ぐための冪等性チェックを実装

ステータス監視と結果処理（ステップ1B-5B）

1B. 保留中ログの取得: specific-viewpoint:check-batch-statusコマンドは確認するログを特定します：

保留中ステータスのログをbatch_jobs_vp_logsテーブルから照会
古い保留中ログを優先
--chunkパラメータ（デフォルト：10）に基づいて制限を適用
各保留中ログに対してCheckBatchStatusJobをディスパッチ

2B. ステータス確認: 各保留中ログに対して：

OpenAIとの通信にはBatchProcessingHandlerInterfaceを使用
バッチの現在のステータスを確認するためにOpenAI APIを呼び出し
バッチが完了または失敗したかどうかを判断するためにレスポンスを解釈
一時的な失敗のためのリトライを管理

3B. 結果ダウンロード: バッチが完了したとき：

ステータスレスポンスから出力ファイルIDを取得
結果ファイルをダウンロードするためにBatchFileHandlerInterfaceを使用
適切なエラー記録と共に潜在的なダウンロード失敗を処理
レート制限のための指数バックオフを実装

4B. 結果保存: システムは分類結果を処理します：

生の結果を解析するためにBatchResultHandlerInterfaceを使用
成功したレスポンスから視点マッピングを抽出
データベース保存用にデータをフォーマット
レビュー文と特定視点間の関連付けを一括挿入するためにReviewSentenceSpecificViewpointRepositoryInterfaceを使用
ステータスレポート用に処理された文をカウント

5B. ステータス更新: 処理結果に基づいて：

batch_jobs_vp_logsでログステータスを更新（保留中 → 完了/失敗）
関連するすべてのログに基づいてbatch_jobs_vpsでバッチジョブステータスを更新
統計とエラー詳細を記録
重要なイベントに対してSlack通知を送信
監査と監視のためにタイムスタンプを更新

データベーススキーマ

コンソールデータベーステーブル（gb_console）

erDiagram
    wl_spec_vps {
        bigint id PK
        bigint wl_cat_vp_detail_id FK "wl_cat_vp_detailsへの外部キー（カスケード削除）"
        string name "視点名（最大100文字）"
        text description "視点説明"
        timestamp created_at
        timestamp updated_at
    }
    
    wl_cat_vp_details {
        bigint id PK
        text detail "カテゴリ視点詳細説明"
        timestamp created_at
        timestamp updated_at
    }
    
    wl_cat_vp_details ||--o{ wl_spec_vps : "has many"

アナライザーデータベーステーブル（gb_analyzer）

erDiagram
    batch_jobs_vps {
        bigint id PK
        json product_ids "処理する商品IDのリスト"
        json wl_spec_vp_ids "処理する特定視点IDのリスト"
        bigint wl_cat_vp_detail_id "wishlist_category_viewpoint_detailsへの参照"
        bigint last_review_sentence_id "最後に処理されたレビューID（デフォルト：0）"
        tinyint log_creation_status "ログ作成ステータス（保留中/処理中/完了/失敗）"
        tinyint status "ジョブステータス（保留中/処理中/完了/失敗）"
        timestamp created_at
        timestamp updated_at
    }
    
    batch_jobs_vp_logs {
        bigint id PK
        bigint batch_job_id "batch_jobs_vpsへの参照"
        string batch_id "OpenAIバッチID"
        integer total_sentences "処理する文の合計（デフォルト：0）"
        integer processed_sentences "処理された文の数（デフォルト：0）"
        json log_details "エラーの詳細（nullable）"
        integer status "ログステータス（デフォルト：保留中）"
        timestamp created_at
        timestamp updated_at
    }
    
    review_sentences {
        bigint sentence_id PK
        string mall_product_id "モールからの商品ID"
        text content "レビューから抽出された文内容"
        timestamp created_at
        timestamp updated_at
    }
    
    review_sentences_wl_spec_vp {
        bigint review_sentence_id PK "review_sentences.sentence_id"
        bigint wl_spec_vp_id PK "wishlist_specific_viewpoints.id"
    }
    
    batch_jobs_vps ||--o{ batch_jobs_vp_logs : "has many"
    review_sentences ||--o{ review_sentences_wl_spec_vp : "has many"

頻度概要

タイムライン

timeline
    title 特定視点オペレーションスケジュール
    section バッチ処理
        5分毎 <br>（例：08.00、08.05など） : specific-viewpoint process-batches
                                        : 特定視点分類ジョブの作成とディスパッチ
                                        : specific-viewpoint check-batch-status
                                        : バッチステータスの確認とOpenAIからの結果処理

期待される結果

これらのコマンドが正常に実行されると、システムは以下を提供します：

自動AI駆動分類: OpenAIの機能を使用したレビュー文の定期的な処理により、内容を意味のある視点カテゴリに分類
構造化感情分析: 対象を絞ったインサイトを可能にする関心の特定側面でグループ化された商品レビューの体系的分析
スケーラブルなバッチ処理: チャンク処理とキュー管理を通じた大量のレビューデータの効率的な処理
リアルタイムステータス監視: 自動結果取得と保存を伴うOpenAIバッチ処理ステータスの継続的な追跡
データ品質保証: 意味のある分類結果を確保するためのAI処理前の入力データの完全性と正確性の検証
包括的な監査証跡: トラブルシューティングのための作成イベント、ステータス変更、エラー条件を含むバッチ操作の完全なログ記録
パターン認識機能: 複数の商品とカテゴリにわたる顧客フィードバックのトレンドとパターンを大規模に識別する能力
意思決定支援データ: 構造化された視点分析に基づく情報に基づいた製品開発とマーケティング決定のためのサポートデータ

バッチリスト

名前	説明
バッチ処理	レビュー文をOpenAIに送信して視点分類を行うためのバッチジョブを作成およびディスパッチするコマンド
バッチステータス確認	OpenAIバッチ処理操作を監視し、完了した結果を取得し、分類された視点関連付けを保存するコマンド

Backend Documentation