# バッチ設計書 2-prepare-yarn-cache

## 概要

本ドキュメントは、GitHub Actions CI/CDパイプラインにおけるYarnキャッシュ準備バッチの設計仕様を定義する。

### 本バッチの処理概要

後続のCIジョブで使用するYarn依存関係キャッシュを準備するバッチ処理である。依存関係のインストールを最適化し、CI全体の実行時間を短縮する役割を担う。

**業務上の目的・背景**：Babelプロジェクトは多数のパッケージと依存関係を持つモノレポ構成である。各CIジョブで毎回依存関係をインストールすると、ネットワーク負荷とビルド時間が増大する。本バッチはキャッシュを事前準備することで、後続ジョブの効率化を実現し、開発者のフィードバックループを高速化する。

**バッチの実行タイミング**：リポジトリへのpush時およびプルリクエスト作成時に自動実行される。CIワークフローの最初のジョブとして実行され、他のジョブの依存元となる。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. Node.js最新版（25.6.1）のセットアップとYarnキャッシュ設定
3. Yarnのハードンモードを有効化しセキュリティを強化
4. post-installスクリプトを無効化して高速化
5. PnPリンカーを使用してパフォーマンスを最適化
6. yarn install --mode=skip-buildで依存関係をインストール

**前後の処理との関連**：本バッチは他の全てのビルド・テストジョブの前提条件となる。yarn-validate、build、build-babel9などのジョブはこのバッチの完了を待ってから実行される。

**影響範囲**：GitHub ActionsのYarnキャッシュストレージ、後続の全CIジョブ。

## バッチ種別

キャッシュ準備 / CI/CD

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（イベント駆動） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | push / pull_request イベント |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| yarn.lock | 依存関係定義ファイルが存在すること |
| package.json | プロジェクト設定ファイルが存在すること |
| GitHub Actions | ワークフロー実行環境が利用可能であること |

### 実行可否判定

GitHub Actionsのワークフロートリガー条件（push、pull_request）に基づき自動実行される。concurrencyグループ設定により、同一リファレンスへの複数実行は最新のものが優先される。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| YARN_ENABLE_HARDENED_MODE | boolean | No | true | セキュリティ強化モード |
| YARN_ENABLE_SCRIPTS | boolean | No | false | post-installスクリプトの無効化 |
| YARN_NODE_LINKER | string | No | pnp | PnPリンカーの使用 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| yarn.lock | YAML | 依存関係のロックファイル |
| package.json | JSON | プロジェクト設定 |
| .yarnrc.yml | YAML | Yarn設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions Cache | キャッシュ | Yarn依存関係キャッシュ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| キャッシュキー | yarn-{platform}-{yarn.lockハッシュ} |
| 出力先 | GitHub Actions キャッシュストレージ |
| 有効期限 | GitHub Actionsデフォルト（7日間未使用で削除） |

## 処理フロー

### 処理シーケンス

```
1. Checkout code
   └─ actions/checkout@v4でリポジトリをチェックアウト
2. Use Node.js latest
   └─ actions/setup-node@v4でNode.js 25.6.1をセットアップ
   └─ cache: "yarn"でYarnキャッシュを有効化
3. Check or update Yarn cache
   └─ 環境変数を設定（HARDENED_MODE, SCRIPTS無効, PnP）
   └─ yarn install --mode=skip-buildを実行
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[actions/checkout: リポジトリ取得]
    B --> C[actions/setup-node: Node.js セットアップ]
    C --> D{キャッシュ存在?}
    D -->|あり| E[キャッシュ復元]
    D -->|なし| F[新規インストール]
    E --> G[yarn install --mode=skip-build]
    F --> G
    G --> H{インストール成功?}
    H -->|成功| I[キャッシュ保存]
    H -->|失敗| J[バッチ失敗終了]
    I --> K[バッチ正常終了]
```

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

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

本バッチではデータベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| EXIT_1 | インストールエラー | yarn install失敗時 | yarn.lockの整合性確認、パッケージレジストリの状態確認 |
| NETWORK_ERROR | ネットワークエラー | npmレジストリ接続失敗時 | リトライまたはレジストリ状態確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（GitHub Actionsデフォルト） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. GitHub Actionsのジョブログを確認
2. yarn.lockとpackage.jsonの整合性を確認
3. npmレジストリの状態を確認
4. ローカル環境でyarn installを実行して再現確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（キャッシュ操作のみ） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約1000パッケージの依存関係処理 |
| 目標処理時間 | キャッシュヒット時：1分以内、ミス時：5分以内 |
| メモリ使用量上限 | ubuntu-latestランナーのデフォルト |

## 排他制御

concurrency設定により、同一ワークフロー・同一リファレンスの実行は1つに制限される。後続実行は前の実行をキャンセルする（cancel-in-progress: true）。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | GitHub Actions自動出力 |
| キャッシュログ | キャッシュ操作時 | キャッシュヒット/ミス情報 |
| 進捗ログ | インストール時 | パッケージ解決・インストール進捗 |
| 終了ログ | ジョブ終了時 | 成功/失敗ステータス |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功率 | 100% | GitHubステータスチェック |
| キャッシュヒット率 | 80%以上推奨 | N/A（メトリクス監視なし） |

## 備考

- YARN_ENABLE_HARDENED_MODEは信頼できないリポジトリのPR実行時のセキュリティ対策
- --mode=skip-buildはビルドスクリプトをスキップしてインストール時間を短縮
- PnPリンカー使用によりnode_modules生成をスキップし、リンク処理を高速化
