# 環境構築手順 (Environment Setup Guide)

新しい PC で開発環境を構築する際の手順．メンバーの参加時や環境の再構築時に使用する．

## 前提条件 (Prerequisites)

- OS: Windows 10 以降
- インターネット接続
- GitHub アカウント（リポジトリへのアクセス権があること）
- Python 3.7 以上と `bash`（Claude Code のフック実行に使用）
  - フックは `bash .claude/hooks/run_python.sh` 経由で起動し，`python3` → `python` → `py` の順に起動できるものを使う（いずれか 1 つで起動できればよい）
  - `bash` は Git for Windows 付属のものを使う
  - ※ Python が見つからないと，リポジトリ外アクセス制限フックが Claude Code の Read・Write・Edit・Glob・Grep・Bash をすべてブロックする

## 手順 (Steps)

### Scoop のインストール (Install Scoop)

PowerShell を開き，以下を実行する．

```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
```

インストール後，ターミナルを再起動して以下で確認する．

```bash
scoop --version
```

### リポジトリの取得 (Clone Repository)

```bash
git clone https://github.com/<organization>/SmTIAS-Capture.git
cd SmTIAS-Capture
```

※ Git が未インストールの場合は `scoop install git` を先に実行する．
※ リポジトリの URL は管理者に確認すること．

### セットアップスクリプトの実行 (Run Setup Script)

リポジトリに含まれるセットアップスクリプトを実行し，必要なツールを一括インストールする．

```powershell
.\scripts\setup.ps1
```

以下が自動的にインストールされる．

- Flutter SDK（Dart SDK 同梱）
- Android Studio
- GitHub CLI（`gh`）

### Android Studio の初期設定 (Android Studio Initial Setup)

Android Studio を一度起動し，セットアップウィザードを完了させる．以下が自動的にインストールされる．

- Android SDK
- Android SDK Command-line Tools
- Android SDK Build-Tools
- JDK（Android Studio に同梱）

**手順:**

1. Android Studio を起動する
2. セットアップウィザードで「Standard」を選択する
3. ライセンスに同意し，ダウンロードを完了させる
4. セットアップ完了後，Android Studio は閉じてよい（エディタとしては VS Code を使用する）

### Flutter の設定 (Configure Flutter)

Flutter が Android SDK を認識できるように設定する．

```bash
flutter doctor --android-licenses
```

表示されるライセンスにすべて同意する（`y` を入力）．

### 環境の確認 (Verify Environment)

以下のコマンドで環境の過不足を確認する．

```bash
flutter doctor
```

すべての項目にチェック（✓）が付いていれば OK．問題がある項目は表示されるガイドに従って対処する．

### GitHub CLI の認証 (Authenticate GitHub CLI)

```bash
gh auth login
```

対話形式で GitHub アカウントにログインする．PR の作成・管理に使用する．

### VS Code のセットアップ (VS Code Setup)

1. VS Code でプロジェクトフォルダを開く
2. 推奨拡張機能のインストール通知が表示されるので，すべてインストールする
   - Flutter
   - Dart

※ 推奨拡張機能は `.vscode/extensions.json` で定義されている．

### 実機デバッグの準備 (USB Debugging Setup)

AQUOS sense3（または他の Android 端末）を USB デバッグできるようにする．

**スマートフォン側の設定:**

1. 「設定」→「デバイス情報」を開く
2. 「ビルド番号」を 7 回タップする → 「開発者になりました」と表示される
3. 「設定」→「開発者向けオプション」を開く
4. 「USB デバッグ」を ON にする

**PC との接続:**

1. USB ケーブルでスマートフォンと PC を接続する
2. スマートフォンに「USB デバッグを許可しますか？」と表示されたら「許可」をタップする
3. 以下のコマンドで接続を確認する

```bash
flutter devices
```

接続した端末名が表示されれば OK．

### 環境変数の設定 (Environment Variables)

新しいターミナルを開くたびに以下の設定が必要になる場合がある．ビルドエラーが出た際に確認すること．

**JAVA_HOME（Gradle ビルドに必要）:**

```powershell
$env:JAVA_HOME = "$env:USERPROFILE\scoop\apps\android-studio\current\jbr"
```

**ADB パス（実機デバッグに必要）:**

```powershell
$env:Path += ";$env:LOCALAPPDATA\Android\Sdk\platform-tools"
```

※ 上記は現在のターミナルのみ有効な一時設定．恒久化するにはシステムの環境変数に追加する．

### アプリの実行確認 (Run App)

```bash
flutter run
```

実機にアプリがインストールされ，起動すれば環境構築は完了．

## トラブルシューティング (Troubleshooting)

### `flutter doctor` で Android SDK が見つからない場合

Android SDK のパスを手動で設定する．

```bash
flutter config --android-sdk <Android SDKのパス>
```

Scoop 経由でインストールした場合，Android SDK は通常以下にある．

```text
%LOCALAPPDATA%\Android\Sdk
```

### ADB で端末が認識されない場合

- USB ケーブルが「データ転送対応」であることを確認する（充電専用ケーブルでは認識されない）
- スマートフォンの USB 接続モードが「ファイル転送（MTP）」になっていることを確認する
- 端末のメーカー固有の USB ドライバが必要な場合がある（AQUOS の場合は SHARP 公式サイトからダウンロード）
- `adb` コマンドが見つからない場合は，ADB パスの環境変数設定（上記「環境変数の設定」セクション）を確認する

### Gradle ビルドで `JAVA_HOME is not set` エラーが出る場合

JAVA_HOME の環境変数設定（上記「環境変数の設定」セクション）を確認する．Scoop 経由で Android Studio をインストールした場合，JDK は以下にある．

```text
%USERPROFILE%\scoop\apps\android-studio\current\jbr
```

### Gradle ビルドで Java と Gradle の非互換エラーが出る場合

`flutter build apk` で「Java/Gradle incompatibility」（例: Java 25 と Gradle 8.14 は非互換）と表示される場合，Android Studio 同梱の JDK が新しすぎる．JDK 21 を別途導入し，Flutter が使う JDK として指定する．

```powershell
scoop bucket add java
scoop install java/temurin21-jdk
flutter config --jdk-dir="$env:USERPROFILE\scoop\apps\temurin21-jdk\current"
```

※ `temurin21-jdk` の導入でユーザー環境変数 `JAVA_HOME` も JDK 21 に設定される．Android Studio は同梱の JDK を使うため影響しない．

### `Failed to find target with hash string 'android-37'` エラーが出る場合

Android SDK Platform 37 は `platforms/android-37.0` という名前でインストールされるが，Android Gradle Plugin は `platforms/android-37` を探すため見つからない（[flutter/flutter#192478](https://github.com/flutter/flutter/issues/192478)）．SDK の `platforms` に `android-37` から `android-37.0` へのジャンクションを作成する（管理者権限は不要）．

```powershell
$p = "<Android SDKのパス>\platforms"
New-Item -ItemType Junction -Path "$p\android-37" -Target "$p\android-37.0"
```

※ SDK Platform 37 が未導入の場合は，先に SDK Manager（または `sdkmanager "platforms;android-37.0"`）で導入する．