Entity: contract

Entity: contract

Description: An energy supply contract covering one or more gauges (via contractGauge), typically representing a joint/bulk purchase agreement negotiated centrally for a group of metering points, but equally valid for a single metering point with its own individual contract (N=1 is the common case — see the Migration Notes on the source Confluence page, id 523993090). Carries the supplier and unit prices for the contract's validity period; individual price components are stored on contractItem.

Entity Type: database table

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
medium	Commodity this contract covers.	string (enum)	-	Yes	No	enum — see Medium (source Confluence page; not yet migrated to the local enum catalog)	Must be one of the supported subset values	-	electricity
purchaseType	Whether this contract is an individual contract for a single metering point, or a joint/bulk purchase agreement covering a group.	string (enum)	individual	Yes	No	enum — see ContractPurchaseType (source Confluence page; not yet migrated to the local enum catalog)	Must be one of the listed values	-	individual
supplierId	The supplier for this contract.	UUID	-	Yes	No	UUID v7	Foreign Key: contractSupplier; must exist	-	018fa51f-fda3-7c63-b5a9-3fa33dc989de
validFrom	Start of the contract's validity period.	date	-	Yes	No	ISO 8601 — YYYY-MM-DD	Must be ≤ validTo	-	2026-01-01
validTo	End of the contract's validity period.	date	-	Yes	No	ISO 8601 — YYYY-MM-DD	Must be ≥ validFrom. For a given gauge + medium, validity periods of different contracts must not overlap (carried over from EM2 business rule)	-	2026-12-31
isManual	Whether this record was entered manually by a user (true) or created by an automated backfill/migration process (false). Kept for audit traceability of data origin, mirrors EM2's manual flag.	boolean	true	Yes	No	-	-	-	true
documentId	The uploaded contract document (PDF), if any.	UUID	-	No	No	UUID v7	Foreign Key: document; must exist if set	-	018fa51f-fda4-7e95-88e8-5f5675f0ddf8
createdAt	Timestamp of entity creation. Immutable.	timestamp with time zone	now()	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	2026-01-15T09:00:00Z
updatedAt	Timestamp of last entity update. Mutable.	timestamp with time zone	now()	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	2026-01-15T09:00:00Z
deletedAt	Timestamp of entity soft delete. 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	-	null
createdBy	Identifier of the author who created this record.	string	-	Yes	No	type:actor	-	-	user:c2d3f586-1c9a-4f5f-b9ae-45f2c4f69f7e
updatedBy	Identifier of the author who last updated this record.	string	-	Yes	No	type:actor	-	-	system:contract-backfill-v1

Audited fields

Recorded on created (in full), updated (changed only) and deleted (in full): medium, purchaseType, supplierId, validFrom, validTo, isManual, documentId.

Excluded:

• validityStatus — computed in SQL on every read from validFrom/validTo, never stored. It can flip from upcoming to active to expired with no write happening at all; auditing it would fabricate entries for the mere passage of time.

supplierName is not a column on this entity at all (it is joined from contractSupplier.name for display) and so is outside this derivation entirely; when supplierId changes, the resolved supplierName at that time is carried alongside it as a display value, not as an audited field of its own.

medium is create-only — absent from the update path entirely, so it never appears in an updated diff, only in a created entry.

Registered for entityName resolution — resolves to the contract's supplier name and validity range (e.g. "Acme Energy (2024-01-01 – 2024-12-31)"), composed at read time from contractSupplier.name and this entity's own validFrom/validTo — not a contract-number attribute, since none exists on this DAT (architecture 61-audit-log.md §7.4 in the code repo).