01.database-schema-changes

Dataset Workflow - Database Changes

Database Schema & Changes

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TB
    %%ds_analyzer.
    subgraph GBConsoleDB ["gb_console DB (MySQL)"]
        direction TB
        WTG["wishlist_to_groups<br/>📝 name, group_id<br/>📊 status: 1 | Active"]
        
        subgraph SummaryTables ["Summary Wishlist Tables"]
            direction LR
            SWP["summary_wishlist_products<br/>📝 input, input_type<br/>📊 crawl_status: 0→1→2"]
            SWPR["summary_wishlist_product_reviews<br/>📝 summary_wishlist_product_id<br/>📊 crawl_status: 0→1→2"]
            SWC["summary_wishlist_categories<br/>📝 category_id, mall_id<br/>📊 crawl_status: 0→1→2"]
            SWSQ["summary_wishlist_search_queries<br/>📝 keyword, mall_id<br/>📊 crawl_status: 0→1→2"]
        end
        
        WDH["wishlist_dataset_histories<br/>📝 dataset_id, config<br/>📊 status: 1→2→3<br/>📊 spvp_status: 1→2→3"]
    end

    subgraph AnalyzerV2DB ["analyzer_v2 DB (MySQL)"]
        direction LR
        CP["products<br/>📝 name, price, description<br/>📊 生マーケットプレイスデータ"]
        CR["reviews<br/>📝 content, rating<br/>📊 ユーザーレビュー"]
        CRS["review_sentences<br/>📝 sentence, embedding<br/>📊 処理済み文章"]
    end

    subgraph DSAnalyzerDB ["ds_analyzer DB (MySQL)"]
        direction TB
        DS["datasets<br/>📝 name, settings<br/>📊 status: 1→2→3<br/>📊 progress: 0→100"]
        
        subgraph AnalyzerBatchTables ["analyzer_batch作成"]
            direction LR
            ADP["products<br/>📝 processed_name<br/>📊 Dataset商品"]
            ADPD["product_details<br/>📝 specifications<br/>📊 商品メタデータ"]
            PS["product_similarities<br/>📝 similarity_score<br/>📊 類似度マトリックス"]
            AV["ai_viewpoints<br/>📝 name, description<br/>📊 AI生成ラベル"]
            RSAIVP["review_sentence_aivp<br/>📝 sentence-ai_viewpointマッピング<br/>📊 クラスタリング結果"]
            ADR["reviews<br/>📝 sentiment_overall<br/>📊 Dataset reviews"]
            ARS["review_sentences<br/>📝 cluster_id, sentiment<br/>📊 クラスター化文章"]
        end
        
        subgraph SPVPBatchTables ["spvp_batch管理"]
            direction LR
            SV["specific_viewpoints<br/>📝 last_object_id<br/>📊 SPVP進捗追跡"]
            VC["viewpoint_categories<br/>📝 category_name<br/>📊 SPVPカテゴリ"]
            RSSPVP["review_sentence_spvp<br/>📝 sentence-viewpointマッピング<br/>📊 Qwen結果"]
        end
    end

    %% Phase 1: Wishlist Creation
    WTG --- 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'>Wishlistアイテム作成</p>
        </div>
    ]
    Step1 --> SummaryTables

    %% Phase 2: Data Crawling
    SummaryTables --- 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'>マーケットプレイスクロール</p>
        </div>
    ]
    Step2 --> CP
    CP --> CR
    CR --> CRS

    %% Phase 3: Dataset Creation
    SummaryTables --- Step3[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6699 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3</span>
            <p style='margin-top: 8px'>Datasetメタデータ作成</p>
        </div>
    ]
    Step3 --> DS
    DS --> WDH

    %% Phase 4: ML Analysis
    CRS --- Step4[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #ff9900 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4</span>
            <p style='margin-top: 8px'>分析・クラスター</p>
        </div>
    ]
    Step4 --> AnalyzerBatchTables

    %% Phase 5: SPVP Processing
    ARS --- Step5[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc3366 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5</span>
            <p style='margin-top: 8px'>SPVP処理</p>
        </div>
    ]
    Step5 --> SPVPBatchTables
    SV -.-> WDH

    %% Styling per api-guide.md
    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 GBConsoleDB fill:#fcf3d2
    style SummaryTables fill:#faf4de
    style AnalyzerV2DB fill:#d2e3fc
    style DSAnalyzerDB fill:#d9f2d9
    style AnalyzerBatchTables fill:#e6ffe6
    style SPVPBatchTables fill:#ffe6f2
    
    style WTG fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style WDH fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style SWP fill:#fffae8,stroke:#ebdba2,stroke-width:2px
    style SWPR fill:#fffae8,stroke:#ebdba2,stroke-width:2px
    style SWC fill:#fffae8,stroke:#ebdba2,stroke-width:2px
    style SWSQ fill:#fffae8,stroke:#ebdba2,stroke-width:2px
    style CP fill:#e6f0ff,stroke:#6699cc,stroke-width:1px
    style CR fill:#e6f0ff,stroke:#6699cc,stroke-width:1px
    style CRS fill:#e6f0ff,stroke:#6699cc,stroke-width:1px
    style DS fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    
    %% analyzer_batch tables
    style ADP fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style ADPD fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style PS fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style AV fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style RSAIVP fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style ADR fill:#d9f2d9,stroke:#339933,stroke-width:2px
    style ARS fill:#d9f2d9,stroke:#339933,stroke-width:2px
    
    %% spvp_batch tables
    style SV fill:#ffccdd,stroke:#cc3366,stroke-width:2px
    style VC fill:#ffccdd,stroke:#cc3366,stroke-width:2px
    style RSSPVP fill:#ffccdd,stroke:#cc3366,stroke-width:2px

