# 機能設計書 92-ManagedFileChooser

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるマネージドファイルチューザー（ManagedFileChooser）機能の設計仕様を記述します。ManagedFileChooserは、クロスプラットフォームで動作するマネージド実装のファイル選択ダイアログを提供し、プラットフォーム固有のネイティブダイアログが利用できない環境でも一貫したファイル選択UIを実現します。

### 本機能の処理概要

ManagedFileChooserは、ファイル・フォルダの参照・選択を行うためのUIコンポーネントです。ファイルシステムのナビゲーション、ファイルフィルタリング、複数選択などの機能を提供し、ファイルを開く・保存・フォルダ選択の各モードをサポートします。

**業務上の目的・背景**：デスクトップアプリケーションでは、ユーザーがファイルを開いたり保存したりする操作が頻繁に必要です。しかし、LinuxやmacOS、Windowsなど異なるプラットフォームでは、ネイティブのファイルダイアログAPIが異なります。ManagedFileChooserは、.NETで完全に実装されたファイルダイアログを提供することで、プラットフォーム間の差異を吸収し、一貫したユーザーエクスペリエンスを実現します。また、ネイティブダイアログが利用できないHeadless環境やカスタム環境でも動作します。

**機能の利用シーン**：
- ファイルを開くダイアログの表示
- ファイルを保存するダイアログの表示
- フォルダを選択するダイアログの表示
- ネイティブダイアログが利用できない環境でのファイル選択
- カスタマイズされたファイル選択UIが必要な場面

**主要な処理内容**：
1. ファイルシステムの参照（ディレクトリ内容の列挙）
2. クイックリンク（お気に入りパス）の表示
3. ファイルフィルタの適用（拡張子によるフィルタリング）
4. 隠しファイルの表示/非表示切り替え
5. 複数ファイル選択のサポート
6. ファイル保存時の上書き確認
7. デフォルト拡張子の自動付与

**関連システム・外部連携**：ファイルシステムAPI（System.IO）を使用してディレクトリ・ファイル情報を取得します。IMountedVolumeInfoProviderインターフェースを通じてマウントされたボリューム情報を取得し、クイックリンクに表示します。

**権限による制御**：ファイルシステムへのアクセス権限が必要です。アクセス権限がないディレクトリへのナビゲート時はUnauthorizedAccessExceptionをキャッチして処理を継続します。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 29 | Dialogs | 主機能 | ファイル選択ダイアログのデモ表示 |

## 機能種別

ダイアログUI / ファイル選択 / データ取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| FilePickerOpenOptions | FilePickerOpenOptions | No | ファイルを開くダイアログのオプション | - |
| FilePickerSaveOptions | FilePickerSaveOptions | No | ファイルを保存するダイアログのオプション | - |
| FolderPickerOpenOptions | FolderPickerOpenOptions | No | フォルダ選択ダイアログのオプション | - |
| ManagedFileDialogOptions | ManagedFileDialogOptions | Yes | ダイアログ共通オプション | - |
| Title | string | No | ダイアログタイトル | - |
| AllowMultiple | bool | No | 複数選択許可フラグ | - |
| FileTypeFilter | IReadOnlyList<FilePickerFileType> | No | ファイルタイプフィルタ | - |
| SuggestedStartLocation | IStorageFolder | No | 初期表示ディレクトリ | 存在確認 |

### 入力データソース

- ファイルシステム（ディレクトリ・ファイル情報）
- IMountedVolumeInfoProvider（マウントボリューム情報）
- ManagedFileChooserSources（クイックリンク情報）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 選択ファイルパス | string[] | ユーザーが選択したファイル/フォルダのフルパス配列 |
| キャンセル | - | ユーザーがキャンセルした場合は空配列 |

### 出力先

- CompleteRequestedイベント経由で呼び出し元に返却
- CancelRequestedイベントでキャンセル通知

## 処理フロー

### 処理シーケンス

```
1. ダイアログ初期化
   └─ オプションに応じたViewModelの生成
2. クイックリンク取得
   └─ IMountedVolumeInfoProviderからマウントボリューム取得
3. 初期ディレクトリナビゲーション
   └─ SuggestedStartLocationまたはカレントディレクトリへ移動
4. ファイルリスト表示
   └─ ディレクトリ内容を列挙しItemsに追加
5. ユーザー操作の待機
   └─ ナビゲーション、選択、フィルタ変更等
6. ファイル選択確定
   └─ OKボタン押下で選択パスを返却
```

