# 機能設計書 418-Copy-DbaPolicyManagement

## 概要

本ドキュメントは、SQL Serverインスタンス間でポリシーベース管理（PBM）のポリシー、条件、カテゴリをコピーする`Copy-DbaPolicyManagement`機能の設計を定義する。

### 本機能の処理概要

本機能は、ポリシーベース管理フレームワーク全体をあるSQL Serverインスタンスから別のインスタンスに転送する。これにはカスタムポリシー、条件、カテゴリが含まれる。これにより環境の標準化やディザスタリカバリシナリオで複数サーバー間で同一のコンプライアンスポリシーが必要な場合に効率化される。

**業務上の目的・背景**：企業環境ではデータベースのガバナンスとコンプライアンスのためにポリシーベース管理を使用することが多い。新しいサーバーのセットアップや既存環境の標準化時に、手動でポリシーを再作成するのは時間がかかりエラーが発生しやすい。本機能を使用することで、ソースサーバーから宛先サーバーへポリシーを自動的にコピーできる。

**機能の利用シーン**：
- 新規SQL Serverインスタンスへのポリシー展開
- 複数環境（開発、ステージング、本番）間でのポリシー標準化
- ディザスタリカバリ準備
- サーバー移行時のポリシー移行

**主要な処理内容**：
1. ソースインスタンスからPolicyStoreオブジェクトを取得
2. 非システムのポリシーとコンディションを抽出
3. 一意のポリシーカテゴリを特定してコピー
4. コンディションをコピー（依存関係考慮）
5. ポリシーをコピー

**関連システム・外部連携**：
- Microsoft.SqlServer.Management.DMF（Policy Store）
- Microsoft.SqlServer.Management.Sdk.Sfc（SqlStoreConnection）

**権限による制御**：ソースおよび宛先でsysadmin権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

データ移行処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | コピー元SQL Serverインスタンス | SQL 2008以降 |
| SourceSqlCredential | PSCredential | No | ソース接続用代替資格情報 | - |
| Destination | DbaInstanceParameter[] | Yes | コピー先SQL Serverインスタンス（複数可） | SQL 2008以降 |
| DestinationSqlCredential | PSCredential | No | 宛先接続用代替資格情報 | - |
| Policy | object[] | No | コピーするポリシー名（ソースから自動補完） | - |
| ExcludePolicy | object[] | No | 除外するポリシー名（ソースから自動補完） | - |
| Condition | object[] | No | コピーするコンディション名 | - |
| ExcludeCondition | object[] | No | 除外するコンディション名 | - |
| Force | switch | No | 既存オブジェクトを上書き | - |
| EnableException | switch | No | 例外の詳細表示有効化 | - |

### 入力データソース

- ソースSQL Server: PolicyStore（Policies, Conditions, PolicyCategories）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | コピー操作のタイムスタンプ |
| SourceServer | string | コピー元SQL Serverインスタンス名 |
| DestinationServer | string | コピー先SQL Serverインスタンス名 |
| Name | string | ポリシー/コンディション/カテゴリの名前 |
| Type | string | オブジェクトタイプ（Policy Category/Policy Condition/Policy） |
| Status | string | 操作結果（Successful/Skipped/Failed） |
| Notes | string | 追加情報（Already exists on destination等） |

### 出力先

PowerShellパイプライン(PSCustomObject)

## 処理フロー

### 処理シーケンス

