# מרחב אנרגיה מאוחד

> תיעוד מקור. מקור: docs/product/unified-energy-workspace.md · 6a466bf.
> בגרסה הציבורית הושמטו מזהים תפעוליים ופרטי חשבון אישיים. קובץ המקור נשמר במאגר.

## Authorized change boundary

The customer request is to finish the mixed-energy product workflow on desktop
and mobile while preserving the approved interface. This slice adds the
`energy` workspace section, complete-period dashboard totals, CSV import,
review, pagination and export. Existing shell, layouts, visual tokens, approved
images, provider selections and charging discovery remain in place. Charging
history and comparison analytics keep their existing electricity-specific
meaning and link to the unified report.

No supplier integration, charging command, fuel authorization, collection or
tax invoice is activated by this release. Choosing a supplier is a preference;
importing its export is customer-provided evidence, not verification by it.

## Customer workflow

- All four account plans expose **הוצאות אנרגיה** to owners, administrators,
  fleet managers and finance members. Drivers cannot open the report or import.
- Choose a date period, supplier, energy kind and vehicle, including unassigned
  events. Electricity is measured in kWh; petrol, diesel and LPG are measured in
  litres. The report totals cover every matching event, not just the visible page.
- Download the UTF-8 CSV template. Its required columns are
  `external_reference,energy_kind,quantity,amount_ils,occurred_at`; optional
  columns are `vehicle_plate,vehicle_id,station_name`. Decimal quantities have
  up to three places and shekel amounts up to two. Dates must include an explicit
  UTC offset or `Z`. Examples and field guidance appear before confirmation.
- Select the supplier and preview every row. A file with invalid rows cannot
  start importing. References duplicated within the file are errors. Customers
  can explicitly choose to match a plate to exactly one known vehicle in their
  own account and review the assignment before importing. There is no fuzzy or
  cross-account matching. The server verifies ownership and any supplied plate
  before committing.
- Each request is bounded by both 100 records and 16,000 actual UTF-8 bytes.
  The UI shows processed, inserted and duplicate counts. A failed request can
  be retried with its original content; previously completed batches are kept.
  Re-uploading identical source references is idempotent. Changed evidence for
  an existing source reference is a conflict, never an overwrite.
- The report shows the evidence source and any differences between a platform
  session and its imported counterpart. The platform event counts once; the
  imported evidence remains available for inspection. This is a review state,
  not automatic settlement or certification of either source.
- CSV export traverses every report page. It includes source provenance and
  conflicting evidence and protects spreadsheet text cells from formulas. If
  traversal changes, fails, loops or is incomplete, no partial file is downloaded.

## API and database

`GET /api/platform/tenants/:tenantId/energy/report` accepts `from`, `to`,
`provider`, `kind`, `vehicle`, `limit` (1–500), and an opaque continuation cursor.
`vehicle=unassigned` selects events without a linked fleet vehicle. Defaults and
boundaries use the account timezone; both local midnight boundaries are converted
independently for daylight-saving transitions.

The additive `infra/energy/003_unified_energy_report.sql` RPC calculates source
reconciliation, filtered totals and a bounded page in one database statement.
Every call independently checks active account membership and an allowed role.
No direct browser table grants are added. The existing import and legacy list
endpoints retain their contracts.

The cursor binds the tenant, period, filters, source position, cutoff and content
fingerprint. A cutoff excludes newly arriving source records; a fingerprint detects
changes to included evidence. It is **not** a persisted MVCC snapshot. If evidence
changes (including a late transaction commit), the server returns
`409 REPORT_CHANGED` and the customer restarts the report/export.

## Bounded browser work

An import file is limited to 2 MB and 5,000 rows. Export is limited to 100,000
matching events; larger periods must be narrowed before downloading. These are
visible operation limits, not silent truncation of totals. Existing vehicle
selector lists may be capped at 1,000 loaded records and are labeled when partial.

Demonstration imports never call production APIs. They are stored separately by
demo account and member under the existing browser-data namespace, participate
in demo export/reset, and preserve idempotency, batch atomicity, role checks and
report traversal behavior. The demo allows up to 10,000 locally imported records.

## Acceptance gates

- Fixed-point CSV conversion, Hebrew/quoted fields, invalid files, batch byte
  bounds, safe resumable imports, formula protection and complete exports.
- More than 500 source records, stable pagination, complete totals, cross-period
  duplicate reconciliation, DST boundaries and source-change detection.
- Unauthorized, driver, cross-account and suspended membership access denied;
  existing table isolation and applied migrations preserved.
- Desktop/mobile import, preview, error, completion, filtering, export, account
  switching and driver navigation tested using synthetic data.
- Full hosted CI, additive migration, exact reviewed commit deployment and live
  smoke checks before announcing release.

Baseline for rollback: product deployment `[operational-id-redacted]`,
Git commit `6a5ddb06044e1a0f8390b733b64fc9aa05ae7d52`. The additive reporting RPC
can remain in place when rolling the application back; no existing table or
function is removed.

## Production release · 10 November 2026

- [PR #16](https://github.com/DigitalOps-Inc/LinkNodesEnergy/pull/16) merged as
  `519d3139f0d785f513207eda0e81909377de2532`. Its tree exactly matches the tested
  head: `416bc5be052f835dfb9432e5a514252e9162d1f0`.
- [CI run 42848355964](https://github.com/DigitalOps-Inc/LinkNodesEnergy/actions/runs/42848355964)
  passed all four jobs: check, database, browser and website. The browser suite
  includes desktop and 320/390-pixel energy import, preview, filtering, export,
  source conflict, account isolation and driver-denial scenarios.
- Supabase migration `20261110155824_lne_unified_energy_report_workspace` was
  applied to the LinkNodes Energy project. Read-only production checks confirmed
  the reviewed function body, valid indexes, private ledger grants, anonymous
  execution denial and authenticated execution denial without a JWT subject.
  Those checks used `BEGIN READ ONLY` and `ROLLBACK`, with no customer fixtures.
- Vercel deployment `[operational-id-redacted]` reached READY and was promoted
  to [product.linknodesenergy.com](https://product.linknodesenergy.com). The alias
  was verified to point to that exact deployment and commit.
- The live demo workspace showed the new navigation and report. A synthetic
  two-row Pazomat CSV was previewed and imported into browser-only demo storage.
  Filtering to Pazomat returned exactly those two rows, 74.25 litres and
  ILS 570.75, with the provider logo and unverified provenance. No production
  customer records, supplier commands or payments were created.

This releases the management/reporting UI. Actual supplier API connections,
charging commands, fuel authorization and payment processing remain separate
integrations and are not enabled by these screens.

![Production energy report with synthetic browser-only Pazomat transactions](/evidence/unified-energy-production.jpg)
