# 機能設計書 15-ファイル操作(SPC f)

## 概要

本ドキュメントは、space-vimにおけるファイル操作機能（SPC f）の設計仕様を記述する。SPCキーに続いて「f」を押下することで、ファイル保存、ファイルツリー表示、フォールド操作などのファイル関連操作を提供する機能である。

### 本機能の処理概要

ファイル操作機能は、ファイルの保存、ファイルエクスプローラの表示/切替、コード折りたたみ（フォールド）レベルの制御など、ファイル操作に関連するキーバインディング群を提供する。NERDTreeとの連携、fzfによるファイル検索、vimrcのリロードなども含まれる。

**業務上の目的・背景**：プログラミング作業では、ファイルの保存、プロジェクト内のファイル探索、コードの折りたたみ表示切替などが頻繁に行われる。SPC fプレフィックスにより、これらの操作を統一的なキー体系で提供し、作業効率を向上させる。

**機能の利用シーン**：
- ファイルを素早く保存したい場合（SPC f s）
- ファイルツリーを表示/非表示したい場合（SPC f t）
- 現在のファイルをファイルツリーで表示したい場合（SPC f d）
- コードのフォールドレベルを変更したい場合（SPC f 0-9）
- ホームディレクトリのファイルを検索したい場合（SPC f f）
- 設定ファイル（vimrc）をリロードしたい場合（SPC f R）

**主要な処理内容**：
1. SPC f s：ファイル保存（:w）
2. SPC f t：NERDTreeトグル表示
3. SPC f d：NERDTreeで現在ファイルを表示
4. SPC f 0-9：フォールドレベル設定
5. SPC f f：ホームディレクトリのファイル検索
6. SPC f ?：カレントディレクトリのファイル検索
7. SPC f R：vimrcリロード
8. SPC f b：現在バッファ内でのfzf検索

**関連システム・外部連携**：
- NERDTree：ファイルツリー表示
- fzf.vim / vim-clap：ファイル検索
- devicons：ファイルアイコン表示

**権限による制御**：本機能に権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | NERDTree（ファイルエクスプローラ） | 補助機能 | SPC f tでNERDTreeトグル、SPC f dでカレントファイル位置表示 |
| 5 | CtrlP（ファイル検索） | 補助機能 | SPC f rで最近使用したファイル検索 |

## 機能種別

ファイル管理 / ナビゲーション / フォールド制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| キーシーケンス | String | Yes | SPC f に続くキー入力 | 定義済みキーのみ受付 |
| フォールドレベル | Number | No | 0-9の数字キー | 0-9の範囲 |

### 入力データソース

- ユーザーキー入力
- ファイルシステム（ファイル検索時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ファイル保存 | ファイル | ディスクへの書き込み |
| NERDTree表示 | UI | サイドバーファイルツリー |
| fzfウィンドウ | UI | ファイル検索インターフェース |
| フォールドレベル変更 | Vim状態 | コード折りたたみ表示 |

### 出力先

- ファイルシステム（保存時）
- Vimウィンドウ空間（NERDTree、fzf）
- Vim foldlevel設定

## 処理フロー

### 処理シーケンス

```
1. SPC f キー入力
   └─ which-keyによるサブキー一覧表示
2. サブキー入力に応じた処理分岐
   ├─ s:    ファイル保存（:w）
   ├─ t:    NERDTreeトグル
   ├─ d:    NERDTree現在ファイル表示
   ├─ 0-9:  フォールドレベル設定（:set foldlevel=N）
   ├─ f:    ホームディレクトリファイル検索
   ├─ ?:    カレントディレクトリファイル検索
   ├─ R:    vimrcリロード（:source $MYVIMRC）
   └─ b:    現在バッファ内検索（BLines）
```

### フローチャート

