# 機能設計書 360-Copy-DbaInstanceAudit

## 概要

本ドキュメントは、SQL Serverサーバー監査オブジェクトを移行する `Copy-DbaInstanceAudit` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、ソースSQL Serverインスタンスのサーバー監査オブジェクト（Audit）とその設定を、デスティネーションSQL Serverインスタンスにコピーする。監査ファイルパスの処理、ディレクトリの作成も含む。

**業務上の目的・背景**：SQL Server監査機能（SQL Server 2008で導入）は、セキュリティコンプライアンスとデータベース活動の追跡に不可欠である。サーバー移行時や災害復旧環境の構築時に、監査設定を維持することが重要。本機能により、監査オブジェクトの設定を一括でコピーでき、コンプライアンス要件を満たす環境を迅速に構築できる。

**機能の利用シーン**：
- サーバー移行時の監査設定移行
- DR環境構築時の監査ポリシー同期
- 複数サーバー間での監査ポリシー標準化
- 開発/テスト環境への監査設定展開

**主要な処理内容**：
1. ソースサーバーへの接続とサーバー監査オブジェクトの取得
2. デスティネーションサーバーへの接続
3. 監査ファイルパスの検証・作成
4. 既存監査の存在チェックと削除（-Force時）
5. Script()メソッドで監査スクリプト生成・実行

**関連システム・外部連携**：sys.server_audits、監査ファイルパス

**権限による制御**：sysadmin権限が必要。ファイルパスへの書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ移行 / セキュリティ設定コピー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | - |
| SourceSqlCredential | PSCredential | No | ソース認証情報 | - |
| Destination | DbaInstanceParameter[] | Yes | デスティネーションインスタンス（複数可） | - |
| DestinationSqlCredential | PSCredential | No | デスティネーション認証情報 | - |
| Audit | Object[] | No | コピー対象の監査名 | - |
| ExcludeAudit | Object[] | No | 除外する監査名 | - |
| Path | String | No | デスティネーションの監査ファイルパス | - |
| Force | Switch | No | 既存監査を上書き、ディレクトリ作成 | - |
| EnableException | Switch | No | 例外制御 | - |
| WhatIf | Switch | No | 実行シミュレーション | - |
| Confirm | Switch | No | 実行確認 | - |

### 入力データソース

- ソースサーバーのAuditsコレクション（SMO）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作日時 |
| SourceServer | String | ソースサーバー名 |
| DestinationServer | String | デスティネーションサーバー名 |
| Name | String | 監査名 |
| Type | String | オブジェクトタイプ（"Server Audit"） |
| Status | String | 結果（Successful / Skipped / Failed） |
| Notes | String | 追加情報 |

### 出力先

- PowerShellパイプライン（MigrationObject）

## 処理フロー

### 処理シーケンス

