budget-app/docs/IMPLEMENTATION.md

4.7 KiB

Historical revision record. For the current Cargo-only pipeline and test locations, see Readme, TESTING.md and GRADLE_FREE_VALIDATION.md.

Implementation handoff

Delivered source

Branch: main. The temporary feature branch was retired after integration.

  • budget-app/src/history.rs: inclusive period validation, saved non-overlapping budget snapshots, monthly grouping, separate income/expenses, complete-period coverage checks.
  • budget-app/src/sheet.rs: lossless, deterministic versioned JSON snapshots; reconstructs formula dependencies by loading raw inputs. Legacy workbook parser length-overflow guard.
  • budget-app/src/persistence.rs: changed-state deduplication, temp-write/sync/rename, fail-closed load on corrupt state.
  • budget-app/src/products.rs: validated confirmed product quotes, checked minor-unit arithmetic, ZAR currency enforcement, import-ID deduplication, planned expense allocation without creating payments.
  • budget-app/src/app.rs, budget-app/src/view.rs: History screen source, period capture/report actions, startup restore, model-refresh autosave, confirmed-share inbox import.
  • budget-app/src/budget.rs: real Gregorian date validation.
  • budget-capture/src/sys/android/: explicit share receiver and review screen; its Android library owns the restricted component manifest.
  • tools/: guarded Makepad Java packaging hook and equivalent patch.
  • core-tests/: independent harness testing production model sources without UI dependencies.

Reference implementation review

Read these paths in andodeki/nigig-org:

  • crates/nigig-core/src/shared/persistence.rs: serde JSON state, app-data directory, explicit load/save errors.
  • crates/nigig-core/src/dir.rs: app-data directory abstraction.
  • crates/apps/spreadsheet/spreadsheet-engine/src/persistence.rs: workbook containers, legacy import paths, filename validation.

Adapted app-private, versioned JSON persistence rather than importing the large nigig workspace. Improved direct file truncation to synced temporary-file replacement, and rejected corrupt state rather than silently treating it as an empty budget. Avoided the spreadsheet reference's build-manifest-relative generated directory, which is unsuitable for installed Android apps.

Validation actually performed

  • cargo test --manifest-path app/tests/core-tests/Cargo.toml: 93 passed, including existing formula/sheet tests and new calendar, snapshots, history coverage, products and corruption tests.
  • ShareToBudget.java: javac compile using Android API and JSON stubs passed. This is a source/API check, not device execution.
  • Packager hook: applied to inspected fork source, verified second invocation is idempotent, captured resulting diff, restored fork source unchanged.
  • git diff --check: passed.
  • Follow-up: native cargo +1.97.1 check passes with Makepad integration candidate 25e742949dada71af6899ea1c32b25f1e82b3935, after adapting the theme accessor to makepad_wm_theme::current. The default public fork remains the wrong dependency checkout.

Not completed / not claimed

  • No desktop UI runtime validation, Android APK build, emulator test or installed-device test.
  • No background screen scraping, OCR, overlay, notification-tray control or Quick Settings tile. User selected the Android share workflow.
  • No automatic website fetch or FX conversion; shared title/link are prefilled, financial fields require review and entry.
  • Branch policy: budget-app and nigig-org changes are integrated into their existing main branches. Temporary feature/migration branches are retired. Makepad uses its pre-existing dev/work and nigig integration branches; the original histories were exported to makepad-original-histories.bundle before deleting the temporary backup refs. Full latest-work integration is still pending.
  • No encryption-at-rest, multi-process write coordination or database migration from external nigig stores.

Suggested acceptance checks after supplying compatible Makepad

  1. Save a January budget, add payments on Jan 1, Jan 31 and Feb 1. January report includes only the first two.
  2. Change the planner for February. January's saved budget stays unchanged; overlapping snapshots fail clearly.
  3. Restart after edits; formulas, currency formatting, column widths and all sheets survive.
  4. Corrupt a copy of the state file; app reports restore failure and does not overwrite it.
  5. Share a shopping product in cold and warm app states. Cancel creates nothing. Confirmed import adds one product and planned expense, never a payment.
  6. Replay the same queued product ID; no duplicate allocation. Simulate disk failure before acknowledgment; queued item remains for retry.
  7. Verify failure paths, narrow-screen History scrolling, input focus and app lifecycle flushing on real Android devices.