Documentation

Appearance

Updated Sep 11, 2026 by Barča Dvořáková · Owner: analysisactivefeatureconfluence-migration Edit on GitHub

Consumption Normalisation ​

Business Context ​

Raw consumption figures across buildings are not directly comparable — a cold winter drives heating consumption up regardless of how efficiently a building is managed. Consumption normalisation adjusts measured figures to what they would have been under standard climate conditions, making year-on-year and building-to-building comparisons meaningful.

Business-Level Definition ​

Consumption normalisation applies a climate-based correction to raw consumption data at the building level, so that year-on-year and building-to-building comparisons are not distorted by weather. The correction is derived from outdoor temperature data (degree-days) provided by the linked WeatherStation, combined with the building's reference internal temperature.

Two distinct adjustments are involved, with two distinct lifecycles:

  • Gauge coefficient — a per-gauge multiplier for unit conversion (e.g. m³ of gas → kWh, litres of fuel → kWh). Applied once, at write time, before the building total consumption figure is written. Versioned (validFrom) so historical figures remain correct after a change. Defined in Gauge Management.
  • Climate correction (building-level) — not applied at write time and not stored. It is computed on demand, at read time, from climateData + climateNormal + the building's temperatureReference (see the WeatherStation Management formula), whenever normalised consumption is requested — in reports, charts, or a one-off calculated-consumption snapshot action. Because the underlying climate data and normals can be corrected retroactively, the normalised figure for a given past period can change between two queries of the same period. This is expected behaviour, not a bug.

Requirements Definition ​

  • Each building can be linked to a WeatherStation as its climate data source
  • Climate data or climate normal corrections are reflected immediately in subsequent normalised-consumption queries — no recalculation job is needed, since nothing is materialised
  • Normalised consumption is available alongside raw consumption in all charts and reports
  • The system supports degree-day normalisation using actual outdoor temperature data from the linked WeatherStation

Acceptance Criteria ​

Pending — to be defined during detailed feature design. Acceptance criteria will be added once the detailed design of this feature is completed. The criteria must cover: WeatherStation linking, the read-time normalisation calculation itself, behaviour when climate data is missing, and display of normalised vs. raw consumption in charts and reports.

N/A — not available in the source material.

Technical Context ​

User Stories / Use Cases ​

Placeholder — to be completed. Use cases will be defined during detailed feature design. Expected scenarios: linking a building to a WeatherStation, viewing normalised vs. raw consumption in reports/charts, and using normalised consumption as the source for a one-off calculated-consumption snapshot.

UI/UX Design ​

Pending UI/UX review. UI/UX design has not been completed. Visual and interaction design will be added once wireframes are approved.

Functional Requirements ​

Placeholder — to be completed. Functional requirements will be defined during detailed feature design. Key areas to cover: the degree-day calculation method (see WeatherStation Management for the formula), how manual override (if retained — see buildingCoefficient) interacts with the read-time calculation, and handling of periods without climate data.

Non-Functional Requirements ​

Placeholder — to be completed. Non-functional requirements will be defined during detailed feature design. Key areas: performance of the read-time normalisation calculation at query volume (reports, dashboards), and caching strategy if repeated queries for the same period become a bottleneck.

API Analysis ​

Placeholder — to be completed. API endpoints will be defined during detailed feature design.

Domain Model (ER diagram) & Data Attribute Table ​

No ER diagram in source material. Entity status (Confluence entity pages, not yet migrated into this repo's Entity DAT catalog):

  • buildingCoefficient — status under review. This entity was originally modelled as a stored, versioned climate coefficient, but following the decision that climate correction is computed at read time (and not stored), it likely needs to be either removed or narrowed to manual-override use only. This is an open design question, not yet resolved — flagged here rather than decided in this migration pass.

Related entities (defined in their respective feature pages):

  • building — building.climateStationId links the building to its WeatherStation
  • buildingParameter — buildingParameter.temperatureReference is the reference internal temperature used in degree-day calculation
  • climateData (WeatherStation sensor readings) — to be defined under a future Data Collection domain, not yet in this repo

Data ​

To be defined during detailed feature design.

Test Data ​

N/A — not covered in source material; no Test Data location was specified in the source page.

Logging ​

To be defined during detailed feature design.

Monitoring ​

N/A — not covered in source material.

Caching ​

N/A — not covered in source material.

Backward Compatibility and Migration ​

Placeholder — to be completed. The legacy system stored normalised consumption figures as part of the building energy management data (hospodaření s energií). The migration mapping from legacy fields to the new coefficient model will be defined during detailed feature design.

N/A — not addressed in the source Confluence page; migrated as a reference copy without new legal analysis.

Cybersecurity Considerations ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new security analysis.

Risk Assessment ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new risk analysis.

Auditing, Reporting & Measurement ​

N/A — not addressed in the source Confluence page; migrated as a reference copy without new analysis.

Note on this document's completeness: Unlike the other migrated feature pages, the Confluence source for this feature was itself explicitly a work-in-progress (multiple sections marked "Placeholder — to be completed" or "Pending" in the source). This migration preserves that incomplete state faithfully rather than filling gaps — the placeholders above are not migration artifacts, they reflect the true state of the source at the time of this pass.