Entity: contractItem

Entity: contractItem

Description: A single priced line item within a contract — e.g. "high tariff rate C02d" or "vodné" (water rate). Links a contract to a contractItemType (what is being priced) and a contractItemRate (in what unit), together with the negotiated price. A contract typically has multiple contractItem rows (one per priced component).

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. Denormalised from contract.tenantId for defence-in-depth query scoping.	UUID	-	Yes	No	UUID v7	Foreign Key: tenant; must match the tenantId of the parent contract	-	018fa51f-fda1-79f4-8461-2cb8f1cabc10
contractId	The contract this priced item belongs to.	UUID	-	Yes	No	UUID v7	Foreign Key: contract; must exist	-	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
contractItemTypeId	What is being priced (e.g. a specific distribution tariff rate, vodné, stočné, paušální poplatek).	UUID	-	Yes	No	UUID v7	Foreign Key: contractItemType; must exist. The (contractItemTypeId, contractItemRateId) pair must exist in contractItemAllowedTypeRate	-	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
contractItemRateId	The unit this price is expressed in (e.g. Kč/MWh, Kč/m³).	UUID	-	Yes	No	UUID v7	Foreign Key: contractItemRate; must exist	-	018ed0b3-c298-7c7a-96d5-8b36f5a7f8d2
price	The negotiated unit price.	decimal	-	Yes	No	2 decimal places	Must be ≥ 0	-	2450.00
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

Note — indexing. No secondary indexes beyond the primary key are defined. At current scale (~90 tenants, ~15,000 gauges, a contract typically has a handful of line items) a sequential scan filtered by tenantId/contractId/contractItemTypeId/contractItemRateId is not a performance concern. Revisit if data volume or query patterns change materially.

Audited fields

Recorded on created (in full), updated (changed only) and deleted (in full): contractId, price, contractItemTypeId, contractItemRateId.

Excluded: none.

No Zod validation map exists yet for this entity (its shape lives only as a repository-port type) — the recorded set above is hand-listed rather than formula-derived until one is created. Row ids are stable across a contract's saves (a payload item carrying an id updates that row; one without inserts a new row), so an item's entries share one id for its whole life. Every entry files with subjectEntityType = contract / subjectEntityId = contract.id — it does not self-subject.

Not registered for entityName resolution, and has no independent human-readable attribute to register — identified by its contractId/contractItemTypeId/contractItemRateId combination.