# バッチ設計書 18-DownloadApiBaselinePackages

## 概要

本ドキュメントは、API比較用のベースラインNuGetパッケージをダウンロード・展開するNukeビルドターゲット「DownloadApiBaselinePackages」の設計仕様を記載したものです。

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

DownloadApiBaselinePackagesターゲットは、現在のバージョンのAPIを過去のバージョンと比較するために、ベースラインとなるNuGetパッケージをNightlyフィードからダウンロードし、アセンブリを展開するバッチ処理です。

**業務上の目的・背景**：APIの後方互換性を維持することは、フレームワーク開発において極めて重要です。破壊的変更がリリースされると、既存のユーザーアプリケーションが動作しなくなる可能性があります。本バッチは、API互換性検証の前準備として、比較対象となるベースラインパッケージをダウンロードし、ValidateApiDiffおよびOutputApiDiffターゲットでの差分検出を可能にします。

**バッチの実行タイミング**：CreateNugetPackagesターゲット完了後に実行されます。ValidateApiDiffおよびOutputApiDiffターゲットの前提条件となります。

**主要な処理内容**：
1. ベースラインバージョンの決定（リリースブランチでは最新安定版、それ以外では最新Nightly版）
2. NuGetフィードからベースラインパッケージのダウンロード
3. 現在のパッケージとベースラインパッケージからアセンブリを展開
4. 各フレームワーク別にアセンブリをマッピング
5. 欠落しているアセンブリの空アセンブリ生成

**前後の処理との関連**：CreateNugetPackagesターゲットに依存しています。生成されたGlobalDiff情報はValidateApiDiffおよびOutputApiDiffターゲットで使用されます。

**影響範囲**：artifacts/api-diff/assemblies/ディレクトリにベースラインと現在のアセンブリが展開されます。GlobalDiffプロパティが設定され、後続のAPI差分処理で参照されます。

## バッチ種別

データ取得 / API互換性検証準備

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（CI/CDパイプライン実行時） |
| 実行時刻 | 指定なし |
| 実行曜日 | 指定なし |
| 実行日 | 指定なし |
| トリガー | CreateNugetPackages完了後 / 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| CreateNugetPackages完了 | 現在のNuGetパッケージが生成されていること |
| ネットワーク接続 | NuGetフィードへのアクセスが可能であること |
| 比較可能なバージョン | ベースラインバージョンがNuGetフィードに存在すること |

### 実行可否判定

- DependsOnでCreateNugetPackagesターゲットに依存
- 明示的な条件チェックはなく、依存関係が満たされれば実行可能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| configuration | string | No | Release | ビルド構成（Debug/Release） |
| force-api-baseline | string | No | null | 強制指定するベースラインバージョン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| artifacts/nuget/*.nupkg | NuGetパッケージ | 現在のビルドのパッケージ |
| NuGet Nightly Feed | NuGetフィード | ベースラインパッケージのダウンロード元 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| artifacts/api-diff/assemblies/baseline/ | DLL | ベースラインアセンブリ |
| artifacts/api-diff/assemblies/current/ | DLL | 現在のアセンブリ |
| GlobalDiffプロパティ | オブジェクト | 差分情報（バージョン、パッケージ情報） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {パッケージID}/lib/{フレームワーク}/*.dll |
| 出力先 | artifacts/api-diff/assemblies/ |
| 文字コード | バイナリ |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. CreateNugetPackages依存関係の確認
   └─ 現在のパッケージ存在確認
2. api-diffディレクトリのクリーンアップ
   └─ 既存データの削除
3. NuGetダウンロードコンテキスト作成
   └─ Nightlyフィードへの接続設定
4. ベースラインバージョン決定
   └─ リリースブランチ: 最新安定版
   └─ その他: 最新Nightly版
   └─ または force-api-baseline で指定
5. 各パッケージの処理
   └─ 現在のパッケージからアセンブリ展開
   └─ ベースラインパッケージのダウンロード
   └─ ベースラインからアセンブリ展開
   └─ フレームワーク別マッピング
   └─ 欠落アセンブリの空アセンブリ生成
6. GlobalDiff情報の設定
   └─ 後続ターゲットで使用
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[api-diffディレクトリクリア]
    B --> C[NuGetコンテキスト作成]
    C --> D[ベースラインバージョン決定]
    D --> E{各パッケージループ}
    E --> F[現在パッケージ展開]
    F --> G{ベースライン存在?}
    G -->|Yes| H[ベースラインダウンロード]
    G -->|No| I[空として扱う]
    H --> J[ベースライン展開]
    I --> J
    J --> K[フレームワークマッチング]
    K --> L[欠落アセンブリ生成]
    L --> M{次のパッケージ?}
    M -->|Yes| E
    M -->|No| N[GlobalDiff設定]
    N --> O[バッチ終了]
```

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

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

本バッチはデータベース操作を行いません。

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

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

データベース操作は行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NetworkError | ネットワークエラー | NuGetフィードへの接続失敗 | ネットワーク設定の確認 |
| PackageNotFound | パッケージ未発見 | ベースラインパッケージが存在しない | バージョン指定の確認または新パッケージとして扱う |
| VersionNotFound | バージョン未発見 | 比較可能なバージョンが見つからない | force-api-baselineで明示指定 |
| ExtractionFailed | 展開失敗 | ZIPアーカイブの展開エラー | パッケージの整合性確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | NuGetクライアントのデフォルト設定に依存 |
| リトライ間隔 | NuGetクライアントのデフォルト設定に依存 |
| リトライ対象エラー | ネットワーク一時エラー |

### 障害時対応

1. ネットワークエラーの場合：NuGetフィードのURLとネットワーク接続を確認
2. パッケージ未発見の場合：新規パッケージとして扱い、空のベースラインで比較
3. バージョン決定失敗の場合：force-api-baselineパラメータで明示的にバージョン指定

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十パッケージ |
| 目標処理時間 | ネットワーク速度に依存（5-10分） |
| メモリ使用量上限 | パッケージ展開に必要なメモリ |

## 排他制御

- 同一マシン上での複数実行は推奨されない
- NuGetキャッシュへのアクセスが必要
- CI環境では各ジョブが独立したワークスペースで実行

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 処理開始時 | "API baseline version is {Baseline} for current version {Current}" |
| 進捗ログ | 各パッケージダウンロード時 | "Downloading {Id} {Version} baseline package" |
| 情報ログ | 新規パッケージ検出時 | "Baseline package {Id} {Version} does not exist. Assuming new package." |
| エラーログ | エラー発生時 | エラー詳細情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 20分 | Azure Pipelines通知 |
| ダウンロード失敗 | 1件以上 | 手動確認 |

## 備考

- NuGet Nightly FeedのURL: https://nuget-feed-nightly.avaloniaui.net/v3/index.json
- ベースラインバージョン決定ロジック:
  - リリースブランチ: 現在バージョン未満の最新安定版（非プレリリース）
  - その他（main、PR）: 現在バージョン未満の最新版（プレリリース含む）
- プラットフォームバージョン（net8.0-android34.0等）は無視して比較（net8.0-androidとして扱う）
- 片方にしか存在しないアセンブリは空アセンブリを生成して比較対象に含める
- 非同期処理（async/await）で実装されている
