# バッチ設計書 20-OutputApiDiff

## 概要

本ドキュメントは、API差分をMarkdown形式で出力するNukeビルドターゲット「OutputApiDiff」の設計仕様を記載したものです。

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

OutputApiDiffターゲットは、Microsoft.DotNet.ApiDiff.Toolを使用して、現在のビルドとベースラインバージョン間のAPI差分をMarkdown形式で出力し、人間が読みやすいドキュメントとして生成するバッチ処理です。

**業務上の目的・背景**：APIの変更内容を開発者やリリースマネージャーが理解しやすい形式で提供することは、リリースノートの作成やAPI変更のレビューに不可欠です。本バッチは、ValidateApiDiffによる機械的な互換性チェックを補完し、API変更の内容を視覚的に確認できるMarkdownドキュメントを生成します。これにより、リリース前のレビューや変更履歴の追跡が容易になります。

**バッチの実行タイミング**：DownloadApiBaselinePackagesターゲット完了後に実行されます。ValidateApiDiffとは独立して実行可能ですが、同じGlobalDiff情報を使用します。

**主要な処理内容**：
1. GlobalDiff情報から各パッケージの差分情報を取得
2. 各フレームワーク別にApiDiffToolを並列実行
3. フレームワーク別のMarkdownファイルをマージ
4. パッケージ別のMarkdownファイルを統合ファイルにマージ
5. 最終的な_diff.mdファイルの生成

**前後の処理との関連**：DownloadApiBaselinePackagesターゲットに依存しています。出力されたMarkdownファイルはCI成果物として保存され、リリースドキュメントの一部として使用されます。

**影響範囲**：artifacts/api-diff/markdown/ディレクトリにMarkdownファイルが出力されます。このディレクトリにはアセンブリ別のファイルと統合された_diff.mdが含まれます。

## バッチ種別

ドキュメント生成 / API変更レポート

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| DownloadApiBaselinePackages完了 | ベースラインと現在のアセンブリが展開されていること |
| GlobalDiff設定済み | 差分情報が利用可能であること |
| Microsoft.DotNet.ApiDiff.Tool | ApiDiffツールが利用可能であること |

### 実行可否判定

- DependsOnでDownloadApiBaselinePackagesターゲットに依存
- GlobalDiffプロパティが設定されていること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| configuration | string | No | Release | ビルド構成（Debug/Release） |

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| artifacts/api-diff/markdown/{Assembly}.md | Markdown | アセンブリ別の差分ドキュメント |
| artifacts/api-diff/markdown/_diff.md | Markdown | 統合された差分ドキュメント |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {AssemblyName}.md / _diff.md |
| 出力先 | artifacts/api-diff/markdown/ |
| 文字コード | UTF-8 |
| 形式 | Markdown |

## 処理フロー

### 処理シーケンス

```
1. DownloadApiBaselinePackages依存関係の確認
   └─ GlobalDiffの存在確認
2. 出力ディレクトリの設定
   └─ artifacts/api-diff/markdown/の準備
3. 各パッケージの並列処理
   └─ Parallel.ForEachによる並列実行
4. 各パッケージの差分生成
   └─ GenerateMarkdownDiffメソッド呼び出し
5. 各フレームワークの並列処理
   └─ ApiDiffToolの並列実行
6. フレームワーク別ファイルのマージ
   └─ 同一内容のフレームワークはグループ化
7. パッケージ別ディレクトリのクリーンアップ
   └─ 一時ディレクトリの削除
8. 全パッケージのマージ
   └─ MergePackageMarkdownDiffFilesで統合
9. _diff.mdファイルの生成
   └─ 最終統合ドキュメントの出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[GlobalDiff確認]
    B --> C[出力ディレクトリ設定]
    C --> D{各パッケージ並列処理}
    D --> E[一時ファイル準備]
    E --> F{各フレームワーク並列}
    F --> G[ApiDiffTool実行]
    G --> H[Markdown生成]
    H --> I{次のフレームワーク?}
    I -->|Yes| F
    I -->|No| J[フレームワークファイルマージ]
    J --> K[パッケージディレクトリ削除]
    K --> L{次のパッケージ?}
    L -->|Yes| D
    L -->|No| M[全パッケージファイルマージ]
    M --> N[_diff.md生成]
    N --> O[バッチ終了]
```

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

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

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

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ToolExecutionFailed | ツール実行失敗 | ApiDiffToolが異常終了 | ツールのインストール確認 |
| GlobalDiffNull | 差分情報なし | DownloadApiBaselinePackagesが失敗 | 前提ターゲットの確認 |
| IOException | IO例外 | ファイル書き込みエラー | ディスク容量・権限確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. ツール実行失敗の場合：Microsoft.DotNet.ApiDiff.Toolの復元を確認
2. メモリ不足の場合：並列度を下げるか、個別に実行
3. ファイル書き込みエラーの場合：出力ディレクトリの権限を確認

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数十パッケージ × 複数フレームワーク |
| 目標処理時間 | CI環境で10分以内（APIサイズに依存） |
| メモリ使用量上限 | ApiDiffToolの要件に依存 |

## 排他制御

- Parallel.ForEachによる並列処理（パッケージレベル、フレームワークレベル）
- 各パッケージ/フレームワークは独立して処理
- 最終マージ処理は順次実行

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各パッケージ処理開始時 | "Creating markdown diff for package {Id}" |
| エラーログ | ツール実行エラー時 | 詳細なエラーメッセージ |
| 終了ログ | 処理完了時 | 生成されたファイル情報 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 20分 | Azure Pipelines通知 |
| ファイル生成エラー | 1件以上 | 手動確認 |

## 備考

- Microsoft.DotNet.ApiDiff.Tool（net8.0版）を使用
- ApiDiffToolは非常に遅いため、フレームワークレベルでも並列処理を実行
- 一時ファイル（AttributesToExclude.txt）の空ファイルを作成してツールのバグを回避
- 同一内容の差分を持つフレームワークは1つのエントリにグループ化（SHA256ハッシュで比較）
- 最終出力の_diff.mdには「# API diff between {baseline} and {current}」のヘッダーが付与
- 変更がない場合は「No changes.」と出力
- api_diff_プレフィックスは最終ファイル名から削除される
- 各アセンブリのMarkdownにはフレームワーク情報（net8.0, netstandard2.0等）が括弧付きで追記
