# 帳票設計書 3-SSRコンパイル結果

## 概要

本ドキュメントは、Vue.jsのcompiler-ssrパッケージにおける`compile`関数が出力するSSRコンパイル結果（`CodegenResult`）の設計仕様を記述する。SSR（サーバーサイドレンダリング）用テンプレートをコンパイルし、ssrCodegenTransformにより複数要素をテンプレートリテラルに連結する形式のコードを生成する。

### 本帳票の処理概要

compiler-ssrの`compile`関数は、テンプレート文字列またはRootNodeを入力として受け取り、SSR固有のトランスフォーム群を適用した後、`ssrCodegenTransform`でAST codegenNodeをSSR用に変換し、最終的に`generate`関数でCodegenResultを出力する。

**業務上の目的・背景**：サーバーサイドでVueコンポーネントをHTML文字列にレンダリングする場合、DOM APIは使用できない。SSRコンパイラはテンプレートリテラル連結による効率的なHTML文字列生成コードを生成することで、サーバーサイドでの高速なレンダリングを実現する。

**帳票の利用シーン**：Nuxt.js等のSSRフレームワークでのサーバーサイドレンダリング時、compiler-sfcのcompileTemplate関数でssr=trueが指定された場合、およびserver-rendererのssrCompileで使用される。

**主要な出力内容**：
1. `code` - SSR用のssrRender関数コード（テンプレートリテラル連結形式）
2. `preamble` - プリアンブルコード
3. `ast` - SSRトランスフォーム済みRootNode
4. `map` - ソースマップ（オプション）

**帳票の出力タイミング**：SSRビルド時にテンプレートがコンパイルされる際、またはサーバーサイドのランタイムコンパイル時に実行される。

**帳票の利用者**：SSRフレームワーク（Nuxt.js等）、server-renderer、ビルドツールのSSRモード。

## 帳票種別

コード生成結果（データ構造出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | SSRビルドプロセス | - | テンプレートのSSRコンパイル時に自動実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JavaScript/TypeScript オブジェクト（インメモリ） |
| 用紙サイズ | 該当なし |
| 向き | 該当なし |
| ファイル名 | インメモリデータ |
| 出力方法 | 関数戻り値として返却（CodegenResult型） |
| 文字コード | UTF-8 |

### PDF固有設定

該当なし

### Excel固有設定

該当なし

## 帳票レイアウト

### レイアウト概要

出力構造はCodegenResult型（No.1と同一）だが、生成されるコードの特徴はSSR固有。

```
┌─────────────────────────────────────┐
│         CodegenResult               │
├─────────────────────────────────────┤
│  code: string                       │
│  （SSR用ssrRender関数コード）         │
│  テンプレートリテラル連結形式          │
│  _push(`<div>...</div>`)            │
├─────────────────────────────────────┤
│  preamble: string                   │
├─────────────────────────────────────┤
│  ast: RootNode                      │
│  （SSRトランスフォーム済み）           │
├─────────────────────────────────────┤
│  map?: RawSourceMap                 │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | code | SSR用ssrRender関数コード。_push()でHTML文字列を出力する形式 | generate結果 | string |
| 2 | preamble | プリアンブルコード | generate結果 | string |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | ast | SSRトランスフォーム適用済みRootNode | transform + ssrCodegenTransform結果 | RootNode | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | map | ソースマップ | generate結果 | RawSourceMap / undefined |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| source | テンプレート文字列またはRootNode | Yes |
| options | CompilerOptions（ssr: true, inSSR: trueが自動設定される） | No |

### ソート順

該当なし

### 改ページ条件

該当なし

## データベース参照仕様

該当なし（インメモリ処理）

### 参照テーブル一覧

該当なし

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

該当なし

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| ssr | 常にtrue | - | SSRモード固定 |
| inSSR | 常にtrue | - | SSR内部フラグ固定 |
| prefixIdentifiers | 常にtrue | - | SSRではサイズ最適化不要のため常にprefix |
| cacheHandlers | 常にfalse | - | SSRでは不要 |
| hoistStatic | 常にfalse | - | SSRでは不要 |
| scopeId | mode === 'function' ? null : options.scopeId | - | functionモード時はscopeId無効 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[compile関数呼び出し] --> B[SSR固有オプション設定]
    B --> C{source型判定}
    C -->|string| D[baseParse - テンプレートパース]
    C -->|RootNode| E[既存ASTを使用]
    D --> F[rawOptionsMap.set - AST用オプション保存]
    E --> F
    F --> G[transform - AST変換]
    G --> H[SSR固有nodeTransforms適用]
    H --> I[SSR固有directiveTransforms適用]
    I --> J[ssrCodegenTransform - SSR用codegenNode変換]
    J --> K[generate - コード生成]
    K --> L[CodegenResult返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| コンパイルエラー | テンプレート構文エラー | baseParseのエラーメッセージ | テンプレート構文を修正 |
| SSR非対応 | SSRで未対応のディレクティブ使用 | SSR固有のエラーメッセージ | 対応するディレクティブに変更 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1コンポーネントにつき1回 |
| 目標出力時間 | ミリ秒オーダー |
| 同時出力数上限 | 制限なし（同期処理） |

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

SSR用に生成されたコードはサーバーサイドで実行されるため、テンプレート内のユーザー入力はescapeHtml関数で適切にエスケープされる。v-htmlの場合はエスケープされないため注意が必要。

## 備考

- compiler-ssrはcompiler-domのbaseCompileを使用せず、独自にparse -> transform -> ssrCodegenTransform -> generateの4ステップで処理を行う。
- `ssrCodegenTransform`は、通常のVNode生成コードをテンプレートリテラル連結（`_push()`呼び出し）に変換する重要なステップである。
- `rawOptionsMap`にASTとオプションのマッピングを保存するのは、サブコンポーネントのスロットvnodeブランチを変換する際に元のオプションを参照するためである。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | codegen.ts | `packages/compiler-core/src/codegen.ts` | CodegenResult型（108-113行目）- 出力型はcompiler-coreと共通 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/compiler-ssr/src/index.ts` | compile関数（32-94行目）がエントリーポイント |

