# バッチ設計書 42-update

## 概要

本ドキュメントは、InvenTreeインストールを総合的に更新するinvokeタスク「update」の設計書です。

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

**業務上の目的・背景**：InvenTreeのソースコードを更新した後、システムを新しいバージョンに合わせて完全にアップデートする必要があります。このバッチは、依存パッケージのインストール、データベースバックアップ、マイグレーション、フロントエンドのビルド/ダウンロード、静的ファイルの収集、古い設定のクリーンアップを一括で実行し、手動での複雑な更新手順を自動化します。

**バッチの実行タイミング**：GitHubから新しいコードをダウンロードした後、またはInvenTreeのバージョンアップ時に手動で実行します。

**主要な処理内容**：
1. `install`タスクで必要なPythonパッケージをインストール
2. `backup`タスクでデータベースとメディアファイルをバックアップ（オプション）
3. `migrate`タスクでデータベースマイグレーションを実行
4. フロントエンドのコンパイルまたはダウンロード（環境に応じて自動判定）
5. `static`タスクで静的ファイルを収集
6. `clean_settings`タスクで古い設定をクリーンアップ（後処理として自動実行）

**前後の処理との関連**：このタスクは複数の主要タスク（install, backup, migrate, frontend_compile/frontend_download, static, clean_settings）を適切な順序で呼び出すオーケストレーションタスクです。本番環境でのアップデート作業の中心となります。

**影響範囲**：システム全体に影響します。Pythonパッケージ、データベース、フロントエンドアセット、静的ファイル、システム設定のすべてが更新対象となります。

## バッチ種別

システム更新 / オーケストレーション

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（バージョンアップ時） |
| 実行時刻 | 任意（メンテナンス時間帯を推奨） |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ソースコード更新 | 新しいソースコードがダウンロード済みであること |
| Python環境 | 正しいPython仮想環境がアクティブであること |
| データベース接続 | データベースへの接続が確立されていること |
| ディスク容量 | バックアップ用の十分なディスク容量があること |

### 実行可否判定

特別な実行可否判定はありません。前提条件が満たされていれば実行可能です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| skip_backup | bool | No | False | データベースバックアップをスキップする |
| frontend | bool | No | False | INVENTREE_DOCKER環境でもフロントエンドのコンパイル/ダウンロードを強制する |
| no_frontend | bool | No | False | フロントエンドのコンパイル/ダウンロードをスキップする |
| skip_static | bool | No | False | 静的ファイルの収集をスキップする |
| uv | bool | No | False | UVパッケージマネージャーを使用する（実験的） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| ソースコード | Python | 更新されたInvenTreeソースコード |
| requirements.txt | テキスト | Python依存パッケージリスト |
| plugins.txt | テキスト | プラグインリスト |
| データベース | DB | 既存のInvenTreeデータ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Python環境 | パッケージ | 更新されたPythonパッケージ |
| データベース | DB | マイグレーション済みのスキーマとデータ |
| バックアップファイル | 圧縮ファイル | データベースとメディアのバックアップ |
| 静的ファイル | ファイル群 | STATIC_ROOTに収集されたファイル |
| フロントエンド | ビルド済みアセット | コンパイルまたはダウンロードされたフロントエンド |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| バックアップファイル名 | 日時ベースの命名規則（dbbackup/mediabackupコマンドに依存） |
| 出力先 | 設定されたバックアップディレクトリ |
| 文字コード | 該当なし |
| 区切り文字 | 該当なし |

## 処理フロー

### 処理シーケンス

```
1. install実行
   └─ 必要なPythonパッケージとプラグインをインストール

2. backup実行（skip_backup=Falseの場合）
   └─ データベースとメディアファイルをバックアップ

3. migrate実行
   └─ データベースマイグレーションを実行
   └─ 後処理でrebuild_modelsとrebuild_thumbnailsも実行

4. フロントエンド更新（条件付き）
   ├─ INVENTREE_DOCKER環境でfrontend=Falseの場合：スキップ
   ├─ no_frontend=Trueの場合：スキップ
   ├─ node/yarnが利用可能な場合：frontend_compile実行
   └─ それ以外：frontend_download実行

5. static実行（skip_static=Falseの場合）
   └─ 静的ファイルをSTATIC_ROOTに収集

6. clean_settings実行（後処理として自動実行）
   └─ データベースから古い設定をクリーンアップ
```

### フローチャート

```mermaid
flowchart TD
    A[update開始] --> B[install]
    B --> C{skip_backup?}
    C -->|No| D[backup]
    C -->|Yes| E[migrate]
    D --> E
    E --> F{Docker環境かつfrontend=False?}
    F -->|Yes| G{no_frontend?}
    F -->|No| H{node_available?}
    G -->|Yes| I[フロントエンドスキップ]
    G -->|No| H
    H -->|Yes| J[frontend_compile]
    H -->|No| K[frontend_download]
    J --> L{skip_static?}
    K --> L
    I --> L
    L -->|No| M[static]
    L -->|Yes| N[clean_settings]
    M --> N
    N --> O[update完了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| migrate | 全テーブル | ALTER/CREATE/DROP | スキーマ変更 |
| clean_settings | InvenTreeSetting, InvenTreeUserSetting | DELETE | 古い設定の削除 |

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

#### InvenTreeSetting / InvenTreeUserSetting

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | 未定義の古い設定キー | clean_settingsタスクで実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ModuleNotFoundError | 必要なパッケージが見つからない | install実行を確認 |
| - | OperationalError | データベース接続失敗 | データベースサーバーの起動確認 |
| - | FileNotFoundError | requirements.txtが見つからない | ファイルパスの確認 |
| - | UnexpectedExit | サブコマンド実行失敗 | エラーログを確認して個別に対処 |

### リトライ仕様

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

### 障害時対応

1. install失敗：依存パッケージの問題を解決してから再実行
2. backup失敗：ディスク容量を確認し、必要に応じて古いバックアップを削除
3. migrate失敗：バックアップから復元して問題を調査
4. frontend失敗：frontend_downloadを--fileオプションで手動実行
5. static失敗：ディレクトリ権限を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 各サブタスク単位 |
| コミットタイミング | 各サブタスク完了時 |
| ロールバック条件 | サブタスク実行中のエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | タスク数に依存 |
| 目標処理時間 | 環境とデータ量に依存（通常5〜30分） |
| メモリ使用量上限 | 通常のDjango動作範囲内 |

## 排他制御

- 同時実行は禁止
- migrateタスク実行中はメンテナンスモードでアクセスをブロック
- 複数インスタンス環境では、1つのインスタンスのみでupdateを実行すること

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | "Updating InvenTree installation..." |
| 進捗ログ | 各サブタスク実行時 | 各タスクの実行状況 |
| 終了ログ | バッチ終了時 | "InvenTree update complete!" |
| エラーログ | エラー発生時 | エラー詳細とスタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行時間 | 環境依存（30分以上で警告） | システム管理者 |
| エラー発生 | 1件以上 | システム管理者 |

## 備考

- `@state_logger('TASK03')`デコレータにより、デバッグモード時は実行状態がログ出力される
- `post=[clean_settings]`により、update完了後にclean_settingsが自動実行される
- Docker環境（INVENTREE_DOCKER環境変数がTrue）ではフロントエンド更新がデフォルトでスキップされる
- `--frontend`フラグでDocker環境でもフロントエンド更新を強制可能
- フロントエンドのコンパイルにはnode.jsとyarnが必要。利用不可の場合は自動的にダウンロードを試行
- UVパッケージマネージャー（`--uv`オプション）は実験的機能
