# 開発ステップ (Development Steps)

[要件定義書](PLAN_01_要件定義書.md) の目的（1. 誰でもビルド・実行できる状態にする，2. 解析結果を変えずにコードを整理する）を達成するための作業順序を定める．

## 進め方の方針 (Approach)

- **研究で使われてきた旧 exe（2021 年 12 月版）の解析結果を正解とする．**過去の研究データと比べられることを最優先にするため．
- **先に「旧 exe と同じ結果が出る」ことを確かめ，それからコードを整理する．**回帰テスト（ステップ 4）より前には，解析結果に影響しない変更だけを行う．ただしステップ 3 で旧 exe とのずれが見つかった場合は，ずれを直す変更をユーザーの承認のもとで行う．
- 各ステップは `/implement` で進め，ステップごとに作業ブランチを切って `main` に取り込む．

## ステップ一覧 (Steps)

| # | ステップ | 目的 | 解析結果への影響 |
| --- | --- | --- | --- |
| 1 | 実行に必要なファイルの取り込み | ビルドだけで実行ファイル一式が揃うようにする | なし |
| 2 | 実行を妨げる不具合の修正 | 解析を最後まで安定して回せるようにする | なし |
| 3 | 旧 exe と現行ソースの解析結果の比較 | 現行ソースが研究データと同じ結果を出すかを確かめる | ずれがあれば旧 exe に合わせる（ユーザー承認のもと） |
| 4 | テストプロジェクトと回帰テストの作成 | 旧 exe と同じ結果であり続けることを確かめる手段を作る | なし |
| 5 | 未使用コード・参照の削除 | 読む量を減らし，不要な依存（脆弱性のある Newtonsoft.Json 等）をなくす | なし（回帰テストで確認） |
| 6 | 解析処理の切り出しと重複の統合 | 画面から解析処理を分け，2 モードの重複（約 420 行）をなくす | なし（回帰テストで確認） |
| 7 | エラー処理とログの整備 | 失敗の原因が分かるようにする | なし（回帰テストで確認） |

## 各ステップの内容 (Step Details)

### 1. 実行に必要なファイルの取り込み

- 旧ビルド出力（`DeepTIAS2.7.1-Latest`）から，ソースに無く実行に必要なファイルを取り込む
  - ネイティブ DLL: `RemoveSmallRegionDLL.dll`（と依存する `opencv_world320.dll`），`TongueAnalysisDLL.dll`
  - 外部 exe: `python/TongueFeatures.exe`，`rgb2lab/`（`TongueAnalysis.exe` と色補正データ，依存する OpenCV 3.4 のデバッグ版 DLL）
  - 出力雛形: `template_outputDir/`，`template_outputDir_withCalib/`
