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. 基本フロー

```mermaid
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. 依存関係

```mermaid
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. キャッシュキー構造

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

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

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

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

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

**Prediction/Intentの実行制御**:
```typescript
// lastFetchedSelectionHashRefで追跡
const canStartPredictionIntent =
  proposalFv.isSuccess &&
  proposalCn.isSuccess &&
  lastFetchedSelectionHashRef.current === selectionHash;
```

## 再フェッチ条件

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

```mermaid
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. キャッシュライフサイクル

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

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

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

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

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

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

**Prediction/Intent実行制御**:
```typescript
// selectionHashが変わった時の新しいFV/CNデータであることを確認
const canStartPredictionIntent =
  proposalFv.isSuccess &&
  proposalCn.isSuccess &&
  lastFetchedSelectionHash === selectionHash;
```

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

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

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

## エラーハンドリング

### 1. 自動リトライ

```typescript
// 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` | トリガー管理とハッシュ生成 |

## 使用例

```typescript
// 改善案画面での使用
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の実行条件を厳密化
  - 不要な再フェッチを防止