docs/specs/html-preview/fetch-gradio-sequence.md

Gradio API フェッチシーケンス仕様書

概要

本ドキュメントは、改善案生成画面におけるGradio APIの呼び出しシーケンス、キャッシュ管理、および再フェッチ戦略について定義します。

アーキテクチャ概要

主要コンポーネント

1. useProposalTabsOptimized - 統合クエリ管理フック
2. 個別クエリフック
   • useThemeByMomentOptimized
   • useProposalFv
   • useProposalCn
   • useProposalPrediction
   • useProposalIntent
3. キャッシュ管理 - Tanstack Query + MD5ハッシュベースキー

API呼び出しシーケンス

1. 基本フロー

sequenceDiagram
    participant User
    participant Component
    participant ThemeByMoment
    participant FV
    participant CN
    participant Prediction
    participant Intent

    User->>Component: 改善案画面を開く
    Component->>ThemeByMoment: ①テーマ取得
    ThemeByMoment-->>Component: strategy_x_moment返却

    par 並列実行
        Component->>FV: ②FV提案取得
        Component->>CN: ②CN提案取得
    end

    FV-->>Component: FVデータ
    CN-->>Component: CNデータ

    par 並列実行
        Component->>Prediction: ③予測取得(FV+CNデータ利用)
        Component->>Intent: ③インテント取得(FV+CNデータ利用)
    end

    Prediction-->>Component: 予測データ
    Intent-->>Component: インテントデータ
    Component-->>User: 改善案表示

2. 依存関係

graph TD
    A[ThemeByMoment] --> B[strategy_x_moment]
    B --> C[ProposalFv]
    B --> D[ProposalCn]
    C --> E[ProposalPrediction]
    D --> E
    C --> F[ProposalIntent]
    D --> F

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#9ff,stroke:#333,stroke-width:2px
    style F fill:#9ff,stroke:#333,stroke-width:2px

キャッシュキー設計

1. キャッシュキー構造

// 基本構造（選択データに依存するAPI）
[apiName, selectionHash]

// 具体例
['themeByMoment', 'abc123...']                    // selectionに依存
['proposalFv', 'abc123...']                       // selectionに依存
['proposalCn', 'abc123...']                       // selectionに依存
['proposalPrediction', 'abc123...']               // selectionに依存
['proposalIntent', 'abc123...']                   // selectionに依存

2. ハッシュ生成ロジック

// 選択データのハッシュ（全API共通）
selectionHash = MD5({
  selectedMoments,
  fvInfos,
  cnInfo
})

重要な設計原則:

• 全てのAPIでselectionHashのみをキャッシュキーに使用
• triggerVersionはキャッシュキーに含めない（確定ボタンを押しても再フェッチしない）
• Prediction/IntentもFV/CNデータハッシュではなくselectionHashを使用
• FV/CNの値が更新されても、同じ選択肢なら再フェッチしない

Prediction/Intentの実行制御:

// lastFetchedSelectionHashRefで追跡
const canStartPredictionIntent =
  proposalFv.isSuccess &&
  proposalCn.isSuccess &&
  lastFetchedSelectionHashRef.current === selectionHash;

再フェッチ条件

1. 自動再フェッチトリガー

flowchart TD
    Start([開始])

    TriggerChange{triggerVersion<br/>変更?}
    SelectionChange{選択データ<br/>変更?}
    FvCnChange{FV/CNデータ<br/>変更?}

    ClearOldCache[古いキャッシュクリア]
    RefetchAll[全API再実行]
    RefetchPredIntent[Prediction/Intent<br/>のみ再実行]

    Start --> TriggerChange
    Start --> SelectionChange
    Start --> FvCnChange

    TriggerChange -->|Yes| ClearOldCache
    SelectionChange -->|Yes| ClearOldCache
    ClearOldCache --> RefetchAll

    FvCnChange -->|Yes| RefetchPredIntent

    TriggerChange -->|No| End([終了])
    SelectionChange -->|No| End
    FvCnChange -->|No| End

2. 再フェッチ条件詳細

トリガー	影響範囲	説明
selectionHash変更	全API	選択モーメント/FV情報が変わった時
FV/CN成功後	Prediction/Intentが実行	selectionHashが同じ場合は実行されない
エラー時自動リトライ	該当APIのみ	2秒後に自動リトライ（最大2回）

