# AI Contract Mobile

Flutter mobile client for the AI contract workbench.

## Environment

- Flutter `3.41.9`
- Android SDK / platform-tools installed locally
- Default server dogfood target:
  - API: `http://192.168.3.90:8001/api/v1`

## Common Commands

From [mobile](D:/ai-contract-platform/mobile):

```powershell
C:\Users\yuqei-win\develop\flutter\bin\flutter.bat analyze --no-pub
C:\Users\yuqei-win\develop\flutter\bin\flutter.bat test --no-pub
C:\Users\yuqei-win\develop\flutter\bin\flutter.bat build apk --debug --no-pub --dart-define=API_BASE_URL=http://192.168.3.90:8001/api/v1 --dart-define=APP_ENV=server-dogfood
```

## Real Device Workflow

Wireless Android debugging is now the preferred path on this machine.

Current proven device family:

- `model=M20201419`
- `device=X60PRO`
- Android `11`

When the phone drops off ADB because the wireless debug port rotates, reconnect it with:

```powershell
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\reconnect-wireless-device.ps1 -ExpectedIp 192.168.3. -ConfigureDevice
```

That script will:

- rediscover the latest `_adb-tls-connect` mDNS endpoint
- reconnect the device
- optionally re-apply:
  - long screen timeout
  - stay-awake-while-charging

If the phone does not broadcast immediately, the script now retries discovery for a short window instead of failing on the first empty mDNS result.

For a one-shot unattended check that reconnects the phone, verifies the server, relaunches the app, and captures a UI/activity artifact bundle, run:

```powershell
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -ConfigureDevice
```

That smoke helper will:

- call the reconnect helper and rediscover the latest wireless-debug port
- optionally reinstall `build/app/outputs/flutter-apk/app-debug.apk` when it exists
- verify `8001/health` and `3003/`
- wake the phone, relaunch the app, and capture:
  - `dumpsys activity top`
  - `uiautomator` XML
  - a `summary.txt`
- write artifacts under `mobile/qa-artifacts/real-device-smoke/<timestamp>/`

The summary prints:

- `CONNECTED_SERIAL`
- `SERVER_API_STATUS`
- `SERVER_WEB_STATUS`
- `SMOKE_DEPTH`
- `APK_INSTALLED`
- `TOP_ACTIVITY`
- `APP_SURFACE`
- `SHARE_PROOF_OK`
- `SHARE_CHOOSER_ACTIVITY`
- `SHARE_PDF_PREVIEW_OK`
- `SHARE_REPORT_SECTION_REACHED`
- `SMOKE_OK`
- `SMOKE_BLOCKER`

Current blocker meanings:

- `device_locked`
  - the phone is still behind the OEM lockscreen / pattern unlock surface
- `login_required`
  - the app relaunched successfully, but dropped back to the login shell instead of the authenticated workbench
  - this is common after reinstall or when the device-side session has been cleared

Smoke depth options:

- `login-only`
  - verifies the phone reconnects, the server is reachable, the app relaunches, and an auth entrypoint is visible
  - accepts either a login form or an already signed-in app surface
- `shell-only`
  - verifies the phone reconnects, the server is reachable, and the app relaunches into the signed-in bottom-tab shell
  - this is the best default for unattended day-to-day health checks
- `share-proof`
  - starts from the signed-in shell
  - auto-navigates to review history, opens the first review, scrolls to the report section, taps `share report`, and captures chooser evidence
  - intended for deeper proof that the report-share path still reaches the system chooser on the proven X60PRO device profile

Examples:

```powershell
# Fastest unattended check when the APK is already installed
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -ConfigureDevice -SkipInstall -SmokeDepth shell-only

# Deeper proof that report share still reaches the Android chooser
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -ConfigureDevice -SkipInstall -SmokeDepth share-proof
```

## Validation Notes

- Real-device attachment picking is validated through system `DocumentsUI`
- Report download is validated
- Contract download is validated
- External open/share behavior is OEM-dependent and may route into vendor apps such as the default browser or WeChat
- Lightweight mobile notifications now exist for:
  - review status transitions (`completed / partial / failed`)
  - generated contract completion
- Notification taps can route back into:
  - review detail
  - generated contract result
- Background review-status polling is now registered through `workmanager` on signed-in Android sessions
- On some OEM builds, unattended smoke after reinstall can still be obscured by the device lockscreen overlay even when `MainActivity` is already top-most in `dumpsys activity top`

## Key Files

- Runtime notes: [STATUS.md](D:/ai-contract-platform/mobile/STATUS.md)
- Wireless reconnect helper: [reconnect-wireless-device.ps1](D:/ai-contract-platform/mobile/tools/reconnect-wireless-device.ps1)
- One-shot smoke helper: [real-device-smoke.ps1](D:/ai-contract-platform/mobile/tools/real-device-smoke.ps1)