# SPEC-A28-001: 話別プロット生成機能拡張仕様書

## 1. 概要

### 1.1 仕様書の目的
A28_話別プロットプロンプト.md v3.0.0で定義された7つの機能拡張を既存のプロット生成システムに統合し、高品質な話別プロット作成機能を提供する。

### 1.2 背景
既存のプロット生成機能は基本的なテンプレート処理のみを提供していたが、以下の高度な機能が不足していた：
- 伏線追跡システム
- シーン粒度管理
- 感情×技術融合システム
- ステージ間連携強化
- 文字数配分ガイドライン
- 読者反応予測システム
- 視点一貫性チェック

### 1.3 適用範囲
- テンプレート: `templates/話別プロットテンプレート.yaml`
- ドメインサービス: `src/noveler/domain/services/plot_generation_functional_core.py`
- ユースケース: `src/noveler/application/use_cases/generate_episode_plot_use_case.py`
- 関連エンティティおよび値オブジェクト

### 1.4 バージョン管理
- 仕様書バージョン: v1.0.0
- 対応A28ガイドバージョン: v3.0.0
- 実装対象システムバージョン: v2.0.0予定

## 2. 要件定義

### 2.1 機能要件

#### FR-001: 伏線追跡システム
**優先度**: 高
**説明**: プロット内の伏線を体系的に管理し、設置・言及・回収の状態を追跡する。

**詳細要件**:
- 伏線要素の一意識別子管理（FSxxxx形式）
- 伏線状態の追跡（planted/referenced/resolved）
- 伏線間の依存関係管理
- 回収予定エピソード番号の設定
- 未回収伏線の警告機能

**入力**:
```yaml
foreshadowing_tracker:
  - foreshadow_id: "FS001"
    element: "主人公の過去の傷跡についての言及"
    status: "planted"
    resolution_episode: "episode_005"
    dependency: ["FS002"]
```

**出力**: 伏線追跡レポート、未回収伏線リスト

#### FR-002: シーン粒度管理システム
**優先度**: 高
**説明**: シーンごとの重要度ランクと文字数配分を管理し、構成の最適化を支援する。

**詳細要件**:
- シーン重要度ランク管理（S/A/B/C）
- シーンごとの推定文字数設定
- 全体に対する文字数割合計算
- 重要度に基づく配分バランス検証
- シーン構成の可視化機能

**入力**:
```yaml
scene_structure:
  scenes:
    - scene_id: "scene_001"
      importance_rank: "S"
      estimated_words: 800
      percentage: 16
```

**出力**: シーン構成レポート、配分バランス分析

#### FR-003: 感情×技術融合システム
**優先度**: 中
**説明**: プログラミング小説において感情的な展開と技術的概念の融合ポイントを管理する。

**詳細要件**:
- 感情変化と技術概念の対応付け
- 融合効果の定義と管理
- タイミング調整機能
- シナジー効果の検証
- 技術的正確性チェック

**入力**:
```yaml
emotion_tech_fusion:
  peak_moments:
    - timing: "第二幕クライマックス"
      emotion_type: "絶望から希望へ"
      tech_concept: "再帰アルゴリズムの理解"
      synergy_effect: "技術的突破が感情的カタルシスと重なる"
```

**出力**: 融合ポイント分析、シナジー効果レポート

#### FR-004: ステージ間連携強化
**優先度**: 高
**説明**: 5ステージ間の依存関係と引き継ぎ項目を明確化し、一貫性を保証する。

**詳細要件**:
- ステージ間チェックポイント定義
- 引き継ぎ項目の自動検証
- 前段階完了確認機能
- 不整合検出と警告
- 修正提案の自動生成

**入力**: 各ステージの完了データ
**出力**: 連携チェックレポート、不整合警告

#### FR-005: 文字数配分ガイドライン
**優先度**: 中
**説明**: 三幕構成に基づく文字数配分と品質指標を管理する。

**詳細要件**:
- 三幕構成比率の管理（25%-50%-25%）
- 目標文字数の自動計算
- 配分バランスの検証
- 品質閾値の設定と監視
- 調整提案の生成

