# SmartErrorHandlerService 仕様書

## SPEC-QUALITY-011: スマートエラーハンドリング


## 1. 目的

SmartErrorHandlerServiceは、技術的なエラーメッセージをユーザーフレンドリーなメッセージに変換し、具体的な解決策を提案するドメインサービスです。ユーザーの経験レベルやプロジェクトの特性に応じてメッセージをカスタマイズし、効率的な問題解決を支援します。

## 2. 前提条件

### 2.1 依存関係
- `ErrorContext`: エラーの詳細情報を格納するエンティティ
- `WorkflowStageType`: ワークフロー段階を表すEnum

### 2.2 設定要件
- **テンプレートファイル**: `templates/`ディレクトリに必要なテンプレートが存在
- **CLIコマンド**: 統合CLIシステムが利用可能
- **ジャンル設定**: プロジェクト固有のジャンル情報

### 2.3 環境要件
- Python 3.9以上
- プロジェクトディレクトリ構造が標準フォーマットに準拠

## 3. 主要な振る舞い

### 3.1 スマートエラーメッセージ生成
```python
def generate_smart_error_message(error_context: ErrorContext) -> str
```
- **目的**: 技術的エラーを文脈に応じたユーザーフレンドリーなメッセージに変換
- **処理フロー**:
  1. エラーコンテキストから基本情報を抽出
  2. ユーザーの経験レベルを判定
  3. プロジェクトタイプを特定
  4. 基本メッセージを生成
  5. 経験レベル別に詳細度を調整
  6. 解決コマンドを追加
  7. ジャンル別アドバイスを付与
  8. 解決時間見積もりを提供

### 3.2 基本メッセージ生成
```python
def _generate_base_message(error_context: ErrorContext) -> str
```
- **目的**: エラータイプに応じた基本的なメッセージを生成
- **対応エラータイプ**:
  - **PREREQUISITE_MISSING**: 前提条件不足
  - **FILE_ACCESS_ERROR**: ファイルアクセス問題
  - **VALIDATION_ERROR**: 入力検証エラー
  - **その他**: 一般的なエラーメッセージ

### 3.3 前提条件不足メッセージ生成
```python
def _generate_prerequisite_missing_message(error_context: ErrorContext) -> str
```
- **目的**: 不足している前提条件を分かりやすく説明
- **処理内容**:
  1. 影響を受ける段階の日本語名を取得
  2. 主要な不足ファイルを特定
  3. ユーザーフレンドリーなファイル名に変換
  4. 自然な日本語メッセージを構築

### 3.4 経験レベル別詳細調整
```python
def _add_beginner_details(base_message: str, error_context: ErrorContext) -> str
def _add_expert_details(base_message: str, error_context: ErrorContext) -> str
```
- **目的**: ユーザーの経験レベルに応じた適切な詳細度でメッセージを提供
- **初心者向け**:
  - 詳細な手順説明
  - 励ましメッセージ
  - ステップバイステップガイド
- **熟練者向け**:
  - 簡潔な解決策
  - 効率的なコマンド
  - 技術的な詳細

### 3.5 ジャンル別アドバイス提供
```python
def _get_genre_specific_advice(project_type: str, error_context: ErrorContext) -> str | None
```
- **目的**: プロジェクトのジャンルに特化したアドバイスを提供
- **対応ジャンル**:
  - **Fantasy**: 世界観設定、キャラクター開発のアドバイス
  - **SF**: 科学的整合性、技術設定のアドバイス
  - **Mystery**: 事件背景、推理構造のアドバイス
  - **Romance**: 恋愛要素、感情描写のアドバイス

### 3.6 解決時間見積もり
```python
def _estimate_resolution_time(error_context: ErrorContext) -> str
```
- **目的**: 問題解決に要する時間の現実的な見積もり
- **見積もり基準**:
  - **企画書**: 30-60分
  - **キャラクター設定**: 45-90分
  - **世界観設定**: 60-120分
  - **複数ファイル**: ファイル数 × 30分

## 4. 入出力仕様

### 4.1 入力データ形式

#### ErrorContext
```python
class ErrorContext:
    error_type: str                     # エラータイプ
    missing_files: List[str]           # 不足ファイルリスト
    affected_stage: WorkflowStageType  # 影響を受ける段階

    def get_user_experience_level(self) -> str:
        # "beginner", "intermediate", "advanced"

    def get_project_type(self) -> str:
        # "fantasy", "sf", "mystery", "romance"

    def get_primary_missing_file(self) -> str:
        # 最も重要な不足ファイル

    def is_prerequisite_error(self) -> bool:
        # 前提条件エラーかどうか
```

