# 機能設計書 78-Compare-DbaAvailabilityGroup

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Compare-DbaAvailabilityGroup` コマンドレットに関する機能設計書です。このコマンドは、可用性グループレプリカ間でジョブ、ログイン、資格情報、オペレーターの構成差異を比較します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server可用性グループ（AG）環境では、フェイルオーバー後もアプリケーションが正常に動作するために、全レプリカ間でサーバーレベルオブジェクト（ジョブ、ログイン、資格情報、オペレーター）が同期されている必要があります。本機能は、レプリカ間の構成差異を検出し、運用上の問題を未然に防ぐための包括的な比較ツールを提供します。

**機能の利用シーン**：
- 新しいレプリカ追加後の構成検証
- ジュニアDBAによる変更適用の確認
- 定期的な構成監査と整合性チェック
- フェイルオーバーテスト前の準備確認
- 構成ドリフト問題のトラブルシューティング

**主要な処理内容**：
1. 指定されたAGの全レプリカを取得
2. 比較タイプに基づいて内部コマンドを呼び出し
   - AgentJob: Compare-DbaAgReplicaAgentJob
   - Login: Compare-DbaAgReplicaLogin
   - Credential: Compare-DbaAgReplicaCredential
   - Operator: Compare-DbaAgReplicaOperator
3. 差異情報の収集と出力

**関連システム・外部連携**：Compare-DbaAgReplica*コマンド群を内部で呼び出し

**権限による制御**：各レプリカに対するVIEW SERVER STATE権限または適切なログイン権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | 可用性グループ管理 | 補助機能 | 可用性グループレプリカ間の構成比較 |

## 機能種別

構成比較 / 監査 / 可用性グループ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows/SQL認証対応 |
| AvailabilityGroup | string[] | No | 比較対象AG名 | 複数指定可能 |
| Type | string[] | No | 比較タイプ | AgentJob/Login/Credential/Operator/All |
| ExcludeSystemJob | switch | No | システムジョブを除外 | AgentJob比較時のみ |
| ExcludeSystemLogin | switch | No | システムログインを除外 | Login比較時のみ |
| IncludeModifiedDate | switch | No | 変更日時を比較に含める | AgentJob/Login比較時 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

出力はTypeパラメータの値によって異なります。

#### AgentJob比較時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | string | AG名 |
| Replica | string | レプリカのインスタンス名 |
| JobName | string | ジョブ名 |
| Status | string | ステータス（Present/Missing） |
| DateLastModified | datetime | 最終更新日時（IncludeModifiedDate時） |

#### Login比較時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | string | AG名 |
| Replica | string | レプリカのインスタンス名 |
| LoginName | string | ログイン名 |
| Status | string | ステータス（Present/Missing） |
| ModifyDate | datetime | 変更日時（IncludeModifiedDate時） |
| CreateDate | datetime | 作成日時 |

#### Credential比較時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | string | AG名 |
| Replica | string | レプリカのインスタンス名 |
| CredentialName | string | 資格情報名 |
| Status | string | ステータス（Present/Missing） |
| Identity | string | 資格情報のID |

#### Operator比較時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | string | AG名 |
| Replica | string | レプリカのインスタンス名 |
| OperatorName | string | オペレーター名 |
| Status | string | ステータス（Present/Missing） |
| EmailAddress | string | メールアドレス |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- 差異がない場合は出力なし

## 処理フロー

### 処理シーケンス

```
1. processブロック：Typeパラメータの展開
   └─ "All"の場合は全タイプ（AgentJob, Login, Credential, Operator）に展開
2. 各インスタンスに対する処理
3. AgentJob比較の実行（Type含む場合）
   └─ Compare-DbaAgReplicaAgentJobを呼び出し
4. Login比較の実行（Type含む場合）
   └─ Compare-DbaAgReplicaLoginを呼び出し
5. Credential比較の実行（Type含む場合）
   └─ Compare-DbaAgReplicaCredentialを呼び出し
6. Operator比較の実行（Type含む場合）
   └─ Compare-DbaAgReplicaOperatorを呼び出し
7. 各比較結果をパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Type = All?}
    B -->|Yes| C[Type = AgentJob, Login, Credential, Operator]
    B -->|No| D[指定されたType使用]
    C --> E[各インスタンスループ]
    D --> E
    E --> F{AgentJob含む?}
    F -->|Yes| G[Compare-DbaAgReplicaAgentJob呼び出し]
    F -->|No| H{Login含む?}
    G --> H
    H -->|Yes| I[Compare-DbaAgReplicaLogin呼び出し]
    H -->|No| J{Credential含む?}
    I --> J
    J -->|Yes| K[Compare-DbaAgReplicaCredential呼び出し]
    J -->|No| L{Operator含む?}
    K --> L
    L -->|Yes| M[Compare-DbaAgReplicaOperator呼び出し]
    L -->|No| N{次のインスタンス?}
    M --> N
    N -->|Yes| E
    N -->|No| O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-78-01 | デフォルトAll | Type未指定時は全タイプを比較 | Type未指定 |
