# 帳票設計書 4-SFCテンプレートコンパイル結果

## 概要

本ドキュメントは、Vue.jsのcompiler-sfcパッケージにおける`compileTemplate`関数が出力する`SFCTemplateCompileResults`の設計仕様を記述する。SFC（Single File Component）の`<template>`部をコンパイルし、render関数コードを生成する。

### 本帳票の処理概要

compiler-sfcの`compileTemplate`関数は、SFCのtemplate部のソースコードとオプションを入力として受け取り、プリプロセッサ処理（pug等）、アセットURL変換、テンプレートコンパイルを行い、`SFCTemplateCompileResults`を出力する。

**業務上の目的・背景**：Vue SFCの`<template>`ブロックは、HTML風テンプレートとして記述されるが、実行時にはJavaScript render関数として動作する必要がある。compileTemplateはSFC固有の前処理（プリプロセッサ、アセットURL変換、スコープID付与等）を行った上でテンプレートをコンパイルし、ビルドツールが利用可能な形式に変換する。

**帳票の利用シーン**：Vite/webpack等のビルドツールがSFCファイルを処理する際、template部のコンパイルに使用される。compileScript関数からinlineTemplate有効時に内部呼び出しされることもある。

**主要な出力内容**：
1. `code` - 生成されたrender関数コード文字列
2. `ast` - コンパイル後のRootNode（オプション）
3. `preamble` - プリアンブルコード（オプション）
4. `source` - 元のテンプレートソース
5. `tips` - 警告メッセージ配列
6. `errors` - エラー配列
7. `map` - ソースマップ（オプション）

**帳票の出力タイミング**：SFCファイルのビルド時にtemplate部がコンパイルされる際に実行される。

**帳票の利用者**：@vitejs/plugin-vue、vue-loader、その他のSFCビルドプラグイン。

## 帳票種別

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

## 利用画面

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

## 出力形式

### 基本仕様

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

### PDF固有設定

該当なし

### Excel固有設定

該当なし

## 帳票レイアウト

### レイアウト概要

SFCTemplateCompileResultsは7つのフィールドで構成される。