### 4.2 出力データ形式

#### スマートエラーメッセージ（文字列）
```
{基本メッセージ}

📚 詳細な手順:
   1. {ステップ1}
   2. {ステップ2}
   3. {ステップ3}

🔧 実行コマンド:
   {解決コマンド}

💡 {ジャンル}ジャンルのアドバイス:
   {ジャンル固有のアドバイス}

⏱️ 解決予想時間: {時間見積もり}

💭 {励ましメッセージ}
```

#### 具体的な出力例
```
全体構成プロットを作成するには、まず企画書が必要です。

📚 詳細な手順:
   1. プロジェクトのコンセプトを考える
   2. ターゲット読者を決める
   3. 作品の魅力ポイントを整理する
   4. テンプレートをコピーして編集する

🔧 実行コマンド:
   novel init project

💡 ファンタジージャンルのアドバイス:
   既存作品との差別化要素を明確にし、魅力的な設定の組み合わせを考えましょう。

⏱️ 解決予想時間: 30-60分

💭 初回でわからないことがあっても大丈夫です。一歩ずつ進めていきましょう。
```

## 5. エラーハンドリング

### 5.1 入力検証エラー
- **対象**: 無効なErrorContextオブジェクト
- **対応**: デフォルトメッセージの提供
- **復旧**: 利用可能な情報のみで処理継続

### 5.2 テンプレート不在エラー
- **対象**: 参照テンプレートが存在しない
- **対応**: 代替手順の提供
- **復旧**: 手動作成指示への切り替え

### 5.3 ジャンル情報不正エラー
- **対象**: 未知のジャンル情報
- **対応**: 一般的なアドバイスの提供
- **復旧**: ジャンル固有情報を省略

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

### 6.1 応答時間
- **標準メッセージ生成**: 50ms以内
- **複雑なメッセージ生成**: 200ms以内
- **ジャンル別アドバイス**: 100ms以内

### 6.2 メモリ使用量
- **テンプレート管理**: 初期化時に1回だけ読み込み
- **メッセージ生成**: 一時的なオブジェクトの効率的な管理
- **基本動作**: 5MB以内

### 6.3 同時実行
- **スレッドセーフ**: 読み取り専用設定は共有可能
- **状態管理**: インスタンス変数は不変オブジェクト

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

### 7.1 コマンドインジェクション対策
- **コマンド検証**: 予め定義されたコマンドのみ生成
- **パラメータ検証**: 危険な文字列の除去
- **実行権限**: 適切な権限レベルでの実行

### 7.2 情報漏洩対策
- **エラーメッセージ**: システム内部情報を含まない
- **ファイルパス**: 相対パスのみ表示
- **設定情報**: 機密情報をメッセージに含めない

### 7.3 入力検証
- **ファイルパス**: 許可されたディレクトリのみ
- **ユーザー入力**: 適切なサニタイズ
- **設定値**: 範囲チェック

## 8. 実装チェックリスト

### 8.1 コア機能
- [x] スマートエラーメッセージ生成
- [x] 基本メッセージ生成
- [x] 前提条件不足メッセージ生成
- [x] 経験レベル別詳細調整
- [x] ジャンル別アドバイス提供
- [x] 解決時間見積もり

### 8.2 データ管理
- [x] エラーメッセージテンプレート管理
- [x] ジャンル別アドバイスマッピング
- [x] ファイル情報マッピング
- [x] テンプレート名マッピング

### 8.3 品質保証
- [x] 入力検証の実装
- [x] エラーハンドリングの実装
- [x] パフォーマンス最適化
- [x] セキュリティ対策の実装

### 8.4 統合テスト
- [x] 各種エラータイプの処理確認
- [x] 経験レベル別メッセージの確認
- [x] ジャンル別アドバイスの確認
- [x] 解決時間見積もりの確認

### 8.5 ドキュメント
- [x] 仕様書の作成
- [x] メッセージテンプレートの文書化
- [x] 使用例の提供
- [x] カスタマイズガイド

## 実装完了状況（2025年7月22日更新）

### 実装概要
- **ファイル**: `smart_error_handler_service.py`
- **完成度**: 完全実装済み
- **DDD準拠**: ドメインサービスとして適切に実装

### 実装された機能
#### エラーメッセージテンプレート
- `PREREQUISITE_MISSING`: 前提条件不足メッセージ
- `FILE_ACCESS_ERROR`: ファイルアクセスエラー
- `VALIDATION_ERROR`: 検証エラー
- `NETWORK_ERROR`: ネットワークエラー（実装済み）

