# HTML生成システム要件定義書

## 1. 概要

本システムは、マーケティング改善提案を自動生成し、HTML形式でプレビュー表示するシステムである。
各改善案（A案〜I案）に対して、FV（ファーストビュー）画像とコンテンツHTMLを生成し、タブ形式で表示する。

## 2. ユーザーストーリー

### 2.1 改善案の生成と表示
**As a** マーケティング担当者
**I want to** 複数の改善案を自動生成して比較検討したい
**So that** 最適な施策を選択できる

#### 受け入れ条件
- [ ] 9つの改善案（A案〜I案）が生成される
- [ ] 各案のFV画像とコンテンツHTMLが表示される
- [ ] タブで各案を切り替えて閲覧できる
- [ ] 予測値の高い順に案が並んでいる

### 2.2 パフォーマンスの最適化
**As a** システム利用者
**I want to** 快適な操作レスポンスでシステムを利用したい
**So that** 効率的に作業を進められる

#### 受け入れ条件
- [ ] タブ切り替え時に画像が再生成されない
- [ ] ウィンドウフォーカス時に不要なAPI呼び出しが発生しない
- [ ] 一度生成された画像はキャッシュから表示される
- [ ] ページリロードしても24時間はキャッシュが有効

### 2.3 改善案の再生成
**As a** マーケティング担当者
**I want to** 選択条件を変更して新しい改善案を生成したい
**So that** 異なる観点から施策を検討できる

#### 受け入れ条件
- [ ] /refresh-moments画面で選択を変更できる
- [ ] 選択変更後は新しい改善案が生成される
- [ ] 前回と異なるデータで正しく再生成される

## 3. ビジネス要件

### 3.1 改善案の優先順位管理

#### 3.1.1 予測値による並び替え
- **要件ID**: BR-001
- **優先度**: 高
- **説明**: 改善案は機械学習モデルによる予測値（prediction）の降順で並び替えられる
- **詳細**:
  - 予測値は0〜1の範囲の数値
  - 値が高いほど改善効果が期待できる
  - 同一予測値の場合は戦略順（積極化→改善→差別化）で決定

#### 3.1.2 タブラベルの維持
- **要件ID**: BR-002
- **優先度**: 中
- **説明**: 予測値順に並び替えても、表示ラベルはA案〜I案を維持
- **詳細**:
  - 最も予測値の高い案がA案として表示
  - 9番目に高い案がI案として表示
  - ユーザーは予測値の高い順であることを認識できる

### 3.2 パフォーマンス要件

#### 3.2.1 API呼び出しの最適化
- **要件ID**: BR-003
- **優先度**: 高
- **説明**: 不要なAPI呼び出しを削減し、システム負荷を軽減
- **詳細**:
  - ウィンドウフォーカス時の再フェッチを無効化
  - コンポーネント再マウント時の再フェッチを無効化
  - 同一データでの重複実行を防止

#### 3.2.2 キャッシュ管理
- **要件ID**: BR-004
- **優先度**: 中
- **説明**: 生成済みデータを効率的にキャッシュ
- **詳細**:
  - staleTime: Infinity（データは古くならない）
  - gcTime: 24時間（ガベージコレクション）
  - queryKeyベースのキャッシュ管理

### 3.3 データ生成要件

#### 3.3.1 FV画像生成
- **要件ID**: BR-005
- **優先度**: 高
- **説明**: 各改善案のファーストビュー画像を生成
- **詳細**:
  - OpenAI/Gemini APIを使用
  - スクリーンショットを基に画像を編集
  - タブごとに1回だけ生成（同一セッション内）

#### 3.3.2 コンテンツHTML生成
- **要件ID**: BR-006
- **優先度**: 高
- **説明**: 各改善案のコンテンツセクションHTMLを生成
- **詳細**:
  - セクションごとにHTMLを構築
  - Adobe Fireflyで画像生成（オプション）
  - プレースホルダー画像の自動置換

## 4. 技術仕様

### 4.1 アーキテクチャ

#### 4.1.1 フロントエンド
- **フレームワーク**: Next.js (App Router)
- **状態管理**: Zustand
- **データフェッチング**: React Query (TanStack Query)
- **スタイリング**: Tailwind CSS

#### 4.1.2 API層
- **内部API**: Next.js API Routes
- **外部API**:
  - Gradio API（提案データ取得）
  - OpenAI API（画像生成）
  - Gemini API（画像生成）
  - Adobe Firefly API（コンテンツ画像）

### 4.2 データフロー

```mermaid
graph TD
    A[ユーザー選択] --> B[Gradio API]
    B --> C[提案データ取得]
    C --> D[ProposalTranslator]
    D --> E[予測値でソート]
    E --> F[タブデータ生成]
    F --> G[TabContentRenderer]
    G --> H[FV HTML生成]
    G --> I[Contents HTML生成]
    H --> J[画像表示]
    I --> J
```

### 4.3 キー・コンポーネント

#### 4.3.1 React Query設定
- **ファイル**: `api-client/query-config.ts`
- **責務**: 全APIフックの共通設定を提供
- **主要設定**:
  ```typescript
  {
    refetchOnWindowFocus: false,
    refetchOnMount: false,
    staleTime: Infinity,
    gcTime: 24 * 60 * 60 * 1000
  }
  ```

#### 4.3.2 タブコンテンツレンダラー
- **ファイル**: `components/improvement-result/tab-content-renderer.tsx`
- **責務**: 各タブのコンテンツ生成と表示制御
- **主要機能**:
  - 初回生成フラグ管理（useRef）
  - 条件付きレンダリング
  - キャッシュ制御

#### 4.3.3 提案データ変換
- **ファイル**: `api-client/proposal/proposal/translator.ts`
- **責務**: APIレスポンスを表示用データに変換
- **主要機能**:
  - 予測値によるソート
  - タブラベル割り当て
  - データ正規化

## 5. 制約事項

### 5.1 技術的制約
- React Query v5を使用
- Node.js 18以上が必要
- ブラウザはChrome/Firefox/Safari/Edgeの最新版をサポート

### 5.2 ビジネス制約
- 改善案は必ず9案生成される
- 予測値は0〜1の範囲に正規化される
- ダミーモードでも正常動作が必要

## 6. 非機能要件

### 6.1 パフォーマンス
- タブ切り替え: 100ms以内でレスポンス
- 画像生成: 各タブ30秒以内で完了
- キャッシュヒット率: 90%以上

### 6.2 可用性
- システム稼働率: 99.5%以上
- エラー発生時のフォールバック機能
- ダミーモードでの継続動作

### 6.3 保守性
- TypeScriptによる型安全性
- ESLint/Prettierによるコード品質維持
- 包括的なログ出力

## 7. リスクと対策

### 7.1 API制限
- **リスク**: 外部APIのレート制限
- **対策**:
  - ローカル環境では画像生成をスキップ
  - キャッシュを積極的に活用
  - リトライ処理の実装

### 7.2 パフォーマンス劣化
- **リスク**: 大量データによる処理遅延
- **対策**:
  - 非同期バッチ処理
  - プログレッシブレンダリング
  - 遅延ローディング

## 8. 今後の拡張性

### 8.1 短期的拡張
- 改善案数の動的変更（9案→12案など）
- 新しいAIプロバイダーの追加
- カスタムソート条件の追加

### 8.2 長期的拡張
- リアルタイム協業機能
- A/Bテスト結果の自動反映
- 機械学習モデルの継続的改善