# Railway Framework for Python - 要件定義書

## 1. 概要

### 1.1 目的
Pythonで型安全かつエラーに強い運用自動化ツールを簡単に作成できるフレームワークを提供する。
Railway Oriented Programming（ROP）パラダイムにより、エラーハンドリングを簡潔かつ安全に記述できる環境を構築する。  
Railwayの骨子以外のコーディングや全体の設計は関数型パラダイムに従う。  

### 1.2 対象ユーザー
- 運用自動化スクリプトを開発するエンジニア(例えばzabbixやpagerdutyなどからトリガされる)  
- API統合やバッチ処理を実装する開発者  
- 既存のPythonスクリプトをより堅牢にしたい運用担当者  

### 1.3 解決する課題
- 従来の運用スクリプトにおける複雑なエラーハンドリング
- エラー処理の漏れによる障害
- try-except、if文のネストによる可読性の低下
- 環境別設定管理の煩雑さ
- テストやリトライ処理の実装コスト

## 2. 機能要件

### 2.1 プロジェクト構造

#### FR-2.1.1 複数エントリーポイント対応
- プロジェクト内に複数の実行可能スクリプト（エントリーポイント）を配置可能
- 配置場所: `project_root/src/entry1.py`, `project_root/src/entry2.py` など
- 各エントリーポイントは独立して実行可能
- 実行方法: `uv run python -m src.entry_name`

#### FR-2.1.2 共通ライブラリの分離
- 共通コードは `project_root/src/common/` ディレクトリに配置
- API呼び出し、ユーティリティ関数などを共有
- 例: `project_root/src/common/api_caller.py`

#### FR-2.1.3 ノード単位の処理分離
- 再利用可能な処理単位（ノード）は `project_root/src/nodes/` ディレクトリに配置
- 各ノードはステートレスで関数型パラダイムに準拠
- ノード間の依存関係は明示的に定義

### 2.2 CLIコマンド

#### FR-2.2.1 プロジェクト初期化
- `railway init <project_name>`: 新規プロジェクトの作成
- 必要なディレクトリ構造とテンプレートファイルを自動生成
- pyproject.toml、.env、統合設定ファイル（config/{env}.yaml）のテンプレート生成
- TUTORIAL.mdの自動生成

#### FR-2.2.2 エントリーポイント/ノード管理（統合コマンド）
- `railway new entry <name>`: 新規エントリーポイント作成
- `railway new entry <name> --example`: サンプルコード付きで生成
- `railway new node <name>`: 新規ノード作成
- `railway new node <name> --example`: サンプルコード付きで生成
- 生成されるテンプレートに含まれる要素:
  - @entry_pointまたは@nodeデコレータ適用
  - コマンドライン引数のパース（typer使用、エントリーポイントのみ）
  - .envからの設定値読み込み
  - 完全な型ヒント
  - ドキュメント文字列
  - テストテンプレート（自動生成）

#### FR-2.2.3 一覧表示
- `railway list`: エントリーポイントとノードの一覧表示
- `railway list entries`: エントリーポイントのみ表示
- `railway list nodes`: ノードのみ表示
- 統計情報の表示（エントリーポイント数、ノード数、テスト数）

#### FR-2.2.4 実行コマンド（新規追加）
- `railway run <entry_name>`: エントリーポイントを実行
- `railway run <entry_name> --help`: ヘルプ表示
- `railway run <entry_name> [OPTIONS]`: オプション付きで実行
- 利点:
  - `uv run python -m src.entry_name` よりシンプル
  - プロジェクトルートの自動検出
  - 一貫したCLI体験

### 2.3 設定管理

#### FR-2.3.1 環境変数管理
- `.env` ファイルで環境設定を管理
- 環境変数 `RAILWAY_ENV` で環境（development/staging/production）を指定
- python-dotenv による自動読み込み

#### FR-2.3.2 環境別設定ファイル（統合版）
- `project_root/config/{env}.yaml` に環境別設定を配置（1ファイルに統合）
- YAML形式での設定記述
- 設定内容:
  - `app`: アプリケーション固有の設定
  - `logging`: ログレベル、出力先の設定
  - `retry`: リトライポリシー設定
  - `api`: API接続設定
  - `database`: データベース接続設定（オプション）
  - `notification`: 通知設定（オプション）
  - `features`: 機能フラグ（オプション）

