budget-app/docs/ANDROID_CAPTURE.md

59 lines
3.6 KiB
Markdown

# Android capture — Cargo/Makepad backend
Build/run: `cargo makepad android run -p budget --release`.
Java belongs to `budget-capture/src/sys/android`, not an Android/Gradle project.
The capture build script emits `OUT_DIR/classes.dex`; Makepad adds it as a normal
APK secondary DEX. The application manifest lives at
`app/resources/android/AndroidManifest.xml.template`.
## Flow and trust boundaries
1. User adds and taps the Add to Budget Quick Settings tile.
2. Native permission authority explains capture and requests overlay/notification
permissions as appropriate. Requests are not treated as permission grants.
3. A draggable, dismissible overlay button appears with a stop notification.
4. Each capture requests a new Android MediaProjection grant. Grants are not
persisted or reused after process death; service is START_NOT_STICKY.
5. One frame is acquired; projection is stopped before OCR starts.
6. A worker calls Rust Ocrs/RTen through the APK's exported JNI entry. Verified
pretrained models are embedded, so there is no model-download/network service.
7. A generation/destroyed guard rejects stale results. Bitmap resources are
recycled, and raw screenshot/OCR text is not persisted.
8. User reviews suggestions, corrects the product/title/price/currency, then opens
ShareToBudget review. Nothing is added without explicit confirmation.
9. Confirmed private-inbox entries retain UUID/idempotence and ZAR/foreign-currency
safeguards. Link/text Share-to-Budget remains available independently of OCR.
## Packaging compatibility
- App ID: `org.nigig.oldmutualbudget`; native classes retain
`org.nigig.budgetshare` identifiers.
- No Internet permission or accessibility service.
- Compile platform SDK 35 is required for the symbolic `specialUse|mediaProjection`
flags. The included Makepad patch updates that platform without raising minimum
Android API 26, changing target SDK 35, or replacing the NDK. Matching build tools 35.0.1 read the SDK 35 resource table.
- API 34+ tile launch uses the required PendingIntent overload; older Android uses
the original Intent overload, guarded by runtime version checks.
- Update packages must use the existing release signing certificate. The development
signer is not a production update strategy; data/certificate compatibility needs
an actual signed-update test.
- OCR model attribution/CC BY-SA 4.0 terms ship as application resources and appear
in the capture result panel. The model licence does not change the engine licence.
## Required device acceptance tests (not replaced by desktop tests)
- Android 13 and Android 14/15: tile registration, unlock behavior and overlay
grant/deny/revoke; notification denial; stop from bubble and notification.
- Fresh consent on every capture; cancel, timeout, screen-off, app/process death;
no resurrected projection token or stale result panel.
- Drag on portrait/landscape displays; status/navigation inset and keyboard behavior.
- Known product text, multiple prices, ambiguous $, foreign currencies, protected
windows, blank screens and OCR failure; confirm all suggestions remain editable.
- Capture launched before opening the Makepad activity; JNI library/class loading.
- Share text/link; explicit confirmation; replayed inbox item; restart and restore;
no automatic purchase/payment or duplicate planned entry.
- Install update signed with the existing key over an existing data-bearing app.
Desktop UI tests drive real Budget widgets, not these Android OS interactions.
APK inspection proves packaged components/DEX/JNI/models, not device execution.
iOS cross-app overlays remain unsupported; Swift imported-image OCR is unwired.