# 機能設計書 7-Compare-DbaAgReplicaOperator

## 概要

本ドキュメントは、dbatools PowerShellモジュールのCompare-DbaAgReplicaOperator機能の設計仕様を定義する。本機能は、可用性グループ（AG）の全レプリカ間でSQL Agentオペレーターの構成を比較し、不整合を検出する。

### 本機能の処理概要

Compare-DbaAgReplicaOperatorは、可用性グループに参加しているすべてのレプリカ間でSQL Agentオペレーターの構成を比較し、差異を特定するPowerShellコマンドである。オペレーターはアラート通知の宛先であり、サーバーレベルで定義されるため、AGによる自動同期は行われない。

**業務上の目的・背景**：SQL Agentオペレーターは、ジョブ失敗やアラート発生時の通知先を定義する。フェイルオーバー後にオペレーターが存在しない場合、重要なアラートが通知されず、障害の検知が遅れる可能性がある。本機能は、オペレーター構成の不整合を事前に検出し、運用監視の信頼性を確保する。

**機能の利用シーン**：
- フェイルオーバー前の通知構成確認
- オペレーター変更後の全レプリカへの適用検証
- 定期的な運用監視構成の監査
- トラブルシューティング時の構成差異分析

**主要な処理内容**：
1. 可用性グループとレプリカの取得
2. 各レプリカからオペレーター情報の収集
3. 全オペレーター名のユニオンリスト作成
4. 各オペレーターについてレプリカ間の存在・メールアドレス比較
5. 差異の出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- SQL Server Agent
- メールシステム（SMTP）

**権限による制御**：
- 各レプリカへの接続権限
- SQL Agentオペレーターの参照権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | AGレプリカ管理 | 補助機能 | レプリカ間のオペレーター比較 |

## 機能種別

比較/検証処理 / 運用監視構成監査

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | パイプライン対応 |
| SqlCredential | PSCredential | No | SQL Server接続用認証情報 | - |
| AvailabilityGroup | string[] | No | 可用性グループ名フィルタ | - |
| EnableException | switch | No | 例外有効化 | - |

### 入力データソース

- SQL Serverインスタンスへの直接接続
- パイプライン経由のインスタンス指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AvailabilityGroup | string | 可用性グループ名 |
| Replica | string | レプリカインスタンス名 |
| OperatorName | string | オペレーター名 |
| Status | string | 状態（Present/Missing） |
| EmailAddress | string | メールアドレス |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- 差異がある場合のみ出力

## 処理フロー

### 処理シーケンス

```
1. インスタンス接続
   └─ Connect-DbaInstance（MinimumVersion 11）

2. HADR有効確認
   └─ IsHadrEnabledチェック

3. 可用性グループ取得
   └─ AvailabilityGroupパラメータでフィルタ

4. 各AGについてレプリカ一覧取得
   └─ 2レプリカ未満は比較スキップ

5. 各レプリカからオペレーター収集
   └─ Connect-DbaInstance（各レプリカ）
   └─ Get-DbaAgentOperator

6. 全オペレーター名のユニオンリスト作成

7. 各オペレーターについて差異検出
   └─ レプリカに存在しない場合: Missing
   └─ EmailAddress比較（異なれば出力）

8. 結果出力
   └─ Missing または EmailAddress差異がある場合
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{HADR有効?}
    C -->|No| Z1[エラー: HADR未構成]
    C -->|Yes| D[可用性グループ取得]
    D --> E{AG存在?}
    E -->|No| Z2[エラー: AG見つからず]
    E -->|Yes| F[各AGをループ]
    F --> G{レプリカ数>=2?}
    G -->|No| H[比較スキップ]
    G -->|Yes| I[レプリカ一覧取得]
    H --> F
    I --> J[各レプリカからオペレーター収集]
    J --> K[全オペレーター名ユニオン]
    K --> L[各オペレーターをループ]
    L --> M[各レプリカをループ]
    M --> N{オペレーター存在?}
    N -->|No| O[Missing記録]
    N -->|Yes| P[Present+EmailAddress記録]
    O --> M
    P --> M
    M --> Q{差異あり?}
    Q -->|Yes| R[結果出力]
    Q -->|No| L
    R --> L
    L --> S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | SQLバージョン要件 | SQL Server 2012以上が必要 | 常時 |
| BR-02 | HADR必須 | HADRが有効でない場合はエラー | 常時 |
| BR-03 | 最小レプリカ数 | 2レプリカ未満は比較対象外 | 常時 |
| BR-04 | 差異時のみ出力 | Missing または EmailAddress差異時 | 常時 |

### 計算ロジック

- 特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| オペレーター取得 | msdb.dbo.sysoperators | SELECT | オペレーター一覧取得 |

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

#### msdb.dbo.sysoperators

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name | - | オペレーター名 |
| SELECT | email_address | - | メールアドレス |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | 接続情報確認 |
| - | HADRError | HADRが有効でない | HADR有効化確認 |
| - | NoAGError | 指定AGが見つからない | AG名確認 |
| - | ReplicaError | レプリカ接続失敗 | レプリカ接続確認 |

### リトライ仕様

- 本機能にリトライロジックは実装されていない

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

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

## パフォーマンス要件

- 各レプリカへの接続と取得に時間を要する
- オペレーター数は通常少ないため高速

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

- オペレーターのメールアドレスは参照可能
- SQL Agent参照権限が必要

## 備考

- Get-DbaAgentOperatorを使用してオペレーターを取得

---

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

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

### 推奨読解順序

#### Step 1: データ構造を理解する

パラメータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | param()ブロック（64-71行目） |

#### Step 2: メイン処理フローを理解する

接続からAG取得までの流れを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | 接続とHADRチェック（74-84行目） |
| 2-2 | Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | AG取得とフィルタ（86-94行目） |

**主要処理フロー**:
1. **76行目**: Connect-DbaInstance（MinimumVersion 11）
2. **81-83行目**: IsHadrEnabled確認

#### Step 3: オペレーター収集ロジックを理解する

各レプリカからのオペレーター収集を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | レプリカループとオペレーター収集（110-130行目） |

**主要処理フロー**:
- **118行目**: Get-DbaAgentOperatorでオペレーター取得
- **122-125行目**: allOperatorNamesへの追加

#### Step 4: 差異検出ロジックを理解する

オペレーターの存在チェックとEmailAddress比較を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | 差異検出ループ（132-168行目） |

**主要処理フロー**:
- **138-145行目**: Missing検出
- **146-153行目**: Present+EmailAddress記録
- **157-166行目**: 差異判定（Missing or EmailAddress差異）

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

```
Compare-DbaAgReplicaOperator
    │
    ├─ Connect-DbaInstance (初期接続)
    │
    ├─ server.AvailabilityGroups (AG取得)
    │
    ├─ ag.AvailabilityReplicas (レプリカ取得)
    │
    └─ 各レプリカについて
           ├─ Connect-DbaInstance (レプリカ接続)
           └─ Get-DbaAgentOperator (オペレーター取得)
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
AvailabilityGroup ────────▶ AG取得・フィルタ
                                  │
                          各レプリカ接続
                          オペレーター収集
                                  │
                          全オペレーター名ユニオン
                                  │
                          差異検出
                          (Missing/EmailAddress比較)
                                  │
                          PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Compare-DbaAgReplicaOperator.ps1 | `public/Compare-DbaAgReplicaOperator.ps1` | ソース | メインコマンド実装 |
| Get-DbaAgentOperator.ps1 | `public/Get-DbaAgentOperator.ps1` | ソース | オペレーター取得 |