| BR-78-02 | 差異のみ出力 | 全レプリカで同一の項目は出力しない | 常時 |
| BR-78-03 | システム除外 | ExcludeSystemJob/Loginでシステムオブジェクトを除外可能 | 各フラグ指定時 |
| BR-78-04 | 変更日時比較 | IncludeModifiedDateで更新日時の差異も検出 | フラグ指定時 |

### 計算ロジック

- 各内部コマンドが比較ロジックを実装
- 本コマンドはオーケストレーターとして機能

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 比較 | 各種システムビュー | SELECT（読み取り） | レプリカ間の構成比較 |

### 参照されるシステムビュー

- msdb.dbo.sysjobs（ジョブ情報）
- sys.server_principals（ログイン情報）
- sys.credentials（資格情報）
- msdb.dbo.sysoperators（オペレーター情報）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | レプリカに接続できない | 内部コマンドで処理 |
| PermissionError | 権限エラー | 参照権限がない | 内部コマンドで処理 |

### リトライ仕様

- リトライ機能なし（手動で再実行が必要）

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

- 読み取り専用操作のためトランザクション不要

## パフォーマンス要件

- レプリカ数と比較対象オブジェクト数に応じて実行時間が変動
- 大規模環境では特定のTypeのみ指定して実行を推奨

## セキュリティ考慮事項

- 各レプリカに対する適切な参照権限が必要
- SqlCredentialパラメータで安全な認証情報の受け渡しをサポート

## 備考

- 著者: dbatools team
- 関連コマンド: Compare-DbaAgReplicaAgentJob, Compare-DbaAgReplicaLogin, Compare-DbaAgReplicaCredential, Compare-DbaAgReplicaOperator

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: コマンドの全体構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Compare-DbaAvailabilityGroup.ps1 | `public/Compare-DbaAvailabilityGroup.ps1` | 4種類の比較タイプとパラメータの関係性 |

**読解のコツ**: このコマンドはオーケストレーターとして機能し、実際の比較ロジックは内部コマンドに委譲される。

#### Step 2: processブロック - Type展開とディスパッチ

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Compare-DbaAvailabilityGroup.ps1 | `public/Compare-DbaAvailabilityGroup.ps1` | 138-141行目：Allの場合の展開処理 |

**主要処理フロー**:
1. **139-141行目**: "All"を4タイプに展開
2. **143行目**: インスタンスループ開始
3. **144-163行目**: AgentJob比較（splatパターン使用）
4. **165-185行目**: Login比較
5. **187-199行目**: Credential比較
6. **201-213行目**: Operator比較

#### Step 3: splatパターンの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Compare-DbaAvailabilityGroup.ps1 | `public/Compare-DbaAvailabilityGroup.ps1` | 145-149行目, 167-171行目：条件付きsplat構築 |

**読解のコツ**: 各比較コマンドへのパラメータはsplatパターンで構築され、条件に応じてオプションパラメータが追加される。

### プログラム呼び出し階層図

```
Compare-DbaAvailabilityGroup
    │
    ├─ Compare-DbaAgReplicaAgentJob (Type = AgentJob時)
    │      └─ レプリカ間のジョブ比較
    │
    ├─ Compare-DbaAgReplicaLogin (Type = Login時)
    │      └─ レプリカ間のログイン比較
    │
    ├─ Compare-DbaAgReplicaCredential (Type = Credential時)
    │      └─ レプリカ間の資格情報比較
    │
    └─ Compare-DbaAgReplicaOperator (Type = Operator時)
           └─ レプリカ間のオペレーター比較
```

### データフロー図

```
[入力]               [処理]                    [出力]

SqlInstance ───▶ Type展開 ──────────────▶ 比較タイプリスト
                        │
AvailabilityGroup ──▶ 各インスタンスループ
                        │
Type ───────────▶ 条件分岐 ─────────────▶ 内部コマンド呼び出し
    │                   │
    ├─ AgentJob ──────▶ Compare-DbaAgReplicaAgentJob ──▶ ジョブ差異
    ├─ Login ─────────▶ Compare-DbaAgReplicaLogin ─────▶ ログイン差異
    ├─ Credential ────▶ Compare-DbaAgReplicaCredential ▶ 資格情報差異
    └─ Operator ──────▶ Compare-DbaAgReplicaOperator ──▶ オペレーター差異
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Compare-DbaAvailabilityGroup.ps1 | `public/Compare-DbaAvailabilityGroup.ps1` | ソース | メインコマンド実装（オーケストレーター） |
| Compare-DbaAvailabilityGroup.Tests.ps1 | `tests/Compare-DbaAvailabilityGroup.Tests.ps1` | テスト | Pester v5テストファイル |
| Compare-DbaAgReplicaAgentJob.ps1 | `public/Compare-DbaAgReplicaAgentJob.ps1` | ソース | ジョブ比較実装 |
| Compare-DbaAgReplicaLogin.ps1 | `public/Compare-DbaAgReplicaLogin.ps1` | ソース | ログイン比較実装 |
| Compare-DbaAgReplicaCredential.ps1 | `public/Compare-DbaAgReplicaCredential.ps1` | ソース | 資格情報比較実装 |
| Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | ソース | オペレーター比較実装 |
