refactor: 2ライン方式の採用に伴うディレクトリ整理

[ucn-yushin]

対応Issue

ディレクトリ整理そのもののIssueは立てていません。方式決定の経緯は以下を参照してください。

• [experiment] 2ライン判定による出庫判定検証 #88 2ライン方式の検証
• [experiment] ROI (Region Of Interest)のbbox変動分析 #89 ROI方式の検証
• experiment/ucn/two-lines-detection #90 2ライン方式の実装（本PRの前提）

なぜやったか

PR #90 で2ライン方式の採用が決まり、リポジトリの位置づけが「複数方式を並べて比較する実験リポジトリ」から「採用方式を運用するプロダクト」へ変わった。しかし構造は実験時代のままで、以下の問題があった。

• 採用されなかった方式（ROI方式、センサー方式、SAHI+YOLOの旧台数計測）のコードが同居している
• パッケージ化されておらず、各スクリプトが sys.path.insert で common を import している
• 依存定義がルートの pyproject.toml と各所の requirements.txt に二重化している
• .gitignore が docs/ を丸ごと無視しており、方式決定の記録をコミットできない
• テストが common/tests、line_detection/tests、eval/tests の3箇所に分散している

何をやったか

レガシーの削除

raspi/detect/（SAHI+YOLOの旧台数計測）、raspi/sensor/（センサー方式のハンズオンサンプル）、cron/（sakura.ioからのデータ取得）、run_gate4_alternating.py（ROI方式との速度比較、完了済み）を削除した。削除前の状態は archive/pre-cleanup タグに保存してある。

srcレイアウトへの移行

scripts/            CLIエントリポイント（run_detection, setup_lines, visualize_lines, run_multi_video）
src/tracking_parking/
  ├── config.py     設定管理
  ├── detection/    ライン交差判定・トラッキング
  ├── output/       動画・イベントログ出力
  ├── common/       計測・GT・W&Bの共通基盤
  └── eval/         精度評価
tests/              common / detection / output / eval / scripts にミラー配置
docs/               設計・検証・決定の記録
data/, models/      入出力データとモデル重み（Git管理外）
plate_recognition/  ← raspi/number/
training/           ← yolo_fine_tuning/

pyproject.toml に hatchling のビルド設定を追加し、uv sync で editable install されるようにした。これにより全ファイルの sys.path.insert を削除し、from tracking_parking.common.x import ... の絶対 import に統一した。raspi/line_detection/requirements.txt は依存定義がルートと重複していたため削除した。

Git管理外への参照の解消

ドキュメントやコードから、読み手が辿れない参照（docs.local/ のHTML、gitignore対象の newcam.env / img2787.env）を排除し、情報がリポジトリ内で完結するようにした。判断の内訳は本文末尾の備考を参照。

run_multi_video.py は対象動画リストをハードコードしていたため、data/inputs/videos.json（gitignore対象）から読む方式へ変更し、雛形 data/inputs/videos.example.json をGit管理下に追加した。

意思決定の記録

.gitignore の docs/ 一括除外をやめ、docs/decisions/0001-two-line-method.md として2ライン方式採用のADRを追加した。速度・集計精度の比較結果、決め手になった「実行と観測の基盤」の差に加えて、この決定が主張していないこと（イベント単位の精度は未評価、エッジ実機でのロバスト性は未検証など）と、ROI方式の削除で失われるパラメータ探索基盤を引き継ぐ課題として明記している。

ルート README.md も書き直した（従来はwikiへのリンク1行のみ）。

どのように実装したか

レビューしやすさのため、フェーズごとにコミットを分けている。

1. chore: レガシー削除（対象ごとに1コミット、ロールバック可能な粒度）
2. refactor: srcレイアウトへディレクトリを移動（内容変更なし） — git mv のみ。89ファイルがリネームとして検出されており履歴が追える
3. refactor: パッケージ化しimportからsys.pathハックを除去 — import書き換えとパッケージ化
4. chore: / docs: — .gitignore 整理、ADR追加、ドキュメントの旧パス更新

