Hugging Face's logo

Spaces:
KazukiWatanabe
/
FE_Dev
Sleeping

App Files Community
FE_Dev / docs /specs /html-preview /requirements.md
GitHub Actions
Deploy from GitHub Actions [dev] - 2025-10-31 07:28:50
68f7925
preview code
|
raw
history blame contribute delete
7.31 kB

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 データフロー 

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フックの共通設定を提供
  • 主要設定:
    {
  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テスト結果の自動反映
  • 機械学習モデルの継続的改善