# 機能設計書 550-Find-DbaUserObject

## 概要

本ドキュメントは、saまたはdbo以外のユーザーが所有するSQL Serverオブジェクトを検索する、または特定のユーザーパターンに一致するオブジェクトを検索するPowerShell関数`Find-DbaUserObject`の機能設計書である。

### 本機能の処理概要

Find-DbaUserObjectは、SQL Serverインスタンスをスキャンして、標準的なシステムアカウント（saやdbo）以外が所有するオブジェクトを特定する。セキュリティ監査やユーザー管理において、オブジェクトの所有権を把握することは重要である。ユーザーアカウントの削除時に、そのユーザーが所有するオブジェクトを事前に把握しておくことで、依存関係の問題を回避できる。

**業務上の目的・背景**：ユーザーの退職やアカウント整理の際、そのユーザーが所有するオブジェクトが存在すると、アカウント削除時にエラーが発生したり、オブジェクトが孤立したりする問題が発生する。また、セキュリティ監査では、誰がどのオブジェクトを所有しているかを正確に把握する必要がある。本機能により、これらの課題に対応できる。

**機能の利用シーン**：
- ユーザーアカウント削除前の影響調査
- セキュリティ監査での所有権レポート生成
- 特定ユーザーの所有オブジェクト一括変更準備
- システムアカウント以外の所有権の棚卸し
- コンプライアンス報告のための所有者情報収集

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. サーバーレベルオブジェクトの検索（データベース、ジョブ、資格情報、プロキシ、エンドポイント、サーバーロール）
3. データベースレベルオブジェクトの検索（スキーマ、ロール、アセンブリ、シノニム）
4. Patternパラメータによるフィルタリング（正規表現対応）
5. 結果の出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用。

**権限による制御**：各オブジェクトへの読み取りアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | なし（CLI専用機能） | - | PowerShellコマンドラインから実行 |

## 機能種別

検索・照会 / セキュリティ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | ValueFromPipeline |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | 有効なPSCredential |
| Pattern | string | No | 検索パターン（正規表現） | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- SQL Server SMOの各種コレクション
- sys.server_principals、sys.databases等のシステムビュー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Type | string | オブジェクトタイプ |
| Owner | string | 所有者名 |
| Name | string | オブジェクト名 |
| Parent | string | 親オブジェクト名 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パターン前処理
   └─ Windowsアカウントのバックスラッシュをエスケープ
2. インスタンスループ
   └─ 各SqlInstanceに対して処理
3. SQL Server接続
   └─ Connect-DbaInstance
4. saログイン名取得
   └─ Get-SaLoginName
5. サーバーレベルオブジェクト検索
   └─ Credentials、Proxies、Endpoints、Roles
6. データベース検索
   └─ Owner判定
7. Agent Job検索
   └─ OwnerLoginName判定
8. Proxy使用ジョブステップ検索
   └─ ProxyName判定
9. データベースオブジェクト検索
   └─ スキーマ、ロール、アセンブリ、シノニム
10. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パターン前処理]
    B --> C[インスタンスループ]
    C --> D[SQL Server接続]
    D --> E[saログイン名取得]
    E --> F{Pattern指定?}
    F -->|Yes| G[Patternマッチ検索]
    F -->|No| H[非sa/dbo検索]
    G --> I[Credentials検索]
    H --> I
    I --> J[Proxies検索]
    J --> K[Databases検索]
    K --> L[Agent Jobs検索]
    L --> M[Endpoints検索]
    M --> N[Server Roles検索]
    N --> O[DBオブジェクトループ]
    O --> P[Schemas検索]
    P --> Q[DB Roles検索]
    Q --> R[Assemblies検索]
    R --> S[Synonyms検索]
    S --> T{全DB完了?}
    T -->|No| O
    T -->|Yes| U{全インスタンス完了?}
    U -->|No| C
    U -->|Yes| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-550-01 | sa除外 | Pattern未指定時はsa所有オブジェクトを除外 | Pattern未指定時 |
| BR-550-02 | dbo除外 | Pattern未指定時はdbo所有オブジェクトを除外 | Pattern未指定時 |
| BR-550-03 | システムスキーマ除外 | システムスキーマ（DatabaseMailUserRole等）は除外 | スキーマ検索時 |
| BR-550-04 | システムオブジェクト除外 | IsSystemObject=trueは除外 | 常時 |
| BR-550-05 | パターンエスケープ | Windowsアカウントのバックスラッシュを正規表現用にエスケープ | Pattern指定時 |

