---
paths: ["TIASshot/**/*.cs"]
---

# エラーハンドリング方針 (Error Handling Policy)

本プロジェクトにおけるエラーの分類・処理方法・ログ出力の方針を定める．

## 基本方針 (Basic Policy)

本プロジェクトは単独開発のデスクトップ（WinForms）アプリであり，重厚なエラーコード体系や構造化ログ基盤は導入しない．既存コードの実装パターン（`ErrorMsg` ＋ `bool` 返却・`MessageBox`・`Debug.WriteLine`・`ShowMessage`）を踏襲し，最小限に標準化する．

- 例外を握りつぶさない．回復できないエラーはユーザーに伝えて安全に停止し，回復可能なエラーは当該処理のみ中断してアプリは継続する．
- ユーザー向けの通知（`ShowMessage` / `MessageBox`）と，開発者向けのログ（`Debug.WriteLine`）を混同しない．

## エラーの分類 (Error Classification)

| 分類 | 例 | 処理方針 |
| --- | --- | --- |
| 起動時の致命的エラー | 設定ファイル・参照ファイルの読み込み失敗，カメラ未接続 | 下位層で `ErrorMsg` に日本語の理由を設定し `bool` で失敗を返す．最終的に `Form` 層が `MessageBox` で通知して起動を中止する |
| 処理中の回復可能エラー | 撮影・保存・色変換中の一時的な失敗 | 例外境界で捕捉し，`ShowMessage` でユーザーに通知して当該処理のみ中断する（アプリは継続）．UI 状態を適切に復帰させる |
| プログラミングエラー（バグ） | null 参照，配列範囲外，想定外の状態 | 握りつぶさない．`Debug.WriteLine` で記録し，原則そのまま伝播させて開発中に検知する |

## エラーの処理方法 (Handling)

### 起動時のエラー

- `Connect()` / `Open()` 等の初期化メソッドは `bool` を返し，失敗時は `ErrorMsg` に日本語の理由を設定する．
- ユーザーへの通知は `Form` 層の `MessageBox.Show` に集約する．下位層（カメラ・光源・設定）は UI を直接呼び出さない．

### 処理中のエラー

- 撮影・保存・色変換など，失敗が想定される境界で例外を捕捉し，`_form.ShowMessage` で通知して当該処理を中断する．
- 中断時は UI 状態（`EnableShots` 等）を必ず復帰させる．
- スレッド同期に関わる資源は，例外時にも `finally` で確実に終端する（例: `BlockingCollection` の `CompleteAdding()` を `finally` で呼び，消費側スレッドを停止させる）．

### 共通ルール

- 例外を握りつぶす空の `catch` を禁止する．`catch` する場合は必ず「ログ出力＋ユーザー通知」または「再スロー」のいずれかを行う．
- `Mat`・`StreamWriter`・スレッド同期資源などは `using` または `try-finally` で確実に解放する．

## ログ出力 (Logging)

- **ログは `Debug.WriteLine` のみを使用する**．永続ログファイルは作成しない（リリースビルドでは出力されない点を許容する）．
- 用途は開発・デバッグ時のトレース（パラメータ値，処理の節目，捕捉した例外の内容）とする．
- ユーザーに見せるメッセージは `ShowMessage` / `MessageBox` で行い，`Debug.WriteLine` と役割を分ける（ログ＝開発者向け，メッセージ＝利用者向け）．

※ 将来，撮影現場でのトラブル解析のために永続的な記録が必要になった場合は，ログファイル方式への変更を別途検討し，本方針を更新する．

## 関連 (Related)

- テストとの関係は [testing](testing.md) を参照する（エラー処理のうち純粋ロジックで検証可能な部分は自動テストの対象とする）．