**主要処理フロー**:
1. **36-47行目**: SSR固有オプション設定（ssr: true, prefixIdentifiers: true, cacheHandlers: false, hoistStatic: false）
2. **49行目**: sourceが文字列の場合baseParseでパース
3. **53行目**: `rawOptionsMap.set(ast, options)`でAST用オプション保存
4. **55-87行目**: transform呼び出し（SSR固有トランスフォーム群を適用）
5. **91行目**: `ssrCodegenTransform(ast, options)` - SSR用codegenNodeに変換
6. **93行目**: `generate(ast, options)` - CodegenResultを生成して返却

#### Step 3: SSR固有トランスフォームを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/compiler-ssr/src/index.ts` | nodeTransforms（58-71行目）: ssrTransformIf, ssrTransformFor, ssrTransformElement, ssrTransformComponent等 |
| 3-2 | index.ts | `packages/compiler-ssr/src/index.ts` | directiveTransforms（73-86行目）: ssrTransformModel, ssrTransformShow, cloak/once/memoはnoop |

#### Step 4: ssrCodegenTransformを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ssrCodegenTransform.ts | `packages/compiler-ssr/src/ssrCodegenTransform.ts` | SSR用codegenNode変換ロジック。通常のVNodeコードをテンプレートリテラル連結に変換 |

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

```
compile (compiler-ssr/src/index.ts:32)
    |
    +-- baseParse (compiler-core/src/parser.ts) [sourceが文字列の場合]
    |
    +-- rawOptionsMap.set(ast, options)
    |
    +-- transform (compiler-core/src/transform.ts)
    |       +-- transformVBindShorthand
    |       +-- ssrTransformIf
    |       +-- ssrTransformFor
    |       +-- trackVForSlotScopes
    |       +-- transformExpression
    |       +-- ssrTransformSlotOutlet
    |       +-- ssrInjectFallthroughAttrs
    |       +-- ssrInjectCssVars
    |       +-- ssrTransformElement
    |       +-- ssrTransformComponent
    |       +-- trackSlotScopes
    |       +-- transformStyle
    |       +-- [ユーザートランスフォーム]
    |
    +-- ssrCodegenTransform (compiler-ssr/src/ssrCodegenTransform.ts)
    |       +-- AST codegenNodeをSSR形式に変換
    |
    +-- generate (compiler-core/src/codegen.ts:283)
            +-- CodegenResult を返却
```

### データフロー図

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

テンプレート文字列       ──▶  baseParse                   ──▶  RootNode (AST)
  or RootNode                    |
                           transform                     ──▶  変換済みAST
                           (SSR固有トランスフォーム適用)
                                 |
                           ssrCodegenTransform           ──▶  SSR用codegenNode
                           (テンプレートリテラル連結形式)
                                 |
                           generate                      ──▶  CodegenResult
                                                                { code, preamble, ast, map }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/compiler-ssr/src/index.ts` | ソース | compile関数（SSRエントリーポイント） |
| ssrCodegenTransform.ts | `packages/compiler-ssr/src/ssrCodegenTransform.ts` | ソース | SSR用codegenNode変換 |
| ssrTransformElement.ts | `packages/compiler-ssr/src/transforms/ssrTransformElement.ts` | ソース | 要素のSSR変換 |
| ssrTransformComponent.ts | `packages/compiler-ssr/src/transforms/ssrTransformComponent.ts` | ソース | コンポーネントのSSR変換 |
| ssrTransformSlotOutlet.ts | `packages/compiler-ssr/src/transforms/ssrTransformSlotOutlet.ts` | ソース | スロットアウトレットのSSR変換 |
| ssrVIf.ts | `packages/compiler-ssr/src/transforms/ssrVIf.ts` | ソース | v-ifのSSR変換 |
| ssrVFor.ts | `packages/compiler-ssr/src/transforms/ssrVFor.ts` | ソース | v-forのSSR変換 |
| ssrVModel.ts | `packages/compiler-ssr/src/transforms/ssrVModel.ts` | ソース | v-modelのSSR変換 |
| ssrVShow.ts | `packages/compiler-ssr/src/transforms/ssrVShow.ts` | ソース | v-showのSSR変換 |
| ssrInjectFallthroughAttrs.ts | `packages/compiler-ssr/src/transforms/ssrInjectFallthroughAttrs.ts` | ソース | fallthrough属性の注入 |
| ssrInjectCssVars.ts | `packages/compiler-ssr/src/transforms/ssrInjectCssVars.ts` | ソース | CSS変数の注入 |
| codegen.ts | `packages/compiler-core/src/codegen.ts` | ソース | generate関数、CodegenResult型 |
