# バッチ設計書 8-package-electron

## 概要

本ドキュメントは、Electron版（デスクトップアプリ）Actual Budgetのビルドパッケージスクリプト「package-electron」の設計仕様を記載したものです。

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

このバッチは、Windows、macOS、Linux向けのElectronデスクトップアプリケーションのビルドパッケージを生成します。翻訳ファイルの更新、各ワークスペースのビルド、Electronパッケージングを実行し、配布可能なインストーラーやアプリケーションバンドルを生成します。

**業務上の目的・背景**：Actual Budgetはブラウザ版に加えて、デスクトップアプリケーションとしても提供されています。デスクトップアプリはオフライン利用が可能で、ネイティブアプリとしての使い勝手を提供します。このスクリプトにより、クロスプラットフォーム対応のデスクトップアプリケーションをビルドし、各OS向けの配布パッケージ（.exe、.dmg、.AppImage等）を生成します。リリースプロセスの中核を担うスクリプトです。

**バッチの実行タイミング**：手動実行またはCI/CDパイプラインからの自動実行。リリースビルド作成時に実行されます。

**主要な処理内容**：
1. コマンドライン引数解析（--release、--skip-exe-build、--skip-translations）
2. 翻訳ファイルリポジトリをクローンまたは更新
3. 未翻訳の言語ファイルを削除
4. NODE_OPTIONSでメモリ上限を設定（4096MB）
5. plugins-serviceワークスペースをビルド
6. loot-coreワークスペース（Node.js向け、ブラウザ向け）をビルド
7. desktop-clientワークスペース（デスクトップモード、ブラウザモード）をビルド
8. sync-serverワークスペースをビルド
9. desktop-electronのupdate-clientスクリプト実行
10. Electronパッケージング（cleanしてからbuild）

**前後の処理との関連**：ビルド完了後、生成されたパッケージはリリースとして配布されます。CI/CDパイプラインでは、このスクリプトの後にGitHub Releasesへのアップロードが行われます。

**影響範囲**：packages/desktop-electron/dist/ディレクトリ、各ワークスペースのビルド出力

## バッチ種別

ビルド・デプロイ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（リリース時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 / CI/CD |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 22以上がインストールされていること |
| yarn利用可能 | yarnコマンドが利用可能であること |
| git利用可能 | gitコマンドが利用可能であること（翻訳リポジトリ用） |
| メモリ | 4GB以上のメモリが利用可能であること |
| ビルドツール | 各プラットフォームのネイティブビルドツール |

### 実行可否判定

常に実行可能。依存関係がインストール済みであることが前提です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --release | フラグ | No | なし | 本番リリース用ビルドを実行 |
| --skip-exe-build | フラグ | No | false | 実行ファイルビルドをスキップ |
| --skip-translations | フラグ | No | false | 翻訳更新をスキップ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| packages/*/src | TypeScript/JavaScript | ソースコード |
| packages/desktop-client/locale | 翻訳ファイル | 多言語翻訳データ |
| package.json | JSON | ビルド設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/desktop-electron/dist | インストーラー | 各OS向けインストーラー |
| packages/desktop-client/build | 静的ファイル | ビルドされたWebアプリケーション |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | Actual-{version}.exe, Actual-{version}.dmg, Actual-{version}.AppImage等 |
| 出力先 | packages/desktop-electron/dist |
| 文字コード | 該当なし（バイナリ） |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. 引数解析
   └─ --release, --skip-exe-build, --skip-translationsを解析
2. ディレクトリ移動
   └─ プロジェクトルートへ移動
3. 翻訳ファイル更新（--skip-translationsでスキップ可能）
   ├─ localeディレクトリが存在しない場合: git clone
   └─ 存在する場合: git pull
4. 未翻訳言語削除
   └─ remove-untranslated-languagesスクリプト実行
5. NODE_OPTIONS設定
   └─ --max-old-space-size=4096
6. ワークスペースビルド
   ├─ plugins-service build
   ├─ loot-core build:node
   ├─ @actual-app/web build --mode=desktop
   ├─ loot-core build:browser
   ├─ @actual-app/web build:browser
   └─ @actual-app/sync-server build
7. Electronクライアント更新
   └─ desktop-electron update-client
8. Electronパッケージング
   ├─ yarn clean
   ├─ --skip-exe-buildの場合: build:distのみ
   └─ 通常: yarn build（インストーラー生成）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[引数解析]
    B --> C{--skip-translations?}
    C -->|No| D[翻訳更新]
    C -->|Yes| E[翻訳更新スキップ]
    D --> F[未翻訳言語削除]
    E --> G[NODE_OPTIONS設定]
    F --> G
    G --> H[plugins-service build]
    H --> I[loot-core build:node]
    I --> J[desktop-client build desktop]
    J --> K[loot-core build:browser]
    K --> L[desktop-client build:browser]
    L --> M[sync-server build]
    M --> N[update-client]
    N --> O[yarn clean]
    O --> P{--skip-exe-build?}
    P -->|Yes| Q[build:dist only]
    P -->|No| R{--release?}
    R -->|Yes| S[yarn build production]
    R -->|No| T[yarn build]
    Q --> U[バッチ終了]
    S --> V[Created release表示]
    T --> U
    V --> U
```

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

該当なし。ビルドプロセスはデータベース操作を行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | git-error | 翻訳リポジトリへのアクセス失敗 | ネットワーク接続を確認 |
| - | build-error | ビルド失敗 | エラーメッセージを確認、依存関係を再インストール |
| - | memory-error | メモリ不足 | NODE_OPTIONS値の調整、物理メモリの確保 |
| - | electron-build-error | Electronパッケージング失敗 | electron-builderの設定を確認 |

### リトライ仕様

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

### 障害時対応

1. git cloneエラー：ネットワーク接続とGitHubへのアクセス権限を確認
2. ビルドエラー：エラーメッセージを確認し、該当ワークスペースを個別にビルド
3. Electronビルドエラー：electron-builderの依存関係とプラットフォーム要件を確認
4. メモリエラー：`--max-old-space-size`の値を増やすか、物理メモリを確保

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

該当なし。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回（ビルド） |
| 目標処理時間 | 十数分〜数十分（プラットフォーム依存） |
| メモリ使用量上限 | 4096MB（NODE_OPTIONS設定） |

## 排他制御

同一ディレクトリでの同時実行は推奨されません。ビルド出力が競合する可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各ステップ | 「Updating translations...」等 |
| ビルドログ | 各ワークスペースビルド時 | webpack/vite/electron-builder出力 |
| リリースログ | --release時 | 「Created release」 |
| スキップログ | --skip-exe-build時 | 「Skipping exe build」 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | CI/CDシステム |
| ビルド時間 | 異常に長い場合 | 開発者 |

## 備考

- 実行コマンド: `./bin/package-electron`
- オプション付き例: `./bin/package-electron --release`
- スクリプト種別: Bashスクリプト（-eオプションでエラー時停止）
- 翻訳リポジトリ: https://github.com/actualbudget/translations
- Electronビルド出力は`packages/desktop-electron/dist`ディレクトリに生成
- sync-serverもビルドされ、デスクトップアプリに組み込まれる（ローカルサーバー機能用）
- CI環境変数（CI=false）のデフォルト設定あり
- --skip-exe-buildオプションでインストーラー生成をスキップし、distフォルダのみ生成可能
- NODE_OPTIONS環境変数でV8ヒープサイズを4096MBに制限（大規模プロジェクトのビルドに必要）