### 計算ロジック

パターンのバックスラッシュエスケープ:
```powershell
if ($Pattern -match '^[\w\d\.-]+\\[\w\d\.-]+$') {
    $Pattern = $Pattern.Replace('\', '\\')
}
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| データベース取得 | sys.databases | SELECT | データベース一覧 |
| ジョブ取得 | msdb.dbo.sysjobs | SELECT | Agent Job一覧 |
| 資格情報取得 | sys.credentials | SELECT | 資格情報一覧 |
| プロキシ取得 | msdb.dbo.sysproxies | SELECT | プロキシ一覧 |
| エンドポイント取得 | sys.endpoints | SELECT | エンドポイント一覧 |
| ロール取得 | sys.server_principals | SELECT | サーバーロール一覧 |

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

読み取り専用。SMOコレクション経由でのSELECTのみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報を確認 |

### リトライ仕様

リトライ機能なし。

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

読み取り専用操作のためトランザクション不要。

## パフォーマンス要件

特に定義なし。大規模環境では処理時間が増加する可能性がある。

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

- 各オブジェクトへの読み取りアクセス権限が必要
- IsAccessible判定でアクセス不可データベースはスキップ

## 備考

- Pattern未指定時はsa/dbo以外の全所有者を検索
- Pattern指定時は正規表現マッチングを使用
- データベースオブジェクト検索はIsAccessible=trueのDBのみ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaUserObject.ps1 | `public/Find-DbaUserObject.ps1` | 78-85行目のパラメータ定義 |

#### Step 2: パターン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaUserObject.ps1 | `public/Find-DbaUserObject.ps1` | 86-90行目 |

**読解のコツ**: Windowsアカウント形式（DOMAIN\user）のバックスラッシュを正規表現用に2重化。

#### Step 3: サーバーレベルオブジェクト検索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaUserObject.ps1 | `public/Find-DbaUserObject.ps1` | 102-234行目 |

**主要処理フロー**:
- **103-121行目**: $pattern判定による分岐
- **124-150行目**: データベース所有者検索
- **152-177行目**: Agent Job所有者検索
- **179-220行目**: Credentials、Proxies、Job Steps検索
- **222-262行目**: Endpoints、Server Roles検索

#### Step 4: データベースオブジェクト検索を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaUserObject.ps1 | `public/Find-DbaUserObject.ps1` | 264-342行目 |

**主要処理フロー**:
- **265-266行目**: IsAccessible判定
- **268行目**: システムスキーマ除外リスト
- **270-285行目**: スキーマ検索
- **287-303行目**: データベースロール検索
- **305-322行目**: アセンブリ検索
- **324-341行目**: シノニム検索

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

```
Find-DbaUserObject
    │
    ├─ Connect-DbaInstance
    │
    ├─ Get-SaLoginName
    │
    ├─ Server.Credentials
    │
    ├─ Server.JobServer.ProxyAccounts
    │
    ├─ Server.Endpoints
    │
    ├─ Server.Roles
    │
    ├─ Server.Databases
    │
    ├─ Server.JobServer.Jobs
    │
    └─ Database.Schemas/Roles/Assemblies/Synonyms
```

### データフロー図

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

SqlInstance       ───▶ Connect-DbaInstance     ───▶ SMO Server Object
    │                                                      │
    ▼                                                      ▼
Server Objects    ───▶ Filter by Owner         ───▶ Server Level Objects
(Credentials,                                              │
 Proxies, etc.)                                            │
    │                                                      │
    ▼                                                      ▼
Server.Databases  ───▶ Filter by Owner         ───▶ Database Owners
    │                                                      │
    ▼                                                      ▼
JobServer.Jobs    ───▶ Filter by OwnerLogin    ───▶ Job Owners
    │                                                      │
    ▼                                                      ▼
DB Objects        ───▶ Filter by Owner         ───▶ DB Level Objects
(Schemas, Roles,                                           │
 Assemblies)                                               │
    │                                                      ▼
    └─────────────────────────────────────────────▶ PSCustomObject Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaUserObject.ps1 | `public/Find-DbaUserObject.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Get-SaLoginName.ps1 | `private/functions/Get-SaLoginName.ps1` | ソース | saログイン名取得 |