### フローチャート

```mermaid
flowchart TD
    A[ダイアログ表示] --> B[初期ディレクトリへナビゲート]
    B --> C[ファイル一覧取得]
    C --> D{隠しファイル表示?}
    D -->|Yes| E[全ファイル表示]
    D -->|No| F[隠しファイル除外]
    E --> G{フィルタ適用?}
    F --> G
    G -->|Yes| H[フィルタ条件でファイル絞込]
    G -->|No| I[全ファイル表示]
    H --> J[ファイル一覧表示]
    I --> J
    J --> K{ユーザー操作}
    K -->|ナビゲート| B
    K -->|選択| L[選択項目更新]
    K -->|OK| M{保存モード?}
    K -->|キャンセル| N[CancelRequested発火]
    M -->|Yes| O{上書き確認必要?}
    M -->|No| P[CompleteRequested発火]
    O -->|Yes| Q[上書き確認ダイアログ]
    O -->|No| P
    Q -->|OK| P
    Q -->|キャンセル| J
    L --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-92-01 | 隠しファイル判定 | Windowsでは Hidden/System属性、Unix系では先頭ドット | ShowHiddenFiles=false時 |
| BR-92-02 | フォルダ優先ソート | フォルダを先に、その後ファイルを名前順で表示 | 常時 |
| BR-92-03 | 拡張子自動付与 | 保存時に拡張子がなければDefaultExtensionを付与 | 保存モード時 |
| BR-92-04 | 上書き確認 | 既存ファイルへの保存時は確認ダイアログ表示 | ShowOverwritePrompt=true時 |
| BR-92-05 | フォルダ選択制限 | ファイル選択モードではフォルダを選択不可 | AllowDirectorySelection=false時 |

### 計算ロジック

ファイルサイズはFileInfo.Lengthから取得し、表示時にFileSizeStringConverterで人間が読みやすい形式（KB/MB/GB）に変換されます。

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

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

本機能はデータベース操作を伴いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| UnauthorizedAccess-01 | UnauthorizedAccessException | アクセス権限のないディレクトリへのナビゲート | 例外をキャッチしてリスト表示をスキップ |
| DirectoryNotFound-01 | 正常処理 | 存在しないパスへのナビゲート | ルートディレクトリへナビゲート |

### リトライ仕様

エラー発生時のリトライは行いません。アクセス権限エラー時は空のリストを表示します。

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

本機能はUI処理のため、トランザクション管理は不要です。

## パフォーマンス要件

- ディレクトリ内容の列挙は非同期で実行
- 大量ファイルのディレクトリでも応答性を維持
- マウントボリューム変更の監視は弱参照で実装

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

- ファイルシステムアクセス権限に従った動作
- 隠しファイル・システムファイルのデフォルト非表示
- サンドボックス環境での動作制限

## 備考

ManagedFileChooserは、ネイティブファイルダイアログの代替として使用されます。プラットフォームがネイティブダイアログをサポートしている場合は、そちらが優先されることがあります。

---

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

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

### 推奨読解順序

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

まず、ファイルチューザーで使用されるViewModelとデータモデルを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ManagedFileChooserItemViewModel.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserItemViewModel.cs` | ファイル/フォルダアイテムのViewModel |
| 1-2 | ManagedFileChooserFilterViewModel.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserFilterViewModel.cs` | ファイルフィルタのViewModel |
| 1-3 | ManagedFileChooserItemType.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserItemType.cs` | アイテムタイプの列挙型 |

**読解のコツ**: AvaloniaDialogsInternalViewModelBaseからの継承を確認し、RaisePropertyChangedパターンを理解してください。

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

UIコントロールのエントリーポイントを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ManagedFileChooser.cs | `src/Avalonia.Dialogs/ManagedFileChooser.cs` | ファイルチューザーUIコントロール |

**主要処理フロー**:
1. **22-24行目**: PointerPressedイベントハンドラの登録
2. **28-55行目**: OnPointerPressed - ダブルクリックとクイックリンク選択の処理
3. **57-90行目**: OnDataContextChanged - 初期選択アイテムへのスクロール
4. **92-96行目**: OnApplyTemplate - テンプレートパーツの取得

