VRCT/src-python/docs/error_handling_migration_guide.md

エラーハンドリング統一システム移行ガイド

概要

errors.pyで定義された統一エラーシステムを使用して、すべてのエラーハンドリングを標準化しました。

変更パターン

1. 基本的なエラーレスポンス

修正前:

response = {
    "status": 400,
    "result": {
        "message": "Error message",
        "data": some_value
    }
}

修正後:

from errors import ErrorCode, VRCTError

response = VRCTError.create_error_response(
    ErrorCode.APPROPRIATE_ERROR_CODE,
    data=some_value
)

2. run_mapping経由のエラー通知

修正前:

self.run(
    400,
    self.run_mapping["error_device"],
    {
        "message": "No mic device detected",
        "data": None
    },
)

修正後:

error_response = VRCTError.create_error_response(
    ErrorCode.DEVICE_NO_MIC,
    data=None
)
self.run(
    error_response["status"],
    self.run_mapping["error_device"],
    error_response["result"],
)

3. 例外からのエラー生成

修正前:

except Exception as e:
    errorLogging()
    response = {
        "status": 400,
        "result": {
            "message": f"Error {e}",
            "data": original_value
        }
    }

修正後:

except Exception as e:
    errorLogging()
    response = VRCTError.create_exception_error_response(
        e,
        data=original_value
    )

既に移行済みの箇所

デバイスエラー

• ✅ progressBarMicEnergy - ErrorCode.DEVICE_NO_MIC
• ✅ progressBarSpeakerEnergy - ErrorCode.DEVICE_NO_SPEAKER

ウェイトダウンロードエラー

• ✅ DownloadCTranslate2.downloaded - ErrorCode.WEIGHT_CTRANSLATE2_DOWNLOAD
• ✅ DownloadWhisper.downloaded - ErrorCode.WEIGHT_WHISPER_DOWNLOAD

翻訳エラー

• ✅ micMessage - ErrorCode.TRANSLATION_ENGINE_LIMIT, ErrorCode.TRANSLATION_VRAM_MIC, ErrorCode.TRANSLATION_DISABLED_VRAM
• ✅ speakerMessage - ErrorCode.TRANSLATION_ENGINE_LIMIT, ErrorCode.TRANSLATION_VRAM_SPEAKER, ErrorCode.TRANSLATION_DISABLED_VRAM
• ✅ chatMessage - ErrorCode.TRANSLATION_ENGINE_LIMIT, ErrorCode.TRANSLATION_VRAM_CHAT, ErrorCode.TRANSLATION_DISABLED_VRAM
• ✅ setEnableTranslation - ErrorCode.TRANSLATION_VRAM_ENABLE, ErrorCode.TRANSLATION_DISABLED_VRAM

バリデーションエラー

• ✅ setMicThreshold - ErrorCode.VALIDATION_MIC_THRESHOLD
• ✅ setSpeakerThreshold - ErrorCode.VALIDATION_SPEAKER_THRESHOLD
• ✅ setMicRecordTimeout - ErrorCode.VALIDATION_MIC_RECORD_TIMEOUT
• ✅ setMicPhraseTimeout - ErrorCode.VALIDATION_MIC_PHRASE_TIMEOUT
• ✅ setMicMaxPhrases - ErrorCode.VALIDATION_MIC_MAX_PHRASES
• ✅ setSpeakerRecordTimeout - ErrorCode.VALIDATION_SPEAKER_RECORD_TIMEOUT
• ✅ setSpeakerPhraseTimeout - ErrorCode.VALIDATION_SPEAKER_PHRASE_TIMEOUT
• ✅ setSpeakerMaxPhrases - ErrorCode.VALIDATION_SPEAKER_MAX_PHRASES
• ✅ setOscIpAddress - ErrorCode.VALIDATION_INVALID_IP, ErrorCode.VALIDATION_CANNOT_SET_IP

VRC連携エラー

• ✅ setEnableVrcMicMuteSync - ErrorCode.VRC_MIC_MUTE_SYNC_OSC_DISABLED

認証エラー

• ✅ setDeeplAuthKey - ErrorCode.AUTH_DEEPL_LENGTH, ErrorCode.AUTH_DEEPL_FAILED

未移行の箇所（要対応）

以下の箇所は同様のパターンで移行が必要です:

認証関連

