# התאמת יבוא וסתירות

> תיעוד מקור. מקור: docs/product/energy-import-conflict-recovery.md · 6a466bf.

## Purpose and boundary

A supplier file can be syntactically valid while one of its source references
already exists with different evidence. The import remains atomic per batch and
refuses to replace the stored transaction. This change identifies the submitted
reference and CSV row that require review, so the customer can recover without
guessing among the records in the failed batch.

The approved workspace shell, pricing, existing analytics, assets, supplier
connections and payment behavior are unchanged. Charging history gains a link
to the complete energy report for the same roles already allowed to read it.

## Error contract and tenant boundary

The additive `infra/energy/004_energy_import_conflict_details.sql` replaces only
the existing `lne_energy_import(uuid,text,jsonb)` function. It preserves its
membership check, private-table access, matching rules, transaction semantics,
idempotency and grants. No previously applied SQL file is edited.

On an immutable source conflict, PostgreSQL still raises `PT409` with message
`LNE_ENERGY_SOURCE_CONFLICT`. Its detail contains only:

```json
{"external_reference":"submitted-reference","record_index":2}
```

`record_index` is one-based within the failed request batch. Authorization occurs
before inspecting any record. No stored amount, plate, vehicle, station or other
account identity is returned. The API accepts this strict shape only when both
fields match the current submitted batch, then returns it as `error.conflict`.
Malformed, unexpected or missing details are discarded; the generic safe
`SOURCE_CONFLICT` error remains available for older RPC versions.

The browser validates the shape and matches it again to its failed batch. It
marks the corresponding preview row, switches to the error-only view and shows
the original CSV line number. Duplicate references inside a file are still
rejected before importing, so this mapping is unambiguous even for quoted
multiline CSV cells.

## Customer recovery

The UI explains that the failed batch was not saved, previously confirmed
batches remain saved, and the existing conflicting transaction was not changed.
It asks the customer to compare the supplier source, correct an erroneous file,
or contact support if the stored transaction needs correction. It explicitly
discourages inventing a new reference to bypass the conflict.

Choosing a new file clears the prior conflict marker. Re-importing corrected
evidence retains the existing duplicate protection. The browser-only demo uses
the same detail shape, review behavior and batch rollback rules.

## Validation and release gate

Focused unit/API/demo tests cover validated error transport, unknown or malformed
detail suppression, revoked access, cross-account source identities, unchanged
stored evidence, whole-batch rollback and corrected replay. SQL regressions run
the actual RPC with isolated identities and assert that access denials disclose
no conflict detail. Browser regressions exercise a conflict beyond the first
preview page at 390 px, exact row visibility, failed-batch rollback, corrected
replay, and the role-gated charging-history link.

Before production, require the full hosted CI including isolated PostgreSQL 17
and browser tests. Apply the additive SQL to the intended project, verify the
function definition and grants, then deploy the reviewed application commit.
The application remains compatible with the earlier RPC (generic error only),
and older application releases safely ignore the additional database detail.
An application rollback does not require deleting records or reversing SQL.

## Reference

PostgREST forwards PostgreSQL `DETAIL` as the error `details` field and supports
custom HTTP status codes through `PTxyz` SQLSTATE values:
[PostgREST custom errors](https://docs.postgrest.org/en/v14/references/errors.html#custom-errors).