```
1. ソースサーバー接続
   └─ Connect-DbaInstance (MinimumVersion 10 = SQL Server 2008以上)

2. サーバー監査オブジェクト取得
   └─ $sourceServer.Audits

3. デスティネーションループ開始

4. デスティネーションサーバー接続
   └─ Connect-DbaInstance (MinimumVersion 10)

5. 監査ループ開始

6. フィルタチェック
   └─ Audit/ExcludeAudit パラメータ適用

7. パス設定
   └─ -Path パラメータでファイルパス上書き

8. 既存チェック
   ├─ 存在しない場合: パス検証へ
   ├─ 存在 + Force なし: スキップ
   └─ 存在 + Force: 削除（Audit Specificationも）

9. ファイルパス検証
   ├─ パス存在確認 (Test-DbaPath)
   ├─ 存在しない + Force なし: スキップ
   └─ 存在しない + Force: ディレクトリ作成

10. 監査コピー実行
    └─ Script() でSQL生成、Query() で実行

11. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースサーバー接続]
    B --> C[サーバー監査取得]
    C --> D[デスティネーションループ]
    D --> E[デスティネーション接続]
    E --> F[監査ループ]
    F --> G{フィルタ通過?}
    G -->|No| H[スキップ]
    G -->|Yes| I{-Path指定?}
    I -->|Yes| J[FilePath上書き]
    I -->|No| K{既存あり?}
    J --> K
    K -->|No| L[パス検証]
    K -->|Yes| M{-Force?}
    M -->|No| N[Skipped出力]
    M -->|Yes| O[AuditSpecification削除]
    O --> P[監査削除]
    P --> L
    L --> Q{パス存在?}
    Q -->|Yes| R[コピー実行]
    Q -->|No| S{-Force?}
    S -->|No| T[Skipped: パス不存在]
    S -->|Yes| U[ディレクトリ作成]
    U --> R
    R --> V{成功?}
    V -->|Yes| W[Successful出力]
    V -->|No| X[Failed出力]
    H --> Y{次の監査?}
    N --> Y
    T --> Y
    W --> Y
    X --> Y
    Y -->|Yes| F
    Y -->|No| Z{次のデスティネーション?}
    Z -->|Yes| D
    Z -->|No| AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL Server 2008以上必須 | MinimumVersion 10 | 常時 |
| BR-002 | パス存在必須 | 監査ファイルパスが存在する必要あり | -Force未指定時 |
| BR-003 | ディレクトリ作成 | -Force時にパスが存在しない場合は作成 | -Force時 |
| BR-004 | AuditSpec削除 | 監査削除前にAuditSpecificationも削除 | -Force時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 取得 | sys.server_audits | SELECT (SMO経由) | 監査一覧取得 |
| 削除 | sys.server_audits | DROP SERVER AUDIT | 既存監査削除 |
| 削除 | sys.server_audit_specifications | DROP SERVER AUDIT SPECIFICATION | 監査仕様削除 |
| 追加 | sys.server_audits | CREATE SERVER AUDIT | 監査追加 |

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

#### sys.server_audits (SMO Audits)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, audit_id, filepath, etc. | 全監査取得 | Auditsコレクション |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンス接続失敗 | Stop-Function、continue |
| PathNotFound | パスエラー | 監査ファイルパス不存在 | Skipped出力、continue |
| DropFailed | 削除エラー | 監査削除失敗 | Failed出力、continue |
| CreateFailed | 作成エラー | 監査作成失敗 | Failed出力、continue |
| DirectoryCreateFailed | ディレクトリエラー | ディレクトリ作成失敗 | デフォルトパス使用 |

### リトライ仕様

リトライ処理なし。

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

各監査は個別に処理。

## パフォーマンス要件

- 監査数に比例した処理時間

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

- sysadmin権限が必要
- 監査ファイルパスへの書き込み権限が必要
- 監査設定はセキュリティコンプライアンスに関わる

## 備考

- ファイル監査以外の監査タイプ（Windows Security Log等）もサポート
- -Pathパラメータで監査ファイルパスを上書き可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | Auditsコレクション（132行目） |

**読解のコツ**: SMO Audit オブジェクトのFilePathプロパティに注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **109-124行目**: パラメータ定義
2. **125-134行目**: ソース接続と監査取得
3. **163-166行目**: -Path パラメータでFilePath上書き
4. **167-196行目**: 既存チェックと削除処理
5. **198-228行目**: ファイルパス検証とディレクトリ作成
6. **229-243行目**: 監査コピー実行

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

```
Copy-DbaInstanceAudit
    │
    ├─ Connect-DbaInstance (Source, MinimumVersion 10)
    │
    ├─ $sourceServer.Audits
    │
    ├─ Connect-DbaInstance (Destination, MinimumVersion 10)
    │
    ├─ Test-DbaPath
    │      └─ ファイルパス存在確認
    │
    ├─ $destServer.ServerAuditSpecifications
    │      └─ 関連AuditSpecification削除
    │
    ├─ $destServer.audits[$name].Disable() / Drop()
    │      └─ 既存監査削除
    │
    ├─ New-DbaDirectory
    │      └─ ディレクトリ作成 (-Force時)
    │
    └─ $currentAudit.Script() → Query()
           └─ 監査作成
```

### データフロー図

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

Source ───▶ Connect-DbaInstance (MinimumVersion 10)
                 │
                 ▼
          $sourceServer.Audits取得
                 │
Destination ───▶ Connect-DbaInstance (MinimumVersion 10)
                 │
                 ▼
          フィルタ適用
                 │
                 ▼
          パス設定 (-Path上書き)
                 │
                 ▼
          既存チェック
                 │
          ┌──────┴──────┐
          ▼             ▼
       存在しない     存在する
          │             │
          │        ┌────┴────┐
          │        ▼         ▼
          │     -Force    Force無し
          │        │         │
          │    AuditSpec/   Skipped
          │    Audit削除      │
          │        │         │
          └────┬───┘         │
               ▼             │
          パス検証
               │
          ┌────┴────┐
          ▼         ▼
       存在する   存在しない
          │         │
          │    ┌────┴────┐
          │    ▼         ▼
          │  -Force   Force無し
          │    │         │
          │  ディレクトリ  Skipped
          │  作成         │
          │    │         │
          └────┬─────────┘
               ▼
          Script()→Query()
               │
               ▼
          MigrationObject出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaInstanceAudit.ps1 | `public/Copy-DbaInstanceAudit.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス検証 |
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | ディレクトリ作成 |
