ai-contract-platform/mobile/README.md

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:

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 -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 -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
• wait for the target serial to reach adb state device before launching the app
• 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
• TAXONOMY_PROOF_OK
• TAXONOMY_TARGET_CARD_OK
• TAXONOMY_FILTER_ACTIVE_OK
• TAXONOMY_VISIBLE_KEYS
• CONTRACT_RESULT_PROOF_OK
• CONTRACT_RESULT_DOWNLOAD_OK
• CONTRACT_RESULT_SHARE_OK
• CONTRACT_RESULT_CONTINUE_OK
• CONTRACT_VERSION_CHAIN_PROOF_OK
• CONTRACT_VERSION_CHAIN_ENTRY_OK
• CONTRACT_VERSION_CHAIN_DOWNLOAD_OK
• CONTRACT_VERSION_CHAIN_DIFF_VISIBLE
• CONTRACT_VERSION_CHAIN_SAVE_OK
• CONTRACT_VERSION_CHAIN_CREATED_VISIBLE
• CONTRACT_VERSION_CHAIN_SAVE_MARKER
• CONTRACT_VERSION_CHAIN_VISIBLE_LABELS
• DOCUMENTS_PROOF_OK
• DOCUMENTS_WORKSPACE_READY
• DOCUMENTS_TYPE_LIST_OK
• DOCUMENTS_BUILDER_OK
• DOCUMENTS_VISIBLE_CODES
• BUSINESS_AUXILIARY_PROOF_OK
• BUSINESS_AUXILIARY_PROMPTS_OK
• BUSINESS_AUXILIARY_TRIGGER_OK
• BUSINESS_AUXILIARY_ASSISTANT_OK
• BUSINESS_AUXILIARY_VISIBLE_LABELS
• SMOKE_OK
• SMOKE_BLOCKER

Current blocker meanings:

• wireless_adb_unavailable
  • the workstation cannot discover or connect to the phone's wireless ADB endpoint
  • re-enable or re-pair Wireless debugging on the phone, then rerun the smoke command
  • if adb devices -l shows the serial as offline, wait for the phone to finish reconnecting or toggle Wireless debugging off/on once
• 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
• contract-taxonomy
  • starts from the signed-in shell
  • opens AI tools -> contract workbench, applies the compliance/general-enterprise template filters, and verifies the filtered template keys
  • intended for deeper proof that template-category and industry-entry filtering still works on the proven X60PRO device profile
• contract-result-actions
  • starts from the signed-in shell
  • opens AI tools -> contract workbench -> generated result, then verifies download, share, and continue-editing actions
  • intended for proof that generated contract delivery actions remain reachable after result-page changes
• contract-version-chain
  • starts from the signed-in shell
  • opens a generated contract result, enters the lightweight editor, appends a smoke marker, saves a new version, and verifies the version-chain entry, diff entry, download entry, and created version visibility
  • intended for proof that generated contracts can complete a real mobile version-management save loop on device
• documents-workspace
  • starts from the signed-in shell
  • opens AI tools -> legal document workspace, verifies the document type list, and continues toward the builder surface
  • intended for deeper proof that the legal-document drafting flow remains reachable on the proven X60PRO device profile
• business-auxiliary
  • starts from the signed-in shell
  • opens AI tools, verifies the four mobile business-auxiliary quick prompts, and taps the obligation-extraction entry
  • intended for deeper proof that the mobile Chat product entry exposes business auxiliary routes directly on device

Examples:

# 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

# Deeper proof that contract template taxonomy filters work on device
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -ConfigureDevice -SkipInstall -SmokeDepth contract-taxonomy

# Deeper proof that generated-contract result actions remain reachable
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -ConfigureDevice -SkipInstall -SmokeDepth contract-result-actions

# Deeper proof that generated-contract version-chain can create and surface a saved version
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -ConfigureDevice -SkipInstall -SmokeDepth contract-version-chain

# Deeper proof that legal-document drafting remains reachable on device
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -SkipInstall -SmokeDepth documents-workspace

# Deeper proof that business auxiliary prompts are reachable from the mobile chat entry
powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -ExpectedIp 192.168.3. -SkipInstall -SmokeDepth business-auxiliary

When the phone's current wireless-debug port is already known, bypass mDNS discovery with -DeviceSerial:

powershell -ExecutionPolicy Bypass -File D:\ai-contract-platform\mobile\tools\real-device-smoke.ps1 -DeviceSerial 192.168.3.93:44421 -ConfigureDevice -SkipInstall -SmokeDepth documents-workspace

Validation Notes

• Real-device attachment picking is validated through system DocumentsUI
• Report download is validated
• Contract download is validated
• Contract template taxonomy filtering is validated through contract-taxonomy smoke depth
• Generated-contract result download/share/continue-editing is validated through contract-result-actions
• Generated-contract version-chain entry, editor save, diff affordance, version download affordance, and created-version visibility are validated through contract-version-chain
• Legal-document types, schema loading, and draft persistence are now wired into the mobile app; the documents-workspace smoke depth now proves the workspace, type list, and builder entry path on the signed-in X60PRO session
• The AI tools surface now exposes a first-class business-auxiliary launch strip for obligation extraction, filing-materials checklists, negotiation strategy, and legal-opinion boundary fallback, and the embedded legal chat keeps the same four quick prompts available for continuity
• 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
• Wireless reconnect helper: reconnect-wireless-device.ps1
• One-shot smoke helper: real-device-smoke.ps1