# 機能設計書 7-バックアップ機能

## 概要

本ドキュメントは、space-vimのバックアップ機能の設計について記述する。この機能は、インストール時に既存のvimrcをバックアップしてから新規設定を適用する仕組みを提供する。

### 本機能の処理概要

バックアップ機能は、space-vimのインストール前に既存のVim/NeoVim設定ファイルを日付付きのファイル名でリネーム保存する。これにより、ユーザーが既存の設定を失うことなく、必要に応じて元の設定に戻すことができる。

**業務上の目的・背景**：多くのVimユーザーは長年かけてカスタマイズした.vimrc設定を持っている。space-vimのインストール時にこれらの設定を上書きしてしまうと、ユーザーの大切な設定が失われる恐れがある。バックアップ機能はこのリスクを軽減し、ユーザーが安心してspace-vimを試用できるようにする。また、space-vimが合わなかった場合に元の設定に戻すことも容易になる。

**機能の利用シーン**：
- space-vimを初めてインストールし、既存の.vimrcが存在する場合
- space-vimを再インストールする場合
- NeoVimのinit.vimが存在する状態でspace-vimをインストールする場合

**主要な処理内容**：
1. バックアップ対象ファイルの存在確認
2. 現在の日時を取得してファイル名サフィックスを生成
3. mvコマンドで既存ファイルをリネーム
4. 成功メッセージの表示

**関連システム・外部連携**：
- ファイルシステム: mvコマンドによるファイルリネーム
- dateコマンド: バックアップファイル名の日時サフィックス生成

**権限による制御**：本機能に権限制御はない。ただし、対象ファイルへの書き込み権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | ターミナル | 実行環境 | バックアップ処理の実行とメッセージ表示 |

## 機能種別

データバックアップ / ファイル操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ファイルパス | String | Yes | バックアップ対象のファイルパス | ファイルが存在すること |

### 入力データソース

1. **ファイルシステム**: 既存の設定ファイル
   - Vim: `~/.vimrc`
   - NeoVim: `~/.config/nvim/init.vim`

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| バックアップファイル | ファイル | 日付付きのリネームファイル |

### 出力先

- ファイルシステム（元ファイルと同じディレクトリ）
- ファイル名形式: `{元のファイル名}.{YYYYMMDD}_{UNIXタイムスタンプ}`

## 処理フロー

### 処理シーケンス

```
1. backup()関数呼び出し
   └─ 引数: バックアップ対象ファイルパス

2. ファイル存在確認
   └─ [ -e "$1" ] でファイル存在をチェック

3. 日時サフィックス生成
   └─ date +%Y%m%d_%s で日付とUNIXタイムスタンプを生成

4. ファイルリネーム
   └─ mv -v で既存ファイルをリネーム

5. 成功メッセージ表示
   └─ success関数でメッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[backup関数呼び出し] --> B{ファイル存在?}
    B -->|No| C[処理終了 - 何もしない]
    B -->|Yes| D[メッセージ表示]
    D --> E[日付サフィックス生成]
    E --> F[mv -v でリネーム]
    F --> G{成功?}
    G -->|Yes| H[成功メッセージ表示]
    G -->|No| I[エラー - ret値が非0]
    H --> J[完了]
    I --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 存在確認 | ファイルが存在する場合のみバックアップ実行 | 常時 |
| BR-02 | 日付形式 | YYYYMMDD_UNIXタイムスタンプの形式でサフィックス | 常時 |
| BR-03 | 非破壊 | 元ファイルは削除せずリネームのみ | 常時 |
| BR-04 | 冪等性 | 同じ秒で複数回実行されない限り競合しない | 通常使用時 |

### 計算ロジック

バックアップファイル名の計算:
```
バックアップファイル名 = 元ファイルパス + "." + YYYYMMDD + "_" + UNIXタイムスタンプ
```

例: `~/.vimrc.20240115_1705312500`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | mvエラー | ファイルのリネームに失敗 | ret変数が非0になる |
| - | 権限エラー | ファイルへの書き込み権限がない | mvコマンドのエラー出力 |

### リトライ仕様

該当なし（手動で再実行）

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

該当なし

## パフォーマンス要件

- 処理時間: 即座に完了（ファイルシステム操作のみ）

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

- バックアップファイルは元ファイルと同じ権限を維持
- バックアップファイルには機密情報が含まれる可能性がある

## 備考

- 複数回インストールしても、それぞれ異なるタイムスタンプでバックアップされる
- バックアップファイルの手動削除はユーザーの責任

---

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

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

### 推奨読解順序

#### Step 1: バックアップ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | install.sh | `install.sh` | backup()関数の実装 |

**読解のコツ**: backup()関数は以下の構造:
```bash
backup() {
  if [ -e "$1" ]; then
    echo
    msg "\\033[1;34m==>\\033[0m Attempting to back up your original vim configuration"
    today=$(date +%Y%m%d_%s)
    mv -v "$1" "$1.$today"

    ret="$?"
    success "Your original vim configuration has been backed up"
  fi
}
```
- `$1`: 第1引数（バックアップ対象ファイルパス）
- `[ -e "$1" ]`: ファイル存在確認
- `date +%Y%m%d_%s`: 日付形式（例: 20240115_1705312500）
- `mv -v`: 詳細出力付きでリネーム
- `$?`: 直前コマンドの終了ステータス

#### Step 2: 呼び出し元を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | install.sh | `install.sh` | install_for_vim(), install_for_neovim()からの呼び出し |

**主要処理フロー**:
- **122-134行目**: install_for_vim()
  - **123行目**: `backup "$HOME/.vimrc"` - Vim設定をバックアップ
- **136-149行目**: install_for_neovim()
  - **137行目**: `backup "$HOME/.config/nvim/init.vim"` - NeoVim設定をバックアップ

#### Step 3: 成功メッセージ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | install.sh | `install.sh` | success()関数の実装 |

**主要処理フロー**:
- **60-64行目**: success()関数
  - **61行目**: `$ret`が0（成功）の場合のみメッセージ表示
  - **62行目**: チェックマーク付きの緑色メッセージを出力

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

```
install_for_vim()  [install.sh:122]
    │
    └─ backup("$HOME/.vimrc")  [install.sh:110]
           │
           ├─ [ -e "$1" ] ファイル存在確認
           │
           ├─ date +%Y%m%d_%s サフィックス生成
           │
           ├─ mv -v リネーム実行
           │
           └─ success() 成功メッセージ
                  └─ msg() メッセージ出力

install_for_neovim()  [install.sh:136]
    │
    └─ backup("$HOME/.config/nvim/init.vim")  [install.sh:110]
           │
           └─ （同上の処理）
```

### データフロー図

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

~/.vimrc ────────────────────▶ backup() ──────────────────────▶ ~/.vimrc.YYYYMMDD_s
  │                               │
  │                               ├─ ファイル存在確認
  │                               │
  │                               ├─ 日付サフィックス生成
  │                               │      └─ date +%Y%m%d_%s
  │                               │
  │                               └─ mv -v でリネーム
  │
~/.config/nvim/init.vim ─────▶ backup() ──────────────────────▶ ~/.config/nvim/init.vim.YYYYMMDD_s
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| install.sh | `install.sh` | スクリプト | バックアップ関数の実装 |
