Entity: clientTolerance

Entity Definition

• Entity Name: clientTolerance

• Entity Type: Database table

• Description: Stores per-client overrides to the system-wide consumption tolerance bands. A row exists only when the client has explicitly overridden the default (±20%). The lookup key is the combination of clientId, medium and primarySource. When no matching row exists, the system falls back to the hardcoded defaults.

  The same toleranceMin / toleranceMax values are used in two contexts: (1) validating manually entered reading values, and (2) detecting anomalous consumption in automated readings. The UI presents these as two separate sections on the Tolerances tab, but both read from this single entity. The UI slider is capped at ±25%.

  Invoice validation tolerances are not covered by this entity — they are out of scope for v1.

Data Attributes Table

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key	UUID	Generated in code (app layer)	Yes	Yes	UUID v7	-	Primary Key	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
tenantId	Tenant this record belongs to.	UUID	-	Yes	No	UUID v7	FK → tenant; must exist	name: idx_client_tolerance_tenantId, type: btree	018fa51f-fda1-79f4-8461-2cb8f1cabc10
clientId	Client this tolerance override applies to	UUID	-	Yes	No	UUID v7	FK → client; must exist — see client	name: idx_client_tolerance_clientId, type: btree	018fa51f-fda1-79f4-8461-2cb8f1cabc10
medium	Energy medium this tolerance applies to	String	-	Yes	No	See Enum - GaugeMedium	Must be a valid GaugeMedium string value. Composite unique with (clientId, primarySource).	name: idx_client_tolerance_clientId_medium_primarySource, type: btree (unique)	electricity
primarySource	Energy medium this tolerance applies to. Null means the override applies to all sources of the medium.	Integer	-	No	No	See Enum - PrimarySource	Nullable; must be a valid PrimarySource integer value if set	-	17
toleranceMin	Lower tolerance bound as a percentage deviation (negative value). Used for both manual reading validation and consumption anomaly detection. System default: −20. UI slider limit: −25.	Integer	-	Yes	No	-	Negative integer; range −25 to −1	-	-20
toleranceMax	Upper tolerance bound as a percentage deviation (positive value). Used for both manual reading validation and consumption anomaly detection. System default: +20. UI slider limit: +25.	Integer	-	Yes	No	-	Positive integer; range 1 to 25	-	20
createdAt	Timestamp of when the record was created. Immutable after insert.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Cannot be null; cannot be modified after creation	-	2025-03-16T18:00:00Z
updatedAt	Timestamp of the last update to the record.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Cannot be null	-	2025-03-16T18:00:00Z
deletedAt	Timestamp of soft deletion. Null means active. Once set, immutable.	Timestamp with time zone	-	No	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Immutable once set. Active records: WHERE deletedAt IS NULL	-	2025-06-01T09:00:00Z
createdBy	Identifier of the actor who created the record	String	-	Yes	No	type:actor	Non-empty	-	user:018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
updatedBy	Identifier of the actor who last updated the record	String	-	Yes	No	type:actor	Non-empty	-	user:018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2

Note: the source page states primarySource is "nullable" and describes the unique constraint as composite (clientId, medium, primarySource) — reflected in the index name — but the medium row's Validations text says "Composite unique with (clientId, primarySource)", omitting medium itself from that phrase (self-referential omission, likely just imprecise wording rather than a real conflict, since the index name lists all three columns). Carried over verbatim; flagging in case the source wording should be tightened.

Audited fields

Recorded on created (in full), updated (changed only) and deleted (in full): clientId, medium, primarySource, toleranceMin, toleranceMax.

Excluded: none.

A missing row is a valid, meaningful state (the system falls back to hardcoded defaults) — its absence is not itself an audited fact, only the creation, change or removal of an explicit override row is.

Not registered for entityName resolution, and has no independent human-readable attribute to register — identified by its clientId/medium/primarySource scope.