Spaces:
Sleeping
Sleeping
| # 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テスト結果の自動反映 | |
| - 機械学習モデルの継続的改善 |