# 機能設計書 32-Find-DbaBackup

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Find-DbaBackup`コマンドレットに関する機能設計書です。このコマンドは、ファイルシステムディレクトリからSQL Serverバックアップファイルを検索し、保持期間やアーカイブビット条件に基づいてフィルタリングする機能を提供します。

### 本機能の処理概要

Find-DbaBackupは、指定されたディレクトリを再帰的にスキャンし、SQL Serverバックアップファイル（.bak, .trn, .dif等）を検出します。ユーザー定義の保持期間に基づいて古いバックアップファイルを特定し、クリーンアップワークフローに適したFileInfoオブジェクトを返します。

**業務上の目的・背景**：バックアップ保持ポリシーの運用において、古いバックアップファイルの識別と削除は重要な定期タスクです。手動でのディレクトリ検索は時間がかかりミスが発生しやすいため、この機能により自動化されたバックアップクリーンアップワークフローを実現します。ディスク容量管理とコンプライアンス要件の両方を満たすために活用されます。

**機能の利用シーン**：
- バックアップ保持ポリシーに基づく古いファイルの特定
- 定期メンテナンススクリプトでの削除対象ファイルの抽出
- ネットワーク共有上のバックアップファイルの棚卸し
- アーカイブ済みバックアップの確認と管理

**主要な処理内容**：
1. 指定パスの検証とアクセス確認
2. 保持期間文字列の解析と日時への変換
3. Get-ChildItemによるファイル再帰検索
4. LastWriteTimeによる保持期間フィルタリング
5. アーカイブビットによる追加フィルタリング（オプション）
6. FileInfoオブジェクトとしての結果出力

**関連システム・外部連携**：
- ファイルシステム（ローカルおよびネットワーク共有）
- Remove-Item等の後続処理コマンドへのパイプライン連携

**権限による制御**：対象ディレクトリへの読み取りアクセス権限が必要です。削除操作を行う場合は追加の書き込み権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | バックアップ管理 | 主機能 | バックアップファイルの検索 |

## 機能種別

検索処理 / ルックアップ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string | Yes | 検索対象のルートディレクトリパス | Containerとして存在すること |
| BackupFileExtension | string | Yes | 検索対象のファイル拡張子（ピリオドなし） | - |
| RetentionPeriod | string | Yes | 保持期間（例：48h, 7d, 4w, 1m） | 有効な単位(h/d/w/m)と数値の組み合わせ |
| CheckArchiveBit | switch | No | アーカイブビットチェックを有効化 | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- ファイルシステム（指定パス配下のファイル）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| FullName | string | ファイルの完全パス |
| Name | string | ファイル名（拡張子含む） |
| Extension | string | ファイル拡張子 |
| DirectoryName | string | ファイルが存在するディレクトリ |
| Length | long | ファイルサイズ（バイト） |
| LastWriteTime | DateTime | 最終更新日時 |
| Attributes | FileAttributes | ファイル属性（Archiveビット含む） |
| CreationTime | DateTime | 作成日時 |
| LastAccessTime | DateTime | 最終アクセス日時 |

### 出力先

- PowerShellパイプライン（System.IO.FileInfo）
- Remove-Item等の後続コマンドへパイプ可能

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ BackupFileExtensionがピリオドで始まる場合は警告出力
   └─ Pathがコンテナ（ディレクトリ）として存在するか確認

2. 保持期間の変換
   └─ Convert-UserFriendlyRetentionToDatetime関数呼び出し
   └─ 単位（h/d/w/m）と値を分離して解析
   └─ DateTimeへ変換

3. アーカイブビットフィルタの準備
   └─ CheckArchiveBit指定時: アーカイブビットなしのファイルのみ通過
   └─ 未指定時: 全ファイル通過

4. ファイル検索実行
   └─ Get-ChildItem -File -Recurse でファイル一覧取得
   └─ Where-Object LastWriteTime -lt $RetentionDate でフィルタ
   └─ DbaArchiveBitFilter でアーカイブビットフィルタ

5. 結果出力
   └─ FileInfoオブジェクトをパイプラインへ出力
   └─ エラー発生時は警告メッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path存在?}
    B -->|No| C[Stop-Function]
    B -->|Yes| D[保持期間変換]
    D --> E{変換成功?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G{CheckArchiveBit?}
    G -->|Yes| H[アーカイブビットフィルタ設定]
    G -->|No| I[全通過フィルタ設定]
    H --> J[Get-ChildItem 再帰検索]
    I --> J
    J --> K[LastWriteTimeフィルタ]
    K --> L[アーカイブビットフィルタ適用]
    L --> M{エラー発生?}
    M -->|Yes| N[警告出力]
    M -->|No| O[FileInfo出力]
    N --> O
    O --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 保持期間単位 | h=時間, d=日, w=週, m=月の単位を使用 | RetentionPeriod解析時 |
| BR-02 | 拡張子自動補完 | ピリオドは自動で追加される | 検索時 |
| BR-03 | アーカイブ確認 | アーカイブビット未設定=他の場所にバックアップ済み | CheckArchiveBit指定時 |
| BR-04 | 再帰検索 | サブディレクトリも含めて検索 | 常時 |

### 計算ロジック

保持期間からDateTimeへの変換：
```
h: (Get-Date).AddHours(-$Value)
d: (Get-Date).AddDays(-$Value)
w: (Get-Date).AddDays(-$Value * 7)
m: (Get-Date).AddMonths(-$Value)
```

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

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

この機能はデータベース操作を行いません。ファイルシステムのみを対象とします。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | PathNotFound | 指定パスが存在しない | 有効なパスを指定 |
| - | InvalidRetention | 保持期間形式が不正 | 正しい形式（例：7d, 48h）を使用 |
| - | EnumError | ファイル列挙エラー | アクセス権限を確認 |

### リトライ仕様

リトライ機能は実装されていません。エラー発生時は警告メッセージを出力して継続します（ErrorAction SilentlyContinue）。

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

ファイルシステム操作のためトランザクションは使用しません。

## パフォーマンス要件

- ストリーミング処理により大量ファイルでもメモリ効率的に処理
- 再帰検索のため、深いディレクトリ構造では時間がかかる場合あり
- GitHub Issue #970を参考にストリーミング処理を採用

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

- 対象ディレクトリへの読み取り権限が必要
- ネットワーク共有の場合は適切な認証が必要
- 削除操作を行う場合は書き込み権限が別途必要

## 備考

- ピリオドで始まるBackupFileExtensionは警告を出力（自動で追加されるため）
- アーカイブビットチェックは、ファイルがテープや他のストレージにコピー済みかを確認するために使用

---

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

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

### 推奨読解順序

#### Step 1: 関数定義とパラメータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaBackup.ps1 | `public/Find-DbaBackup.ps1` | パラメータ定義（79-90行目）を確認、特にHelpMessageに注目 |

**読解のコツ**: `HelpMessage`属性でパラメータの用途が明確に記述されている。

#### Step 2: 内部ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaBackup.ps1 | `public/Find-DbaBackup.ps1` | beginブロック内の`Convert-UserFriendlyRetentionToDatetime`関数（94-136行目） |

**主要処理フロー**:
1. **114-116行目**: 値と単位の分離処理
2. **119-121行目**: 単位のバリデーション（h/d/w/m）
3. **124-126行目**: 値が整数であることのバリデーション
4. **128-134行目**: 単位に基づくDateTime計算

#### Step 3: バリデーション処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaBackup.ps1 | `public/Find-DbaBackup.ps1` | beginブロック後半（138-147行目）のバリデーション処理 |

**主要処理フロー**:
- **140-142行目**: 拡張子のピリオドチェックと警告
- **144-146行目**: パス存在チェック

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaBackup.ps1 | `public/Find-DbaBackup.ps1` | processブロック（149-182行目）のファイル検索とフィルタリング |

**主要処理フロー**:
- **154-159行目**: 保持期間のDateTime変換
- **162-173行目**: 動的フィルタ定義（CheckArchiveBit対応）
- **177-178行目**: Get-ChildItem + Where-Object + フィルタによるパイプライン処理
- **179-181行目**: エラー処理

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

```
Find-DbaBackup
    │
    ├─ begin ブロック
    │      │
    │      ├─ Convert-UserFriendlyRetentionToDatetime (内部関数)
    │      │      └─ 保持期間文字列をDateTimeに変換
    │      │
    │      ├─ Write-Message (警告)
    │      │      └─ 拡張子形式警告
    │      │
    │      └─ Test-Path / Stop-Function
    │             └─ パス存在チェック
    │
    └─ process ブロック
           │
           ├─ Convert-UserFriendlyRetentionToDatetime
           │      └─ 保持期間変換
           │
           ├─ filter DbaArchiveBitFilter (動的定義)
           │      └─ アーカイブビットフィルタ
           │
           └─ Get-ChildItem | Where-Object | DbaArchiveBitFilter
                  └─ ファイル検索パイプライン
```

### データフロー図

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

$Path ─────────────────▶ Test-Path ──────────────────▶ 存在確認
                                │
$RetentionPeriod ──────▶ Convert-UserFriendlyRetention ▶ $RetentionDate
                                │
$BackupFileExtension ──▶ "*.$BackupFileExtension" ───▶ フィルタパターン
                                │
$CheckArchiveBit ──────▶ DbaArchiveBitFilter定義 ────▶ フィルタ関数
                                │
                         Get-ChildItem
                                │
                         Where-Object LastWriteTime
                                │
                         DbaArchiveBitFilter
                                │
                                └─────────────────────▶ FileInfo[]
                                                        (パイプライン出力)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaBackup.ps1 | `public/Find-DbaBackup.ps1` | ソース | メイン関数実装 |
| Stop-Function.ps1 | `internal/functions/Stop-Function.ps1` | ソース | エラー停止ヘルパー |
| Write-Message.ps1 | `internal/functions/Write-Message.ps1` | ソース | ログ出力ヘルパー |