```
┌─────────────────────────────────────┐
│    SFCTemplateCompileResults        │
├─────────────────────────────────────┤
│  code: string                       │
│  （render関数コード）                 │
├─────────────────────────────────────┤
│  ast?: RootNode                     │
├─────────────────────────────────────┤
│  preamble?: string                  │
├─────────────────────────────────────┤
│  source: string                     │
│  （元のテンプレートソース）            │
├─────────────────────────────────────┤
│  tips: string[]                     │
│  （警告メッセージ）                   │
├─────────────────────────────────────┤
│  errors: (string | CompilerError)[] │
│  （エラー情報）                       │
├─────────────────────────────────────┤
│  map?: RawSourceMap                 │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | code | 生成されたrender関数コード | compiler.compile結果 | string |
| 2 | source | 元のテンプレートソースコード | options.source | string |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | ast | コンパイル後のRootNode | compiler.compile結果 | RootNode / undefined | - |
| 2 | preamble | プリアンブルコード | compiler.compile結果 | string / undefined | - |
| 3 | tips | 警告メッセージ配列（位置情報付き） | warnings -> generateCodeFrame | string[] | - |
| 4 | errors | エラー配列 | コンパイルエラー・プリプロセッサエラー | (string/CompilerError)[] | - |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | map | ソースマップ（inMapとのマージ後） | mapLines関数 | RawSourceMap / undefined |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| source | テンプレートソース文字列 | Yes |
| filename | SFCファイル名 | Yes |
| id | スコープID（data-v-xxxxxx形式） | Yes |
| scoped | スコープ付きCSSの有無 | No |
| ssr | SSRモードフラグ | No |
| compiler | カスタムコンパイラ | No（デフォルト: CompilerDOM/CompilerSSR） |
| preprocessLang | プリプロセッサ言語（pug等） | No |
| transformAssetUrls | アセットURL変換設定 | No |

### ソート順

該当なし

### 改ページ条件

該当なし

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

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

### 参照テーブル一覧

該当なし

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

該当なし

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| shortId | id.replace(/^data-v-/, '') | - | data-v-プレフィクスを除去 |
| longId | `data-v-${shortId}` | - | スコープIDを正規化 |
| defaultCompiler | ssr ? CompilerSSR : CompilerDOM | - | SSRフラグに応じてコンパイラを選択 |
| map（マージ後） | mapLines(inMap, map) | - | parse時のソースマップとコンパイル後のソースマップをマージ |
| tips | warnings.map(w => msg + generateCodeFrame(...)) | - | 警告をコードフレーム付きメッセージに変換 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[compileTemplate呼び出し] --> B{preprocessLang?}
    B -->|あり| C[プリプロセッサ実行]
    C --> D[doCompileTemplate]
    B -->|なし| D
    D --> E[アセットURL変換設定]
    E --> F{ssr判定}
    F -->|ssr=true| G[CompilerSSR使用]
    F -->|ssr=false| H[CompilerDOM使用]
    G --> I[compiler.compile呼び出し]
    H --> I
    I --> J{inMap存在?}
    J -->|あり| K[mapLines - ソースマップマージ]
    J -->|なし| L[そのまま使用]
    K --> M[tips/errors構築]
    L --> M
    M --> N[SFCTemplateCompileResults返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| プリプロセッサ未インストール | preprocessLang指定でプリプロセッサが見つからない | Component {filename} uses lang {lang} for template, however it is not installed. | プリプロセッサをインストール |
| ブラウザビルドでのプリプロセッサ | ブラウザビルドでpreprocessCustomRequireなし | Template preprocessing in the browser build must provide the preprocessCustomRequire option | preprocessCustomRequireを指定 |
| コンパイルエラー | テンプレート構文エラー | CompilerErrorのメッセージ | テンプレート構文を修正 |
| AST再利用不可 | 変換済みASTが再渡された場合 | （エラーではなく再パースで対応） | 自動的に新しいASTを生成 |

## パフォーマンス要件

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

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

transformAssetUrlsオプションにより、テンプレート内のアセットURL（img srcなど）がimport文に変換されるため、ビルドツールのモジュール解決を通じてファイルパスの検証が行われる。プリプロセッサにカスタムrequireを渡す場合は、信頼できるソースからのみモジュールを読み込むこと。

## 備考

- `inAST?.transformed`が真の場合、既に変換済みのASTは再利用できないため、新たにパースし直す。
- `compilerOptions`の`hmr: !isProd`により、開発モードではHMR用のフラグが有効化される。
- ソースマップのマージは`source-map-js`ライブラリのSourceMapConsumer/SourceMapGeneratorを使用して行われる。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | SFCTemplateCompileResults型（37-45行目）とSFCTemplateCompileOptions型（47-73行目） |
| 1-2 | compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | TemplateCompiler型（32-35行目）- コンパイラインターフェース |

**読解のコツ**: SFCTemplateCompileResultsはCodegenResultの拡張版であり、source、tips、errorsフィールドが追加されている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | compileTemplate関数（107-160行目）がエントリーポイント |

**主要処理フロー**:
1. **110行目**: `preprocessLang`の有無を確認
2. **124-130行目**: プリプロセッサが存在する場合、preprocess関数でテンプレートを前処理
3. **133-136行目**: 前処理済みソースでdoCompileTemplateを呼び出し
4. **158行目**: プリプロセッサ不要の場合、直接doCompileTemplateを呼び出し

#### Step 3: 内部コンパイル処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | doCompileTemplate関数（162-275行目）が実際のコンパイル処理 |

**主要処理フロー**:
- **181-189行目**: transformAssetUrlsオプションに基づいてnodeTransformsを設定
- **205-206行目**: SSRフラグに応じてデフォルトコンパイラを選択
- **214-228行目**: 変換済みASTの場合は再パース
- **230-248行目**: compiler.compile呼び出し（mode: 'module', sourceMap: true等のオプション付き）
- **253-260行目**: inMapが存在する場合、mapLines関数でソースマップをマージ
- **262-272行目**: warningsをtipsメッセージに変換
- **274行目**: SFCTemplateCompileResultsオブジェクトを返却

#### Step 4: ソースマップマージ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | mapLines関数（277-328行目）- 2つのソースマップのマージ |
| 4-2 | compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | patchErrors関数（330-348行目）- エラーの位置情報補正 |

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

```
compileTemplate (compileTemplate.ts:107)
    |
    +-- preprocess (compileTemplate.ts:83) [preprocessLang指定時]
    |       +-- preprocessor.render()
    |
    +-- doCompileTemplate (compileTemplate.ts:162)
            |
            +-- normalizeOptions (template/transformAssetUrl.ts) [transformAssetUrls設定時]
            |
            +-- compiler.compile (CompilerDOM or CompilerSSR)
            |       +-- baseCompile or SSR compile
            |
            +-- mapLines (compileTemplate.ts:277) [inMap存在時]
            |       +-- SourceMapConsumer
            |       +-- SourceMapGenerator
            |
            +-- patchErrors (compileTemplate.ts:330) [inMap存在時]
            |
            +-- SFCTemplateCompileResults を返却
```

### データフロー図

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

SFCTemplateCompileOptions
  source             ──▶  preprocess (pug等)      ──▶  前処理済みソース
  filename                       |
  id                       doCompileTemplate
  scoped                         |
  ssr              ──▶  compiler.compile         ──▶  {code, ast, preamble, map}
  inMap                          |
                           mapLines (マージ)       ──▶  マージ済みmap
                                 |
                           warnings -> tips        ──▶  SFCTemplateCompileResults
                                                          { code, ast, preamble,
                                                            source, tips, errors, map }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| compileTemplate.ts | `packages/compiler-sfc/src/compileTemplate.ts` | ソース | compileTemplate関数、SFCTemplateCompileResults型、ソースマップマージ |
| transformAssetUrl.ts | `packages/compiler-sfc/src/template/transformAssetUrl.ts` | ソース | アセットURL変換トランスフォーム |
| transformSrcset.ts | `packages/compiler-sfc/src/template/transformSrcset.ts` | ソース | srcset属性変換トランスフォーム |
| cssVars.ts | `packages/compiler-sfc/src/style/cssVars.ts` | ソース | genCssVarsFromList関数 |
| warn.ts | `packages/compiler-sfc/src/warn.ts` | ソース | warnOnce関数 |
| index.ts | `packages/compiler-dom/src/index.ts` | ソース | CompilerDOM（デフォルトクライアントコンパイラ） |
| index.ts | `packages/compiler-ssr/src/index.ts` | ソース | CompilerSSR（デフォルトSSRコンパイラ） |
