# 機能設計書 579-Remove-DbaServerRole

## 概要

本ドキュメントは、SQL Serverからカスタムサーバーロールを削除する `Remove-DbaServerRole` 機能の設計仕様を定義するものです。

### 本機能の処理概要

`Remove-DbaServerRole` は、SQL Serverインスタンスからユーザー定義のサーバーレベルロールを削除するdbatools PowerShellコマンドレットです。不要になったカスタムサーバーロールを安全に削除し、サーバーのセキュリティ構成をクリーンアップします。組み込みの固定サーバーロール（sysadmin、serveradminなど）は保護され、削除できません。

**業務上の目的・背景**：アプリケーションの廃止やセキュリティモデルの変更により、不要になったカスタムサーバーロールを削除する必要があります。放置された不要なロールは、セキュリティ監査の問題となる可能性があり、定期的なクリーンアップが推奨されます。

**機能の利用シーン**：
- アプリケーション廃止時のサーバーロールクリーンアップ
- セキュリティモデル再構築時の旧ロール削除
- セキュリティ監査後の不要ロール削除
- 環境統合時のロール整理

**主要な処理内容**：
1. SqlInstance指定時はGet-DbaServerRoleでロール取得
2. InputObject処理（パイプライン入力対応）
3. ShouldProcessによる削除確認
4. SMOのDrop()メソッドによるロール削除
5. 削除結果の出力

**関連システム・外部連携**：SQL Server SMOライブラリ、Get-DbaServerRoleとの連携。

**権限による制御**：ALTER ANY SERVER ROLE権限または同等の権限（sysadminメンバーシップ）が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SSMSサーバーロール管理画面 | 参照画面 | GUIでのロール削除に相当する操作 |

## 機能種別

CRUD操作（Delete）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効なPSCredentialオブジェクト |
| ServerRole | String[] | No | 削除対象のサーバーロール名 | - |
| InputObject | ServerRole[] | No | パイプライン入力 | SMO ServerRoleオブジェクト |
| EnableException | Switch | No | 例外を有効化するスイッチ | - |

### 入力データソース

- PowerShellコマンドライン入力
- パイプライン入力（Get-DbaServerRoleからの出力）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverが動作するコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名 |
| ServerRole | String | 削除されたサーバーロール名 |
| Status | String | 操作結果（"Success" または "Failed"） |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. process ブロック
   ├─ SqlInstance指定時
   │   └─ Get-DbaServerRoleでロール取得・InputObjectに追加
   └─ InputObject処理
       ├─ ShouldProcess確認
       ├─ Drop()実行
       └─ 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|Yes| C[Get-DbaServerRole]
    C --> D[InputObjectに追加]
    B -->|No| E[InputObject処理]
    D --> E
    E --> F[ロールループ開始]
    F --> G{ShouldProcess確認}
    G -->|No| H[スキップ]
    G -->|Yes| I[Drop実行]
    I --> J{成功?}
    J -->|Yes| K[Status=Success]
    J -->|No| L[Stop-Function]
    L --> M[Status=Failed]
    K --> N[結果出力]
    M --> N
    H --> O{次のロール?}
    N --> O
    O -->|Yes| F
    O -->|No| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 固定ロール保護 | 固定サーバーロールは削除不可（Get-DbaServerRoleでフィルタ済み） | 常時 |
| BR-002 | 確認プロンプト | ConfirmImpact=Highにより、デフォルトで確認を要求 | Confirm:$false以外 |
| BR-003 | メンバー依存 | ロールにメンバーがいる場合でも削除可能 | 常時 |

### 計算ロジック

特に計算ロジックはありません。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ロール削除 | sys.server_principals | DELETE | サーバーロールの削除 |
| メンバーシップ削除 | sys.server_role_members | DELETE | 関連メンバーシップの削除（カスケード） |

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

#### sys.server_principals

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | principal_id | 対象ロールのID | SMO Drop()で実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| DropFailed | 削除エラー | Drop()の失敗 | エラー内容を確認 |
| PermissionDenied | 権限エラー | ALTER ANY SERVER ROLE権限なし | 権限付与を依頼 |

### リトライ仕様

エラー発生時はStop-Functionで処理を中断し、Status="Failed"の結果オブジェクトを出力して次のロールへ継続します。

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

SMOのDrop()メソッドによる暗黙的トランザクションで処理されます。

## パフォーマンス要件

通常のロール削除は1秒以内で完了します。

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

- ALTER ANY SERVER ROLE権限が必要
- ConfirmImpact=Highによるデフォルト確認プロンプト
- 監査ログによる操作追跡を推奨

## 備考

- Get-DbaServerRoleとのパイプライン連携が推奨
- SQL Server 2012以降でカスタムサーバーロールが利用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ServerRole (SMO) | Microsoft.SqlServer.Management.Smo | SMOのServerRoleクラスの構造 |

**読解のコツ**: ServerRoleオブジェクトはName、IsFixedRole、Parentプロパティを持ちます。Drop()メソッドで削除されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Remove-DbaServerRole.ps1 | `public/Remove-DbaServerRole.ps1` | 関数定義とパラメータバインディング |

**主要処理フロー**:
1. **72-80行目**: パラメータ定義
2. **81-84行目**: SqlInstance指定時のロール取得
3. **86-110行目**: ロール削除処理

#### Step 3: ロール取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Remove-DbaServerRole.ps1 | `public/Remove-DbaServerRole.ps1` | Get-DbaServerRole呼び出し |

**主要処理フロー**:
- **82-84行目**: `if ($SqlInstance) { $InputObject += Get-DbaServerRole ... }`

#### Step 4: 削除処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaServerRole.ps1 | `public/Remove-DbaServerRole.ps1` | Drop実行と結果出力 |

**主要処理フロー**:
- **86-110行目**: ロールループと削除処理
- **87行目**: ShouldProcess確認
- **89行目**: Drop()実行
- **91-97行目**: 成功時の結果オブジェクト
- **98-107行目**: 失敗時の処理と結果オブジェクト

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

```
Remove-DbaServerRole
    │
    ├─ Get-DbaServerRole (SqlInstance指定時)
    │      └─ ロール取得
    │
    └─ ServerRole.Drop()
           └─ ロール削除
```

### データフロー図

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

SqlInstance ─────────▶ Get-DbaServerRole ──────▶ ServerRoleコレクション
        +                                              │
ServerRole ─────────────────────────────────────────▶ フィルタ
                                                       │
        or                                             │
                                                       ▼
InputObject ───────────────────────────────▶ ShouldProcess確認
                                                       │
                                               Drop()実行
                                                       │
                                                       ▼
                                               PSCustomObject ──▶ パイプライン
                                               (Status: Success/Failed)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Remove-DbaServerRole.ps1 | `public/Remove-DbaServerRole.ps1` | ソース | メイン関数定義 |
| Get-DbaServerRole.ps1 | `public/Get-DbaServerRole.ps1` | ソース | サーバーロール取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