```
1. beginブロック: 初期化
   └─ 1.1 Windows以外はサポート外でStop-Function
   └─ 1.2 Add-PbmLibraryでPBMライブラリロード
   └─ 1.3 ソースサーバー接続（MinimumVersion 10）
   └─ 1.4 PolicyStoreオブジェクト作成
   └─ 1.5 非システムのポリシーとコンディションを抽出

2. processブロック: 宛先ごとの処理ループ
   └─ 2.1 宛先サーバー接続
   └─ 2.2 宛先PolicyStoreオブジェクト作成
   └─ 2.3 ポリシー/コンディションフィルタリング

3. カテゴリコピー:
   └─ 3.1 ポリシーから一意のカテゴリを抽出
   └─ 3.2 各カテゴリをScriptCreate()でコピー

4. コンディションコピー:
   └─ 4.1 各コンディションの存在確認
   └─ 4.2 -Force時は依存ポリシーを削除後にDrop
   └─ 4.3 ScriptCreate()でコピー

5. ポリシーコピー:
   └─ 5.1 各ポリシーの存在確認
   └─ 5.2 -Force時はDrop
   └─ 5.3 ScriptCreate()でコピー
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Windows環境?}
    B -->|No| C[Stop-Function/return]
    B -->|Yes| D[Add-PbmLibrary]
    D --> E[ソースサーバー接続]
    E --> F{接続成功?}
    F -->|No| G[Stop-Function/return]
    F -->|Yes| H[PolicyStore作成]
    H --> I[非システムポリシー/コンディション抽出]
    I --> J{各Destinationをループ}
    J --> K[宛先サーバー接続]
    K --> L{接続成功?}
    L -->|No| M[Stop-Function/Continue]
    M --> J
    L -->|Yes| N[宛先PolicyStore作成]
    N --> O[ポリシー/コンディションフィルタ]
    O --> P[カテゴリコピー]
    P --> Q[コンディションコピー]
    Q --> R[ポリシーコピー]
    R --> J
    J -->|完了| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Windowsのみ | Linuxはサポート外（Core SMO未対応） | 常時 |
| BR-002 | SQL 2008以降 | MinimumVersion 10を要求 | 接続時 |
| BR-003 | システムオブジェクト除外 | IsSystemObject=trueのオブジェクトは除外 | 常時 |
| BR-004 | 既存スキップ | 同名オブジェクトが存在する場合はスキップ | -Force未指定時 |
| BR-005 | 強制上書き | -Force指定時は既存オブジェクトをDropして再作成 | -Force指定時 |
| BR-006 | 依存関係処理 | コンディションDrop時は依存ポリシーも削除 | -Force + コンディション存在時 |

### 計算ロジック

特になし（オブジェクトのスクリプト化とコピー）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カテゴリ作成 | msdb.dbo.syspolicy_policy_categories | INSERT | カテゴリの作成 |
| コンディション作成 | msdb.dbo.syspolicy_conditions | INSERT | コンディションの作成 |
| ポリシー作成 | msdb.dbo.syspolicy_policies | INSERT | ポリシーの作成 |
| オブジェクト削除 | 上記テーブル | DELETE | -Force時の既存削除 |

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

#### PolicyStore操作

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| ScriptCreate() | - | 全プロパティ | CREATE文生成 |
| Drop() | - | - | -Force時に使用 |
| Refresh() | - | - | 操作後のキャッシュ更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| PlatformError | プラットフォームエラー | Linux環境 | Stop-Function/return |
| ConnectionError | 接続エラー | Connect-DbaInstance失敗 | Stop-Function/Continue |
| CopyError | コピーエラー | ScriptCreate()実行失敗 | Notes記録/Continue |
| DropError | 削除エラー | Drop()失敗 | Notes記録/Continue |

### リトライ仕様

リトライ処理なし（単一試行）

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

各オブジェクトのコピーは個別トランザクション（エラー時は該当オブジェクトのみ影響）

## パフォーマンス要件

- オブジェクト数に比例した処理時間
- ScriptCreate()によるT-SQL生成がボトルネックとなる可能性

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

- ソースおよび宛先でsysadmin権限が必要
- SQL認証/Windows認証/Azure AD認証に対応
- 資格情報はPSCredentialで安全に渡される
- ShouldProcessで変更前に確認

## 備考

- Chrissy LeMaire氏(@cl)による開発
- Core SMOがリリースされるまでLinuxはサポート外

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | 出力ステータスオブジェクトの構造（185-192, 232-239, 301-308行目） |

**読解のコツ**: Category、Condition、Policyそれぞれで同様の構造を持つステータスオブジェクトを出力

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | パラメータ定義（107-122行目） |

**主要処理フロー**:
1. **106行目**: DefaultParameterSet="Default", SupportsShouldProcess, ConfirmImpact="Medium"
2. **108-109行目**: Source（必須）
3. **113-114行目**: Destination（必須、複数可）

#### Step 3: 初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | beginブロック（124-144行目） |

**主要処理フロー**:
- **125-128行目**: Windows環境チェック
- **130行目**: Add-PbmLibrary
- **131-136行目**: ソース接続（MinimumVersion 10）
- **137-141行目**: PolicyStore作成と非システムオブジェクト抽出

#### Step 4: コピー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | カテゴリコピー（179-222行目） |
| 4-2 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | コンディションコピー（228-291行目） |
| 4-3 | Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | ポリシーコピー（297-361行目） |

**主要処理フロー**:
- **180行目**: 一意のカテゴリ抽出
- **207行目**: ScriptCreate().GetScript()でSQL生成
- **243-250行目**: コンディション既存チェック
- **256-260行目**: 依存ポリシーのDrop
- **311-318行目**: ポリシー既存チェック
- **343行目**: ScriptCreate().GetScript()でポリシーSQL生成

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

```
Copy-DbaPolicyManagement
    │
    ├─ beginブロック
    │      ├─ Add-PbmLibrary
    │      ├─ Connect-DbaInstance (Source)
    │      └─ PolicyStore作成
    │
    ├─ processブロック（各Destination）
    │      ├─ Connect-DbaInstance (Destination)
    │      └─ PolicyStore作成
    │
    ├─ カテゴリコピー
    │      ├─ 一意カテゴリ抽出
    │      ├─ 存在確認
    │      └─ ScriptCreate() + Query()
    │
    ├─ コンディションコピー
    │      ├─ 存在確認
    │      ├─ -Force時: 依存ポリシーDrop + Drop
    │      └─ ScriptCreate() + Query()
    │
    └─ ポリシーコピー
           ├─ 存在確認
           ├─ -Force時: Drop
           └─ ScriptCreate() + Query()
```

### データフロー図

```
[Source]                  [処理]                      [Destination]

PolicyStore ────────▶ Policies抽出 ──────────────────┐
    │                 (非システムのみ)                │
    │                                                 │
    ├─ Policies       フィルタリング                  │
    │   └─ Categories  (Policy/ExcludePolicy)        │
    │                                                 │
    ├─ Conditions      フィルタリング                  │
    │                  (Condition/ExcludeCondition)   │
    │                                                 ▼
    │                                          PolicyStore
    │                                                 │
    └─────────────────────────────────────────────────┤
                                                      │
              ScriptCreate() ─────────────────▶ Query()
                                                      │
                                               ┌──────┴──────┐
                                               │             │
                                           Categories   Conditions
                                               │             │
                                               └──────┬──────┘
                                                      │
                                                  Policies
                                                      │
                                                      ▼
                                              ステータス出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaPolicyManagement.ps1 | `public/Copy-DbaPolicyManagement.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Add-PbmLibrary.ps1 | `internal/functions/Add-PbmLibrary.ps1` | ソース | PBMライブラリロード |
