# Issue #07: README.md 更新

## 概要

Phase2（#01-#06）で実装されるバージョン管理機能を `readme.md` に反映する。
機能の概要だけでなく、**なぜこの設計を採用したか**を明確にし、ユーザーが安心して使える情報を提供する。

## 現状

現在のREADME.mdはPhase1.6までの機能を記載:
- `@node`, `@entry_point` デコレータ
- `typed_pipeline()` による型安全なパイプライン
- 3層エラーハンドリング（`on_error`, `on_step`, `RetryPolicy`）

Phase2の機能が欠如:
- バージョン管理（`.railway/project.yaml`）
- `railway update` コマンド
- `railway backup` コマンド
- バージョン互換性チェック

## 目標

### 1. ロードマップセクションの更新

```markdown
### Phase 2 ✅ 完了（バージョン管理）
- ✅ プロジェクトバージョン記録（`.railway/project.yaml`）
- ✅ バージョン互換性チェック（`railway new` 実行時）
- ✅ `railway update` コマンド（プロジェクトマイグレーション）
- ✅ `railway backup` コマンド（バックアップ・ロールバック）
- ✅ Dry-run モード（`--dry-run` で変更プレビュー）

### Phase 3 📋 計画中
- 🔜 並列パイプライン実行
- 🔜 グラフベースワークフロー
- 🔜 WebUI
- 🔜 メトリクス収集
```

### 2. CLI Commands セクションに追加

```markdown
### バージョン管理
```bash
railway update                   # プロジェクトを最新バージョンに更新
railway update --dry-run         # 変更をプレビュー（実行しない）
railway update --init            # バージョン情報のないプロジェクトを初期化
railway backup list              # バックアップ一覧
railway backup restore           # バックアップから復元
railway backup clean --keep 3    # 古いバックアップを削除
```
```

### 3. 新セクション「バージョン管理」を追加

READMEの「設定管理」セクションの後に挿入:

---

## バージョン管理

Railway Framework はプロジェクトのバージョン情報を追跡し、安全なアップグレードを支援します。

### なぜバージョン管理が必要か？

| 問題 | 影響 | Railway の解決策 |
|------|------|------------------|
| バージョン不明 | チームで不整合発生 | `.railway/project.yaml` で明示 |
| テンプレート変更 | `railway new` で不整合 | 互換性チェック + 警告 |
| 手動マイグレーション | 面倒、ミスしやすい | `railway update` で自動化 |

### プロジェクトメタデータ

`railway init` 実行時に自動生成:

```yaml
# .railway/project.yaml
railway:
  version: "0.10.0"              # 生成時のrailway-frameworkバージョン
  created_at: "2026-01-23T10:30:00+09:00"
  updated_at: "2026-01-23T10:30:00+09:00"

project:
  name: "my_automation"

compatibility:
  min_version: "0.10.0"          # 必要な最小バージョン
```

**設計判断:**

| 判断 | 理由 |
|------|------|
| YAML形式 | 人間が読みやすく、手動編集も可能 |
| `.railway/` ディレクトリ | フレームワーク関連ファイルを集約、`.gitignore` 不要 |
| Git管理対象 | チーム全員でバージョン情報を共有 |

### バージョン互換性チェック

`railway new` 系コマンド実行時に自動チェック:

```bash
$ railway new node fetch_data

⚠️  バージョン不一致を検出
    プロジェクト: 0.9.0
    現在:         0.10.0

    マイナーバージョンが異なります。
    テンプレートが更新されている可能性があります。

    [c] 続行 / [u] 'railway update' を実行 / [a] 中止
    Choice: _
```

**互換性ルール:**

| 条件 | 動作 |
|------|------|
| 同一バージョン | そのまま実行 |
| マイナー差異 | 警告 + 確認 |
| メジャー差異 | エラー + 拒否 |
| バージョン不明 | 警告 + 確認 |

### railway update コマンド

プロジェクトを最新バージョンにマイグレーション:

```bash
$ railway update

🔍 プロジェクトを分析中...

   プロジェクト名:      my_automation
   現在のバージョン:    0.9.0
   ターゲットバージョン: 0.10.0

📋 適用される変更:

   [ファイル追加]
   + .railway/project.yaml

   [設定更新]
   ~ config/development.yaml
     - 新規キー: railway.version_check

続行しますか? [y/N]: y

✅ 更新完了
   バックアップ: .railway/backups/0.9.0_20260123_103000/
   新バージョン: 0.10.0
```

**オプション:**

