# 機能設計書 5-Compare-DbaAgReplicaCredential

## 概要

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

### 本機能の処理概要

Compare-DbaAgReplicaCredentialは、可用性グループに参加しているすべてのレプリカ間でSQL Server資格情報の構成を比較し、差異を特定するPowerShellコマンドである。資格情報はサーバーレベルオブジェクトであり、AGによる自動同期は行われないため、手動での管理が必要である。

**業務上の目的・背景**：SQL Server資格情報（Credential）は、外部リソースへのアクセスに使用されるセキュリティプリンシパルである。ジョブのプロキシ、SSIS、バックアップ暗号化などで使用される。フェイルオーバー後に資格情報が存在しない場合、これらの機能が正常に動作しない可能性がある。本機能は、資格情報の不整合を事前に検出する。

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

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

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- Windows Credential Manager連携

**権限による制御**：
- 各レプリカへの接続権限
- 資格情報の参照権限（CONTROL SERVER または ALTER ANY CREDENTIAL）

## 関連画面

| 画面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 | レプリカインスタンス名 |
| CredentialName | string | 資格情報名 |
| Status | string | 状態（Present/Missing） |
| Identity | string | 資格情報のIdentity |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

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

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

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

5. 各レプリカから資格情報収集
   └─ Connect-DbaInstance（各レプリカ）
   └─ Get-DbaCredential

6. 全資格情報名のユニオンリスト作成

7. 各資格情報について差異検出
   └─ レプリカに存在しない場合: Missing
   └─ Identity比較（異なれば出力）

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

### フローチャート

```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+Identity記録]
    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 または Identity差異時 | 常時 |

### 計算ロジック

- 特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 資格情報取得 | master.sys.credentials | SELECT | 資格情報一覧取得 |

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

#### master.sys.credentials

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name | - | 資格情報名 |
| SELECT | credential_identity | - | Identity |

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- 各レプリカへの接続と取得に時間を要する
- 資格情報数に比例した処理時間

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

- 資格情報のパスワードは取得・比較されない
- Identity（プリンシパル名）のみ比較
- 資格情報参照には高い権限が必要

## 備考

- Get-DbaCredentialを使用して資格情報を取得

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **78行目**: Connect-DbaInstance（MinimumVersion 11）
2. **83-85行目**: IsHadrEnabled確認
3. **89-91行目**: AvailabilityGroupフィルタ適用

#### Step 3: 資格情報収集ロジックを理解する

各レプリカからの資格情報収集を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Compare-DbaAgReplicaCredential.ps1 | `public/Compare-DbaAgReplicaCredential.ps1` | レプリカループと資格情報収集（112-132行目） |

**主要処理フロー**:
- **120行目**: Get-DbaCredentialで資格情報取得
- **124-127行目**: allCredentialNamesへの追加

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

資格情報の存在チェックとIdentity比較を把握する。

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

**主要処理フロー**:
- **140-147行目**: Missing検出
- **148-155行目**: Present+Identity記録
- **159-168行目**: 差異判定（Missing or Identity差異）

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

```
Compare-DbaAgReplicaCredential
    │
    ├─ Connect-DbaInstance (初期接続)
    │
    ├─ server.AvailabilityGroups (AG取得)
    │
    ├─ ag.AvailabilityReplicas (レプリカ取得)
    │
    └─ 各レプリカについて
           ├─ Connect-DbaInstance (レプリカ接続)
           └─ Get-DbaCredential (資格情報取得)
```

### データフロー図

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

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

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Compare-DbaAgReplicaCredential.ps1 | `public/Compare-DbaAgReplicaCredential.ps1` | ソース | メインコマンド実装 |
| Get-DbaCredential.ps1 | `public/Get-DbaCredential.ps1` | ソース | 資格情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
