Add comprehensive detailed design documents

src-python/docs/details/controller.md

@@ -0,0 +1,349 @@
+# controller.py - VRCTコントローラーモジュール
+
+## 概要
+
+VRCTアプリケーションのビジネスロジックを制御するコントローラークラスです。UI層とモデル層の間に位置し、ユーザーの入力を適切な処理に変換し、結果を UI に返す役割を担います。全ての機能制御、設定管理、状態管理を一元的に行います。
+
+## 主要機能
+
+### 機能制御
+- 翻訳機能の有効化・無効化
+- 音声認識機能の制御
+- VRオーバーレイの管理
+- WebSocketサーバーの制御
+
+### 設定管理
+- アプリケーション設定の取得・更新
+- デバイス設定の管理
+- 言語・エンジン設定の制御
+
+### 状態管理
+- システム状態の監視
+- エラー状態の管理
+- 初期化プロセスの制御
+
+### 通信制御
+- OSC通信の管理
+- WebSocket通信の制御
+- 外部アプリケーション連携
+
+## クラス構造
+
+### Controller クラス
+```python
+class Controller:
+    def __init__(self) -> None
+```
+
+中核となるコントローラークラス
+
+### 内部ヘルパークラス
+
+#### DownloadCTranslate2 クラス
+```python
+class DownloadCTranslate2:
+    def progressBar(self, progress) -> None
+    def downloaded(self) -> None
+```
+- 翻訳モデルのダウンロード進捗管理
+
+#### DownloadWhisper クラス  
+```python
+class DownloadWhisper:
+    def progressBar(self, progress) -> None
+    def downloaded(self) -> None
+```
+- 音声認識モデルのダウンロード進捗管理
+
+## 主要メソッド
+
+### 初期化・設定
+
+```python
+init() -> None
+```
+- コントローラーの初期化
+- 各コンポーネントの起動
+- 初期設定の適用
+
+```python
+setInitMapping(init_mapping: dict) -> None
+setRunMapping(run_mapping: dict) -> None
+setRun(run: Callable) -> None
+```
+- エンドポイント・コールバック設定
+
+### 翻訳機能制御
+
+```python
+setEnableTranslation(data) -> dict
+setDisableTranslation(data) -> dict
+```
+- 翻訳機能の有効化・無効化
+
+```python
+setSelectedTranslationEngines(data) -> dict
+getSelectedTranslationEngines(data) -> dict
+```
+- 翻訳エンジンの選択・取得
+
+```python
+setSelectedYourLanguages(data) -> dict
+setSelectedTargetLanguages(data) -> dict
+```
+- 送信・受信言語の設定
+
+```python
+sendMessageBox(data) -> dict
+```
+- メッセージの翻訳・送信処理
+
+### 音声認識機能制御
+
+```python
+setEnableTranscriptionSend(data) -> dict
+setEnableTranscriptionReceive(data) -> dict
+```
+- 音声認識機能の有効化
+
+```python
+setSelectedTranscriptionEngine(data) -> dict
+getSelectedTranscriptionEngine(data) -> dict
+```
+- 音声認識エンジンの選択・取得
+
+```python
+setSelectedMicDevice(data) -> dict
+setSelectedSpeakerDevice(data) -> dict
+```
+- 音声デバイスの選択
+
+```python
+setMicThreshold(data) -> dict
+setSpeakerThreshold(data) -> dict
+```
+- 音声しきい値の設定
+
+### VRオーバーレイ制御
+
+```python
+setEnableOverlaySmallLog(data) -> dict
+setEnableOverlayLargeLog(data) -> dict
+```
+- VRオーバーレイの有効化
+
+```python
+setOverlaySmallLogSettings(data) -> dict
+setOverlayLargeLogSettings(data) -> dict
+```
+- オーバーレイ設定の更新
+
+### WebSocket制御
+
+```python
+setEnableWebSocketServer(data) -> dict
+setDisableWebSocketServer(data) -> dict
+```
+- WebSocketサーバーの制御
+
+```python
+setWebSocketHost(data) -> dict
+setWebSocketPort(data) -> dict
+```
+- WebSocket接続設定
+
+### システム管理
+
+```python
+updateSoftware(data) -> dict
+updateCudaSoftware(data) -> dict
+```
+- ソフトウェアアップデート
+
+```python
+downloadCtranslate2Weight(data) -> dict
+downloadWhisperWeight(data) -> dict
+```
+- AIモデルのダウンロード
+
+```python
+feedWatchdog(data) -> dict
+```
+- ウォッチドッグの生存シグナル送信
+
+## 使用方法
+
+### 基本的な使い方
+
+```python
+from controller import Controller
+
+# コントローラーの初期化
+controller = Controller()
+controller.init()
+
+# 翻訳機能の有効化
+result = controller.setEnableTranslation(None)
+print(f"翻訳機能: {result}")
+
+# メッセージ送信
+message_data = {"id": "123", "message": "Hello World"}
+result = controller.sendMessageBox(message_data)
+```
+
+### エンドポイント設定
+
+```python
+# マッピング設定
+mapping = {
+    "/set/enable/translation": controller.setEnableTranslation,
+    "/get/data/version": controller.getVersion,
+}
+
+# 実行関数の設定
+def run_callback(status, endpoint, result):
+    print(f"Status: {status}, Endpoint: {endpoint}, Result: {result}")
+
+controller.setRun(run_callback)
+```
+
+### 音声認識の設定
+
+```python
+# マイクデバイスの選択
+host_data = "DirectSound"
+result = controller.setSelectedMicHost(host_data)
+
+device_data = "マイク (USB Audio Device)"
+result = controller.setSelectedMicDevice(device_data)
+
+# 音声認識の開始
+result = controller.setEnableTranscriptionSend(None)
+```
+
+## レスポンス形式
+
+全てのメソッドは統一されたレスポンス形式を返します：
+
+```python
+{
+    "status": int,    # HTTPステータスコード(200, 400, 500等)
+    "result": any     # 処理結果（成功時）または エラーメッセージ（失敗時）
+}
+```
+
+### 成功レスポンス例
+```python
+{
+    "status": 200,
+    "result": "翻訳機能が有効化されました"
+}
+```
+
+### エラーレスポンス例
+```python
+{
+    "status": 400,
+    "result": "Invalid device selection"
+}
+```
+
+## 状態管理
+
+### システム状態
+- 各機能の有効・無効状態
+- デバイスの接続状態
+- ネットワーク接続状態
+
+### エラー状態  
+- デバイスエラー
+- 翻訳エンジンエラー
+- VRAMオーバーフローエラー
+
+### 初期化状態
+- 段階的な初期化プロセス
+- 依存関係の解決状態
+
+## イベント処理
+
+### 音声認識イベント
+
+```python
+micMessage(result: dict) -> None
+```
+- マイク音声認識結果の処理
+- 翻訳・フィルタリング・送信
+
+```python
+speakerMessage(result: dict) -> None  
+```
+- スピーカー音声認識結果の処理
+
+### ダウンロードイベント
+- 進捗通知
+- 完了通知  
+- エラー通知
+
+### デバイス変更イベント
+- マイク・スピーカーの選択変更
+- 計算デバイスの変更
+
+## 依存関係
+
+### 直接依存
+- `config`: 設定管理
+- `model`: コアモデル機能  
+- `device_manager`: デバイス管理
+- `utils`: ユーティリティ機能
+
+### 間接依存
+- 各種モデルモジュール（翻訳、音声認識等）
+- VRオーバーレイモジュール
+- 通信モジュール
+
+## エラーハンドリング
+
+### VRAM不足エラー
+- 自動的にCTranslate2への切り替え
+- ユーザーへの適切な通知
+
+### デバイスエラー
+- デバイス接続状態の監視
+- 自動復旧機能
+
+### ネットワークエラー  
+- 接続状態の定期確認
+- オフライン機能への切り替え
+
+### 設定エラー
+- 設定値の妥当性チェック
+- デフォルト値への復帰
+
+## パフォーマンス考慮事項
+
+### 遅延初期化
+- 必要な時点での機能初期化
+- メモリ使用量の最適化
+
+### 非同期処理
+- バックグラウンドでの重い処理
+- UI の応答性維持
+
+### キャッシュ機能
+- 設定値のキャッシュ
+- 翻訳結果のキャッシュ
+
+## 注意事項
+
+- すべてのメソッドは例外安全である
+- 設定変更は即座に config に反映される
+- 重い処理は別スレッドで実行される
+- VR機能は適切な環境でのみ動作する
+- ネットワーク機能はオフライン時に制限される
+
+## セキュリティ考慮事項
+
+- 外部入力の適切な検証
+- APIキーの安全な管理
+- ファイルアクセスの制限
+- ネットワーク通信の暗号化（該当する場合）