```bash
railway update --dry-run     # 変更をプレビュー（実行しない）
railway update --init        # バージョン情報のないプロジェクトを初期化
railway update --force       # 確認なしで実行
railway update --no-backup   # バックアップをスキップ
```

**設計判断:**

| 判断 | 理由 |
|------|------|
| 自動バックアップ | 失敗時にロールバック可能、安全第一 |
| 確認プロンプト | 意図しない変更を防止 |
| 段階的マイグレーション | 0.9→0.10→0.11 と順番に適用、大きなジャンプも安全 |
| ユーザーコード不変更 | `src/nodes/*`, `tests/*` は絶対に変更しない |

### バックアップ・ロールバック

```bash
# バックアップ一覧
$ railway backup list
  0.9.0_20260123_103000  2時間前   15KB
  0.8.0_20260120_090000  3日前     12KB

# 復元
$ railway backup restore
どのバックアップに戻しますか? [1]: 1
✅ ロールバック完了

# 古いバックアップを削除
$ railway backup clean --keep 3
🗑️  2件のバックアップを削除しました
```

**バックアップ対象:**

| 対象 | 理由 |
|------|------|
| `.railway/project.yaml` | バージョン情報の復元 |
| `TUTORIAL.md` | 自動生成ファイル |
| `pyproject.toml` | 依存関係 |
| `config/*.yaml` | 設定ファイル |

**除外対象（ユーザーコード）:**

- `src/nodes/*` - 更新対象外
- `tests/*` - 更新対象外
- `.venv/` - 仮想環境

### Dry-run モード

変更を実行せずにプレビュー:

```bash
$ railway update --dry-run

📋 適用される変更:

   [ファイル追加]
   + src/py.typed (0 bytes)

   [ファイル更新]
   ~ TUTORIAL.md (+150/-0 lines)
     - セクション「Step 8」を追加

   [設定更新]
   ~ config/development.yaml
     - 新規キー: railway.version_check
     - キー名変更: log_level → logging.level

   [コード変更ガイダンス（手動対応推奨）]
   ! src/nodes/fetch_data.py:15
     @node(log_input=True)  →  @node(log_inputs=True)

[dry-run] 実際の変更は行われませんでした。
実行するには: railway update
```

---

### 4. 特徴セクションに追加

```markdown
- 🔄 **バージョン管理**: プロジェクトバージョン追跡、自動マイグレーション
```

## 設計

### 追加する情報の構成

```
readme.md
├── ...（既存）
├── CLI Commands
│   └── バージョン管理（追加）
├── 特徴（1行追加）
├── ...（既存）
├── 設定管理
├── バージョン管理（新規セクション）★
│   ├── なぜバージョン管理が必要か？
│   ├── プロジェクトメタデータ
│   ├── バージョン互換性チェック
│   ├── railway update コマンド
│   ├── バックアップ・ロールバック
│   └── Dry-run モード
├── テストの書き方
└── ロードマップ（更新）★
```

### なぜこの構成か

| 判断 | 理由 |
|------|------|
| 「設定管理」の後に配置 | 設定に関連する機能として自然な流れ |
| コマンドは先にCLI Commandsセクションに追加 | 素早くコマンドを探せる |
| 「なぜ必要か」を最初に説明 | 機能の価値を先に伝える |
| 設計判断を各機能に添える | ユーザーが安心して使える |

## 実装

### 実装手順

1. `readme.md` を読み込む
2. CLI Commands セクションに「バージョン管理」を追加
3. 特徴セクションに1行追加
4. 「設定管理」セクションの後に「バージョン管理」セクションを挿入
5. ロードマップセクションを更新

### コード変更

#### 1. CLI Commands セクション（「実行」の後に追加）

```python
# Insert after "### 実行" section
CLI_COMMANDS_ADDITION = """
### バージョン管理
```bash
railway update                   # プロジェクトを最新バージョンに更新
railway update --dry-run         # 変更をプレビュー（実行しない）
railway update --init            # バージョン情報のないプロジェクトを初期化
railway backup list              # バックアップ一覧
railway backup restore           # バックアップから復元
railway backup clean --keep 3    # 古いバックアップを削除
```
"""
```

#### 2. 特徴セクション

```markdown
- 🔄 **バージョン管理**: プロジェクトバージョン追跡、自動マイグレーション
```

#### 3. バージョン管理セクション（全文は「目標」セクション参照）

「設定管理」セクションの `---` の後に挿入。

#### 4. ロードマップセクション

