# 通知設計書 5-フィーチャーフラグ未設定警告

## 概要

本ドキュメントは、Vue.jsのESMバンドラービルドにおけるフィーチャーフラグ未設定警告の設計仕様を記述する。`packages/runtime-core/src/featureFlags.ts`に実装されており、`__VUE_OPTIONS_API__`、`__VUE_PROD_DEVTOOLS__`、`__VUE_PROD_HYDRATION_MISMATCH_DETAILS__`のフラグが未定義の場合に`console.warn`で開発者に設定を促す。

### 本通知の処理概要

この通知は、ESMバンドラービルド（Vite、webpack等）でVueのコンパイル時フィーチャーフラグが明示的に定義されていない場合に、開発者にバンドラー設定の最適化を促す警告を出力する。

**業務上の目的・背景**：Vueはコンパイル時フィーチャーフラグを使用して、不要な機能をツリーシェイキングにより本番バンドルから除去できる仕組みを持つ。これらのフラグが未設定の場合、本番バンドルサイズが最適化されない。この警告は、開発者にバンドラー設定の改善を促し、アプリケーションのパフォーマンス最適化を支援する。フラグ未設定時はデフォルト値が適用されるため動作には影響しないが、意図しないバンドルサイズ増加を防ぐためにガイダンスを提供する。

**通知の送信タイミング**：レンダラー作成時（`baseCreateRenderer`内での`initFeatureFlags()`呼び出し）に1回のみ発火する。アプリケーションの初期化時に実行される。

**通知の受信者**：アプリケーション開発者。ブラウザの開発者コンソールを通じて確認する。

**通知内容の概要**：未設定のフィーチャーフラグ名のリスト、ESMバンドラービルドの説明、バンドラー設定でのグローバル注入の必要性、詳細情報へのリンク（`https://link.vuejs.org/feature-flags.`）が出力される。

**期待されるアクション**：開発者がバンドラー設定（Viteの`define`、webpackの`DefinePlugin`等）でフィーチャーフラグをグローバルに定義する。

## 通知種別

コンソール警告（`console.warn`）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低（ガイダンス通知） |
| リトライ | なし |

### 送信先決定ロジック

`console.warn`のみに出力する。`__DEV__`がtrueの場合のみ動作する。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A（コンソール出力） |
| 送信元名称 | N/A（プレフィックスなし） |
| 件名 | N/A |
| 形式 | テキスト |

### 本文テンプレート

