# Android Device Setup Guide - My Sport Manager Flutter App

## Overview
This guide walks you through connecting your Android phone to your development machine and running the My Sport Manager Flutter app.

---

## Prerequisites
- Android phone with USB debugging enabled
- Development machine with Flutter 3.41.0+ installed
- Local PHP server running with MySQL (serving `/early_access/api`)
- Both devices on the same Wi-Fi network

---

## Step 1: Enable USB Debugging on Your Android Phone

1. **Open Settings** on your phone
2. **Scroll down to "About phone"** (may be under System)
3. **Tap "Build number"** 7 times rapidly (watch for "Developer mode enabled" toast)
4. **Go back** and open **"Developer options"** (now visible in Settings)
5. **Enable "USB Debugging"**
6. **Optional:** Enable "Install via USB" and "USB Debugging (Security settings)"

---

## Step 2: Connect Phone via USB to Development Machine

1. Plug your Android phone into the dev machine via USB cable
2. On your phone, a prompt may appear asking to allow USB debugging from this computer
   - **Tap "Allow"** (optionally check "Always allow")

---

## Step 3: Verify Connection on Dev Machine

```bash
# Set up environment
export PATH="/mnt/ssd_data/flutter/bin:$PATH"
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-arm64
export ANDROID_HOME=/mnt/ssd_data/android-sdk

# Check connected devices
adb devices
# Expected output: lists your phone's device ID (e.g., a1b2c3d4)

flutter devices
# Should show your Android device as available
```

---

## Step 4: Configure API Base URL for LAN Access

The app needs to reach your local PHP server from the phone. Update the config:

1. **Find your dev machine's LAN IP address:**
   ```bash
   hostname -I
   # or
   ip addr show | grep "inet "
   # Look for something like 192.168.1.100 (not 127.0.0.1)
   ```

2. **Edit `mysportmanager-shared/lib/config/app_constants.dart`:**
   - Locate `DevConfig.localApiUrl`
   - Change from `'http://192.168.1.100/early_access/api'` to your actual IP:
   ```dart
   static const String localApiUrl = 'http://<YOUR_LAN_IP>/early_access/api';
   ```
   - Ensure `DevConfig.useLocalApi = true` (it already is)

3. **Verify the server is accessible from phone:**
   - From your phone's browser, navigate to `http://<YOUR_LAN_IP>/early_access/api/dashboard`
   - You should see a JSON response (likely 401 Unauthorized - that's ok, means API is reachable)

---

## Step 5: Build & Run App on Device

```bash
cd /mnt/ssd_data/mysportmanager-shared

export PATH="/mnt/ssd_data/flutter/bin:$PATH"
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-arm64
export ANDROID_HOME=/mnt/ssd_data/android-sdk

# Get dependencies
flutter pub get

# Build and run on the connected device
# (replace <DEVICE_ID> with the ID from `flutter devices`)
flutter run -d <DEVICE_ID>

# Example:
# flutter run -d a1b2c3d4
```

---

## Step 6: Test Login Flow

Once the app opens on your phone:

1. **See the login screen** with username/password fields
2. **Test login:**
   - Username: `testuser` (or valid test account)
   - Password: `TestPassword123!`
   - **Tap "Login"**

3. **Expected dashboard load:**
   - User info card (name, club)
   - Athletes list (taps open athlete detail)
   - Upcoming competitions
   - Recent activities

4. **Test navigation:**
   - **Tap an athlete** → opens athlete detail (best times, comp history)
   - **Go back** → returns to athletes list
   - **Tap "Dashboard"** → returns to main dashboard

---

## Step 7: Hot Reload During Development

While the app is running:
- **Press `R`** in the terminal to hot reload (fast code changes without rebuild)
- **Press `r`** for restart
- **Press `q`** to quit

---

## Troubleshooting

### Phone cannot reach API
**Symptom:** Login fails or "Connection refused" error

**Fix:**
- Verify both devices are on the same Wi-Fi network
- Check LAN IP is correct: `ping <YOUR_LAN_IP>` from phone
- Ensure Apache/Nginx allows requests from all interfaces (not just localhost)
- Use `adb shell` to verify from phone:
  ```bash
  adb shell
  curl http://<YOUR_LAN_IP>/early_access/api/dashboard
  exit
  ```

### Device not detected by `flutter`
**Symptom:** `flutter devices` shows no devices

**Fix:**
- Unplug and re-plug the USB cable
- Restart ADB:
  ```bash
  adb kill-server
  adb start-server
  adb devices
  ```
- On phone, revoke USB debugging permissions and re-enable

### Build fails (gradle, build-tools)
**Symptom:** Gradle errors during `flutter run`

**Fix:**
- Ensure Android SDK components are installed:
  ```bash
  export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-arm64
  /mnt/ssd_data/android-sdk/cmdline-tools/latest/bin/sdkmanager --list | grep installed
  ```
- If missing, install them:
  ```bash
  yes | /mnt/ssd_data/android-sdk/cmdline-tools/latest/bin/sdkmanager \
    --install "platforms;android-34" "build-tools;34.0.0" "platform-tools"
  ```

### App crashes on startup
**Symptom:** App launches but crashes immediately

**Check logs:**
```bash
flutter logs
# Look for error messages; check that ApiClient is using correct base URL
```

---

## Test Credentials

Use these test accounts to log in:

| Username | Password | Role |
|----------|----------|------|
| `testuser` | `TestPassword123!` | Coach |
| `admin` | `AdminPass456!` | Admin |
| `swimmer_parent` | `ParentPass789!` | Parent |

*(Replace with actual test accounts from your database)*

---

## Next Steps

After confirming the app works on device:

1. **Run integration test script** (provided separately) to automate flows
2. **Build release APK:** `flutter build apk --release`
3. **Share APK** to other testers via Android's build output
4. **Test on multiple devices** to verify compatibility

---

## Environment Variables Cheat Sheet

```bash
# Set these before running flutter commands
export PATH="/mnt/ssd_data/flutter/bin:$PATH"
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-arm64
export ANDROID_HOME=/mnt/ssd_data/android-sdk
```

Or add to your shell profile (`~/.bashrc` or `~/.zshrc`):
```bash
export PATH="/mnt/ssd_data/flutter/bin:$PATH"
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-arm64
export ANDROID_HOME=/mnt/ssd_data/android-sdk
```

---

## Support

If you encounter issues:
1. Check terminal logs: `flutter logs` while app is running
2. Check server logs: `tail -f /var/log/apache2/error.log` (or nginx equivalent)
3. Verify API response in browser: `http://<YOUR_LAN_IP>/early_access/api/me` (should return 401 if not logged in)