# Phase2: 正式リリース準備 - バージョン管理機能

## 背景

v0.9.0 リリースにより、Railway Framework は「初期コードジェネレータ」として成熟しました。
しかし、**継続的保守運用**に必要な機能が欠如しています。

### 現状の問題

```
┌─────────────────────────────────────────────────────────────┐
│ 問題1: プロジェクトがバージョン情報を保持していない          │
│                                                             │
│   my_project/                                               │
│   ├── src/                                                  │
│   ├── config/                                               │
│   └── pyproject.toml  ← railway-framework バージョン不明    │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 問題2: railway new がバージョン互換性を検証しない            │
│                                                             │
│   $ railway new node fetch_data                             │
│   → v0.7.0 で生成したプロジェクトに v0.9.0 のテンプレートを │
│     適用してしまう可能性                                     │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ 問題3: railway update コマンドが存在しない                   │
│                                                             │
│   railway-framework をアップグレードしても、                 │
│   既存プロジェクトをマイグレーションする手段がない           │
└─────────────────────────────────────────────────────────────┘
```

### 影響

| 状況 | 現状 | あるべき姿 |
|------|------|------------|
| 初期構築 | ✅ 問題なし | ✅ 問題なし |
| バージョンアップ後のnew | ⚠️ 互換性不明 | ✅ 警告/拒否 |
| プロジェクトのマイグレーション | ❌ 不可能 | ✅ `railway update` |
| チーム開発 | ⚠️ バージョン不一致 | ✅ バージョン明示 |

---

## 解決策

### 1. プロジェクトバージョン記録

生成時に `.railway/project.yaml` にメタ情報を記録:

```yaml
# .railway/project.yaml
railway:
  version: "0.9.0"
  created_at: "2026-01-23T10:30:00Z"
  updated_at: "2026-01-23T10:30:00Z"

project:
  name: "my_project"

compatibility:
  min_version: "0.9.0"
  max_version: null  # null = 現在のメジャーバージョン内
```

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

`railway new` 実行時にバージョン互換性を検証:

```bash
$ railway new node fetch_data
⚠️  Warning: This project was created with railway-framework v0.7.0
    Current railway-framework version: v0.9.0

    Some templates may have changed. Options:
    1. Continue anyway (may cause inconsistencies)
    2. Run 'railway update' first to migrate the project
    3. Cancel

    [1/2/3]:
```

### 3. railway update コマンド

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

```bash
$ railway update
Checking project compatibility...
  Project version: 0.7.0
  Current version: 0.9.0

Changes to apply:
  - Update pyproject.toml template
  - Add py.typed marker to src/
  - Update TUTORIAL.md with new sections
  - Update config/development.yaml format

Proceed? [y/N]: y

✅ Project updated from 0.7.0 to 0.9.0
   Backup created at: .railway/backups/0.7.0_20260123_103000/
```

---

## Issue 一覧

### 機能実装

| # | Issue | 優先度 | 依存 |
|---|-------|--------|------|
| 01 | [プロジェクトバージョン記録](./01_プロジェクトバージョン記録.md) | 高 | なし |
| 02 | [バージョン互換性チェック](./02_バージョン互換性チェック.md) | 高 | #01 |
| 04 | [マイグレーション戦略設計](./04_マイグレーション戦略設計.md) | 高 | なし（基盤型定義） |
| 03 | [railway updateコマンド基本実装](./03_railway_updateコマンド基本実装.md) | 高 | #01, #02, #04 |
| 05 | [バックアップ・ロールバック機能](./05_バックアップロールバック機能.md) | 中 | #03 |
| 06 | [Dry-runモード実装](./06_Dry-runモード実装.md) | 低 | #03, #04 |

### ドキュメント

| # | Issue | 優先度 | 依存 |
|---|-------|--------|------|
| 07 | [README更新](./07_README更新.md) | 低 | #01-#06（全て完了後） |
| 08 | [TUTORIAL更新](./08_TUTORIAL更新.md) | 低 | #01-#06（全て完了後） |

---

## 実装方針

### TDD フロー

```
1. Red:   テストを先に書き、失敗を確認
2. Green: 最小限の実装でテストを通す
3. Refactor: コードを整理
```

各issueには完全なテストコードが記載されています。

### 関数型パラダイム

```
1. イミュータブルデータ: frozen dataclass / Pydantic frozen=True
2. 純粋関数: 副作用なし、参照透過性を保証
3. IO分離: ファイル操作は専用レイヤーで明示的に分離
4. Result型: 操作結果を明示的に表現
```

既存実装の `Contract`（frozen Pydantic）、`RetryPolicy`（frozen dataclass）パターンを継承。

### 設計原則

1. **後方互換性**: 既存プロジェクト（バージョン情報なし）も動作
2. **安全第一**: 破壊的変更前に必ずバックアップ
3. **段階的導入**: 警告 → 確認 → 強制の順で厳格化
4. **透明性**: 何が変更されるか事前に表示

---

## マイルストーン

### v0.10.0 (最小実現可能機能)

- [ ] #01 プロジェクトバージョン記録
- [ ] #02 バージョン互換性チェック（警告のみ）
- [ ] #04 マイグレーション戦略設計（基盤型定義）
- [ ] #03 railway update 基本実装

> **Note**: #04 は `ChangeType`, `FileChange`, `MigrationDefinition` 等の基盤型を定義し、#03 がこれらを使用するため、v0.10.0 に含める必要があります。

### v0.11.0 (完全版)

- [ ] #05 バックアップ・ロールバック
- [ ] #06 Dry-run モード
- [ ] #07 README更新
- [ ] #08 TUTORIAL更新

---

## 成功基準

1. 新規プロジェクトに `.railway/project.yaml` が生成される
2. バージョン不一致時に警告が表示される
3. `railway update` でプロジェクトを最新化できる
4. 既存プロジェクト（バージョン情報なし）でも動作する