#### FR-2.3.3 設定の型安全な読み込み
- `src/settings.py` で設定値の読み込みと初期化を実施
- pydantic-settings による型安全なバリデーション
- 設定値はグローバルな `settings` オブジェクトとしてアクセス可能
- 例: `settings.api.base_url`, `settings.retry.max_attempts`

#### FR-2.3.4 設定管理の明確化（新規追加）
- **環境変数オーバーライドのルール:**
  - `.env`ファイルの値は、`config/{env}.yaml`の値より優先される
  - 環境変数名は大文字で統一（例: `API_BASE_URL`, `LOG_LEVEL`）
  - 明示的にオーバーライド可能な値のみ環境変数で上書き可能
- **設定バリデーションエラー時の挙動:**
  - 起動時に設定ファイルを読み込み、バリデーションエラーがあれば即座に失敗
  - 詳細なエラーメッセージとヒントを表示（例: "api.base_url is required"）
  - 必須フィールドの明示
- **設定ファイルの分割オプション（オプション機能）:**
  - 大規模プロジェクト向けに、設定ファイルを機能別に分割可能
  - 例: `config/{env}/app.yaml`, `config/{env}/retry.yaml`
  - デフォルトは統合ファイル（`config/{env}.yaml`）

### 2.4 Railway Oriented Programming

#### FR-2.4.1 Result型の採用
- `returns` ライブラリによるResult型の使用
- Success/Failureによる明示的な成功・失敗の表現
- 型安全なエラーハンドリング

#### FR-2.4.2 パイプライン処理
- `bind` メソッドによるメソッドチェーン
- `flow` 関数による処理パイプライン構築
- エラー時の自動的な後続処理のスキップ

#### FR-2.4.3 安全な関数変換
- `@safe` デコレータによる通常関数→Result型返却関数への変換
- 例外の自動的なFailureへの変換

### 2.5 エラーハンドリングとリトライ

#### FR-2.5.1 リトライ処理
- tenacity ライブラリによるリトライ機能
- 設定ファイル（retry.yaml）でリトライポリシーを管理
- ノード別のリトライ設定が可能
- 指数バックオフ、ジッター設定

#### FR-2.5.2 カスタムエラー型階層
- 基底エラークラス: `RailwayError`
- リトライ可能エラー: `RetryableError`
- リトライ不可能エラー: `FatalError`
- 各種ドメイン固有エラーの定義

#### FR-2.5.3 エラーコンテキスト
- エラー発生時のスタックトレース自動保存
- エラーログの構造化出力
- リトライ回数のメトリクス記録

### 2.6 ロギング

#### FR-2.6.1 構造化ロギング
- loguru による統一されたログ出力
- 環境別ログレベル設定
- JSON出力オプション（プロダクション環境向け）

#### FR-2.6.2 ログローテーション
- ファイルローテーション設定（日次、サイズベース）
- ログ保持期間の設定
- 複数出力先への対応（ファイル、stderr）

#### FR-2.6.3 ログフォーマット
- タイムスタンプ、ログレベル、メッセージの統一フォーマット
- カスタマイズ可能なフォーマット設定

### 2.7 グラフ定義（Phase 2で実装予定）

**注:** グラフベースの実行機能は、フレームワークのシンプルさを保つため、Phase 2（将来実装）に延期します。
Phase 1では、`pipeline()`関数による明示的なパイプライン構築のみをサポートします。

#### FR-2.7.1 依存関係の定義（Phase 2）
- YAML形式でノード間の依存関係を定義
- ノードタイプの指定（source/transform/sink）
- 依存関係の明示的な記述

#### FR-2.7.2 実行順序の自動解決（Phase 2）
- 依存関係に基づく実行順序の自動計算
- 並列実行可能なノードの検出と並行処理

#### FR-2.7.3 グラフの可視化（Phase 2）
- Mermaid形式での依存関係図の生成
- 循環依存の検出とエラー報告
- WebUIでのインタラクティブな可視化

