# 開発コマンド (Development Commands)

日常の開発で使うコマンド一覧．**コマンドを実行する前に必ず本ファイルを参照する**（推測でコマンドを試さない）．
コマンドが新しく確定・変更されたときは本ファイルを更新する．

前提: [ENV_02_環境構築手順.md](ENV_02_環境構築手順.md) のセットアップが済んでいること．
すべてリポジトリ直下（`pyproject.toml` のある場所）で実行する．OS（Windows / macOS）による差は無い．

## 環境 (Environment)

| 目的 | コマンド |
| --- | --- |
| 依存パッケージを同期（初回・`uv.lock` 更新時） | `uv sync` |
| 依存パッケージを追加 | `uv add <パッケージ>` |
| 開発用（テスト・lint 等）の依存を追加 | `uv add --dev <パッケージ>` |
| 依存パッケージを削除 | `uv remove <パッケージ>` |
| インストール済みパッケージを確認 | `uv pip list` |

※ `pip install` は使わない（ENV_02「環境再現性のルール」）．

## 起動 (Run)

| 目的 | コマンド |
| --- | --- |
| アプリを起動（メイン画面） | `uv run python -m tiasjudge` |
| コンソールスクリプトで起動 | `uv run tiasjudge` |
| 起動可能性のみ確認（画面を出さずに終了） | `uv run python -m tiasjudge --check` |
| 同梱学習データと診断の動作のみ確認（画面を出さない） | `uv run python -m tiasjudge --verify-data` |

※ 診断を実行すると結果画面（モードレス）が開く．結果画面は表示専用で，言語切替と「閉じる」はメイン画面の「結果画面の操作」から行う．
※ ヘッドレス環境（画面の無い CI 等）では `QT_QPA_PLATFORM=offscreen` を付けて `--check` を実行する．

### デバッグ用 (Debug)

結果画面の見た目を確認するための**デバッグ専用**オプション．舌画像の読み込みや診断（SVM 学習）は行わず，ダミーの診断結果とダミー画像で結果画面だけを開く．

| 目的 | コマンド |
| --- | --- |
| 結果画面をダミー結果で開く（成功パターン） | `uv run tiasjudge --preview-result` |
| 結果画面をダミー結果で開く（診断失敗パターン） | `uv run tiasjudge --preview-result --failed` |
| 結果画面を英語表示で開く | `uv run tiasjudge --preview-result --english` |
| プレビュー画面の構築のみ確認（即終了） | `uv run tiasjudge --preview-result --check` |

※ 既定は日本語表示．結果画面は表示専用（言語切替ボタンを持たない）ため，英語表示の確認には `--english` を使う．
※ プライマリ以外のモニタがあればそこに最大化して開く（2 画面運用の確認．SPEC_01「表示先モニタ」参照）．モニタ 1 台なら通常サイズで開く．
※ 結果画面を閉じるとアプリが終了する．
※ ダミー値は成功パターンが淡紅 55% / 紅 25% / 暗赤 10% / 紫 5% / 淡白 5%（上位 2 色は淡紅・紅），失敗パターンが旧実装の失敗時スコア組（紫 42 / 暗赤 0 / 紅 5 / 淡紅 11 / 淡白 3）．
※ オプションを付けなければ通常起動・`--check` の挙動は変わらない．

## テスト (Test)

| 目的 | コマンド |
| --- | --- |
| 全テストを実行 | `uv run pytest` |
| 特定ファイルを実行 | `uv run pytest tests/core/test_color.py` |
| 特定テストを実行 | `uv run pytest tests/core/test_color.py::test_xyz_to_lab` |
| 失敗時に詳細を表示 | `uv run pytest -vv` |
| 最初の失敗で中断 | `uv run pytest -x` |

※ テストが 1 件も収集されない場合，pytest は終了コード 5 で終わる．テスト対象の指定ミスを疑うこと．

## lint・フォーマット (Lint & Format)

| 目的 | コマンド |
| --- | --- |
| lint チェック | `uv run ruff check .` |
| lint の自動修正 | `uv run ruff check --fix .` |
| フォーマット実行 | `uv run ruff format .` |
| フォーマット差分の確認のみ | `uv run ruff format --check .` |

## コミット前の確認 (Pre-commit Checks)

以下の 3 つがすべて通ることを確認してからコミットする．

```bash
uv run ruff check .
uv run ruff format --check .
uv run pytest
```

## 配布用ビルド (Packaging)

Windows 単体 exe（onefile・コンソール非表示）を PyInstaller で作る（PLAN_02 ステップ 8）．

| 目的 | コマンド |
| --- | --- |
| exe をビルド | `uv run pyinstaller TIASjudge.spec --noconfirm` |
| ビルドした exe の起動確認（画面を出さない） | `dist/TIASjudge.exe --check` |
| ビルドした exe の同梱データ・診断確認 | `dist/TIASjudge.exe --verify-data` |
| ビルド成果物を削除 | `rm -r build dist`（PowerShell: `Remove-Item -Recurse build, dist`） |

※ 成果物は `dist/TIASjudge.exe`（約 93 MB）．`build/`・`dist/` は Git 管理外．
※ ビルド設定は リポジトリ直下の `TIASjudge.spec`，エントリスクリプトは `packaging/entry.py`．
※ `data/data.csv` は exe に同梱され，実行時に `sys._MEIPASS/data/data.csv` へ展開される．差し替えたい場合は環境変数 `TIASJUDGE_DATA_CSV` にパスを指定する．
※ ビルドは実行環境の OS 向けの成果物のみ作られる（Windows で Mac 用 app は作れない）．

## 同梱データ (Bundled Data)

| ファイル | 内容 |
| --- | --- |
| `data/data.csv` | SVM 学習データ（旧実装の `data.csv` を UTF-8 に変換して同梱．SPEC_02 参照） |

※ 変換行列 CSV・舌画像は実行時にユーザーが選択するためリポジトリに含めない．