Fork: 0
hasegawa / TIASShot
Transfer to URL with SHA Find file
Newer
Older
TIASShot / .claude / verify-profile.md
@rintoHasegawa rintoHasegawa 15 days ago 14 KB [add] ヘッドレスのセルフテストモードと検証プロファイルを追加し /verify で依存更新後の確認を自動化
Raw Blame History

検証プロファイル (Verify Profile)

TIAS Shot（WinForms / .NET Framework 4.8 / x64 の舌診撮影ソフト）の検証プロファイル．verifier は本ファイルだけを頼りに検証する．

経緯: 2026-09-18 時点では「verifier はハードウェア結合層（カメラ・UI・スレッド）を担保できない」としてプロファイルを作らなかった．その後，ヘッドレスのセルフテストモード（TIASshot.exe --selftest，SELFTEST ビルドフラグ）で起動時の依存解決・プレビュー経路・校正〜保存の一部を実機なしで自動確認できるようになったため，本プロファイルを作成した．

種別・検証手段 (Target & Method)

  • デスクトップアプリ（WinForms）．画面操作・カメラ操作はしない．
  • ランナー scripts/verify/run_selftest.py が，クリーンビルド（Debug|x64）→ 既存テスト（NUnit）→ TIASshot.exe --selftest を実行し，終了コードと結果ファイルで判定する．
  • セルフテストの 3 項目（実行ファイルに組み込み済み．verifier がシナリオを書く必要はない）:
ID確認内容実コードを通す範囲代替している部分
deps起動時にアセンブリ解決エラー（FileLoadException / FileNotFoundException）が出ないTIASshot.exe.config のバインディングリダイレクトと bin の DLL バージョンの一致，本体参照の推移的ロード，bin 内の全管理 DLL のロード，OpenCvSharp（ネイティブ DLL・Mat 演算・Mat.AsSpan（System.Memory）・ArUco），BitmapConverter と BitmapUtil.FastClone の往復，config.xml・TCC CSV の読み込み，Form1 の実コンストラクタ（InitializeComponent）Form1_Load（カメラ・光源への接続）は実行しない
previewプレビュー経路（カメラコールバック → UI 所有コピー（FastClone）→ 表示用 Bitmap）が動くCameraBase（コンストラクタ・BootCheck・ProcessCalibrationFrame），Form1.ShowImage・MainRefreshTimer_Tick（実タイマー），PreviewMonitor（実コンストラクタ・UpdateImage・RefreshTimer_Tick）．入力 Bitmap 解放後も表示コピーが有効であること（所有権モデル）を確認カメラは偽カメラ（SelfTest/SelfTestCamera．Lucam のコールバック手順を再現）．フォームは非表示・InitializeComponent を呼ばないヘッドレス版コンストラクタ．副ディスプレイの存在は模擬
calib-save校正〜保存が一通り動くChartDetector（ArUco 検出・固定判定・ホモグラフィ・マスク），CameraBase.CalcTcc・ColorCorrector（変換行列算出・CSV 保存），CameraBase.ShotOne → RunShotLoop → SaveThread → SaveImages（sRGB 変換画像の保存）．保存物の読み戻し・行列の有限性・変換後の色票が参照値に戻ることを確認チャートは合成画像（ArUco と色票をコードで描画）．ゲイン反映は偽カメラが画像へ乗算して模擬．保存先は一時フォルダ

検証対象の環境 (Target Environments)

  • ローカルの接続先: このマシンのみ（ビルド・実行ファイル・一時フォルダ）．ネットワーク上のサービスは使わない（--full 時の nuget restore による nuget.org からのパッケージ取得のみ例外）
  • ローカル以外で許可する環境: なし
  • 接続を禁止する環境（拒否リスト）: 実機カメラ（Lumenera / ImagingSource）・光源（シリアルポート）・本番の撮影データフォルダ（config.xml の File/SaveFolder，既定 C:\TIAS_Data）．セルフテストはこれらに触れない設計であり，verifier も触れない

実行コマンド (Run Command)

リポジトリルートで実行する．