• ⬜ setPlamoAuthKey - ErrorCode.AUTH_PLAMO_LENGTH, ErrorCode.AUTH_PLAMO_FAILED
• ⬜ setPlamoModel - ErrorCode.MODEL_PLAMO_INVALID
• ⬜ setGeminiAuthKey - ErrorCode.AUTH_GEMINI_LENGTH, ErrorCode.AUTH_GEMINI_FAILED
• ⬜ setGeminiModel - ErrorCode.MODEL_GEMINI_INVALID
• ⬜ setOpenAIAuthKey - ErrorCode.AUTH_OPENAI_INVALID, ErrorCode.AUTH_OPENAI_FAILED
• ⬜ setOpenAIModel - ErrorCode.MODEL_OPENAI_INVALID
• ⬜ setGroqAuthKey - ErrorCode.AUTH_GROQ_INVALID, ErrorCode.AUTH_GROQ_FAILED
• ⬜ setGroqModel - ErrorCode.MODEL_GROQ_INVALID
• ⬜ setOpenRouterAuthKey - ErrorCode.AUTH_OPENROUTER_INVALID, ErrorCode.AUTH_OPENROUTER_FAILED
• ⬜ setOpenRouterModel - ErrorCode.MODEL_OPENROUTER_INVALID

接続関連

• ⬜ checkTranslatorLMStudioConnection - ErrorCode.CONNECTION_LMSTUDIO_FAILED
• ⬜ setTranslatorLMStudioURL - ErrorCode.CONNECTION_LMSTUDIO_URL_INVALID
• ⬜ setTranslatorLMStudioModel - ErrorCode.MODEL_LMSTUDIO_INVALID
• ⬜ checkTranslatorOllamaConnection - ErrorCode.CONNECTION_OLLAMA_FAILED
• ⬜ setTranslatorOllamaModel - ErrorCode.MODEL_OLLAMA_INVALID

WebSocket関連

• ⬜ setWebSocketHost - ErrorCode.VALIDATION_INVALID_IP, ErrorCode.WEBSOCKET_HOST_INVALID
• ⬜ setWebSocketPort - ErrorCode.WEBSOCKET_PORT_UNAVAILABLE
• ⬜ setEnableWebSocketServer - ErrorCode.WEBSOCKET_SERVER_UNAVAILABLE

音声認識VRAM関連

• ⬜ startTranscriptionSendMessage - ErrorCode.TRANSCRIPTION_VRAM_MIC, ErrorCode.TRANSCRIPTION_SEND_DISABLED_VRAM
• ⬜ startTranscriptionReceiveMessage - ErrorCode.TRANSCRIPTION_VRAM_SPEAKER, ErrorCode.TRANSCRIPTION_RECEIVE_DISABLED_VRAM

エラーコードとエンドポイントの対応

errors.pyのENDPOINT_ERROR_MAPPINGに、すべてのエンドポイントとエラーコードの対応が定義されています。 UI開発者はこのマッピングを参照して、各エンドポイントがどのようなエラーを返すか確認できます。

エラーレスポンスの構造

統一されたエラーレスポンスは以下の構造を持ちます:

{
    "status": 400,  # HTTPステータスコード
    "result": {
        "error_code": "ERROR_CODE_CONSTANT",  # エラーコード定数
        "message": "Human readable message",   # 人間が読めるメッセージ
        "data": None or original_value,       # エラー時に戻す値（通常は元の値）
        "details": {},                        # 追加情報（オプション）
        "category": "category_name",          # エラーカテゴリ
        "severity": "warning|error|critical", # 重要度
    }
}

UI側での活用

UI側ではerror_codeを使用して、エラーの種類を判定し、適切な処理を行うことができます:

if (response.status === 400) {
    const { error_code, message, data, severity } = response.result;
    
    switch (error_code) {
        case "DEVICE_NO_MIC":
            // マイクデバイスエラーの処理
            break;
        case "VALIDATION_MIC_THRESHOLD":
            // バリデーションエラーの処理（元の値に戻す）
            setValue(data);
            break;
        // ...
    }
    
    // 重要度に応じた表示
    if (severity === "critical") {
        showCriticalError(message);
    }
}

移行作業の進め方

1. パターンの確認: 上記の変更パターンを参照
2. エラーコードの特定: errors.pyから適切なErrorCodeを選択
3. コードの置き換え: 古いエラーハンドリングを新しいシステムに置き換え
4. テスト: エラーが正しく返されることを確認
5. チェックリストの更新: このドキュメントの✅を更新

注意事項

• すべてのエラーはerrors.pyに定義されたエラーコードを使用すること
• 新しいエラーが必要な場合は、まずerrors.pyに追加すること
• エラーメッセージはERROR_METADATAで定義されたデフォルトメッセージを使用すること
  • カスタムメッセージが必要な場合はcustom_messageパラメータを使用
• dataパラメータには、エラー時にUIが元の値に戻せるように、元の値を渡すこと