### 2.8 非同期処理サポート（Phase 1で基本対応、Phase 2で完全対応）

**注:** 非同期処理は`@node`デコレータで`async def`を使用することで基本的にサポートされますが、
詳細な仕様（同期・非同期混在パイプライン等）はPhase 2で定義します。

#### FR-2.8.1 async/await対応（Phase 1: 基本対応）
- `@node`デコレータで`async def`関数をサポート
- 非同期ノードの自動検出とログ記録

#### FR-2.8.2 非同期パイプライン（Phase 2）
- `pipeline_async()`関数の提供
- 同期・非同期の混在パイプラインのサポート
- returns ライブラリのFutureResultとの統合

### 2.9 依存性注入（オプション）

#### FR-2.9.1 DIコンテナ
- punq または dependency-injector によるDI機能
- サービスクラスの自動登録・解決
- ノードへの依存性自動注入

## 3. 技術要件

### 3.1 パッケージ管理

#### TR-3.1.1 uvの使用
- パッケージ管理ツールとして uv を採用
- 高速な依存関係インストール
- 実行コマンド: `uv run python -m module_name`

#### TR-3.1.2 依存関係定義
- pyproject.toml での依存関係管理
- 開発用依存関係の分離

### 3.2 採用技術スタック

#### TR-3.2.1 コア機能ライブラリ
| ライブラリ | 用途 | バージョン |
|-----------|------|----------|
| returns | Railway Oriented Programming | 最新安定版 |
| tenacity | リトライ処理 | 最新安定版 |
| pydantic | データバリデーション | v2系 |
| pydantic-settings | 設定管理 | 最新安定版 |
| typer | CLIインターフェース | 最新安定版 |
| loguru | 構造化ロギング | 最新安定版 |
| python-dotenv | 環境変数管理 | 最新安定版 |
| PyYAML | YAML設定読み込み | 最新安定版 |

#### TR-3.2.2 開発ツール
| ライブラリ | 用途 | バージョン |
|-----------|------|----------|
| ruff | リント・フォーマット | 最新安定版 |
| mypy | 型チェック | 最新安定版 |
| pytest | テスト実行 | 最新安定版 |
| pytest-cov | カバレッジ測定 | 最新安定版 |
| pytest-asyncio | 非同期テスト | 最新安定版 |

#### TR-3.2.3 オプションライブラリ
| ライブラリ | 用途 | バージョン |
|-----------|------|----------|
| punq | 依存性注入 | 最新安定版 |
| mkdocs | ドキュメント生成 | 最新安定版 |

### 3.3 Pythonバージョン
- Python 3.10以上を必須とする
- 3.13での動作確認を推奨

## 4. 品質要件

### 4.1 コード品質

#### QR-4.1.1 リント・フォーマット
- ruff によるコードスタイルチェック
- 事前設定済みの .ruff.toml を提供
- 実行コマンド: `ruff check .`, `ruff format .`

#### QR-4.1.2 型チェック
- mypy による厳格な型チェック
- strictモードでのチェック
- すべてのテンプレートに型ヒントを含める
- 実行コマンド: `mypy src/`

#### QR-4.1.3 テストカバレッジ
- pytest-cov によるカバレッジ測定
- 最低80%のカバレッジを推奨
- 実行コマンド: `pytest --cov=src --cov-report=html`

### 4.2 テスト戦略

#### QR-4.2.1 テスト構造
- `tests/` ディレクトリにテストコードを配置
- ノード単位のユニットテスト
- パイプライン全体の統合テスト
- conftest.py によるテストフィクスチャ共有

#### QR-4.2.2 テストテンプレート自動生成
- `railway add-node` でノードと同時にテストテンプレート生成
- モック、アサーション、リトライテストのテンプレート提供
- 正常系・異常系のテストケース例

#### QR-4.2.3 テスト実行
- `pytest` で全テスト実行
- 特定ファイルのみのテスト実行サポート
- 並列テスト実行のサポート

### 4.3 オブザーバビリティ

