docs/specs/html-preview/iframe-section-alignment.md

HTML プレビュー・セクション管理システム設計書

1. 概要

改善案生成結果の HTML プレビュー機能において、セクションの可視性制御、順序管理、iframe 内表示、位置同期を統合的に管理するシステムの設計仕様。

2. システムアーキテクチャ

2.1 4層アーキテクチャ構成

graph TB
    A[セクション管理レイヤー<br/>useSectionManager] --> B[HTML生成・表示レイヤー<br/>TabContentRenderer]
    B --> C[位置同期レイヤー<br/>usePreciseSectionAlignment]
    B --> D[スクロール制御レイヤー<br/>handleSectionClick]

    E[Zustand Store] --> A
    F[ContentSection[]] --> A
    G[FV/CN HTML Generation] --> B
    H[iframe Display] --> B
    I[Environment Variables] --> C

2.2 レイヤー間の責任分離

レイヤー	責任	主要機能
セクション管理	セクション状態の管理	可視性制御、順序管理、永続化
HTML生成・表示	UI統合とHTML生成	FV/CN HTML生成、iframe表示、ダウンロード
位置同期	iframe内位置同期	セクション位置測定、カード位置計算
スクロール制御	ユーザー操作対応	セクションクリック、スムーズスクロール

3. セクション管理レイヤー仕様

3.1 useSectionManager の機能

3.1.1 型定義

interface SectionVisibility {
  [key: string]: {
    visible: boolean;   // セクションの表示/非表示
    order: number;      // セクションの表示順序
  };
}

interface UseSectionManagerReturn {
  sectionVisibility: SectionVisibility;
  handleSectionVisibility: (key: string) => void;
  handleSectionOrder: (key: string, direction: 'asc' | 'desc') => void;
  filterAndSortSections: (sections: ContentSection[]) => ContentSection[];
  getSectionInfoForDropdown: (sections: ContentSection[]) => SectionInfo[];
  resetSectionVisibility: () => void;
  hasChanges: boolean;
}

3.1.2 状態管理の仕組み

• キー形式: ${section.大区分}-${section.中区分}
• 初期状態: 全セクション visible: true, order: インデックス順
• 永続化: Zustand store でタブ間状態保持
• 変更検知: 初期状態と現在状態の diff による hasChanges 判定

3.1.3 主要機能

// セクション可視性の切り替え
handleSectionVisibility('ヘッダー-メインビジュアル');

// セクション順序の変更
handleSectionOrder('コンテンツ-商品紹介', 'asc');

// 可視セクションのフィルタリング・ソート
const visibleSections = filterAndSortSections(allSections);

// 初期状態にリセット
resetSectionVisibility();

4. HTML生成・表示レイヤー仕様

4.1 TabContentRenderer の責任

4.1.1 統合制御機能

• セクション管理統合: useSectionManager の呼び出しと状態管理
• HTML生成制御: FV/CN HTML生成の条件判定と実行
• iframe表示制御: 生成されたHTMLのiframe表示
• ダウンロード機能: 画像・コードダウンロードの実装

4.1.2 生成条件の制御

// HTML生成の有効化条件
const htmlGenerationEnabled = React.useMemo(() => {
  const hasMinimalData = hasFvData && hasCnData;

  if (dummyMode) {
    return hasScreenshot && hasMinimalData;
  } else if (generateAllTabs) {
    return hasScreenshot && hasMinimalData;
  } else {
    return hasScreenshot && hasMinimalData;
  }
}, [dummyMode, generateAllTabs, hasScreenshot, hasFvData, hasCnData]);

4.1.3 モード別動作

• ダミーモード: 事前生成されたダミーHTML/画像を使用
• 全タブ生成モード: 全タブで一括HTML生成
• 通常モード: アクティブタブのみHTML生成

5. 位置同期レイヤー仕様

5.1 usePreciseSectionAlignment の機能

5.1.1 環境制御

// 環境変数による機能制御
const isAlignmentFeatureEnabled = process.env.NEXT_PUBLIC_ENABLE_SECTION_ALIGNMENT === 'true';
const alignmentEnabled = isAlignmentFeatureEnabled && isActive && !!tabCnData && tabCnData.length > 0;

5.1.2 位置同期アルゴリズム

• 測定: iframe内セクション要素の位置・サイズ測定
• 計算: セクションとカードの位置対応計算
• 同期: transform: translateY による位置調整