主要Database Tables

gb_console DB - ビジネスロジック

Table 主要フィールド ステータス値
wishlist_to_groups name, group_id, subscription_id status: 1 | Active
wishlist_dataset_histories dataset_id, config status: 1→2→3, spvp_status: 1→2→3
summary_wishlist_products input, input_type, mall_id crawl_status: 0→1→2
summary_wishlist_product_reviews summary_wishlist_product_id, schedule_id crawl_status: 0→1→2
summary_wishlist_categories category_id, mall_id crawl_status: 0→1→2
summary_wishlist_search_queries keyword, mall_id crawl_status: 0→1→2

analyzer_v2 DB - 生クロールデータ

Table 主要フィールド 責任サービス
products name, description, price, mall_id Crawler Service
reviews product_id, content, rating Crawler Service
review_sentences review_id, sentence, embedding Crawler Service + PLG API

ds_analyzer DB - 分析結果

Table 主要フィールド 責任サービス
datasets name, settings, status, progress, error_code trend-viewer-backend

analyzer_batchが7テーブル作成:

Table 主要フィールド 説明
products dataset_id, crawler_product_id, processed_name 処理済みデータを持つDataset商品
product_details product_id, specifications, metadata 商品詳細仕様
product_similarities dataset_id, mall_product_id_a, mall_product_id_b, similarity_score 商品類似度マトリックス
ai_viewpoints dataset_id, cluster_id, name, description AI生成クラスターラベル
review_sentence_aivp sentence_id, dataset_id, ai_viewpoint_id, mall_product_id AI Viewpoint ↔ Sentenceマッピング
reviews dataset_id, product_id, sentiment_overall センチメント付きDataset reviews
review_sentences dataset_id, ai_viewpoint_id, cluster_id, is_noise クラスター化review sentences

spvp_batchが3テーブル管理:

Table 主要フィールド 説明
specific_viewpoints viewpoint_category_id, last_object_id SPVP進捗追跡
viewpoint_categories category_name, description SPVPカテゴリ定義
review_sentence_spvp sentence_id, viewpoint_ordinal_number, mall_product_id, viewpoint_category_id Specific Viewpoint ↔ Sentenceマッピング

詳細データ変更

フェーズ1: Wishlist作成 (trend-viewer-api → gb_console)

-- メインwishlist作成
INSERT INTO gb_console.wishlist_to_groups (
    name, group_id, subscription_id, 
    status = 1 -- 1 | Active
);

-- クロールアイテム保存 - Products
INSERT INTO gb_console.summary_wishlist_products (
    wishlist_to_group_id, input, input_type, mall_id,
    crawl_status = 0 -- 0 | New
);

-- クロールアイテム保存 - Product Reviews
INSERT INTO gb_console.summary_wishlist_product_reviews (
    summary_wishlist_product_id, schedule_id,
    crawl_status = 0 -- 0 | New
);

-- クロールアイテム保存 - Categories
INSERT INTO gb_console.summary_wishlist_categories (
    category_id, mall_id, wishlist_to_group_id,
    crawl_status = 0 -- 0 | New
);

-- クロールアイテム保存 - Search Queries
INSERT INTO gb_console.summary_wishlist_search_queries (
    keyword, mall_id, wishlist_to_group_id,
    crawl_status = 0 -- 0 | New
);

フェーズ2: データクローリング (trend-viewer-backend → Crawler Service → analyzer_v2)

-- 全summary tablesのクロールステータス更新
UPDATE gb_console.summary_wishlist_products 
SET crawl_status = 1 -- 1 | InProgress
WHERE crawl_status = 0;