scripts/ はパッケージではないため、テストからの import パス解決は tests/conftest.py の1箇所に集約した（各テストでの sys.path 操作は全廃）。

.env / モデル重み / データの既定パスはすべてリポジトリルート基準へ統一した（data/inputs、data/outputs、models/）。

画面スクリーンショット等

• URL
  スクリーンショット

テスト項目

• uv sync 後、uv run pytest -q が全件パスすること（手元では198件パス、移行前と同数）
• uv run python -c "import tracking_parking" が成功すること
• scripts/ 配下4本の --help がエラーなく表示されること
• 実動画1本で scripts/run_detection.py を実行し、data/outputs/ へイベントログとmanifestが出力されること
• setup_lines.py で保存したとき .env のライン座標以外の設定が保持されること

備考

⚠️ 正解データ（GT）の再構成について

raspi/roi-counter/ の未追跡データを削除した際、そこに置かれていた正解台数ファイル *_gt.json 6本を一緒に消してしまいました（data が .gitignore 対象のため、Git・バックアップのいずれからも復元できませんでした）。

過去runのmanifestに gt_in / gt_out が記録されていたため、そこから data/inputs/configs/ へ再構成しています。値は6動画すべて復元できていますが、ファイルのSHA-256は元と一致しません。 condition_key にGTのハッシュが含まれるため、今後のrunは過去runと同一条件とはみなされなくなります。

• 再構成した値: 1787008160.558032 (55/0), 1787009706.719727 (30/2), 1787011229.231516 (2/3), 1787012751.179971 (7/1), 1787014266.421887 (3/3), IMG_2787 (22/0)
• 元ファイルにあったROI方式用の roi フィールドは復元していません（ROI方式は削除済みのため不要）
• 元ファイルに events（イベント時刻）が入っていた形跡は、どの出力にも見当たりませんでした

手元に元ファイルの控えがある場合は差し替えてください。

Git管理外への参照をどう処理したか

対象	処理
ADRの docs.local/gate4-*.html 参照	内容を取り込み、参照を削除。 6動画の速度比較表、2.27倍の差が熱状態由来だった理由、絶対値が悪い理由をADR本文へ記載
newcam.env / img2787.env（gitignore対象）	設定を外部化。 run_multi_video.py は data/inputs/videos.json から読む方式に変更し、雛形をGit管理下に追加。docstringに作り方も記載
visualize_lines.py の実行例（vis.mp4 等）	汎用の例に差し替え
VERIFICATION.md（旧パス）	docs/verification.md への相対リンクに修正（リポジトリ内に存在するため）
ROI方式の roi-counter/scripts/* 参照	同リポジトリ内の所在を明示して保持。 feat/mike/89-bbox-analysis-within-roi ブランチ名とブランチ内フルパスを併記。W&B仕様書には「2方式並存時代の文書」であることと現行パスの対応表を追加
setup_lines.py の「roi-counterのroi_config.pyと同じ契約」	削除。 契約の内容自体は同じdocstringに書かれており、参照が無くても意味が通るため

訂正

ADRに「ROI方式のコードは archive/pre-cleanup タグに保存する」と書いていましたが誤りでした。ROI方式は develop にマージされたことがなく、タグ（develop ba00a9e 時点）にROI方式のコードは含まれません。ROI方式は feat/mike/89-bbox-analysis-within-roi ブランチ（3968e2d）にのみ存在します。ADRを訂正済みです。

その他

• archive/pre-cleanup タグ（develop ba00a9e 時点）を一緒にpushしています。
• docs.local/ は従来どおりGit管理外のままです（参照はしていません）。
• docs/verification.md にもGT再構成の経緯を追記し、condition_key の継続性が切れる点を明記しました。