5.1.3 観測機能

• MutationObserver: iframe内DOM構造変更の監視
• ResizeObserver: セクションサイズ変更の監視
• デバウンス処理: 150ms のデバウンスで性能最適化

6. スクロール制御レイヤー仕様

6.1 handleSectionClick の動作

6.1.1 セクション検索アルゴリズム

const searchMethods = [
  () => iframeDoc.querySelector(`[data-section-key="${sectionKey}"]`),
  () => iframeDoc.querySelector(`[aria-label="${sectionKey}"]`),
  () => iframeDoc.querySelector(`[aria-label*="${sectionKey}"]`),
  // 複数のフォールバック手法...
];

6.1.2 スクロール位置計算

// 最終スクロール位置の計算
const iframeRect = iframe.getBoundingClientRect();
const finalScrollTop = window.scrollY + iframeRect.top + sectionOffsetTop - 36; // sticky tab height

window.scrollTo({
  top: Math.max(0, finalScrollTop),
  behavior: 'smooth',
});

7. データフローと状態管理

7.1 データフロー

ContentSection[]
  ↓
useSectionManager (状態管理)
  ↓
TabContentRenderer (UI統合)
  ↓
[並行処理]
  ├─ HTML生成 → iframe表示
  ├─ 位置同期 (usePreciseSectionAlignment)
  └─ スクロール制御 (handleSectionClick)

7.2 状態永続化

• 保存場所: Zustand store
• 保存単位: タブ名単位での状態管理
• 保存内容: sectionVisibility オブジェクト
• 復元タイミング: タブ切り替え時の自動復元

7.3 変更検知システム

const checkHasChanges = (current: SectionVisibility, initial: SectionVisibility) => {
  // 可視性変更の検知
  if (current[key].visible !== initial[key].visible) return true;

  // 順序変更の検知
  if (current[key].order !== initial[key].order) return true;

  return false;
};

8. 環境設定と制御

8.1 環境変数による機能制御

• NEXT_PUBLIC_ENABLE_SECTION_ALIGNMENT: 位置同期機能の有効/無効
• 各生成モードの制御: dummyMode, generateAllTabs

8.2 条件分岐による最適化

• ローカル環境: 画像生成をスキップ（RateLimit回避）
• ダミーモード: 事前生成データの使用
• デプロイ環境: 全機能の有効化

9. パフォーマンス仕様

9.1 応答性能

• 状態更新: デバウンス 150ms
• HTML生成: 非同期処理による UI ブロック回避
• 位置同期: リアルタイム更新（有効時のみ）
• スクロール: smooth behavior による自然な動作

9.2 メモリ効率

• Observer: 必要時のみアクティブ化
• 状態管理: 必要最小限のデータ保持
• HTML: ミニファイ化された軽量コンテンツ

10. エラーハンドリング

10.1 段階的フォールバック

// セクション検索の段階的フォールバック
for (let i = 0; i < searchMethods.length; i++) {
  try {
    targetElement = searchMethods[i]();
    if (targetElement) break;
  } catch (error) {
    console.log(`Search method ${i + 1} failed:`, error);
  }
}

10.2 エラー時の安全な動作

• セクション未発見: iframe先頭への安全なスクロール
• HTML生成失敗: エラー表示とリトライ機能
• 位置同期失敗: デフォルト表示への自動フォールバック

11. 実装のポイント

11.1 責任分離の徹底

• セクション管理: 完全に独立したレイヤー
• HTML生成: 非同期処理による分離
• 位置同期: 環境変数による任意機能
• スクロール制御: ユーザー操作への専念

11.2 拡張性の確保

• モジュラー設計: 各レイヤーの独立性
• 設定可能: 環境変数による柔軟な制御
• フォールバック: 段階的な機能劣化

11.3 デバッグ支援

• 詳細ログ: 各段階での状態出力
• 段階的検索: 複数手法による要素発見
• 状態可視化: hasChanges による変更状態の明示

12. 今後の発展可能性

12.1 機能拡張

• セクション編集: インライン編集機能
• プレビュー強化: リアルタイムプレビュー
• エクスポート拡張: 多形式対応

12.2 性能改善

• 仮想化: 大量セクションの効率的表示
• キャッシュ: 生成結果のインテリジェントキャッシュ
• 並列化: 生成処理の更なる並列化