- `*.exe`・`*.dll` を Git LFS の対象に加える
- csproj に「出力ディレクトリにコピー」を指定し，ビルドだけで `bin\x64\Release\` に揃うようにする
- 完了条件: clone → ビルド → 起動 → サンプル画像 1 枚を Image モードで解析し，`analysis.csv` が出力される
- ※ 旧ビルド出力はリポジトリ外にあり，Claude はフックの制限で読めない．ユーザーがリポジトリ内の `_legacy\`（`.git/info/exclude` で管理対象外）に丸ごとコピーして作業した
- 結果: 完了．取り込んだファイルは `Tongue extraction\runtime\` に置いた．`TongueAnalysisDLL.dll`（宣言のみで未使用）と OpenCvSharp3 時代の DLL は取り込んでいない

### 2. 実行を妨げる不具合の修正

- 二値画像のウィンドウ（`Cv2.ImShow`・`Cv2.WaitKey`）で解析が止まる箇所を削除する
- Start を押すたびに解析処理が重複して登録される不具合を直す．モード選択を解析後に押せる状態に戻す
- 解析中の例外を `RunWorkerCompleted` で受け取り，画面に表示して操作できる状態に戻す
- Image&Calib の出力先が `Output\debug` に固定されている件は，ユーザーの判断を得てから直す（[要件定義書](PLAN_01_要件定義書.md) の未決事項）
- Image モードで中間ファイル（`1-detection\1-drawBox\`・`4-featureExtraction\shape\`）が最後の画像の分しか残らない不具合を直す（画像ごとに `MyMakeDir` でフォルダを空にしているため．`analysis.csv` の値には影響しない．ステップ 3 で中間画像を比べるために必要）
- 完了条件: 複数枚の画像を両モードで続けて解析でき，途中で止まらない．中間ファイルが全画像分残る

### 3. 旧 exe と現行ソースの解析結果の比較

配布済みの旧 exe は現行ソースからビルドしたものではない（旧 exe は OpenCvSharp3 / OpenCV 3.2，現行ソースは OpenCvSharp4 / OpenCV 4.9）．二値化・輪郭検出・縮小などは OpenCV のバージョンで結果が変わりうるため，整理を始める前に一致するかを確かめる．

- 同じ入力画像（Image・Image&Calib の両モード）を旧 exe と現行ソースの両方で解析し，`analysis.csv` を列ごとに比べる
- 一致しない場合は，どの工程（検出・抽出・領域分割・特徴量）でずれるかを中間画像で突き止め，原因を調べる
- ずれを直す方針（OpenCV のバージョンを合わせる，処理を旧版に合わせる等）はユーザーと相談して決める．解析結果を変える変更のため，承認なしに行わない
- 比較の結果（一致した列・ずれた列とその大きさ・原因）を記録に残す
- 完了条件: 現行ソースの結果が旧 exe の結果と許容誤差の範囲で一致する．または，残るずれをユーザーが確認し，許容すると判断している

### 4. テストプロジェクトと回帰テストの作成

- MSTest のテストプロジェクト `DeepTIAS.Tests` をソリューションに追加する
- 旧 exe でサンプル画像を解析した結果（`analysis.csv` と中間画像）を正解データとし，`DeepTIAS.Tests/TestData/` に置く
- 現行ソースで解析して正解データと比べる回帰テストを作る（両モード）．許容誤差はステップ 3 の比較結果をもとに決める
- 開発コマンド（[ENV_04](../02_ENV/ENV_04_開発コマンド.md)）にテストの実行コマンドを追記する
- 完了条件: 回帰テストが通り，わざと解析結果を変えると失敗する

### 5. 未使用コード・参照の削除

- 使われていないファイル（`Form1 - backups.cs`，`Settings.Designer.cs`・`Settings1.Designer.cs`）を削除する
- 使われていないメソッド・フィールド・`DllImport` 宣言・`using` を削除する
- 使われていない NuGet 参照（Microsoft.ML 一式，Newtonsoft.Json，OpenCvSharp.WpfExtensions 等）と，リポジトリ外を指す参照（OpenCvSharp.Blob，v4.7.1 の絶対パス）を削除する
- 使われていないモデル `models/ResUnet_0.9518.pb` の扱いを決める（削除するか，別の場所に保管するか）

### 6. 解析処理の切り出しと重複の統合

- `Form1.cs` の解析処理を，画面に依存しないクラスに切り出す（置き場所は `.claude/rules/project-structure.md`）
- Image と Image&Calib でほぼ同じ処理を 1 つにまとめ，違い（色補正の有無，雛形，チャネル）だけを分ける
- 解析結果に影響する数値を名前付きの定数にまとめる
- 切り出した処理に単体テストを追加する

### 7. エラー処理とログの整備

- `.claude/rules/error-handling.md` に沿って，握りつぶしている例外をなくし，失敗の原因をダイアログとログで伝える
- 外部 exe の終了コードと出力ファイルを確認する
- 出力フォルダに `log.txt` を書き出す

## 対象外 (Out of Scope)

要件定義書の「やらないこと」のとおり，新機能の追加，解析手法の変更，モデルの差し替え，外部バイナリの作り直しは本計画に含めない．

## 前提 (Assumptions)

- 研究で使われてきた解析結果は，旧ビルド出力（`DeepTIAS2.7.1-Latest`）にある 2021 年 12 月版の `DeepTIAS2.7.exe` で出したものとする．これより古い版で出したデータが混ざっている場合は，比べる相手を決め直す