**入力**: 目標文字数、三幕構成データ
**出力**: 配分ガイドライン、バランス分析

#### FR-006: 読者反応予測システム
**優先度**: 低
**説明**: プロット要素に基づく読者反応の予測とリスク評価を行う。

**詳細要件**:
- 反応予測アルゴリズム
- リスク要因の特定
- 改善提案の生成
- 予測精度の向上機能
- 過去データとの比較分析

**入力**: プロット要素、過去の反応データ
**出力**: 反応予測レポート、リスク評価

#### FR-007: 視点一貫性チェック
**優先度**: 中
**説明**: 三人称限定視点の一貫性を検証し、視点ブレを防止する。

**詳細要件**:
- 視点キャラクターの特定
- 視点ブレの検出アルゴリズム
- 一貫性スコアの算出
- 修正箇所の特定
- 改善提案の生成

**入力**: プロット内容、視点設定
**出力**: 視点一貫性レポート、修正提案

### 2.2 非機能要件

#### NFR-001: パフォーマンス
- プロット生成処理時間: 30秒以内
- 大規模プロット（50エピソード以上）の処理: 5分以内
- メモリ使用量: 512MB以内

#### NFR-002: 可用性
- システム可用性: 99%以上
- エラー発生時の復旧時間: 5分以内
- データ整合性の保証

#### NFR-003: 保守性
- 新機能追加の容易性
- 設定変更の柔軟性
- ログ記録の充実
- デバッグ機能の提供

#### NFR-004: セキュリティ
- ユーザーデータの保護
- アクセス制御の実装
- 監査ログの記録
- セキュリティ脆弱性への対応

## 3. システム設計

### 3.1 アーキテクチャ概要
DDDアーキテクチャに基づく層構造設計：

```
Application Layer (ユースケース)
├── GenerateEpisodePlotUseCase (拡張)
├── ForeshadowingTrackingUseCase (新規)
└── PlotQualityAnalysisUseCase (新規)

Domain Layer (ドメインサービス)
├── PlotGenerationCore (拡張)
├── ForeshadowingTracker (新規)
├── SceneGranularityManager (新規)
├── EmotionTechFusion (新規)
├── StageInterconnection (新規)
├── WordCountAllocator (新規)
├── ReaderReactionPredictor (新規)
└── ViewpointConsistencyChecker (新規)

Infrastructure Layer
├── PlotTemplateRepository (拡張)
└── QualityMetricsRepository (新規)
```

### 3.2 データモデル

#### 3.2.1 拡張プロット構造
```python
@dataclass
class EnhancedPlotStructure:
    episode_number: int
    basic_plot: PlotStructure
    foreshadowing_elements: list[ForeshadowingElement]
    scene_structure: SceneGranularityData
    emotion_tech_fusion: EmotionTechFusionData
    stage_connections: StageInterconnectionData
    word_allocation: WordAllocationData
    reader_prediction: ReaderPredictionData
    viewpoint_consistency: ViewpointConsistencyData
```

#### 3.2.2 伏線要素
```python
@dataclass
class ForeshadowingElement:
    foreshadow_id: str
    element_description: str
    status: ForeshadowingStatus  # planted/referenced/resolved
    resolution_episode: Optional[int]
    dependencies: list[str]
    importance_level: int
    planted_episode: int
    last_referenced_episode: Optional[int]
```

#### 3.2.3 シーン粒度データ
```python
@dataclass
class SceneGranularityData:
    total_scenes: int
    scenes: list[SceneData]
    importance_distribution: dict[str, int]  # S/A/B/C counts
    word_distribution: dict[str, int]
    balance_score: float
```

### 3.3 API設計

#### 3.3.1 プロット生成API
```python
async def generate_enhanced_plot(
    episode_number: int,
    basic_requirements: PlotRequirements,
    enhancement_options: EnhancementOptions
) -> EnhancedPlotResult
```

#### 3.3.2 伏線追跡API
```python
async def track_foreshadowing(
    project_id: str,
    foreshadowing_elements: list[ForeshadowingElement]
) -> ForeshadowingTrackingResult
```

