# バッチ設計書 7-package-browser

## 概要

本ドキュメントは、ブラウザ版Actual Budgetのビルドパッケージスクリプト「package-browser」の設計仕様を記載したものです。

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

このバッチは、ブラウザ版Actual Budgetのプロダクションビルドを生成します。翻訳ファイルの更新、各ワークスペース（plugins-service、loot-core、desktop-client）のビルドを順次実行し、デプロイ可能なビルドアーティファクトを生成します。

**業務上の目的・背景**：Actual Budgetは、ブラウザ経由でアクセスするWebアプリケーションとしても提供されています。ユーザーが自前のサーバー（セルフホスト）でActual Budgetを運用する場合、このスクリプトで生成されたビルドアーティファクトをデプロイします。リリースプロセスの一環として、CI/CDパイプラインからこのスクリプトが呼び出され、配布用のビルドが生成されます。翻訳ファイルを最新の状態に更新することで、多言語対応を維持しています。

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

**主要な処理内容**：
1. 翻訳ファイルリポジトリをクローンまたは更新
2. 未翻訳の言語ファイルを削除
3. NODE_OPTIONSでメモリ上限を設定（4096MB）
4. plugins-serviceワークスペースをビルド
5. loot-coreワークスペース（ブラウザ向け）をビルド
6. desktop-clientワークスペース（ブラウザ向け）をビルド
7. ビルド出力ディレクトリパスを表示

**前後の処理との関連**：ビルド完了後、生成された`packages/desktop-client/build`ディレクトリをWebサーバーにデプロイします。sync-serverと組み合わせて使用されます。

**影響範囲**：packages/desktop-client/build/ディレクトリ、翻訳ファイル

## バッチ種別

ビルド・デプロイ

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js環境 | Node.js 22以上がインストールされていること |
| yarn利用可能 | yarnコマンドが利用可能であること |
| git利用可能 | gitコマンドが利用可能であること（翻訳リポジトリ用） |
| メモリ | 4GB以上のメモリが利用可能であること |

### 実行可否判定

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | パラメータなし |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| packages/desktop-client/build | 静的ファイル | ビルドされたWebアプリケーション |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | index.html, *.js, *.css, assets/* |
| 出力先 | packages/desktop-client/build |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. ディレクトリ移動
   └─ スクリプトのあるディレクトリから親ディレクトリへ
2. 翻訳ファイル更新
   ├─ localeディレクトリが存在しない場合: git clone
   └─ 存在する場合: git checkout . && git pull
3. 未翻訳言語削除
   └─ remove-untranslated-languages スクリプト実行
4. NODE_OPTIONS設定
   └─ --max-old-space-size=4096
5. plugins-serviceビルド
   └─ yarn workspace plugins-service build
6. loot-coreビルド
   └─ yarn workspace loot-core build:browser
7. desktop-clientビルド
   └─ yarn workspace @actual-app/web build:browser
8. 完了メッセージ
   └─ ビルド出力パスを表示
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[プロジェクトルートへ移動]
    B --> C{localeディレクトリ存在?}
    C -->|No| D[git clone translations]
    C -->|Yes| E[git checkout && git pull]
    D --> F[remove-untranslated-languages]
    E --> F
    F --> G[NODE_OPTIONS設定]
    G --> H[plugins-service build]
    H --> I[loot-core build:browser]
    I --> J[desktop-client build:browser]
    J --> K[ビルドパス表示]
    K --> L[バッチ終了]
```

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

### 障害時対応

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

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

該当なし。

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回（ビルド） |
| 目標処理時間 | 数分〜十数分 |
| メモリ使用量上限 | 4096MB（NODE_OPTIONS設定） |

## 排他制御

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 進捗ログ | 各ステップ | 「Updating translations...」等 |
| ビルドログ | 各ワークスペースビルド時 | webpack/vite出力 |
| 完了ログ | バッチ終了時 | 「packages/desktop-client/build」 |

## 監視・アラート

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

## 備考

- 実行コマンド: `./bin/package-browser`
- スクリプト種別: Bashスクリプト（-eオプションでエラー時停止）
- 翻訳リポジトリ: https://github.com/actualbudget/translations
- ビルド出力は`packages/desktop-client/build`ディレクトリに生成
- sync-serverの静的ファイル配信機能でこのビルド出力を配信可能
- NODE_OPTIONS環境変数でV8ヒープサイズを4096MBに制限（大規模プロジェクトのビルドに必要）
