Entity: clientEmissionFactor

Entity Definition

• Entity Name: clientEmissionFactor
• Entity Type: Database table
• Description: Tier-2 client-level override for CO₂ emission factors. Structurally identical to the client scope of calorificValue but represents a separate domain — emission factors express the CO₂ equivalent emitted per unit of energy consumed (e.g. t CO₂/MWh). The three-tier resolution is: per-gauge individual → client override (this entity) → system default.

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_emission_factor_tenantId, type: btree	018fa51f-fda1-79f4-8461-2cb8f1cabc10
clientId	Client this override applies to	UUID	-	Yes	No	UUID v7	FK → client; must exist — see client	name: idx_client_emission_factor_clientId, type: btree	018fa51f-fda1-79f4-8461-2cb8f1cabc10
medium	Energy medium this factor applies to	String	-	Yes	No	See Enum - GaugeMedium	Must be a valid GaugeMedium string value	name: idx_client_emission_factor_clientId_medium_primarySource, type: btree (unique)	electricity
primarySource	Energy medium this factor applies to	Integer	-	Yes	No	See Enum - PrimarySource	Must be a valid PrimarySource integer value. Composite unique with (clientId, medium).	-	17
value	Emission factor value (CO₂ equivalent per unit of energy)	Float	-	Yes	No	-	Positive number	-	0.205
unitFrom	Source unit (energy unit)	Integer	-	Yes	No	See Enum - Unit	Must be a valid Unit integer value	-	2
unitTo	Target unit (CO₂ unit — typically t = 5)	Integer	-	Yes	No	See Enum - Unit	Must be a valid Unit integer value	-	5
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.	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: same copy/paste artefact as the migrated clientCalorificValue page — the source page's primarySource row Description reads "Energy medium this factor applies to", duplicating the medium row's description instead of describing the primary-source concept. Carried over verbatim.

Audited fields

Recorded on created (in full), updated (changed only) and deleted (in full): clientId, medium, primarySource, value, unitFrom, unitTo.

Excluded: none.

Structurally identical to clientCalorificValue — same natural-key caveat applies to clientId.

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