#### Step 3: ビジネスロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ManagedFileChooserViewModel.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserViewModel.cs` | メインのビジネスロジック |

**主要処理フロー**:
- **110-135行目**: コンストラクタ - クイックリンク初期化、ボリューム監視
- **137-156行目**: FilePickerOpenOptions用コンストラクタ
- **158-177行目**: FilePickerSaveOptions用コンストラクタ
- **179-192行目**: FolderPickerOpenOptions用コンストラクタ
- **290-365行目**: Navigate() - ディレクトリナビゲーション処理
- **399-430行目**: Ok() - 選択確定処理

#### Step 4: 外部連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ManagedFileChooserSources.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserSources.cs` | クイックリンクソース管理 |
| 4-2 | BclMountedVolumeInfoProvider.cs | `src/Avalonia.Dialogs/Internal/BclMountedVolumeInfoProvider.cs` | マウントボリューム情報提供 |
| 4-3 | ManagedStorageProvider.cs | `src/Avalonia.Dialogs/ManagedStorageProvider.cs` | ストレージプロバイダ実装 |

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

```
ManagedFileChooser (UIコントロール)
    │
    ├─ ManagedFileChooserViewModel
    │      ├─ Navigate() → ディレクトリ内容列挙
    │      │      └─ DirectoryInfo.EnumerateFileSystemInfos()
    │      ├─ Ok() → CompleteRequested発火
    │      ├─ Cancel() → CancelRequested発火
    │      └─ Refresh() → Navigate(Location)
    │
    ├─ ManagedFileChooserSources
    │      └─ GetAllItems() → クイックリンク取得
    │
    └─ IMountedVolumeInfoProvider
           └─ Listen() → ボリューム変更監視
```

### データフロー図

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

ダイアログオプション ───▶ ManagedFileChooserViewModel ───▶ 選択パス配列
         │                     │
         │                     ├─ Navigate()
         │                     │      └─ DirectoryInfo
         │                     │             └─ ファイル情報
         │                     │
         │                     └─ フィルタリング
         │                            └─ 表示アイテム
         │
ファイルシステム ───────▶ Items コレクション
         │
IMountedVolumeInfoProvider ─▶ QuickLinks コレクション
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ManagedFileChooser.cs | `src/Avalonia.Dialogs/ManagedFileChooser.cs` | ソース | UIコントロール本体 |
| ManagedFileChooserViewModel.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserViewModel.cs` | ソース | メインViewModel |
| ManagedFileChooserItemViewModel.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserItemViewModel.cs` | ソース | アイテムViewModel |
| ManagedFileChooserFilterViewModel.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserFilterViewModel.cs` | ソース | フィルタViewModel |
| ManagedFileChooserNavigationItem.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserNavigationItem.cs` | ソース | ナビゲーションアイテム |
| ManagedFileChooserSources.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserSources.cs` | ソース | クイックリンクソース |
| ManagedFileChooserItemType.cs | `src/Avalonia.Dialogs/Internal/ManagedFileChooserItemType.cs` | ソース | アイテムタイプ列挙 |
| ManagedFileDialogOptions.cs | `src/Avalonia.Dialogs/ManagedFileDialogOptions.cs` | ソース | ダイアログオプション |
| ManagedFileDialogExtensions.cs | `src/Avalonia.Dialogs/ManagedFileDialogExtensions.cs` | ソース | 拡張メソッド |
| ManagedStorageProvider.cs | `src/Avalonia.Dialogs/ManagedStorageProvider.cs` | ソース | ストレージプロバイダ |
| ManagedFileChooserOverwritePrompt.cs | `src/Avalonia.Dialogs/ManagedFileChooserOverwritePrompt.cs` | ソース | 上書き確認ダイアログ |
| BclMountedVolumeInfoProvider.cs | `src/Avalonia.Dialogs/Internal/BclMountedVolumeInfoProvider.cs` | ソース | ボリューム情報プロバイダ |
| FileSizeStringConverter.cs | `src/Avalonia.Dialogs/Internal/FileSizeStringConverter.cs` | ソース | ファイルサイズ変換 |
