RBE Utilities MVP — Developer & Ops Guide
========================================

Overview
--------
Unified landlord–tenant utilities management MVP. PHP (no external frameworks), MySQL persistence, modular backend, fetch‑based frontend.

Key Paths
---------
- Core: `core/db_connect.php`, `core/auth.php`, `core/functions.php`
- Billing: `modules/billing/` (frontend + backend)
- Reports: `modules/reports/reports.php`
- Wallet: `modules/wallet/` (hub + settings API/UI)
- Dashboards: `modules/dashboard/*` wrappers for existing pages
- Cron: `cron/` (Flecto/Water sync, `purge_report_archives.php`)

Database (configure via core/config.php)
---------------------------
- Users/Roles: `rbe_users`, `rbe_roles`
- Meters: `smart_meters`, `flecto_meters`, `water_meters`
- Readings: `smart_meter_readings`, `flecto_meter_readings`, `water_meter_readings`
- Billing config: `billing_settings`, `billing_settings_history`, `billing_tiers`, `billing_fee_modes`, `extra_fees`
- Wallet: `tenant_wallet_deposits`, `wallet_transactions`, `landlord_wallet_payouts`
- Mapping: `tenant_landlord_map`, `properties` (with `square_meters`)
- Reports archive: `report_archives` (CSV payloads retained)

Core Helpers
------------
- `core/auth.php` — session + role helpers: `require_login()`, `current_user_role()`, `landlord_scope_id()`
- `core/functions.php`
  - `calculate_tiered_cost(amount, tiers)` — block‐tier billing
  - `distribute_fee(pdo, landlord_id, amount, mode, property_id=null)` — modes: `flat|equal|proportional` (sqm)

Billing Module
--------------
UI: `modules/billing/billing.php` + `billing-front.php` + `billing.js`
API: `modules/billing/billing-back.php` actions
- `get_tenants` — tenants under landlord
- `get_properties` — landlord properties (id, property_number)
- `get_fees` / `save_fee` / `delete_fee` — manage extra fees
- `get_tiers` / `get_tier` / `save_tiers` / `delete_tier` — tier CRUD
- `get_fee_modes` / `save_fee_modes` — fee distribution modes
- `get_settings` / `save_settings` — live settings; versions archived to `billing_settings_history`
- `get_history` — settings history (latest 50)
- `preview_distribution` — preview allocation for amount + mode (optional property)

Reports Module
--------------
`modules/reports/reports.php`
- Role-aware filters (admin/landlord/tenant)
- Pulls IAMMETER, Flecto, Water; applies tiered costs
- CSV export and archive to `report_archives`

Wallet Module
-------------
Hub: `modules/wallet/wallet.php` (role‑aware routing)
Settings UI: `modules/wallet/wallet-front.php`
API: `modules/wallet/wallet-back.php`
- `get_wallet_settings` — landlord toggle + per‑tenant flags
- `save_wallet_settings` — persist toggles
Landlord/Tenant flows reuse existing pages under `wallet/`.

Cron
----
- Data syncs (existing): `cron/flecto_electric_sync.php`, `cron/water_meter_sync.php`
- Retention: `cron/purge_report_archives.php` — deletes `report_archives` older than `global_settings.report_retention_years` (default 5)

Testing Walkthrough
-------------------
1) Login as admin
- Navigate to `/admin-dashboard.php` → use sidebar or quick links

2) Billing setup
- Open `/modules/billing/billing.php`
- For admin, choose a landlord
- Tiers tab: create electricity and water tiers
- Modes tab: set `sewage/refuse/rates/other` to `flat|equal|proportional`
- Modes tab: use “Preview Distribution” to sanity check allocations
- Settings tab: enter global fees; use “Preview Settings” to estimate per‑tenant lines; then Save

3) Reports
- Open `/modules/reports/reports.php`
- Filter by landlord/property/date; verify usage and cost
- Export CSV; confirm row appears in `report_archives`

4) Wallet
- Open `/modules/wallet/wallet.php`
- Admin sees Wallet Settings UI; toggle global/per‑tenant
- Landlord sees wallet cards; tenant sees deposit screen

5) Invoicing
- Use `print_invoice.php?tenant_id=...&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD`
- Verify “Fee Distribution Legend” and that fees align with modes/settings

Notes
-----
- IAMMETER/Flecto data expected to be present from cron ingests
- `properties.square_meters` enables `proportional` fee mode; missing/zero falls back to equal split
- All new module routes use absolute links so they work from any depth

