budget-app/Readme

110 lines
5.2 KiB
Text

# Budget workspace
```
budget-app/
├── Cargo.toml # virtual workspace, exactly two members
├── app/ # package budget: Makepad UI, resources, tests
├── budget-capture/ # native permissions, Java, offline OCR, tests
├── Readme
└── docs/
```
Budget is standalone, not a member or dependency of Nigig. Makepad paths are
centralized in root `Cargo.toml`; the expected checkout is `../rustdev/makepad`.
The application package remains `budget`, and Android identity remains
`org.nigig.oldmutualbudget`. Required Java lives in
`budget-capture/src/sys/android`. There are no Gradle projects or wrappers.
## Desktop
Tray → explicit per-capture consent → one frame → embedded offline OCR → editable
review → explicit durable confirmation. The tray and Capture tab do not create
purchases automatically. See [desktop workflow/platform limits](docs/DESKTOP_CAPTURE.md)
and [desktop validation](docs/DESKTOP_VALIDATION.md). Use the documented Makepad
revision/desktop patch (it fixes a Windows compilation blocker). HarmonyOS **PC** remains
blocked on its Huawei SDK; generic OHOS support is not a substitute.
```sh
cp docs/Cargo.lock Cargo.lock
cargo run --locked
```
Cargo creates generated `Cargo.lock`/`target` files; they are not authored root
folders. The versioned dependency lock is `docs/Cargo.lock`.
## Android: Cargo/Makepad only
Install `cargo-makepad` from the same Makepad checkout as the app. The existing
Makepad revision `2d732a5` has CLI compile errors; the narrow fix is supplied in
`docs/MAKEPAD_PACKAGER_COMPILE_FIX.patch` and applied to the local checkout. Apply
that patch if using the unfixed revision, before installing the tool. Then:
```sh
cargo install --path ../rustdev/makepad/tools/cargo_makepad --force
cargo makepad android install-toolchain
cargo makepad android run -p budget --release
```
The capture crate's build script compiles its Java with javac/D8. Makepad bundles
that `classes.dex` as an APK secondary DEX, visible to Android's system component
loader. The app's manifest template registers the tile, overlay, consent and share
activities. No patched APK, fake native library, Gradle host or AAR is involved.
Offline OCR uses Ocrs/RTen instead of ML Kit. Two models are downloaded **at build
time**, SHA-256 checked, then embedded in the native library. `curl` is required;
air-gapped builds can set `BUDGET_OCR_MODEL_DIR` to a directory containing the two
pinned `.onnx` files. Installed apps neither download models nor upload captures.
Models are CC BY-SA 4.0; attribution, original URLs and full terms ship under
`app/resources/licenses/` and attribution is displayed in the capture review.
The Makepad prerequisite patch also updates its compile platform to SDK 35,
required to encode Android 14's `specialUse` foreground-service type. Minimum
Android/API level remains 26 and target SDK remains 35; runtime API guards,
NDK is retained and build tools are updated to 35.0.1 to read SDK 35 resources. Reinstall the Makepad toolchain after
applying the patch. No numeric manifest workaround or patched resource table is used.
**Signing:** use your existing release signing key when distributing updates.
Preserving the package ID alone does not prove signing-certificate compatibility;
the tool's development signer must not replace your production certificate.
## Owner-local tests
```sh
cargo test --workspace --lib
cargo test -p budget --test models
cargo test -p budget-capture --test ocr
cargo test --release -p budget --test ui -- --test-threads=1
python3 -m unittest discover -s app/tests -p 'test_*.py'
python3 -m unittest discover -s budget-capture/tests -p 'test_*.py'
```
`app/tests/ui.rs` drives real app inputs/buttons with `makepad-test`, in isolated
user-data directories. It follows the current Makepad API and Nigig's package-local
UI/public-API test patterns; it does not require Studio and has no ignored tests.
Use a display or `xvfb-run -a` on headless Linux. Model integration tests use the
actual application library, not a duplicated nested Cargo workspace.
For a disposable Rust environment, full native launch, UI tests, Java extraction
tests, real OCR inference, and optional actual APK build/inspection:
```sh
FULL_ANDROID=1 bash app/tests/run-clean.sh
```
The runner needs Linux native Makepad development libraries, curl, JDK, Python 3.11+,
Xvfb/xauth and readelf. It removes its temporary toolchains/builds even on failure.
See `docs/GRADLE_FREE_VALIDATION.md` for measured results and remaining limits.
## Privacy and platform boundaries
Tile → movable floating button → fresh screen-sharing consent → one frame →
offline OCR → editable review → explicit confirmation/private inbox. Projection
stops before OCR; screenshots are not persisted. Share-to-Budget text/link review
is retained. Currency ambiguity, ZAR conversion and idempotent import rules remain.
No Internet permission, continuous monitoring or automatic financial actions.
A build or desktop UI test is not Android device validation. Permission prompts,
projection lifecycle, overlay dragging, OCR latency and signed-update data retention
still require an Android device. iOS cross-app overlays are unsupported; its Swift
imported-image OCR helper remains source-only.