Entity: gaugeUsageAllocationItem

Entity Type: Database table

Description: One usage inside a gaugeUsageAllocation version: which usage, and — depending on the allocation's mode — its twelve monthly percentage shares (estimated), or the sub-gauge channels that measure it and whether it is the computed remainder (measured). A single allocation has exactly one item with neither. Items are immutable with their version: a change creates a new allocation version. Decided 1 Oct 2026 (R2: monthly shares are enough; D03: explicit 100 % without remainder in the estimated mode; O01: one remainder usage in the measured mode).

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	01960000-0000-7000-8000-000000000901
tenantId	Tenant that owns this record. Denormalised from the allocation.	UUID	-	Yes	No	UUID v7	Foreign Key → tenant; must equal the parent allocation's tenantId.	name: idx_gaugeUsageAllocationItem_tenantId, type: btree	01960000-0000-7000-8000-000000000099
allocationId	The allocation version this item belongs to.	UUID	-	Yes	No	UUID v7	Foreign Key → gaugeUsageAllocation; must exist.	name: idx_gaugeUsageAllocationItem_allocationId, type: btree	01960000-0000-7000-8000-000000000801
usageTypeId	The usage.	UUID	-	Yes	No	UUID v7	Foreign Key → usageType; must be active at write time and allowed for the channel's medium and purpose (N01, N09); unique within one allocation (N04).	name: idx_gaugeUsageAllocationItem_allocation_usage, type: btree (unique composite allocationId, usageTypeId)	01960000-0000-7000-8000-000000000702
shares	Twelve percentages January → December, estimated mode only.	Array of Decimal(5,2)	null	No (required when mode = estimated)	No	[85, 85, 80, 60, 30, 10, 10, 10, 30, 70, 80, 85]	Exactly 12 values, each 0–100; across the allocation's items every month sums to exactly 100.00 (D03). Null in the other modes.	-	[85,85,80,60,30,10,10,10,30,70,80,85]
sourceGaugeIds	Sub-gauge channels whose daily consumption measures this usage, measured mode only.	Array of UUID	null	No (required when mode = measured and isRemainder = false)	No	UUID v7	Each must be a channel of the same medium inside the parent's balance boundary (sub-gauge of the parent, or of its sub-gauges), not the parent channel itself, and not overlapping another item's branch (D04, UC-13). Several non-overlapping sources are summed. Null in the other modes.	-	["01960000-0000-7000-8000-000000000031"]
isRemainder	measured mode: this usage receives parent − Σ measured parts (O01).	Boolean	false	Yes	No	-	Exactly one item per measured allocation has true; always false in single and estimated (no remainder in the estimated mode — D03).	-	true
sortOrder	Order of items in the modal and reports.	Integer	0	Yes	No	-	-	-	1
createdAt	Timestamp of entity creation. Immutable.	Timestamp with time zone	Set in code	Yes	No	ISO 8601	-	-	2026-10-05T10:00:00Z
createdBy	Identifier of the actor who created this record.	String	-	Yes	No	type:actor	-	-	user:01960000-0000-7000-8000-000000000099

Notes

• Arithmetic at read time (variant C): estimated → daily consumption × shares[month of the day] / 100; measured → source items take the sum of their sources' daily aggregates, the remainder item takes the parent's daily aggregate minus that sum; single → the whole daily aggregate. Days are computed unrounded and summed before rounding (acceptance condition 5 of the variant C use cases).
• Quality flag travels with the result: a source channel may itself be estimated, so "measured" means "taken from a sub-gauge", not "metrologically exact"; the read model reports method, completeness and the allocation version it used.
• Migration (M8): EM2 gauge_consumption_usage_combi rows become shares; where EM2 left a month implicit, the remainder goes to heating so the month sums to 100 %; the migration report lists channels whose EM2 shares do not sum to 100 for the client to confirm.