# 機能設計書 212-Resolve-DbaPath

## 概要

本ドキュメントは、ファイルシステムパスを検証・解決するResolve-DbaPath関数の機能設計書です。

### 本機能の処理概要

Resolve-DbaPathは、PowerShellの組み込みResolve-Pathコマンドレットを超える追加の安全性チェックを備えたファイルシステムパスの検証と解決を行います。バックアップ、リストア、ログファイル管理などのデータベース操作を実行する前に、パスが存在しアクセス可能であることを確認します。

**業務上の目的・背景**：SQL Server管理において、バックアップの保存先、データベースファイルの場所、スクリプトのパスなど、ファイルシステムパスの妥当性確認は重要です。無効またはアクセス不可能なパスによる操作失敗を防ぐため、事前にパスを検証する必要があります。本機能は、パスの存在確認、プロバイダーの検証（FileSystem、Registry等）、新規ファイル作成のための親ディレクトリの存在確認などの機能を提供します。

**機能の利用シーン**：
- バックアップ先のパスを検証してからバックアップを実行する場合
- データベースファイルの移動先パスを確認する場合
- スクリプトファイルのパスを解決する場合
- 新規ファイル作成前に親ディレクトリの存在を確認する場合

**主要な処理内容**：
1. 入力パスの正規化と解決
2. プロバイダーの検証（FileSystem等の指定プロバイダーであることを確認）
3. 単一項目制約の確認（SingleItemオプション使用時）
4. 新規ファイル作成用の親ディレクトリ解決（NewChildオプション使用時）
5. 解決されたパスの出力

**関連システム・外部連携**：PowerShellのプロバイダーシステムと連携し、FileSystem、Registry、Certificate、ActiveDirectoryなどの各種プロバイダーに対応します。

**権限による制御**：ファイルシステムへのアクセス権限に依存します。アクセス権がないパスは解決できません。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

パス検証 / ユーティリティ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string[] | Yes | 検証・解決するファイルシステムパス | 絶対パス・相対パス、ワイルドカード対応 |
| Provider | string | No | 解決されたパスが属すべきプロバイダー | FileSystem, Registry等のプロバイダー名 |
| SingleItem | switch | No | パスが正確に1つの場所に解決されることを要求 | スイッチ型 |
| NewChild | switch | No | 新規ファイル作成用に親ディレクトリの存在を確認 | スイッチ型 |

### 入力データソース

- コマンドライン引数からのパス指定
- パイプラインからの文字列入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 解決されたパス | System.String | 完全修飾ファイルシステムパス |

### 出力先

- パイプライン出力（文字列型）
- 各入力パスが正常に解決された場合、個別の文字列として出力

## 処理フロー

### 処理シーケンス