用途コマンド
通常（コード変更の確認）python scripts/verify/run_selftest.py
依存更新（NuGet パッケージ・バインディングリダイレクトの変更）の確認python scripts/verify/run_selftest.py --full
  • ランナーの --no-clean（Debug 出力を消さない）・--skip-tests（既存テストを省略）は開発時の短縮用であり，判定には使わない（verifier は上表のコマンドだけを使う）
  • --full は packages を退避して nuget restore からやり直す（git clone 直後と同じ状態．ENV_04「クリーン環境での検証」）．復元に失敗した場合は退避した packages を自動で戻す．packages の退避（改名）自体に失敗した場合（Visual Studio が使用中等）は packages を変更せずに終了コード 2 で止まる
  • 出力先: .verify/selftest/run-<日時>/（.gitignore 済み．実行ごとに別ディレクトリ）
  • 出力されるもの: summary.json（各ステップの成否）・build.log・test.log・restore.log（--full 時）・selftest-result.txt（セルフテストの詳細．UTF-8 BOM 付き）
  • ランナーの終了コード: 0=全て合格，1=不合格あり（ビルド失敗・テスト失敗・セルフテスト失敗），2=前提条件を満たさない（→「検証不能」）
  • セルフテスト単体の終了コード（summary.json の selftest_exit_code）: 0=全項目合格，1=不合格あり，2=セルフテスト自体の異常，3=タイムアウト（5 分．ハングの疑い）

判定の読み方

  • selftest-result.txt は項目ごとに [PASS] <ID>: ... / [FAIL] <ID>: ... の見出し行と，その下の詳細行（- 情報，WARN: 参考，FAIL: 失敗理由）で構成され，最終行が RESULT: PASS (3/3) または RESULT: FAIL (...) になる
  • FAIL: 行には例外型・メッセージ・対象アセンブリ名（[assembly: ...]）・Fusion ログの要点（[fusion: ...]）・スタックの先頭が入る．依存の問題はここで特定できる
  • 判定は終了コードと結果ファイルで行う．TIASshot.exe の標準出力は OS のコードページ（cp932）で出るため，直接実行すると文字化けすることがある（ランナーは標準出力を使わない）

前提条件と確認方法 (Preconditions)

前提条件確認方法満たされない場合
Visual Studio 2022 または Build Tools（MSBuild・vstest）が導入済みランナーが vswhere で自動検出する（見つからなければ終了コード 2）検証不能とし，docs/02_ENV/ENV_02_環境構築手順.md に従った導入を人間に案内する
NuGet パッケージが復元済み（packages/）ls packagespython scripts/verify/run_selftest.py --full を実行してよい（nuget.exe が無ければ検証不能とし setup.ps1 の実行を人間に案内する）
IC Imaging Control 3.5 .NET Library が導入済み（ビルドに必要．実機カメラは不要）ビルドの成否（build.log に TIS.Imaging の参照エラーが無いこと）検証不能とし，ENV_02 の SDK 導入手順を人間に案内する
TIASshot.exe やテストが実行中でない（Debug 出力を削除できる）ランナーがクリーンするのは Debug 出力（TIASshot/ と TIASshot.Tests/ の bin/x64/Debug・obj/x64/Debug）のみで，bin/x64/Release 等ほかの構成の出力には触れない．削除に失敗すると終了コード 2 で止まる検証不能とし，人間にアプリ・Visual Studio のデバッグ実行の終了を依頼する（自分でプロセスを止めない）

認証方法・ロール (Auth & Roles)

  • 認証なし

テストデータの規約 (Test Data Rules)

  • セルフテストが書き込むのは次の 2 か所だけ:
    • %TEMP%\TIASshot-selftest\work-<日時>-<PID>\（一時設定ファイル・校正データ・撮影画像）．合格時は自動削除，不合格時は証拠として残し，結果ファイルの末尾に work dir kept: <パス> と出る
    • .verify/selftest/run-<日時>/（ランナーのログと結果）
  • 同梱の config.xml は変更しない（セルフテストは複製して保存先・参照パス・効果音を差し替えた一時設定を使う）．本番の保存先（C:\TIAS_Data 等）には書き込まない
  • 不合格時に残った work-* フォルダの有無とパスを，報告の「後始末」に書く（削除は人間の判断に任せてよい）

待ち方・操作の癖 (Waiting & Selectors)

  • ランナーは同期実行で，完了まで待つだけでよい（通常 10〜30 秒．--full はパッケージ取得で数分）
  • セルフテストはウィンドウを表示しない．画面の確認手段は無く，スクリーンショットも出ない
  • Release 構成にはセルフテストが含まれない（SELFTEST フラグは Debug 系のみ）．Release の exe に --selftest を渡すと通常起動（UI 表示・カメラ接続）になるため，実行しない

既知のノイズ (Known Noise)

  • deps の リソース系の AssemblyResolve n 件（サテライトリソースの探索．判定対象外）: 日本語カルチャのサテライトリソース（TIASshot.resources）を探して見つからないのは通常動作
  • deps の redirect System.ValueTuple → 4.0.3.0: bin に DLL なし: .NET Framework 4.7.1 以降は mscorlib に統合されており bin に置かれないのが正常
  • カメラ SDK（TIS.*・lumenera.*）のロード失敗は WARN:（判定対象外）．SDK 未導入の環境では出うる
  • preview / calib-save の所要時間は環境で変わる（判定条件ではない）

