Entity: buildingCalculatedConsumption

Entity Type: Database table

Description: Versioned, append-only record of a building's calculated (predicted/target) consumption or production, broken down by usage type. This entity does not use updatedAt/updatedBy/deletedAt — a revision is written as a brand-new row with its own validFrom; existing rows are never edited or removed in order to keep every historical value auditable. Production data (e.g. FVE) uses the same structure as consumption, distinguished only by usageType = production. For versioning/correction behaviour (how partial corrections to already-entered periods are resolved), see buildingCalculatedConsumption versioning.

Data Attributes Table

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key of the entity	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	Foreign Key → tenant; must exist	-	018fa51f-fda1-79f4-8461-2cb8f1cabc10
buildingId	The building this calculated value belongs to.	UUID	-	Yes	No	UUID v7	Foreign Key → building; must exist	-	b2c3d4e5-…
usageType	What the value represents.	String (enum)	-	Yes	No	enum	Must be one of the enum values	-	heating
periodStart	Start of the period this value covers (inclusive).	Date	-	Yes	No	YYYY-MM-DD	Must be ≤ periodEnd	-	2026-01-01
periodEnd	End of the period this value covers (inclusive).	Date	-	Yes	No	YYYY-MM-DD	Must be ≥ periodStart	-	2026-01-31
value	The calculated consumption or production value for this period and usageType.	Decimal	-	Yes	No	decimal(12,2)	-	-	405.00
source	Who/what produced this value — an auditor's calculation, or a user snapshot.	String (enum)	-	Yes	No	enum	Must be one of the enum values	-	userSnapshot
snapshotSourcePeriodFrom	When source = userSnapshot: the beginning of the period of the normalised-consumption average. When source = auditor → null.	Date	null	No	No	YYYY-MM-DD	Required (non-null) when source = userSnapshot; must be null when source = auditor	-	2023-01-01
snapshotSourcePeriodTo	When source = userSnapshot: the end of the period of the normalised-consumption average. When source = auditor → null.	Date	null	No	No	YYYY-MM-DD	Required (non-null) when source = userSnapshot; must be ≥ snapshotSourcePeriodFrom; must be null when source = auditor	-	2025-12-31
validFrom	The date from which this record is the current value for its buildingId/usageType/period combination.	Date	-	Yes	No	YYYY-MM-DD	Must not be in the future	-	2026-07-30
legacyId	Legacy-system identifier; migration provenance.	String	null	No	No	-	-	UNIQUE (tenantId, legacySource, legacyId) WHERE legacyId IS NOT NULL	9931
legacySource	Which legacy table this record was migrated from.	String (enum)	null	No	No	enum: calculated_consumption, calculated_consumption_months	Must be one of the listed values, or null	(composite with legacyId above)	calculated_consumption
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	-	2026-07-30T11:00:00Z
createdBy	Identifier of the actor who created the record (user ID or system actor).	String	-	Yes	No	type:actor — e.g. user:uuid or system:migration	Non-empty	-	user:018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2

Note: this entity intentionally omits updatedAt, updatedBy and deletedAt from the standard trailing audit set — see Description above (append-only versioning via validFrom/createdAt).

Audited fields

Recorded on created (in full) only — this entity has no update or delete path (see Description): buildingId, usageType, value, periodStart, periodEnd, source, validFrom, snapshotSourcePeriodFrom, snapshotSourcePeriodTo, legacyId, legacySource.

Excluded: none.

Not registered for entityName resolution, and has no independent human-readable attribute to register — identified by its buildingId/usageType/period combination.