UPDATE gb_console.summary_wishlist_product_reviews 
SET crawl_status = 1 -- 1 | InProgress
WHERE crawl_status = 0;

UPDATE gb_console.summary_wishlist_categories 
SET crawl_status = 1 -- 1 | InProgress
WHERE crawl_status = 0;

UPDATE gb_console.summary_wishlist_search_queries 
SET crawl_status = 1 -- 1 | InProgress
WHERE crawl_status = 0;

-- Crawler Serviceからの生データ - Products & Reviews
INSERT INTO analyzer_v2.products (name, description, price, mall_id);
INSERT INTO analyzer_v2.reviews (product_id, content, rating);
INSERT INTO analyzer_v2.review_sentences (review_id, sentence, embedding);

-- 全summary tablesのクロール完了
UPDATE gb_console.summary_wishlist_*
SET crawl_status = 2 -- 2 | Success
WHERE crawl_completed;

フェーズ3: Dataset作成 (trend-viewer-backend → ds_analyzer)

-- datasetメタデータ作成
INSERT INTO ds_analyzer.datasets (
    name, group_id, viewpoint_category_id,
    status = 1, -- 1 | Pending
    progress = 0,
    settings = JSON_OBJECT('product_ids', [...])
);

-- 履歴レコード作成
INSERT INTO gb_console.wishlist_dataset_histories (
    wishlist_to_group_id, dataset_id,
    status = 1, -- 1 | Pending
    spvp_status = 1 -- 1 | Pending
);

フェーズ4: ML分析 (analyzer_batch → ds_analyzer)

-- 進捗更新
UPDATE ds_analyzer.datasets 
SET status = 2, progress = 50 -- 2 | Processing
WHERE id = dataset_id;

-- analyzer_batchが7テーブル完全作成
-- 1. Products & Details
INSERT INTO ds_analyzer.products (dataset_id, crawler_product_id, processed_name);
INSERT INTO ds_analyzer.product_details (product_id, specifications, metadata);

-- 2. 商品類似度  
INSERT INTO ds_analyzer.product_similarities (dataset_id, mall_product_id_a, product_id_2, similarity_score);

-- 3. AI Viewpoints & クラスタリング
INSERT INTO ds_analyzer.ai_viewpoints (dataset_id, cluster_id, name, description);
INSERT INTO ds_analyzer.review_sentence_aivp (
    sentence_id, 
    dataset_id,
    ai_viewpoint_id, 
    mall_product_id,
    created_at = NOW()
);

-- 4. センチメント分析付きReviews & Sentences
INSERT INTO ds_analyzer.reviews (dataset_id, product_id, sentiment_overall);
INSERT INTO ds_analyzer.review_sentences (dataset_id, ai_viewpoint_id, cluster_id, is_noise);

-- 分析完了
UPDATE ds_analyzer.datasets 
SET status = 3, progress = 100 -- 3 | Completed
WHERE id = dataset_id;

-- ステータス同期
UPDATE gb_console.wishlist_dataset_histories 
SET status = 3, spvp_status = 2 -- 2 | Analyzing (SPVP)
WHERE dataset_id = dataset_id;

フェーズ5: SPVP処理 (spvp_batch → ds_analyzer)

-- SPVP処理用データロード
SELECT * FROM ds_analyzer.review_sentences WHERE dataset_id = ?;
SELECT * FROM ds_analyzer.specific_viewpoints WHERE viewpoint_category_id = ?;
SELECT * FROM ds_analyzer.viewpoint_categories WHERE id = ?;

-- Qwenマッピングプロセス: specific_viewpoints ↔ review_sentences
-- マッピング結果保存
INSERT INTO ds_analyzer.review_sentence_spvp (
    sentence_id, 
    viewpoint_ordinal_number, 
    mall_product_id,
    viewpoint_category_id
);

-- 進捗追跡更新
UPDATE ds_analyzer.specific_viewpoints 
SET last_object_id = max_processed_sentence_id
WHERE viewpoint_category_id = dataset_viewpoint_category;

-- SPVP完了確認
UPDATE gb_console.wishlist_dataset_histories 
SET spvp_status = 3 -- 3 | Completed
WHERE dataset_id = dataset_id 
  AND all_specific_viewpoints_processed();

サービス責任

trend-viewer-api

  • 作成: gb_console.wishlist_to_groups, gb_console.summary_wishlist_*
  • 更新: ユーザー向け操作のステータスフィールド

trend-viewer-backend

  • 作成: ds_analyzer.datasets, gb_console.wishlist_dataset_histories
  • 更新: クロールステータス同期、datasetステータス監視
  • トリガー: analyzer_batch, spvp_batch
  • スケジュールされたクロール管理
  • Dataset作成ロジック
  • ステータス同期