禁止操作 (Prohibited Operations)

  • --selftest を付けない TIASshot.exe の起動（UI が開き，実機カメラ・光源（シリアルポート）へ接続を試みる）
  • config.xml（リポジトリ内・bin 内とも）や本番の保存先フォルダ（C:\TIAS_Data 等）の編集・削除
  • 自分が起動していないプロセスの停止（人間が起動した TIASshot・Visual Studio のデバッグ実行を止めない）
  • packages.bak-* 以外のリポジトリ内ディレクトリの手動削除・改名（packages の退避と復元はランナーの --full だけが行う）
  • ランナーを通さない独自のビルド・実行手順の組み立て（コマンドは本ファイルに書かれたものだけを使う）
  • 失敗注入（bin 内 DLL の一時除去・TIASshot.exe.config の改ざん等）や TIASshot.exe --selftest の直接実行．セルフテストが依存の問題を検出できるかの確認が必要な場合は，人間が docs/02_ENV/ENV_04_開発コマンド.md の手順で行う（verifier には許可しない）

シナリオのテンプレート (Scenario Template)

本プロジェクトでは verifier がシナリオを書く必要はない（確認項目は TIASshot.exe --selftest に組み込み済みで，引数で項目を選ぶ仕組みも無い）．verifier の作業は次のとおり．

1. 変更内容に応じてコマンドを選ぶ
   - NuGet パッケージ・App.config（バインディングリダイレクト）・csproj の参照を変えた → --full
   - それ以外のコード変更 → 通常
2. python scripts/verify/run_selftest.py [--full] を実行する
3. 出力ディレクトリの summary.json と selftest-result.txt を Read で開き，
   - 各ステップ（clean / restore / build / tests / selftest）の成否
   - 各項目（deps / preview / calib-save）の [PASS]/[FAIL] と，FAIL: 行・WARN: 行の内容
   を確認する．PASS でも，今回の変更に関係する項目の詳細行（ロードされた DLL のバージョン等）を必ず見る
4. FAIL の場合は FAIL: 行（例外型・アセンブリ名・Fusion ログ）を証拠として報告する
   （build.log / test.log の該当箇所も併記する）

変更がセルフテストの 3 項目で観測できない領域（下記「自動で確認できない範囲」）にある場合は，その部分を「未確認」として人間に回す．

自動で確認できない範囲（人間が確認する項目）(Out of Scope)

セルフテストが PASS でも，以下は確認していない．変更がこれらに関わる場合は「人間が確認すべき残り項目」に具体的に書く．

  • 実カメラ SDK との結合: Lucam / IScam の接続・パラメータ設定・フレームコールバック・撮影（Snap・Sink 切り替え）・ROI 切り出し・白板撮影（WHITEBOARD）
  • 実プレビュー表示: 実ウィンドウへの描画・表示の滑らかさ・副ディスプレイでの表示位置・F9 トグル（MEMMONITOR）
  • 実チャートの検出性能: 実物の舌診チャートを実照明・実レンズで撮った画像での ArUco 検出・固定判定・マスク位置（合成チャートは理想条件）
  • 画像の見た目: 校正後の sRGB 画像の色・露出・ホワイトバランスが臨床的に妥当か（セルフテストは合成チャートでの数値一致のみ）
  • 長時間のメモリ / GDI: 長時間プレビュー・連続撮影でのメモリリーク・GDI ハンドル枯渇（docs/06_TEST/TEST_03_メモリ修正効果計測.md の手順）
  • 光源（シリアル通信）の制御，効果音の再生，エラー時のダイアログ表示（セルフテストでは記録のみに差し替えている）
  • Release 構成の実行（セルフテストを含まないため，起動確認は人間が行う）

実行基盤の要件 (Runner Requirements)

  • 決定的な処理（ツールの検出・bin/obj の削除・パッケージ復元・ビルド・テスト・セルフテスト実行・結果の集計）はランナー scripts/verify/run_selftest.py が行う．verifier は判断（結果の読み取り・報告）のみ行う
  • 実行ごとに .verify/selftest/run-<日時>/ へ出力し，前回の証拠を上書きしない
  • ランナーは自分が起動したプロセス（MSBuild・vstest・TIASshot.exe）以外を停止しない．セルフテストは内部のウォッチドッグ（5 分）でハング時も終了コード 3 で終わる
  • 前提を満たさない場合は破壊的な復旧を試みず，終了コード 2 と理由を出して終了する
  • セルフテストの実装は TIASshot/SelfTest/ と TIASshot/UI/*.SelfTest.cs（#if SELFTEST），ビルドフラグは docs/02_ENV/ENV_06_ビルド構成とビルドフラグ.md を参照する