重要な変更点:

• triggerVersion（確定ボタン）での再フェッチを廃止
• Prediction/IntentはselectionHashが変わった時のみ、新しいFV/CNデータで実行
• selectionHashが同じ場合、FV/CNが更新されてもPrediction/Intentは再実行しない

キャッシュ管理戦略

1. キャッシュライフサイクル

stateDiagram-v2
    [*] --> Fresh: 初回フェッチ
    Fresh --> Stale: staleTime経過(30分)
    Stale --> Fresh: 再フェッチ
    Stale --> Garbage: gcTime経過(60分)
    Garbage --> [*]: メモリから削除

    Fresh --> Canceled: キャンセル
    Stale --> Canceled: キャンセル
    Canceled --> [*]: 即削除

2. キャッシュキーによる自動管理

重要: selectionHashのみでキャッシュを管理、triggerVersionは使用しない

// 全APIで統一されたキャッシュキー構造
const cacheKey = [
  'apiName',
  selectionHash      // 選択データ変更時のみ新しいキーになる
];

// 例
['proposalFv', 'abc123...']
['proposalCn', 'abc123...']
['proposalPrediction', 'abc123...']
['proposalIntent', 'abc123...']

Prediction/Intent実行制御:

// selectionHashが変わった時の新しいFV/CNデータであることを確認
const canStartPredictionIntent =
  proposalFv.isSuccess &&
  proposalCn.isSuccess &&
  lastFetchedSelectionHash === selectionHash;

3. 最適化されたクリーンアップ

// コンポーネントアンマウント時のみ実行中クエリをキャンセル
useEffect(() => {
  return () => {
    // アクティブなクエリをキャンセル（ネットワーク負荷軽減）
    queryClient.cancelQueries({ queryKey: 現在のキー });
  };
}, []);

// 古いキャッシュはgcTimeで自動削除（明示的削除は不要）

エラーハンドリング

1. 自動リトライ

// Prediction/Intentは自動リトライ
useEffect(() => {
  if (proposalPrediction.isError && !proposalPrediction.isFetching) {
    setTimeout(() => {
      proposalPrediction.refetch();
    }, 2000); // 2秒後
  }
}, [proposalPrediction]);

2. 部分的失敗の処理

• 各APIは独立して管理
• 失敗したAPIのみ再実行可能
• 他のAPIの成功データは保持

パフォーマンス最適化

1. 並列実行

• FV/CNは並列実行
• Prediction/Intentも並列実行
• 依存関係がないAPIは同時実行

2. キャッシュ共有

• 同一キーのデータはタブ間で共有
• staleTime: 30分（データ新鮮期間）
• gcTime: 60分（ガベージコレクション）

3. 不要なフェッチの防止

• ダミーモードではThemeByMomentをスキップ
• enabledフラグで条件付き実行
• キャッシュヒット時は再フェッチしない

実装ファイル

ファイル	役割
/api-client/proposal/proposal/optimized-queries.ts	統合クエリ管理
/api-client/proposal/proposal/individual-queries.ts	個別クエリフック
/services/gradio-with-dummy.ts	API呼び出し関数
/store/proposal-trigger.ts	トリガー管理とハッシュ生成

使用例

// 改善案画面での使用
const {
  data: proposalTabsData,
  rawData: proposalRawData,
  isLoading,
  isError,
  refetch,
  refetchAll
} = useProposalTabsOptimized({
  strategy_x_moment: strategyXMoment,
  enabled: selectedMoments.length > 0,
  dummyMode: isDummyMode,
});

注意事項

1. キャッシュキーの一意性

   • MD5ハッシュで一意性を保証
   • データ変更時は必ず新しいキーになる

2. メモリ管理

   • アンマウント時にクエリをキャンセル
   • 古いキャッシュは自動削除

3. エラー処理

   • 部分的な失敗に対応
   • 自動リトライ機能付き

更新履歴

• 2024-01-21: 初版作成

  • 個別API管理の実装
  • MD5ハッシュベースのキャッシュキー
  • 依存関係に基づく自動再フェッチ

• 2024-01-22: キャッシュキー最適化

  • triggerVersionをキャッシュキーから削除
  • selectionHashのみでキャッシュ管理
  • Prediction/Intentの実行条件を厳密化
  • 不要な再フェッチを防止