Crawler Service

  • 作成: analyzer_v2.products, analyzer_v2.reviews, analyzer_v2.review_sentences
  • 連携: embedding/predictionのためのPLG API

analyzer_batch

  • 読み取り: analyzer_v2.* tables (products, reviews, review_sentences)
  • 作成: ds_analyzerの7テーブル:
    • products - 処理済みデータを持つDataset商品
    • product_details - 商品仕様・メタデータ
    • product_similarities - 商品類似度マトリックス
    • ai_viewpoints - AI生成クラスターラベル
    • review_sentence_aivp - AI Viewpoint ↔ Sentenceマッピング
    • reviews - センチメント分析付きDataset reviews
    • review_sentences - クラスター化review sentences
  • 更新: ds_analyzer.datasets (status, progress)
  • 処理: MLクラスタリング (K-means), AIラベリング (OpenAI GPT-4), 商品類似度計算, センチメント分析
  • アーキテクチャ: 分散トランザクションでのデータ書き込み

spvp_batch

  • 読み取り: ds_analyzer.review_sentences, ds_analyzer.specific_viewpoints, ds_analyzer.viewpoint_categories
  • 作成: ds_analyzer.review_sentence_spvp (sentence-viewpointマッピング)
  • 更新: ds_analyzer.specific_viewpoints (last_object_id), gb_console.wishlist_dataset_histories (spvp_status)
  • Qwenベースsentenceからspecific viewpointへのマッピング
  • last_object_idによる進捗追跡
  • 最終完了ステータス更新

PLG API

  • Embeddingステータス確認
  • Prediction準備状況検証
  • Crawler service連携

重要ステータスフィールド

Datasetライフサイクルステータス

-- trend-viewer-backendがdataset作成
ds_analyzer.datasets.status = 1 | Pending

-- analyzer_batch処理  
ds_analyzer.datasets.status = 2 | Processing
ds_analyzer.datasets.progress = 0 → 100

-- analyzer_batch完了
ds_analyzer.datasets.status = 3 | Completed

-- gb_consoleへのステータス同期
gb_console.wishlist_dataset_histories.status = 3 | Complete
gb_console.wishlist_dataset_histories.spvp_status = 2 | Analyzing

-- spvp_batch完了
gb_console.wishlist_dataset_histories.spvp_status = 3 | Completed

エラー追跡

-- analyzer_batchエラー
ds_analyzer.datasets.status = 9 | Failed
ds_analyzer.datasets.error_code = 1001-3003
ds_analyzer.datasets.progress = -1

ステータス値リファレンス

Dataset Status (ds_analyzer.datasets.status)

  • 1 | Pending: trend-viewer-backendがdataset作成、analyzer_batch待機中
  • 2 | Processing: analyzer_batch処理中
  • 3 | Completed: analyzer_batch完了
  • 9 | Failed: analyzer_batch失敗

SPVP Status (gb_console.wishlist_dataset_histories.spvp_status)

  • 1 | Pending: spvp_batch待機中
  • 2 | Analyzing: spvp_batch処理中
  • 3 | Completed: spvp_batch完了
  • 9 | Failed: spvp_batch失敗

Crawl Status (gb_console.summary_wishlist_*.crawl_status)

  • 0 | New: 未クロール、trend-viewer-backendスケジュール待ち
  • 1 | InProgress: Crawler Serviceクロール中
  • 2 | Success: Crawler Serviceクロール成功
  • 3 | Error: Crawler Serviceクロール失敗
  • 4 | Canceled: クロールキャンセル

サービス別エラー復旧

trend-viewer-backend

  • クロール同期失敗: スケジュールされたジョブでの自動リトライ
  • Dataset作成失敗: 手動トリガー可能
  • ステータス同期問題: 調整ジョブ

analyzer_batch

  • 処理失敗: 完全ロールバック、error_code追跡
  • リソース問題: コンテナ再起動、スケーリング
  • OpenAI API失敗: バックオフでリトライ

spvp_batch

  • 処理スタック: 手動last_object_idリセット
  • 完了検出失敗: 手動ステータス更新

関連ドキュメント

コアワークフローコンポーネント

関連システムドキュメント

バックエンドサービスドキュメント

  • trend-viewer-backendドキュメント - 完全なバックエンドドキュメント
    • Dataset Commands: link - データセット管理用コンソールコマンド
    • Crawler Integration: link - PLG API統合の詳細

Processing Services（ドキュメント開発中）

  • analyzer_batch: Python ML/AI処理サービス
    • 機能: MLクラスタリング、AIラベリング、製品類似性分析
  • spvp_batch: Python Qwenベース特定観点処理サービス
    • 機能: SPVPマッピング、Qwenモデル統合、進捗追跡