# B40_統合コンソールシステムガイド.md

**作成**: 2025-09-03
**バージョン**: v1.0.0
**用途**: Console出力とLogging Frameworkの統合システム利用方法

## 概要

本システムは、print()やconsole_service.print_()の混在問題を解決し、B30品質ガイドライン準拠の統一出力システムを提供します。

### 解決した問題

1. **混在出力問題**: print()とconsole_service.print_()の混在
2. **初期化忘れ**: console_serviceの初期化忘れによるエラー
3. **使い勝手**: 複雑な初期化処理とインポート管理
4. **ログ統合**: console出力とロギングの分離

### システム構成

```
統合コンソールシステム
├── console.print() (共通基盤)
├── Logging Framework (統一ログ)
├── ConsoleLogBridge (出力・ログ統合)
└── IntegratedConsole (ワンストップインターフェース)
```

## 使用方法

### 1. 基本的な出力

```python
from noveler.presentation.cli.shared_utilities import console

# プレーン出力
console.print("基本メッセージ")
console.print("[bold red]Rich形式も利用可能[/bold red]")
```

### 2. レベル付き出力（推奨）

```python
from noveler.infrastructure.logging.integrated_console import get_integrated_console

ic = get_integrated_console(__name__)

# レベル付き出力（console表示 + ログ記録）
ic.info("情報メッセージ")           # ℹ️  + ログINFO
ic.success("成功メッセージ")         # ✅ + ログINFO
ic.warning("警告メッセージ")         # ⚠️  + ログWARNING
ic.error("エラーメッセージ")         # ❌ + ログERROR
ic.debug("デバッグメッセージ")       # 🔍 + ログDEBUG
```

### 3. 構造化出力

```python
# ヘッダー・セクション
ic.header("処理開始", style="bold green")
ic.section("ファイル処理")

# 進行状況
ic.progress_start("変換処理を開始")
ic.info("ファイル変換中: example.py")
ic.success("変換完了: example.py")
ic.progress_complete("全処理完了")

# 区切り線
ic.rule("処理完了", style="bold blue")
```

### 4. エラー時のフォールバック

```python
# MCP環境やインポートエラー時の自動フォールバック
try:
    from noveler.infrastructure.logging.integrated_console import get_integrated_console
    ic = get_integrated_console(__name__)
    ic.info("統合コンソール利用")
except ImportError:
    # フォールバック: 基本console
    from noveler.presentation.cli.shared_utilities import console
    console.print("[blue]ℹ️  統合コンソール利用[/blue]")
```

## 移行ガイド

### 自動移行ツール

```bash
# print()とconsole_service.print_()を自動変換
python src/noveler/tools/console_migration_tool.py src/your_module/

# 特定ファイルのみ変換
python src/noveler/tools/console_migration_tool.py src/your_file.py
```

### 手動移行パターン

#### Before (旧)
```python
# 問題のあるパターン
print("メッセージ")                    # ❌ 直接print()
console_service.print_("メッセージ")    # ❌ 初期化忘れリスク
```

#### After (新)
```python
# 統一されたパターン
from noveler.presentation.cli.shared_utilities import console
console.print("メッセージ")             # ✅ 統一出力

# さらに推奨（ログ統合）
from noveler.infrastructure.logging.integrated_console import get_integrated_console
ic = get_integrated_console(__name__)
ic.info("メッセージ")                   # ✅ 出力+ログ統合
```

## 品質チェック

### Ruff統合

```toml
# .ruff.toml設定
[lint]
select = ["T201"]  # print()検出

# 例外ファイル設定
[lint.per-file-ignores]
"src/legacy/**/*.py" = ["T201"]        # レガシーファイルは例外
"src/mcp_servers/**/*.py" = ["T201"]   # MCPサーバーは例外
```

### 検証コマンド

```bash
# print()使用チェック
ruff check src/ --select T201

# console_service残存チェック
rg "console_service\.print_" --type py src/
```

## ログ設定

### 基本設定

```python
from noveler.infrastructure.logging.integrated_console import setup_integrated_logging

# verboseモード
setup_integrated_logging(verbose=2)    # DEBUG出力

# quietモード
setup_integrated_logging(quiet=True)   # WARNING以上のみ
```

### 環境変数

```bash
# ログレベル設定
export NOVEL_LOG_LEVEL=DEBUG

# ログフォーマット
export NOVEL_LOG_FORMAT=json
```

## 実装詳細

### アーキテクチャ

```
Application Layer
├── IntegratedConsole (統合インターフェース)
└── ConsoleLogBridge (出力・ログ統合)

Infrastructure Layer
├── unified_logger.py (統一ログシステム)
└── shared_utilities.py (共通console)

Tools Layer
└── console_migration_tool.py (自動移行)
```

### コンポーネント責務

- **console.print()**: 共通基盤・Rich形式対応
- **unified_logger**: ファイル・コンソール・JSON出力
- **ConsoleLogBridge**: レベル付き出力とログ統合
- **IntegratedConsole**: ワンストップ・進行状況管理
- **migration_tool**: AST変換による自動移行

## トラブルシューティング

### Q1: インポートエラー

```python
# 解決策: フォールバック実装
try:
    from noveler.infrastructure.logging.integrated_console import get_integrated_console
    ic = get_integrated_console(__name__)
except ImportError:
    from noveler.presentation.cli.shared_utilities import console
    # console.print()で代用
```

### Q2: MCP環境での制限

```python
# MCP環境では統一console使用を推奨
from noveler.presentation.cli.shared_utilities import console
console.print("MCP環境対応出力")
```

### Q3: パフォーマンス考慮

```python
# デバッグ出力は条件分岐で制御
if logger.isEnabledFor(logging.DEBUG):
    ic.debug(f"重い処理結果: {expensive_calculation()}")
```

## 今後の拡張

### Phase 6（将来予定）

1. **Rich Progress統合**: 進行状況バーの統合
2. **ダッシュボード機能**: リアルタイム状況表示
3. **外部システム連携**: Slack/Discord通知連携
4. **メトリクス収集**: 出力頻度・エラー率分析

### 開発者向けAPI

```python
# カスタムフォーマッタ追加
from noveler.infrastructure.logging.console_log_bridge import ConsoleLogBridge

class CustomBridge(ConsoleLogBridge):
    def print_custom(self, message: str) -> None:
        console.print(f"[purple]🔥 {message}[/purple]")
        self.logger.info(f"CUSTOM: {message}")
```

---

## 関連ドキュメント

- **B30_Claude_Code品質作業指示書.md**: 統一出力ガイドライン
- **B35_統一ロギングシステムガイド.md**: ログシステム詳細
- **CLAUDE.md**: 基本開発ルール

## 更新履歴

- **v1.0.0** (2025-09-03): 初版作成・統合システム実装完了
  - AST変換ツールによるprint()一括移行
  - Ruffカスタムルール設定
  - Logging Framework基盤実装
  - 大規模console移行（1000+ファイル）
  - 統合ドキュメント作成