```
1. 入力パスの前処理
   └─ "."の場合は現在のディレクトリパスに変換

2. NewChildモードの処理
   └─ 親パスと子要素に分割
   └─ 親パスの解決
   └─ プロバイダー検証
   └─ 子要素との結合

3. 通常モードの処理
   └─ Resolve-Pathによるパス解決
   └─ プロバイダー検証
   └─ SingleItem検証

4. パスの出力
   └─ ProviderPathプロパティを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Path = "." ?}
    B -->|Yes| C[現在のディレクトリに変換]
    B -->|No| D{NewChild ?}
    C --> D

    D -->|Yes| E[親パスと子要素に分割]
    D -->|No| F[Resolve-Path実行]

    E --> G[親パスを解決]
    G --> H{SingleItem & 複数結果?}
    H -->|Yes| I[エラー終了]
    H -->|No| J{Provider指定?}

    J -->|Yes| K{Providerが一致?}
    K -->|No| I
    K -->|Yes| L[親パス + 子要素を結合]
    J -->|No| L

    L --> M[パス出力]

    F --> N{SingleItem & 複数結果?}
    N -->|Yes| I
    N -->|No| O{Provider指定?}

    O -->|Yes| P{Providerが一致?}
    P -->|No| I
    P -->|Yes| Q[ProviderPath出力]
    O -->|No| Q

    Q --> R[終了]
    M --> R
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | カレントディレクトリ変換 | "."は現在の作業ディレクトリのパスに変換 | Path = "." |
| BR-002 | 単一項目制約 | SingleItemオプション時、複数結果はエラー | SingleItem指定時 |
| BR-003 | プロバイダー検証 | 指定プロバイダーと一致しない場合はエラー | Provider指定時 |
| BR-004 | 新規ファイル用パス構築 | 親ディレクトリは存在必須、ファイル名は新規可 | NewChild指定時 |

### 計算ロジック

該当なし

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

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

該当なし（データベース操作なし）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パス解決失敗 | パスが存在しないまたはアクセス不可 | 例外スロー（EnableException有効時）または警告 |
| - | 複数パス解決 | SingleItem指定時に複数パスが解決された | 例外スロー |
| - | プロバイダー不一致 | 指定Providerと解決結果が不一致 | 例外スロー |

### リトライ仕様

リトライは行いません。

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

該当なし（トランザクション不要）

## パフォーマンス要件

特になし。パス解決は軽量な操作です。

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

- ファイルシステムへのアクセス権限に基づいて動作
- 解決不可能なパスは適切にエラー処理される
- ユーザーがアクセス権を持たないパスは解決できない

## 備考

- dbatools内部でバックアップ、リストア等の操作前にパス検証に使用
- PowerShellの標準Resolve-Pathの拡張版として設計

---

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

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

### 推奨読解順序

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

パス解決で使用されるPowerShellの標準型を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PathInfo型 | PowerShell標準 | Resolve-Pathの戻り値型、ProviderPath/Providerプロパティ |

**読解のコツ**: PowerShellのパス解決はプロバイダーベースで動作し、各パスにはProviderプロパティで種別が示されます。

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

処理の起点となる関数を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Resolve-DbaPath.ps1 | `public/Resolve-DbaPath.ps1` | 関数定義、パラメータ構造 |

**主要処理フロー**:
1. **63-76行目**: パラメータ定義（Path, Provider, SingleItem, NewChild）
2. **78-82行目**: カレントディレクトリ変換処理
3. **83-102行目**: NewChildモードの処理
4. **103-116行目**: 通常モードの処理

#### Step 3: NewChildモード処理を理解する

新規ファイル作成用のパス解決ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Resolve-DbaPath.ps1 | `public/Resolve-DbaPath.ps1` 83-102行目 | 親パス分離、解決、結合ロジック |

**主要処理フロー**:
- **84-85行目**: Split-Pathで親パスと子要素を分離
- **87-90行目**: 親パス解決（空の場合はGet-Location使用）
- **92-94行目**: SingleItem検証
- **96-98行目**: Provider検証
- **100-101行目**: Join-Pathで結合、出力

#### Step 4: 通常モード処理を理解する

標準的なパス解決ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Resolve-DbaPath.ps1 | `public/Resolve-DbaPath.ps1` 103-116行目 | Resolve-Path実行、検証ロジック |

**主要処理フロー**:
- **104行目**: Resolve-Pathでパス解決
- **107-109行目**: SingleItem検証
- **111-113行目**: Provider検証
- **115行目**: ProviderPathを出力

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

```
Resolve-DbaPath
    │
    ├─ Get-Location (カレントディレクトリ取得)
    │
    ├─ Split-Path (パス分割 - NewChildモード)
    │
    ├─ Resolve-Path (パス解決)
    │
    ├─ Join-Path (パス結合 - NewChildモード)
    │
    └─ Stop-Function (エラー処理)
```

### データフロー図

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

Path文字列   ───▶ Resolve-Path実行      ───▶ 解決済みパス文字列
                      │
                ┌─────┴─────┐
                │           │
           NewChild      通常
                │           │
        親パス解決    直接解決
        ＋結合
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Resolve-DbaPath.ps1 | `public/Resolve-DbaPath.ps1` | ソース | メイン関数 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理関数 |
