# バッチ設計書 17-services.install

## 概要

本ドキュメントは、Shopwareプラットフォームにおけるサービスインストールバッチの設計仕様を定義します。Shopwareのセルフマネージドサービス（アプリとして提供される機能）を自動的にインストールします。

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

**業務上の目的・背景**：Shopwareはクラウドベースのサービス連携機能を提供しており、店舗運営をサポートする各種サービス（バックアップ、分析、マーケティング支援等）がアプリとして利用可能です。これらのサービスは「セルフマネージドサービス」として、Shopwareが自動的にインストール・管理します。本バッチはサービスレジストリから利用可能なサービスを取得し、まだインストールされていないサービスを自動的にインストールすることで、店舗運営者が最新のサービスを手間なく利用できるようにします。

**バッチの実行タイミング**：日次（86400秒間隔）でスケジュール実行されます。

**主要な処理内容**：
1. CLIコンテキストを作成
2. LifecycleManagerのinstallメソッドを呼び出し
3. サービス機能が有効かを確認
4. 有効な場合、AllServiceInstallerでサービスをインストール

**前後の処理との関連**：前提として、サービス機能が有効化されている必要があります（環境設定または設定画面で有効化）。app_updateタスクとは異なり、既存アプリの更新ではなく新規サービスのインストールを担当します。

**影響範囲**：appテーブルへの新規レコード挿入、関連する権限設定（acl_role）、インテグレーション設定（integration）の作成が行われます。サービスレジストリへのHTTP通信が発生します。

## バッチ種別

システム更新 / サービス連携

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次 |
| 実行時刻 | スケジュールタスクランナーに依存 |
| 実行曜日 | 毎日 |
| 実行日 | - |
| トリガー | cron（スケジュールタスク） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| サービス機能有効 | LifecycleManager.enabled()がtrueを返すこと |
| 環境設定 | shopware.services.enabled または appEnv === 'prod' |
| 設定無効化なし | core.services.disabledがfalseまたは未設定 |

### 実行可否判定

1. `LifecycleManager.enabled()`でサービス機能の有効性を確認
2. 環境変数`shopware.services.enabled`が'auto'の場合は`appEnv === 'prod'`で判定
3. `core.services.disabled`システム設定がtrueの場合は無効

## 入力仕様

### 入力パラメータ

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

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| サービスレジストリ | HTTP | 利用可能なサービス一覧 |
| app | DB | インストール済みアプリ情報 |
| system_config | DB | サービス無効化設定 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| app | DB | 新規インストールされたサービス（アプリ） |
| acl_role | DB | サービスの権限設定 |
| integration | DB | サービスのインテグレーション設定 |

### 出力ファイル仕様

ファイル出力はありません。

## 処理フロー

### 処理シーケンス

```
1. タスクハンドラー実行
   └─ LifecycleManager.install()呼び出し
2. サービス有効性確認
   └─ enabled()メソッドで確認
3. 環境設定確認
   └─ 環境変数とシステム設定をチェック
4. サービスインストール
   └─ AllServiceInstaller.install()でサービスをインストール
5. 新規インストール通知
   └─ NewServicesInstalledEventを発火（新規インストールがあった場合）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[CLIコンテキスト作成]
    B --> C[LifecycleManager.install呼び出し]
    C --> D{enabled?}
    D -->|No| Z[空配列返却]
    D -->|Yes| E[AllServiceInstaller.install呼び出し]
    E --> F[サービスレジストリ取得]
    F --> G{新規サービス?}
    G -->|No| H[バッチ終了]
    G -->|Yes| I[サービスインストール]
    I --> J[NewServicesInstalledEvent発火]
    J --> H
    Z --> H
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| インストール済み確認 | app | SELECT | selfManaged = trueのアプリ取得 |
| サービスインストール | app | INSERT | 新規サービスの登録 |
| 権限設定 | acl_role | INSERT | サービスの権限設定 |
| インテグレーション設定 | integration | INSERT | サービスのインテグレーション |
| 設定確認 | system_config | SELECT | サービス無効化設定 |

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

#### app

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | selfManaged = true | インストール済みサービス |
| INSERT | name, version, selfManaged等 | サービスレジストリから取得した情報 | 新規サービス |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ネットワークエラー | 接続エラー | サービスレジストリ接続失敗 | ネットワーク確認、再試行 |
| インストール失敗 | アプリエラー | サービスインストール処理失敗 | ログ確認、手動対応 |
| サービス無効 | 設定エラー | サービス機能が無効化されている | 設定確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 失敗時再スケジュール有効 |
| リトライ間隔 | 次回スケジュール実行時 |
| リトライ対象エラー | 全般的なエラー |

### 障害時対応

1. エラーログを確認し原因を特定
2. サービスレジストリへの接続を確認
3. サービス機能の有効化設定を確認
4. 手動でサービスインストールを実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | サービス単位 |
| コミットタイミング | 各サービスインストール完了時 |
| ロールバック条件 | サービスインストール失敗時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜数十件（新規サービス数） |
| 目標処理時間 | 数秒〜数分（ネットワーク速度依存） |
| メモリ使用量上限 | 通常のPHP制限に準拠 |

## 排他制御

特別な排他制御は実装されていません。サービスインストールはアプリライフサイクル層で管理されます。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | タスク開始時 | タスク開始通知 |
| 進捗ログ | サービスインストール時 | サービス名 |
| 終了ログ | タスク終了時 | 処理完了通知、インストール件数 |
| エラーログ | エラー発生時 | エラー詳細、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 600秒 | システム管理者 |
| エラー件数 | 1件以上 | システム管理者 |

## 備考

- 内部使用タスク（@internal）として定義されています
- サービスは「セルフマネージドアプリ」として実装されており、通常のアプリとは異なる管理ライフサイクルを持ちます
- サービス機能の有効化は環境変数（`shopware.services.enabled`）または自動判定（prod環境で自動有効化）で制御されます
- `core.services.disabled`システム設定でサービス機能を無効化できます
- 新規サービスがインストールされた場合、NewServicesInstalledEventが発火され、通知などの後処理をトリガーできます
- LifecycleManagerはサービスの有効化（enable）、無効化（disable）、開始（start）、停止（stop）などの全ライフサイクルを管理します