#### 3.3.3 品質分析API
```python
async def analyze_plot_quality(
    plot_data: EnhancedPlotStructure
) -> PlotQualityAnalysisResult
```

## 4. 実装計画

### 4.1 実装フェーズ

#### Phase 1: 基盤拡張 (1-2日)
- YAMLテンプレートの拡張
- 基本データ構造の定義
- 既存ユースケースの拡張準備

#### Phase 2: 高優先度機能 (3-4日)
- FR-001: 伏線追跡システム
- FR-002: シーン粒度管理システム
- FR-004: ステージ間連携強化

#### Phase 3: 中優先度機能 (2-3日)
- FR-003: 感情×技術融合システム
- FR-005: 文字数配分ガイドライン
- FR-007: 視点一貫性チェック

#### Phase 4: 低優先度機能 (2日)
- FR-006: 読者反応予測システム

#### Phase 5: 統合・テスト (2-3日)
- 統合テスト
- パフォーマンステスト
- ユーザビリティテスト

### 4.2 技術的実装詳細

#### 4.2.1 YAMLテンプレート拡張
既存の342行テンプレートに以下セクションを追加：
- `foreshadowing_tracker`
- `scene_structure`
- `emotion_tech_fusion`
- `stage_interconnections`
- `word_allocation_guide`
- `reader_reaction_predictions`
- `viewpoint_consistency_check`

#### 4.2.2 ドメインサービス拡張
PlotGenerationCoreクラスに新メソッド追加：
- `process_foreshadowing_elements()`
- `manage_scene_granularity()`
- `fuse_emotion_and_technology()`
- `validate_stage_connections()`
- `allocate_word_counts()`
- `predict_reader_reactions()`
- `check_viewpoint_consistency()`

#### 4.2.3 ユースケース統合
GenerateEpisodePlotUseCaseの`execute()`メソッドを拡張し、新機能を順次実行する統合フローを実装。

## 5. テスト計画

### 5.1 単体テスト
- 各ドメインサービスの機能テスト
- 新データ構造の検証テスト
- エラーハンドリングテスト

### 5.2 統合テスト
- ユースケース全体の動作テスト
- YAMLテンプレートとの連携テスト
- 既存機能との互換性テスト

### 5.3 品質テスト
- パフォーマンステスト
- メモリ使用量テスト
- 大規模データ処理テスト

### 5.4 ユーザビリティテスト
- A28ガイドとの整合性確認
- 操作性評価
- 出力品質評価

## 6. リスク管理

### 6.1 技術リスク
- **複雑性増大**: モジュラー設計による緩和
- **パフォーマンス劣化**: 段階的実装による検証
- **既存機能影響**: 下位互換性の保証

### 6.2 運用リスク
- **移行コスト**: 段階的移行計画
- **学習コスト**: 詳細ドキュメント整備
- **保守負荷**: 自動テスト充実

### 6.3 品質リスク
- **バグ発生**: 包括的テスト戦略
- **仕様漏れ**: レビュープロセス強化
- **ユーザビリティ**: 早期フィードバック収集

## 7. 運用・保守

### 7.1 監視項目
- システムパフォーマンス
- エラー発生率
- ユーザー満足度
- 機能利用率

### 7.2 保守計画
- 定期的な機能見直し
- パフォーマンスチューニング
- セキュリティアップデート
- ユーザーフィードバック反映

### 7.3 将来拡張
- AI機能の統合
- マルチプロジェクト対応
- 協働編集機能
- クラウド連携

## 8. 承認・変更管理

### 8.1 承認プロセス
1. 仕様書レビュー
2. 技術設計レビュー
3. 実装レビュー
4. テスト結果評価
5. 本番リリース承認

### 8.2 変更管理
- 仕様変更は本書の更新を必須とする
- 重要な変更は関係者承認を得る
- 変更履歴を明確に記録する

---

**作成日**: 2025-01-06
**作成者**: Claude Code Development Team
**承認者**: TBD
**次回レビュー予定**: 実装完了後
