# 機能設計書 89-フィーチャーフラグ

## 概要

本ドキュメントは、Giselleプラットフォームにおける機能フラグ管理システムの設計を定義する。フィーチャーフラグは、React Contextを使用して機能の有効/無効を管理し、新機能のリリース制御やA/Bテストを可能にする。

### 本機能の処理概要

**業務上の目的・背景**：新機能の段階的リリース、実験的機能の制御、ユーザーセグメント別の機能提供など、柔軟な機能制御が必要となる。フィーチャーフラグシステムは、サーバー側で設定されたフラグ値をReactコンポーネントに提供し、条件付きレンダリングや機能制御を可能にする。

**機能の利用シーン**：
- 新機能（AIゲートウェイ、構造化出力等）の段階的リリース
- 実験的機能（Web検索アクション等）の制御
- レイアウトバージョンの切り替え
- 開発中の機能の保護

**主要な処理内容**：
1. FeatureFlagContextValue: フラグ値のインターフェース定義
2. FeatureFlagContext: React Contextの作成
3. useFeatureFlag: フラグ値を取得するカスタムフック
4. WorkspaceProviderでのフラグ値の注入

**関連システム・外部連携**：
- React Context API
- Vercel Edge Config（本番環境でのフラグ管理）
- 環境変数（開発環境でのフラグ管理）

**権限による制御**：フラグの設定は管理者のみ可能。フラグの参照はすべてのユーザーが可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主機能 | フラグに基づく機能の表示/非表示制御 |

## 機能種別

設定管理 / 機能制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| webSearchAction | boolean | No | Web検索アクション機能の有効化 | - |
| layoutV3 | boolean | No | レイアウトV3の有効化 | - |
| stage | boolean | No | ステージ機能の有効化 | - |
| aiGateway | boolean | No | AIゲートウェイ機能の有効化 | - |
| aiGatewayUnsupportedModels | boolean | No | 未サポートモデルの許可 | - |
| googleUrlContext | boolean | No | Google URLコンテキストの有効化 | - |
| generateContentNode | boolean | No | コンテンツ生成ノードの有効化 | - |
| privatePreviewTools | boolean | No | プライベートプレビューツールの有効化 | - |
| dataStore | boolean | No | データストア機能の有効化 | - |
| sdkAvailability | boolean | No | SDK利用可能性の表示 | - |
| structuredOutput | boolean | No | 構造化出力機能の有効化 | - |

### 入力データソース

- WorkspaceProvider propsからの注入
- サーバー側のフラグ設定（Edge Config / 環境変数）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FeatureFlagContextValue | object | すべてのフラグ値を含むオブジェクト |

### 出力先

- Reactコンポーネントへの状態提供（useFeatureFlagフック経由）

## 処理フロー

### 処理シーケンス

```
1. サーバー側でフラグ値を決定
   └─ Edge Config または環境変数から取得
2. WorkspaceProviderにフラグ値を渡す
   └─ data-loaderで取得したフラグをpropsとして渡す
3. FeatureFlagContextにフラグ値を設定
   └─ デフォルト値とマージ
4. コンポーネントでフラグを参照
   └─ useFeatureFlag()でフラグ値を取得
5. 条件付きレンダリング
   └─ フラグ値に基づいてUIを制御
```

### フローチャート

```mermaid
flowchart TD
    A[サーバー側フラグ設定] --> B{環境判定}
    B -->|開発| C[環境変数から取得]
    B -->|本番| D[Edge Configから取得]
    C --> E[data-loaderでフラグ収集]
    D --> E
    E --> F[WorkspaceProvider]
    F --> G[FeatureFlagContext]
    G --> H[useFeatureFlag]
    H --> I[コンポーネントでの条件分岐]
    I --> J{フラグ有効?}
    J -->|Yes| K[機能を表示]
    J -->|No| L[機能を非表示/代替UI]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-89-01 | デフォルト無効 | すべてのフラグのデフォルト値はfalse | 未設定時 |
| BR-89-02 | Context必須 | FeatureFlagProvider外でのuseFeatureFlagはエラー | 常時 |
| BR-89-03 | サーバー優先 | サーバー設定値がデフォルト値より優先 | 設定値がある場合 |

### 計算ロジック

特になし。

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | データベースアクセスなし |

### テーブル別操作詳細

データベースアクセスは発生しない。フラグ設定はEdge ConfigまたはKV Storeで管理。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | Context外でuseFeatureFlag使用 | FeatureFlagProvider内で使用する |

### リトライ仕様

リトライ不要（同期的な状態参照のみ）

## トランザクション仕様

トランザクション管理は不要

## パフォーマンス要件

- フラグ参照: < 1ms
- Context変更時の再レンダリング最小化

## セキュリティ考慮事項

- フラグ値にはセンシティブな情報を含めない
- 管理者のみがフラグを変更可能
- フラグの変更履歴は監査ログに記録（推奨）

## 備考

- 現在11種類のフラグが定義されている
- 新しいフラグを追加する際はFeatureFlagContextValueインターフェースを更新

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

FeatureFlagContextValueインターフェースの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | context.ts | `packages/react/src/feature-flags/context.ts` | FeatureFlagContextValue定義（3-15行目） |

**読解のコツ**: 各フラグはboolean型で定義。フラグ名から機能を推測可能。

#### Step 2: Context実装を理解する

FeatureFlagContextの作成とuseFeatureFlagフックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | context.ts | `packages/react/src/feature-flags/context.ts` | FeatureFlagContext作成（16-18行目） |
| 2-2 | context.ts | `packages/react/src/feature-flags/context.ts` | useFeatureFlagフック（20-28行目） |

**主要処理フロー**:
- **16-18行目**: createContextでundefined初期値のContextを作成
- **20-22行目**: useContextでContext値を取得
- **23-26行目**: Context外で使用された場合のエラーハンドリング
- **27行目**: Context値を返却

#### Step 3: Provider実装を理解する

WorkspaceProviderでのフラグ注入を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | provider.tsx | `packages/react/src/workspace/provider.tsx` | FeatureFlagContext.Provider（48-62行目） |

**主要処理フロー**:
- **48-62行目**: 各フラグのデフォルト値（false）とpropsからの値をマージ
- **50行目**: webSearchAction設定
- **51行目**: layoutV3設定
- **以降**: その他のフラグ設定

### プログラム呼び出し階層図

```
WorkspaceProvider
    │
    └─ FeatureFlagContext.Provider
           │
           ├─ value = { フラグ設定 }
           │
           └─ children
                  │
                  └─ Component
                         │
                         └─ useFeatureFlag()
                                │
                                └─ FeatureFlagContextValue
```

### データフロー図

```
[サーバー]                    [クライアント]

flags.ts (定義)
       │
       ▼
data-loader (取得) ──────────▶ WorkspaceProvider
       │                             │
       │                             ▼
       │                    FeatureFlagContext
       │                             │
       │                             ▼
       │                      useFeatureFlag()
       │                             │
       │                             ▼
       │                    コンポーネント条件分岐
       │
Edge Config / 環境変数
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| context.ts | `packages/react/src/feature-flags/context.ts` | ソース | Context定義とuseFeatureFlagフック |
| provider.tsx | `packages/react/src/workspace/provider.tsx` | ソース | WorkspaceProviderでのフラグ注入 |
| flags.ts | `apps/studio.giselles.ai/flags.ts` | ソース | フラグ定義（サーバー側） |