#### ジャンル別アドバイス
- **ファンタジー**: 魔法システム、種族設定、世界観の一貫性
- **SF**: 科学的根拠、技術の社会影響、科学的整合性
- **ミステリー**: 事件背景、推理力の根拠、手がかりの配置
- **ロマンス**: 恋愛環境、惹かれ合う理由、感情的説得力

#### ファイル作成ステップ
- **企画書**: コンセプト考案→ターゲット決定→魅力整理→テンプレート編集
- **キャラクター**: 基本設定→性格設定→背景設定→関係性整理
- **世界観**: 舞台設定→歴史設定→社会構造→特殊ルール

#### 解決時間見積もり
- 企画書: 30-60分
- キャラクター: 45-90分
- 世界観: 60-120分
- 複数ファイル: ファイル数×30-60分

### 依存関係
- `ErrorContext`: エラー情報管理エンティティ
- `WorkflowStageType`: ワークフロー段階定義
- `ErrorSeverity`: エラー深刻度定義（実装で使用）

## 9. 使用例

### 9.1 前提条件不足エラーの処理
```python
# エラーコンテキストの作成
error_context = ErrorContext(
    error_type="PREREQUISITE_MISSING",
    missing_files=["10_企画/企画書.yaml"],
    affected_stage=WorkflowStageType.MASTER_PLOT
)

# エラーハンドラーの初期化
handler = SmartErrorHandlerService()

# スマートメッセージの生成
message = handler.generate_smart_error_message(error_context)

# メッセージの表示
print(message)
```

### 9.2 複数ファイル不足の処理
```python
# 複数ファイルが不足している場合
error_context = ErrorContext(
    error_type="PREREQUISITE_MISSING",
    missing_files=[
        "10_企画/企画書.yaml",
        "30_設定集/キャラクター.yaml",
        "30_設定集/世界観.yaml"
    ],
    affected_stage=WorkflowStageType.MASTER_PLOT
)

# スマートメッセージの生成
message = handler.generate_smart_error_message(error_context)

# 複数ファイルの解決手順が表示される
print(message)
```

### 9.3 ジャンル別アドバイスの確認
```python
# ファンタジージャンルのプロジェクトでのエラー処理
error_context = ErrorContext(
    error_type="PREREQUISITE_MISSING",
    missing_files=["30_設定集/世界観.yaml"],
    affected_stage=WorkflowStageType.MASTER_PLOT
)

# プロジェクトタイプを設定（模擬）
error_context.project_type = "fantasy"

# ジャンル固有のアドバイスが含まれたメッセージを生成
message = handler.generate_smart_error_message(error_context)
print(message)
```

## 10. 拡張性

### 10.1 新しいエラータイプの追加
- **エラータイプ定義**: `_generate_base_message`への追加
- **メッセージテンプレート**: 新しいテンプレートの定義
- **解決手順**: 対応する解決コマンドの追加

### 10.2 新しいジャンルの対応
- **ジャンル定義**: `_initialize_genre_advice`への追加
- **アドバイス内容**: 各作業段階での具体的アドバイス
- **差別化要素**: ジャンル固有の特徴を反映

### 10.3 多言語対応
- **メッセージ国際化**: i18n対応の実装
- **言語別テンプレート**: 言語固有のメッセージテンプレート
- **地域別アドバイス**: 文化的背景を考慮したアドバイス

## 11. 運用監視

### 11.1 メトリクス
- **メッセージ生成回数**: 機能の使用状況
- **エラータイプ分布**: 頻出エラーの分析
- **解決時間精度**: 見積もり精度の検証
- **ユーザー満足度**: メッセージの有効性

### 11.2 ログ出力
- **INFO**: 正常なメッセージ生成
- **WARN**: 想定外のエラータイプ
- **ERROR**: メッセージ生成失敗

### 11.3 アラート条件
- **応答時間**: 500msを超えた場合
- **エラー率**: 5%を超えた場合
- **メモリ使用量**: 20MBを超えた場合

## 12. 品質保証

### 12.1 メッセージ品質
- **読みやすさ**: 専門用語の適切な説明
- **行動指向**: 具体的なアクション提示
- **励まし効果**: ユーザーモチベーション向上

### 12.2 技術的品質
- **応答性**: 高速なメッセージ生成
- **拡張性**: 新しい要素の追加容易性
- **保守性**: コードの可読性と変更容易性

### 12.3 ユーザビリティ
- **直感性**: 分かりやすいメッセージ構造
- **実用性**: 実際に役立つ解決策
- **一貫性**: 統一されたメッセージスタイル
