diff --git a/.claude/rules/error-handling.md b/.claude/rules/error-handling.md new file mode 100644 index 0000000..7c69a4c --- /dev/null +++ b/.claude/rules/error-handling.md @@ -0,0 +1,53 @@ +--- +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) + +- 撮影・保存処理の例外時の中断・終端は [PLAN_02_バグ修正計画](../../docs/03_PLAN/PLAN_02_バグ修正計画.md)（特に優先度3）と整合させる． +- テストとの関係は [testing](testing.md) を参照する（エラー処理のうち純粋ロジックで検証可能な部分は自動テストの対象とする）． diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md new file mode 100644 index 0000000..7134d93 --- /dev/null +++ b/.claude/rules/testing.md @@ -0,0 +1,104 @@ +--- +paths: ["TIASshot.Tests/**", "TIASshot/**/*.cs"] +--- + +# テスト方針 (Testing Policy) + +本プロジェクトのテストの種類・粒度・対象範囲・実行タイミングを定める． +具体的な回帰テスト手順は [TEST_01_テスト仕様](../../docs/06_TEST/TEST_01_テスト仕様.md) を参照する（本 rule は方針，TEST_01 は具体手順という役割分担）． + +## 基本方針 (Basic Policy) + +本プロジェクトは実機カメラ（Lucam / ImagingSource）・光源・ネイティブライブラリ（OpenCvSharp）に強く依存する一方で，画像処理・色補正・設定読み込み等のハードウェアに依存しない純粋ロジックも含む．この性質に合わせ，コードを 2 層に分けてテストする． + +- **ピュアロジック層**: ハードウェア・UI・スレッドに依存しない計算/変換ロジック．**自動テスト（単体テスト）で回帰を担保する**． +- **ハードウェア結合層**: カメラ SDK・`Form1`（WinForms UI）・撮影/プレビューのスレッド・コールバックに密結合した処理．**自動テストの対象外**とし，ビルドテスト＋手動テスト＋実機回帰テストで担保する． + +「テストできない」と「テストしていない」を混同しない．ハードウェア結合層は原理的に自動テストが困難なため対象外とするが，ピュアロジック層は自動テスト可能であり，必ずテストを書く． + +標準に則る．NUnit の慣例（AAA: Arrange-Act-Assert）に従い，テストは実装のなぞり書きではなく**仕様（期待される入出力）を基準**に書く． + +## テストの種類 (Test Types) + +| 種類 | 対象 | 自動化 | 実行タイミング | +| --- | --- | --- | --- | +| 単体テスト | ピュアロジック層 | 自動（NUnit） | コミット前・`/implement` Phase 2 | +| ビルドテスト | ソリューション全体 | 自動（MSBuild） | 全コミット前 | +| 回帰テスト | 色補正・チャート検出の出力 | 半自動（基準データ比較） | リファクタ・修正の前後 | +| 手動テスト | 起動〜撮影〜保存の一連動作 | 手動（実機） | 機能追加・修正の完了時 | + +回帰テスト・手動テストの具体手順は [TEST_01_テスト仕様](../../docs/06_TEST/TEST_01_テスト仕様.md) に記載する． + +## テスト対象の切り分け (Test Scope) + +どのクラス・処理を自動テストの対象とするかを明示する．新しいコードを追加した際は，この表に従って対象/対象外を判断する． + +### 自動テスト対象（ピュアロジック層） + +| 対象 | テスト内容の例 | +| --- | --- | +| `ColorCorrection/ColorCorrector` | 次元拡張（`ExtendMat`）・変換行列算出・色変換の入出力．既知の入力 Mat に対する出力 Mat／数値の検証 | +| `ChartDetection/ChartDetector` | 既知のチャート画像を入力したときのマスク位置・検出結果の幾何的検証 | +| `Config` | 設定 XML のパース・型変換・範囲フィルタ（例: チャネル数の `4〜17` 絞り込み） | +| `Utils/IoUtil` | CSV の読み書き往復（`SaveMatToCsv` → `LoadMatFromCsv`）で値が保たれること | +| ゲイン更新比率の計算（`GetRatio` 相当） | 入力値・目標値・更新レートに対する比率計算 | + +### 自動テスト対象外（ハードウェア結合層） + +| 対象 | 対象外の理由 | +| --- | --- | +| `Cameras/CameraBase`・`IScam`・`Lucam` のカメラ制御・撮影/プレビュー | カメラ SDK（`dll.*` / `TIS.Imaging.*`）・フレームコールバック・実機に依存 | +| 撮影/保存のスレッド連携（`RunShotLoop` / `SaveThread`） | カメラフレーム取得・`Form1` に依存．スレッド安全性は設計レビューと実機で担保 | +| `UI/Form1`・`UI/PreviewMonitor` | WinForms UI スレッド・画面描画に依存 | +| `LightSource` | 光源のシリアル通信（実機）に依存 | + +※ ハードウェア結合層に手を入れた場合は，自動テストの代わりに**設計レビュー＋実機回帰**で挙動を確認する．`/implement` の Tester フェーズでは，対象がハードウェア結合層の場合，無理にモックを作らず設計レビューで判断してよい． + +## フレームワークと配置 (Framework & Layout) + +- **フレームワーク**: NUnit（`NUnit3TestAdapter` で Visual Studio / `dotnet test` から実行）． +- **テストプロジェクト**: `TIASshot.Tests`（**x64 / .NET Framework 4.8**．本体と同一ターゲット）． +- **ネイティブ依存**: `ColorCorrector` 等のテストは OpenCvSharp のネイティブ DLL をロードするため，テストプロジェクトも **x64 必須**かつ OpenCvSharp ランタイムを参照すること（プラットフォームを `AnyCPU` にすると Mat 演算が実行時に失敗する）． +- **配置**: ソリューションルート直下にテストプロジェクトを置く． + +```text +TIASshot/ ← ソリューションルート +├── TIASshot.sln +├── TIASshot/ ← 本体プロジェクト +└── TIASshot.Tests/ ← テストプロジェクト（NUnit） + ├── ColorCorrectorTests.cs + ├── ConfigTests.cs + └── ... +``` + +- **命名**: テストクラスは `<対象クラス>Tests`，テストメソッドは「対象_条件_期待結果」が分かる名前にする（日本語名も可）． +- **粒度**: 1 テストにつき 1 つの検証観点とする．1 メソッドで多数の `Assert` を詰め込まない． +- **テストデータ**: 入力画像・基準 CSV 等は `TIASshot.Tests` 配下の専用フォルダ（例: `TestData/`）に置き，テストから相対参照する． + +## テストの実行 (Running Tests) + +テストプロジェクトは本体に合わせたレガシー形式（packages.config）のため `dotnet test` は使えない．ビルド後に `vstest.console.exe` を **x64** で実行する（ネイティブ DLL を x64 でロードするため）． + +```powershell +& "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" TIASshot.sln /t:Build /p:Configuration=Debug /p:Platform=x64 +& "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TestWindow\vstest.console.exe" "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64 +``` + +Visual Studio 上ではテストエクスプローラーから実行できる（プラットフォームを x64 にすること）． + +## モック方針 (Mocking) + +- **過剰なモックを避ける**．ピュアロジックは実値（実際の Mat・数値）で検証する． +- **静的依存の扱い**: `Config` のような静的クラスへの依存がテストの妨げになる場合，テスト容易化のための最小限のシーム（引数化・依存の注入）を導入してよい．ただし**本番の挙動は変えない**こと． +- **ハードウェア SDK はモックしない**．モックしてまでテストする価値が低く，対象外（ハードウェア結合層）とする方針と整合させる． + +## カバレッジ方針 (Coverage) + +- **数値的なカバレッジノルマは課さない**．カバレッジ率の達成自体を目的化しない． +- 代わりに，**重要な計算経路を網羅する**ことを定性的な目標とする．具体的には，色変換行列の算出・次元拡張・CSV 往復・ゲイン更新比率といった「誤ると出力が壊れる中核ロジック」にテストを行き渡らせる． + +## 既存ドキュメントとの関係 (Relation to Existing Docs) + +- 本 rule（`.claude/rules/testing.md`）は**テストの方針**を定める． +- [TEST_01_テスト仕様](../../docs/06_TEST/TEST_01_テスト仕様.md) は**回帰テスト・手動テストの具体手順**（基準データの作成・比較方法・合格条件）を定める． +- 自動テスト（単体テスト）の具体的なケースが増えた場合は，`docs/06_TEST/` に追記する（本 rule には方針のみ残し，個別ケースは重複させない）． diff --git a/CLAUDE.md b/CLAUDE.md index 5368e4d..3ba8def 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,10 +49,8 @@ - プロジェクト立ち上げフロー: docs/01_GUIDE/GUIDE_01_プロジェクト立ち上げフロー.md - エージェント運用ルール: docs/01_GUIDE/GUIDE_02_エージェント運用ルール.md -- テスト方針: docs/01_GUIDE/GUIDE_08_テスト方針.md -- エラーハンドリング方針: docs/01_GUIDE/GUIDE_09_エラーハンドリング方針.md -- ※ Git 規約・ドキュメント書式・命名規則・進捗記録は `.claude/rules/`（git-conventions / markdown-style / docs-naming / progress-log）に定義されている（git-conventions は常時，他は該当ファイル編集時に自動ロード） -- ※ コーディング規約，テスト方針等はプロジェクト立ち上げ時に path-scoped rules（`.claude/rules/`）として作成する（GUIDE_01 参照） +- ※ Git 規約・ドキュメント書式・命名規則・進捗記録・テスト方針・エラーハンドリング方針は `.claude/rules/`（git-conventions / markdown-style / docs-naming / progress-log / testing / error-handling）に path-scoped rule として定義されている（git-conventions は常時，他は該当ファイル編集時に自動ロード） +- ※ コーディング規約・プロジェクト構成規則は未整備（GUIDE_01 の規約整備フェーズ参照） ### 02_ENV（環境） diff --git "a/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" "b/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" deleted file mode 100644 index 60adc4f..0000000 --- "a/docs/01_GUIDE/GUIDE_08_\343\203\206\343\202\271\343\203\210\346\226\271\351\207\235.md" +++ /dev/null @@ -1,100 +0,0 @@ -# テスト方針 (Testing Policy) - -本プロジェクトのテストの種類・粒度・対象範囲・実行タイミングを定める． -具体的な回帰テスト手順は [TEST_01_テスト仕様](../06_TEST/TEST_01_テスト仕様.md) を参照する（本書は方針，TEST_01 は具体手順という役割分担）． - -## 基本方針 (Basic Policy) - -本プロジェクトは実機カメラ（Lucam / ImagingSource）・光源・ネイティブライブラリ（OpenCvSharp）に強く依存する一方で，画像処理・色補正・設定読み込み等のハードウェアに依存しない純粋ロジックも含む．この性質に合わせ，コードを 2 層に分けてテストする． - -- **ピュアロジック層**: ハードウェア・UI・スレッドに依存しない計算/変換ロジック．**自動テスト（単体テスト）で回帰を担保する**． -- **ハードウェア結合層**: カメラ SDK・`Form1`（WinForms UI）・撮影/プレビューのスレッド・コールバックに密結合した処理．**自動テストの対象外**とし，ビルドテスト＋手動テスト＋実機回帰テストで担保する． - -「テストできない」と「テストしていない」を混同しない．ハードウェア結合層は原理的に自動テストが困難なため対象外とするが，ピュアロジック層は自動テスト可能であり，必ずテストを書く． - -標準に則る．NUnit の慣例（AAA: Arrange-Act-Assert）に従い，テストは実装のなぞり書きではなく**仕様（期待される入出力）を基準**に書く． - -## テストの種類 (Test Types) - -| 種類 | 対象 | 自動化 | 実行タイミング | -| --- | --- | --- | --- | -| 単体テスト | ピュアロジック層 | 自動（NUnit） | コミット前・`/implement` Phase 2 | -| ビルドテスト | ソリューション全体 | 自動（MSBuild） | 全コミット前 | -| 回帰テスト | 色補正・チャート検出の出力 | 半自動（基準データ比較） | リファクタ・修正の前後 | -| 手動テスト | 起動〜撮影〜保存の一連動作 | 手動（実機） | 機能追加・修正の完了時 | - -回帰テスト・手動テストの具体手順は [TEST_01_テスト仕様](../06_TEST/TEST_01_テスト仕様.md) に記載する． - -## テスト対象の切り分け (Test Scope) - -どのクラス・処理を自動テストの対象とするかを明示する．新しいコードを追加した際は，この表に従って対象/対象外を判断する． - -### 自動テスト対象（ピュアロジック層） - -| 対象 | テスト内容の例 | -| --- | --- | -| `ColorCorrection/ColorCorrector` | 次元拡張（`ExtendMat`）・変換行列算出・色変換の入出力．既知の入力 Mat に対する出力 Mat／数値の検証 | -| `ChartDetection/ChartDetector` | 既知のチャート画像を入力したときのマスク位置・検出結果の幾何的検証 | -| `Config` | 設定 XML のパース・型変換・範囲フィルタ（例: チャネル数の `4〜17` 絞り込み） | -| `Utils/IoUtil` | CSV の読み書き往復（`SaveMatToCsv` → `LoadMatFromCsv`）で値が保たれること | -| ゲイン更新比率の計算（`GetRatio` 相当） | 入力値・目標値・更新レートに対する比率計算 | - -### 自動テスト対象外（ハードウェア結合層） - -| 対象 | 対象外の理由 | -| --- | --- | -| `Cameras/CameraBase`・`IScam`・`Lucam` のカメラ制御・撮影/プレビュー | カメラ SDK（`dll.*` / `TIS.Imaging.*`）・フレームコールバック・実機に依存 | -| 撮影/保存のスレッド連携（`RunShotLoop` / `SaveThread`） | カメラフレーム取得・`Form1` に依存．スレッド安全性は設計レビューと実機で担保 | -| `UI/Form1`・`UI/PreviewMonitor` | WinForms UI スレッド・画面描画に依存 | -| `LightSource` | 光源のシリアル通信（実機）に依存 | - -※ ハードウェア結合層に手を入れた場合は，自動テストの代わりに**設計レビュー＋実機回帰**で挙動を確認する．`/implement` の Tester フェーズでは，対象がハードウェア結合層の場合，無理にモックを作らず設計レビューで判断してよい． - -## フレームワークと配置 (Framework & Layout) - -- **フレームワーク**: NUnit（`NUnit3TestAdapter` で Visual Studio / `dotnet test` から実行）． -- **テストプロジェクト**: `TIASshot.Tests`（**x64 / .NET Framework 4.8**．本体と同一ターゲット）． -- **ネイティブ依存**: `ColorCorrector` 等のテストは OpenCvSharp のネイティブ DLL をロードするため，テストプロジェクトも **x64 必須**かつ OpenCvSharp ランタイムを参照すること（プラットフォームを `AnyCPU` にすると Mat 演算が実行時に失敗する）． -- **配置**: ソリューションルート直下にテストプロジェクトを置く． - -```text -TIASshot/ ← ソリューションルート -├── TIASshot.sln -├── TIASshot/ ← 本体プロジェクト -└── TIASshot.Tests/ ← テストプロジェクト（NUnit） - ├── ColorCorrectorTests.cs - ├── ConfigTests.cs - └── ... -``` - -- **命名**: テストクラスは `<対象クラス>Tests`，テストメソッドは「対象_条件_期待結果」が分かる名前にする（日本語名も可）． -- **粒度**: 1 テストにつき 1 つの検証観点とする．1 メソッドで多数の `Assert` を詰め込まない． -- **テストデータ**: 入力画像・基準 CSV 等は `TIASshot.Tests` 配下の専用フォルダ（例: `TestData/`）に置き，テストから相対参照する． - -## テストの実行 (Running Tests) - -テストプロジェクトは本体に合わせたレガシー形式（packages.config）のため `dotnet test` は使えない．ビルド後に `vstest.console.exe` を **x64** で実行する（ネイティブ DLL を x64 でロードするため）． - -```powershell -& "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe" TIASshot.sln /t:Build /p:Configuration=Debug /p:Platform=x64 -& "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TestWindow\vstest.console.exe" "TIASshot.Tests\bin\x64\Debug\TIASshot.Tests.dll" /Platform:x64 -``` - -Visual Studio 上ではテストエクスプローラーから実行できる（プラットフォームを x64 にすること）． - -## モック方針 (Mocking) - -- **過剰なモックを避ける**．ピュアロジックは実値（実際の Mat・数値）で検証する． -- **静的依存の扱い**: `Config` のような静的クラスへの依存がテストの妨げになる場合，テスト容易化のための最小限のシーム（引数化・依存の注入）を導入してよい．ただし**本番の挙動は変えない**こと． -- **ハードウェア SDK はモックしない**．モックしてまでテストする価値が低く，対象外（ハードウェア結合層）とする方針と整合させる． - -## カバレッジ方針 (Coverage) - -- **数値的なカバレッジノルマは課さない**．カバレッジ率の達成自体を目的化しない． -- 代わりに，**重要な計算経路を網羅する**ことを定性的な目標とする．具体的には，色変換行列の算出・次元拡張・CSV 往復・ゲイン更新比率といった「誤ると出力が壊れる中核ロジック」にテストを行き渡らせる． - -## 既存ドキュメントとの関係 (Relation to Existing Docs) - -- 本書（GUIDE_08）は**テストの方針**を定める． -- [TEST_01_テスト仕様](../06_TEST/TEST_01_テスト仕様.md) は**回帰テスト・手動テストの具体手順**（基準データの作成・比較方法・合格条件）を定める． -- 自動テスト（単体テスト）の具体的なケースが増えた場合は，`docs/06_TEST/` に追記する（本書には方針のみ残し，個別ケースは重複させない）． diff --git "a/docs/01_GUIDE/GUIDE_09_\343\202\250\343\203\251\343\203\274\343\203\217\343\203\263\343\203\211\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" "b/docs/01_GUIDE/GUIDE_09_\343\202\250\343\203\251\343\203\274\343\203\217\343\203\263\343\203\211\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" deleted file mode 100644 index 36fa125..0000000 --- "a/docs/01_GUIDE/GUIDE_09_\343\202\250\343\203\251\343\203\274\343\203\217\343\203\263\343\203\211\343\203\252\343\203\263\343\202\260\346\226\271\351\207\235.md" +++ /dev/null @@ -1,49 +0,0 @@ -# エラーハンドリング方針 (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) - -- 撮影・保存処理の例外時の中断・終端は [PLAN_02_バグ修正計画](../03_PLAN/PLAN_02_バグ修正計画.md)（特に優先度3）と整合させる． -- テストとの関係は [GUIDE_08_テスト方針](GUIDE_08_テスト方針.md) を参照する（エラー処理のうち純粋ロジックで検証可能な部分は自動テストの対象とする）．