budget-app/docs/IMPLEMENTATION.md

53 lines
4.7 KiB
Markdown

> 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.