#### QR-4.3.1 実行時メトリクス
- 実行時間計測デコレータの提供
- ノード単位の実行時間記録
- パイプライン全体の実行時間測定

#### QR-4.3.2 エラー追跡
- エラー発生率の記録
- リトライ回数の統計
- スタックトレースの自動保存

## 5. 開発環境要件

### 5.1 プロジェクトテンプレート

#### DR-5.1.1 ディレクトリ構造
```
project_root/
├── src/
│   ├── entry1.py              # エントリーポイント
│   ├── nodes/                 # 処理ノード
│   ├── common/                # 共通ライブラリ
│   └── settings.py            # 設定読み込み
├── tests/                     # テストコード
│   ├── nodes/
│   └── conftest.py
├── config/                    # 環境別設定（統合YAML）
│   ├── development.yaml       # 開発環境設定
│   ├── staging.yaml           # ステージング環境設定
│   └── production.yaml        # 本番環境設定
├── logs/                      # ログファイル
├── .env                       # 環境変数
├── .env.example               # 環境変数テンプレート
├── pyproject.toml             # プロジェクト設定
├── .ruff.toml                 # Ruff設定
├── TUTORIAL.md                # 段階的チュートリアル
├── .gitignore
└── README.md
```

#### DR-5.1.2 初期ファイル生成
- `railway init` でディレクトリ構造を自動生成
- 各種設定ファイルのテンプレート配置
- .gitignore の自動生成

### 5.2 開発ワークフロー

#### DR-5.2.1 標準的な開発フロー
1. ノード実装: `railway add-node <name>`
2. テスト作成: `tests/nodes/test_<name>.py` を編集
3. テスト実行: `pytest tests/nodes/test_<name>.py -v`
4. 型チェック: `mypy src/nodes/<name>.py`
5. エントリーポイントに組み込み
6. 動作確認: `uv run python -m src.entry --dry-run`
7. 本番実行: `uv run python -m src.entry`

#### DR-5.2.2 コードレビュー前チェック
```bash
ruff check .         # リント
ruff format .        # フォーマット
mypy src/            # 型チェック
pytest               # テスト実行
```

### 5.3 CI/CD統合

#### DR-5.3.1 GitHub Actions テンプレート
- `.github/workflows/ci.yml` の自動生成
- 実行内容:
  - リント（ruff）
  - 型チェック（mypy）
  - テスト実行（pytest）
  - カバレッジレポート
- プルリクエスト時の自動実行

#### DR-5.3.2 デプロイメント
- 環境別設定の切り替え
- 本番環境への安全なデプロイ手順

## 6. UI/UX要件

### 6.1 CLI ユーザビリティ

#### UX-6.1.1 コマンドヘルプ
- すべてのコマンドに `--help` オプション提供
- 分かりやすいヘルプメッセージ
- 使用例の表示

#### UX-6.1.2 エラーメッセージ
- 明確で具体的なエラーメッセージ
- 問題解決のヒント表示
- エラー発生箇所の明示

#### UX-6.1.3 進捗表示
- 長時間処理の進捗表示
- ノード実行状況のリアルタイム表示
- 成功・失敗の視覚的な表現（✓/✗）

#### UX-6.1.4 エラー表示の改善（新規追加）
- エラー発生時、標準エラー出力に詳細を表示
- ログファイルの場所を明示（例: "詳細は logs/error.log を確認してください"）
- よくあるエラーに対して、具体的な解決ヒントを表示
- エラーコード、エラーメッセージ、コンテキスト情報の構造化出力
- リトライ回数の進捗表示（例: "Retrying... (attempt 2/3)"）

### 6.2 ログの可読性

#### UX-6.2.1 カラー出力
- ログレベルに応じた色分け
- 重要情報のハイライト
- 環境に応じたカラー出力の自動切り替え

#### UX-6.2.2 ログフォーマット
- タイムスタンプの分かりやすい形式
- メッセージの階層構造
- 適切なインデントと整形

## 7. ドキュメント要件

### 7.1 フレームワークドキュメント

#### DOC-7.1.1 README.md
- フレームワークの概要説明
- Railway Oriented Programmingの説明
- クイックスタートガイド
- 主要機能の説明
- 具体的なコード例

