# Android in-app updates on petaV3

## Delivery mode agreed on 2026-09-08

Use petaV3 to report installed Android versions and distribute APK updates.
Firebase is optional and is **not required for this rollout**. The authenticated
Flutter app checks at login/session initialization and on return to the foreground.
It downloads and verifies the update, shows progress, and hands installation to
Android for user confirmation. It does not silently install or notify a closed app.

The legacy native `propertylab-android` client used petaV2's public
`/api/agent-version`. Do not change that server or point that legacy API at the new
authenticated contract as part of this rollout.

## Current local status

- Backend feature is on local `dev-chen`: `81d83b38c`, with direct-route coverage
  in `0dbacd5bf`, followed by this rollout fix.
- This fix makes manifest downloads use `/agent-api`, avoiding the legacy Dingo
  `/api` prefix, and presents foreground updates as the normal admin workflow.
- Flutter feature commit: `ded45a6` in `propertylab-sales-agent`.
- Previously validated baseline APK: `1.0.51 (51)`, package `tech.propertylab.agent`.
- APK SHA-256: `1f5d08651894e7e92a0eab3d8d9df6dbdd2d4fc2f804b4e304802836e46bc640`.
- Build output location: `propertylab-sales-agent/build/app/outputs/flutter-apk/app-production-debug.apk`.
  This is overwritten by subsequent builds; the historical hash above identifies
  build 51 only. Build 52 adds [background diagnostics](agent-app-background-diagnostics.md).
- Backend regression tests: 16 tests / 103 assertions passed, with one existing
  PHPUnit configuration deprecation. Flutter update tests: 11 passed. Vite client
  and SSR production builds and targeted Pint checks passed.
- **Production deployment and end-to-end production update validation are pending.**
  The petaV3 SSH/deployment entry point has not been supplied or verified.

## Deployment checklist

1. Confirm the target serves `https://app.propertylab.com.my`, inspect its current
   revision and worktree, and preserve its rollback revision and database backup.
   Never use the petaV2 deployment instructions/host for this task.
2. Integrate only the app-update task commits onto the verified production base;
   do not publish unrelated local `dev-chen` history. Resolve changes on a release
   branch and run the relevant tests before updating production.
3. Follow the repository production deployment runbook for dependencies, staged
   client/SSR build, cache refresh, and service reload. Review all pending migrations
   first. This feature needs only:
   - `2026_09_07_100000_create_agent_app_releases_table.php`
   - `2026_09_07_100001_create_agent_app_installations_table.php`
   The combined PR also adds `2026_09_08_160000_create_agent_app_diagnostics_table.php`
   and a daily retention command; follow the linked diagnostics deployment notes.
   Do not run test suites, `migrate:fresh`, demo seeders, or unreviewed migrations
   against production.
4. Leave `FIREBASE_PROJECT_ID` and `FIREBASE_SERVICE_ACCOUNT_PATH` unconfigured.
   Verify existing media storage permissions and PHP/web-server upload limits
   accommodate the approximately 95 MB baseline APK.
5. As an authorized admin, open `/manage/app-updates`. Confirm the page loads and
   shows installations once a signed-in baseline app returns to the foreground.
6. Publish the verified APK with its actual version/build and release notes.
   Use minimum supported build `1` for the initial optional rollout; do not force
   upgrades before the installation flow is validated. Future builds must increase
   the build number and use the same package and signing certificate.

## Phone acceptance

- A signed-in baseline app reports agent, installation ID, version/build, model,
  OS version, and last-seen time without a Firebase token.
- Registration and release checks return a manifest with an HTTPS same-origin
  `/agent-api/agent-app/releases/{uuid}/download` URL.
- Anonymous APK download is rejected; the staff JWT downloads the exact bytes
  matching the manifest SHA-256.
- A newer-build APK is required to exercise an update from build 51; publishing
  build 51 will correctly show no update on a phone already using build 51.
- Confirm download progress, system installation confirmation, increased installed
  build, preserved login/recordings, and refreshed installation metadata.
- Employees on older Flutter builds without this update feature must first install
  the baseline APK once. Do not uninstall or clear data. Legacy native-app migration
  needs separate data-compatibility verification, even when the package name matches.

Keep additive release/installation tables on code rollback; do not delete employee
installation records or APK media to roll back the web release.