```markdown
### Phase 2 ✅ 完了（バージョン管理）
- ✅ プロジェクトバージョン記録（`.railway/project.yaml`）
- ✅ バージョン互換性チェック（`railway new` 実行時）
- ✅ `railway update` コマンド（プロジェクトマイグレーション）
- ✅ `railway backup` コマンド（バックアップ・ロールバック）
- ✅ Dry-run モード（`--dry-run` で変更プレビュー）

### Phase 3 📋 計画中
- 🔜 並列パイプライン実行
- 🔜 グラフベースワークフロー
- 🔜 WebUI
- 🔜 メトリクス収集
```

## テスト（TDD: Red → Green → Refactor）

### テストファイル構成

```
tests/unit/docs/
└── test_readme_content.py
```

### Red Phase: テストを先に書く

```python
# tests/unit/docs/test_readme_content.py
"""README.md の内容を検証するテスト。

TDD Red Phase: まずテストを書き、失敗を確認する。
"""
from pathlib import Path

import pytest


class TestReadmeVersionManagementSection:
    """READMEにバージョン管理セクションが含まれることを検証。"""

    @pytest.fixture
    def readme_content(self) -> str:
        """README.mdの内容を読み込む。"""
        readme_path = Path(__file__).parents[4] / "readme.md"
        return readme_path.read_text(encoding="utf-8")

    def test_has_version_management_section(self, readme_content: str):
        """バージョン管理セクションが存在する。"""
        assert "## バージョン管理" in readme_content

    def test_explains_project_yaml(self, readme_content: str):
        """project.yamlの説明がある。"""
        assert ".railway/project.yaml" in readme_content

    def test_has_railway_update_command(self, readme_content: str):
        """railway updateコマンドの説明がある。"""
        assert "railway update" in readme_content
        assert "--dry-run" in readme_content

    def test_has_railway_backup_command(self, readme_content: str):
        """railway backupコマンドの説明がある。"""
        assert "railway backup" in readme_content
        assert "backup list" in readme_content
        assert "backup restore" in readme_content

    def test_version_management_in_cli_commands(self, readme_content: str):
        """CLI Commandsセクションにバージョン管理がある。"""
        # CLI Commandsセクション内にバージョン管理コマンドがある
        cli_section_start = readme_content.find("## CLI Commands")
        cli_section_end = readme_content.find("## ", cli_section_start + 1)
        cli_section = readme_content[cli_section_start:cli_section_end]

        assert "railway update" in cli_section
        assert "railway backup" in cli_section

    def test_version_management_in_features(self, readme_content: str):
        """特徴セクションにバージョン管理がある。"""
        assert "バージョン管理" in readme_content
        # 絵文字付きの特徴行として存在
        assert "🔄" in readme_content or "バージョン管理" in readme_content

    def test_roadmap_updated(self, readme_content: str):
        """ロードマップがPhase 2完了を示している。"""
        assert "Phase 2" in readme_content
        # Phase 2が完了マークされている
        roadmap_section = readme_content[readme_content.find("## ロードマップ"):]
        assert "バージョン管理" in roadmap_section

    def test_design_decisions_explained(self, readme_content: str):
        """設計判断の説明がある。"""
        # 各機能に「なぜ」の説明がある
        has_design_table = (
            "| 判断 | 理由 |" in readme_content
            or "設計判断" in readme_content
        )
        assert has_design_table

    def test_compatibility_rules_documented(self, readme_content: str):
        """互換性ルールが文書化されている。"""
        assert "マイナー" in readme_content or "メジャー" in readme_content
        assert "互換" in readme_content
```

### Green Phase: 最小限の実装

上記「実装」セクションの手順に従い、README.mdを更新してテストを通す。

### Refactor Phase: 改善

1. 文書の一貫性チェック（トーン、形式）
2. コードブロックのシンタックスハイライト確認
3. 内部リンクの検証

### 確認項目（手動レビュー）

- [ ] CLI Commands に「バージョン管理」が追加されている
- [ ] 特徴セクションに「バージョン管理」が追加されている
- [ ] 「バージョン管理」セクションが「設定管理」の後にある
- [ ] ロードマップが更新されている
- [ ] 全てのコードブロックが正しくフォーマットされている
- [ ] 既存セクションとのトーン・形式が一貫している

## 依存関係

- #01 プロジェクトバージョン記録（完了後）
- #02 バージョン互換性チェック（完了後）
- #03 railway updateコマンド基本実装（完了後）
- #04 マイグレーション戦略設計（完了後）
- #05 バックアップ・ロールバック機能（完了後）
- #06 Dry-runモード実装（完了後）

**Note**: 全ての実装完了後にREADMEを更新する。実装途中での部分更新は避ける。

## 優先度

**低** - 機能実装完了後のドキュメント作業