#### DOC-7.1.2 API ドキュメント
- mkdocs による自動生成
- すべての公開API の説明
- コード例とユースケース

#### DOC-7.1.3 サンプルプロジェクト
- `examples/` ディレクトリに実践的なサンプル配置
- シンプルなデータ処理パイプライン
- API統合の例
- 非同期処理の例

### 7.2 生成コードのドキュメント

#### DOC-7.2.1 ドキュメント文字列
- すべてのテンプレートにdocstringを含める
- 引数、戻り値、例外の説明
- 使用例の記載

#### DOC-7.2.2 コメント
- 複雑なロジックへの説明コメント
- 設定項目の説明
- TODOやFIXMEの適切な使用

## 8. セキュリティ要件

### 8.1 機密情報管理

#### SEC-8.1.1 環境変数での管理
- API キー、パスワードは .env で管理
- .env はバージョン管理対象外
- .env.example でテンプレート提供

#### SEC-8.1.2 ログへの機密情報出力防止
- パスワード、トークンのマスキング
- 機密情報のログ出力チェック

### 8.2 依存関係のセキュリティ

#### SEC-8.2.1 脆弱性チェック
- 定期的な依存関係の更新
- セキュリティアドバイザリの確認

## 9. パフォーマンス要件

### 9.1 実行パフォーマンス

#### PERF-9.1.1 起動時間
- エントリーポイントの起動時間: 1秒以内を目標
- 遅延ロードの活用

#### PERF-9.1.2 並列処理
- 依存関係のないノードの並列実行
- 非同期処理の効率的な実装

### 9.2 リソース使用量

#### PERF-9.2.1 メモリ使用量
- 大量データ処理時のメモリ効率
- ストリーミング処理のサポート

## 10. 拡張性要件

### 10.1 プラグイン機構

#### EXT-10.1.1 カスタムノード
- ユーザー定義ノードの簡単な追加
- 標準ノードとの統一的なインターフェース

#### EXT-10.1.2 カスタムエラー型
- プロジェクト固有のエラー型定義
- 標準エラー階層への統合

### 10.2 外部ツール連携

#### EXT-10.2.1 通知システム
- Slack、メール等への通知機能
- カスタム通知ハンドラの実装

#### EXT-10.2.2 メトリクス収集
- Prometheus等のメトリクス収集システムとの連携
- カスタムメトリクスの定義

## 11. 移行サポート

### 11.1 既存スクリプトの移行

#### MIG-11.1.1 段階的移行
- 既存関数の@safeデコレータラッピング
- 段階的なRailwayパラダイムへの移行
- 移行ガイドの提供

#### MIG-11.1.2 移行ツール
- 既存スクリプトの自動解析
- Railway フレームワークへの変換支援

## 12. 非機能要件

### 12.1 可用性
- エラー発生時のグレースフルな停止
- リトライによる一時的障害への対応
- 詳細なエラーログによる障害調査支援

### 12.2 保守性
- 明確なコード構造
- 一貫した命名規則
- 完全な型ヒントによる IDE サポート

### 12.3 可搬性
- プラットフォーム非依存（Linux, macOS, Windows）
- Python 3.10+ での動作保証

### 12.4 学習容易性
- 充実したドキュメント
- 豊富なコード例
- テンプレートによる実装支援

## 13. 制約事項

### 13.1 技術的制約
- Python 3.10以上が必須
- uvのインストールが必要

### 13.2 設計制約
- 関数型パラダイムの採用
- ステートレスなノード設計
- イミュータブルなデータフロー

## 14. 今後の拡張予定

### 14.1 短期（3ヶ月以内）
- WebUIでのグラフ可視化
- インタラクティブなデバッグモード
- より詳細なメトリクス収集

### 14.2 中期（6ヶ月以内）
- 分散実行のサポート
- クラウドサービス連携（AWS, GCP, Azure）
- スケジューラー統合

### 14.3 長期（1年以内）
- ビジュアルなグラフエディタ
- MLOps パイプライン対応
- リアルタイムストリーム処理