```mermaid
flowchart TD
    A[SPC f 入力] --> B{サブキー?}
    B -->|s| C[ファイル保存]
    B -->|t| D[NERDTreeトグル]
    B -->|d| E[NERDTreeで現在ファイル表示]
    B -->|0-9| F[フォールドレベル設定]
    B -->|f| G[ホームディレクトリファイル検索]
    B -->|?| H[カレントディレクトリファイル検索]
    B -->|R| I[vimrcリロード]
    B -->|b| J[バッファ内検索]
    C --> K[保存完了]
    D --> L[NERDTree表示/非表示]
    E --> M[NERDTreeで位置表示]
    F --> N[フォールド表示更新]
    G --> O[fzfファイル選択UI]
    H --> O
    I --> P[設定リロード完了]
    J --> Q[fzf行選択UI]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ファイル保存 | SPC f sで現在のファイルを保存 | バッファが変更されている場合 |
| BR-002 | NERDTreeトグル | SPC f tでNERDTreeの表示/非表示を切り替え | NERDTreeプラグインが読み込まれている場合 |
| BR-003 | フォールドレベル | 0-9でfoldlevelを設定（0=すべて折りたたみ、9=すべて展開） | foldmethodが設定されている場合 |
| BR-004 | vimrcリロード | SPC f Rで$MYVIMRCをsource | 常時実行可能 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E45 | 読み取り専用 | 読み取り専用ファイルに保存しようとした | :w!で強制保存 |
| - | ディレクトリ不在 | 保存先ディレクトリが存在しない | ディレクトリを作成 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ファイル保存は即時実行
- NERDTree表示は100ミリ秒以内
- fzfファイル検索は初回起動時にインデックス構築

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

- 読み取り専用ファイルへの書き込みはVimが警告

## 備考

- NERDTreeが読み込まれていない場合、SPC f tは動作しない
- フォールド機能はfoldmethodが設定されている場合に有効

---

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

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

### 推奨読解順序

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

ファイル操作のキーマッピング定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | leader.vim | `core/autoload/spacevim/map/leader.vim` | s:leader_map['f']の構造を理解 |

**読解のコツ**: ファイル操作は'+find/files/fold'という複合的な名前が付けられている。

**主要データ構造**:
- **72行目**: `let s:leader_map['f'] = {` - ファイル操作グループ開始
- **73行目**: `'name' : '+find/files/fold'` - グループ名
- **74-83行目**: `'0' : '0-fold-level'` 〜 `'9' : '9-fold-level'` - フォールドレベル
- **84行目**: `'d' : 'find-current-buffer-in-NERDTree'` - NERDTreeで表示
- **85行目**: `'f' : 'files-in-home-direcotry'` - ホームディレクトリ検索
- **86行目**: `'s' : 'save-file'` - ファイル保存
- **87行目**: `'t' : 'toggle-filetree'` - NERDTreeトグル
- **89行目**: `'R' : 'reload-vimrc'` - vimrcリロード
- **90行目**: `'b' : ['spacevim#map#manager#BLines()', 'fzf-find-current-buffer']` - バッファ内検索

#### Step 2: キーマッピング実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | keybindings.vim | `layers/+distributions/better-defaults/keybindings.vim` | vimrcリロード |
| 2-2 | config.vim | `layers/+tools/fzf/config.vim` | fzfファイル検索 |

**主要処理フロー**:
- **2行目（keybindings.vim）**: `nnoremap <Leader>fR :source $MYVIMRC<CR>` - vimrcリロード
- **1-4行目（fzf config.vim）**: ファイル・バッファ検索マッピング

#### Step 3: NERDTree連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | config.vim | `layers/+tools/file-manager/config.vim` | NERDTree設定 |

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

```
SPC f キー入力
    │
    ├─ SPC f s
    │      └─ :w コマンド実行
    │
    ├─ SPC f t
    │      └─ :NERDTreeToggle 実行
    │
    ├─ SPC f d
    │      └─ :NERDTreeFind 実行
    │
    ├─ SPC f 0-9
    │      └─ :set foldlevel={N} 実行
    │
    ├─ SPC f f
    │      └─ fzf ホームディレクトリ検索
    │
    ├─ SPC f ?
    │      └─ :Files (fzf.vim) 実行
    │
    ├─ SPC f R
    │      └─ :source $MYVIMRC 実行
    │
    └─ SPC f b
           └─ spacevim#map#manager#BLines()
                  └─ :BLines (fzf.vim) 実行
```

### データフロー図

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

ユーザーキー入力 ────▶ which-keyディスパッチ ───▶ サブキー選択UI
    │                       │
    ▼                       ▼
SPC f + サブキー ────▶ マッピング解決 ──────────▶ コマンド実行
                            │
                            ├─▶ :w ─────────────▶ ファイル保存
                            ├─▶ :NERDTreeToggle ─▶ ツリー表示/非表示
                            ├─▶ :NERDTreeFind ──▶ ツリーで位置表示
                            ├─▶ :set foldlevel ─▶ フォールド変更
                            └─▶ :Files/:BLines ─▶ fzf検索UI
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| leader.vim | `core/autoload/spacevim/map/leader.vim` | ソース | ファイル操作キーマッピング定義 |
| keybindings.vim | `layers/+distributions/better-defaults/keybindings.vim` | ソース | vimrcリロード実装 |
| manager.vim | `core/autoload/spacevim/map/manager.vim` | ソース | BLines関数実装 |
| config.vim | `layers/+tools/fzf/config.vim` | 設定 | fzfファイル検索設定 |
| config.vim | `layers/+tools/file-manager/config.vim` | 設定 | NERDTree設定 |