```
Feature flag{s} {フラグ名リスト} {is/are} not explicitly defined. You are running the esm-bundler build of Vue, which expects these compile-time feature flags to be globally injected via the bundler config in order to get better tree-shaking in the production bundle.

For more details, see https://link.vuejs.org/feature-flags.
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | コンソール出力のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| needWarn | 未設定のフラグ名リスト | typeof演算子によるフラグ存在チェック | Yes |
| multi | 複数フラグが未設定かどうか | needWarn.length > 1 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 初期化 | initFeatureFlags()呼び出し | `__DEV__`がtrueかつneedWarn.lengthが1以上 | レンダラー作成時に1回のみ実行 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| `__DEV__` がfalse | 本番ビルドでは抑止 |
| 全フラグが明示的に定義済み | needWarn配列が空の場合は抑止 |
| `typeof __FEATURE_OPTIONS_API__` が'boolean' | __VUE_OPTIONS_API__が設定済み |
| `typeof __FEATURE_PROD_DEVTOOLS__` が'boolean' | __VUE_PROD_DEVTOOLS__が設定済み |
| `typeof __FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__` が'boolean' | __VUE_PROD_HYDRATION_MISMATCH_DETAILS__が設定済み |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[initFeatureFlags呼び出し] --> B{__FEATURE_OPTIONS_API__<br>がboolean型か?}
    B -->|No| C["needWarnに'__VUE_OPTIONS_API__'を追加<br>デフォルト値: true を設定"]
    B -->|Yes| D[スキップ]
    C --> E{__FEATURE_PROD_DEVTOOLS__<br>がboolean型か?}
    D --> E
    E -->|No| F["needWarnに'__VUE_PROD_DEVTOOLS__'を追加<br>デフォルト値: false を設定"]
    E -->|Yes| G[スキップ]
    F --> H{__FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__<br>がboolean型か?}
    G --> H
    H -->|No| I["needWarnに'__VUE_PROD_HYDRATION_MISMATCH_DETAILS__'を追加<br>デフォルト値: false を設定"]
    H -->|Yes| J[スキップ]
    I --> K{__DEV__ かつ<br>needWarn.length > 0?}
    J --> K
    K -->|Yes| L[console.warnで警告出力]
    K -->|No| M[何もしない]
    L --> N[終了]
    M --> N
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知はデータベースを使用しない。以下のグローバル変数を参照する。

| 参照データ | 用途 | 取得方法 |
|-----------|------|---------|
| __FEATURE_OPTIONS_API__ | Options APIの有効/無効 | typeof演算子でboolean型かチェック |
| __FEATURE_PROD_DEVTOOLS__ | 本番DevToolsの有効/無効 | typeof演算子でboolean型かチェック |
| __FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__ | ハイドレーション不一致詳細の有効/無効 | typeof演算子でboolean型かチェック |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| globalThis | UPDATE | 未定義フラグにデフォルト値を設定 |

#### グローバル変数の更新

| 操作 | 項目 | 更新値 | 備考 |
|-----|------|-------|------|
| SET | `__VUE_OPTIONS_API__` | `true` | 未定義時のデフォルト値 |
| SET | `__VUE_PROD_DEVTOOLS__` | `false` | 未定義時のデフォルト値 |
| SET | `__VUE_PROD_HYDRATION_MISMATCH_DETAILS__` | `false` | 未定義時のデフォルト値 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | N/A | デフォルト値を設定するため、エラーは発生しない |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 1回（initFeatureFlags内で1回のみ出力） |
| 1日あたり上限 | N/A |

### 配信時間帯

制限なし。アプリケーション初期化時に実行される。

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

- フラグ名のみが出力されるため、機密情報の漏洩リスクはない
- 本番ビルドではツリーシェイキングにより除去される

## 備考

- `initFeatureFlags`はesm-bundlerビルドでのみ呼び出される（副作用なしの設計のため、`baseCreateRenderer`内で呼び出される）
- フラグ未設定時はデフォルト値が自動適用されるため、動作自体は正常に行われる
- `getGlobalThis()`を使用してブラウザ/Node.js環境の両方に対応している
- 警告メッセージは文法的に正しい英語を出力するため、単数/複数の分岐処理（`multi`変数）が含まれている
- 3つのフィーチャーフラグはそれぞれ異なる内部変数名（`__FEATURE_*`）と外部公開名（`__VUE_*`）を持つ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | featureFlags.ts | `packages/runtime-core/src/featureFlags.ts` | L9: needWarn配列（未設定フラグ名を収集する一時配列） |

**読解のコツ**: `typeof __FEATURE_*`でグローバル変数の存在をチェックする手法を理解する。バンドラーがこれらのフラグをコンパイル時に置換する仕組みの前提知識が必要。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | featureFlags.ts | `packages/runtime-core/src/featureFlags.ts` | L8-38: initFeatureFlags関数全体。フラグチェック、デフォルト値設定、警告出力の一連の流れ |

**主要処理フロー**:
1. **L9**: `needWarn`配列を初期化
2. **L11-13**: `__FEATURE_OPTIONS_API__`がboolean型でなければ、needWarnに追加しデフォルト値`true`を設定
3. **L16-18**: `__FEATURE_PROD_DEVTOOLS__`がboolean型でなければ、needWarnに追加しデフォルト値`false`を設定
4. **L21-23**: `__FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__`がboolean型でなければ、needWarnに追加しデフォルト値`false`を設定
5. **L26-37**: `__DEV__`かつneedWarnが空でない場合、console.warnで警告メッセージを出力

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

```
baseCreateRenderer()                    [renderer.ts]
    |
    +-- initFeatureFlags()              [featureFlags.ts:8]
            |
            +-- typeof __FEATURE_OPTIONS_API__ チェック
            +-- typeof __FEATURE_PROD_DEVTOOLS__ チェック
            +-- typeof __FEATURE_PROD_HYDRATION_MISMATCH_DETAILS__ チェック
            |
            +-- getGlobalThis()         [@vue/shared]
            |       +-- デフォルト値の設定
            |
            +-- console.warn()          [未設定フラグがある場合]
```

### データフロー図

```
[入力]                           [処理]                           [出力]

__FEATURE_OPTIONS_API__    +-- initFeatureFlags()           +-- console.warn()
  (typeof check)           |     |                          |     "Feature flag(s)..."
__FEATURE_PROD_DEVTOOLS__  |     +-- needWarn収集           |
  (typeof check)      ---->|     +-- デフォルト値設定  ---->+-- globalThis更新
__FEATURE_PROD_HYDRATION_  |     +-- 警告メッセージ生成     |     __VUE_OPTIONS_API__
  MISMATCH_DETAILS__       |                                |     __VUE_PROD_DEVTOOLS__
  (typeof check)           +--                              +--   __VUE_PROD_HYDRATION_
                                                                  MISMATCH_DETAILS__
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| featureFlags.ts | `packages/runtime-core/src/featureFlags.ts` | ソース | initFeatureFlags関数本体 |
| shared | `@vue/shared` | ソース | getGlobalThis()ヘルパー関数 |
