Reading Management

Business Context

Business-Level Definition

Readings are the raw material of every consumption and cost figure the product shows. Reading Management is where a user records a meter reading by hand, sees every reading of a gauge — the ones entered by people and the ones delivered by a datalogger — corrects a wrong one, and exports them.

A reading is what someone saw on the meter at one moment: several registers at once (high and low tariff, supply and feed-in), a note about the circumstances and, when available, a photo of the display as proof. The product keeps it together as one reading, not as unrelated numbers — see Odečet in the glossary.

Requirements Definition

Consumption is derived from the difference between readings, so one wrong value distorts two periods and every report built on them. The product therefore has to make a wrong value hard to enter, easy to notice and safe to correct: it warns while the value is being typed, asks why when a value goes backwards, keeps the evidence with the reading, and records every change with the value before and after.

Customers also need to check what the datalogger delivered against what was read by hand, which is why manual and remote readings are shown side by side in one place, and exported in the same way as every other overview.

Technical Context

User Stories / Use Cases

• As an energy manager, I want to enter all registers of a meter read at one moment in one form, so the reading is stored as one event.
• As an energy manager, I want to see the consumption since the previous reading while I type, so I notice a typo before I save.
• As an energy manager, I want to be asked why when a value is lower than the previous one, so a typo and a meter replacement are each handled correctly.
• As an energy manager, I want to attach a photo of the meter and write a note, so the reading can be checked later.
• As an energy manager, I want to switch the overview between manual and remote readings and export either.
• As a tenant administrator, I want to correct or delete a wrong reading, with the change recorded.
• As anyone reading a gauge, I want to open a reading and see its note, documents and every change made to it.

UI/UX Design

The Readings tab of a gauge detail. Screens: design/ — every artboard of the design canvas Odečty — obrazovky as a page that renders on its own, with the canvas sources.

State	What is shown
At least one parameter of the gauge is read by hand (Ruční or Oba)	Form Nový odečet: date and time (both required), one group of fields per such parameter headed Odečet (parameter name) — one field per series the parameter has at the entered moment, each with the unit of its manual source — with the last value and the resulting consumption under each field; note; documents Z dokumentů / Z počítače; button Výměna měřidla. Parameters read only remotely are not in the form, but are in the overview
No parameter is read by hand (Dálkový only)	Instead of the form, a notice that readings come only from the datalogger and where the reading method is changed; the last remote value; no Výměna měřidla button
Gauge has a datalogger	Card Automatizované odečty: the latest remote value and, as the control value, the remote value closest to the date and time entered in the form; last synchronisation; datalogger status as an icon (active / inactive) with the text in a tooltip
Value lower than the previous reading while typing	Warning under the field group; saving is still possible
Saving such a value	Dialog asking the reason: typo (back to the form), meter replaced — also when the counter ran over its maximum (opens the replacement), value is correct (only with the override permission; the reason is written into the reading's note, which is then required)
Overview	Table Přehled odečtů with a switch Ruční odečty / Dálkové odečty and Export; in the remote view a period choice (default the last 30 days); column choice per Table View Settings
Manual view	One row per reading: date and time, value and consumption per series, an icon when the reading has a note or documents, a Konečný / Počáteční tag on the two readings of a meter replacement; pages, sortable by any column; row actions Detail odečtu, Historie (clock icon, opens the shared per-record history of Audit Log), and Upravit / Smazat for users allowed to change readings
Remote view	One row per logged moment: date and time, value per series, consumption per interval, power; read-only, newest first, loaded in batches with Načíst další
Gas gauge reading volume	Beside the volume consumption a column with the conversion to kWh, computed by Calorific Value Management
Reading detail	Note and the attached documents (name, type, open); button Historie opening the shared per-record history — the detail draws no history of its own
Edit	Dialog with date and time, all values, the note and the documents; no close icon, Zrušit / Uložit změny
Edit of a reading from a meter replacement (Konečný / Počáteční)	Upravit opens the Výměna měřidla dialog filled with the recorded replacement — moment, final and initial values, unit per parameter, serial number, protocol; saving re-records the whole replacement
Delete	Confirmation naming the gauge and moment; no close icon
Archived gauge	Overview only, no form, no row changes
User may only read	Form replaced by a notice; overview and detail available
Loading failed	Error state with retry in place of the overview

Dialogs asking for a decision have no close icon; Esc always cancels.

Functional Requirements

• Store a manual reading as one entry per gauge and moment: all series read then, one note, any documents.
• Offer in the form, per hand-read parameter, the series tariffSeries(gauge, readAt) of Gauge Management gives for the entered moment (celkem, or VT / NT / ST by the distribution rate or tariff switches valid then; a sub-gauge follows its parent). Every series is required, except feed-in on a gauge that also reads consumption.
• Require date and time between 1990-01-01 and now; reject a second reading at the same moment and any reading on a remote-only gauge.
• Show under each field the last value and resulting consumption; warn when a cumulative value drops.
• Reject on save a cumulative value below the previous or above the next reading of its series, naming every offending series; a replaced meter's final reading is not compared.
• Allow the continuity override only with the override permission and a note stating the reason; mark it in the audit trail.
• Attach documents as links to Document Management, registering an uploaded file first; never copy a file into the reading.
• Allow editing a reading as a whole — moment, values, note, documents — with the entry checks; a missing series can be added; the last write wins. A replacement reading is edited only by the Meter Replacement Flow.
• Allow deleting a reading as a whole, keeping its history traceable; refuse for a replacement reading.
• Gate editing and deleting by one permission, shown only to holders (Users & Access).
• Store every value as read from the display, with the unit of the parameter's manual source setting valid at the moment; refuse the entry without such a setting.
• List manual readings by page, newest first, sortable by any column, one row per moment, consumption per series computed on the server.
• List remote readings as logged, read-only, for a chosen period (default 30 days), newest first in batches.
• Export the shown view as XLSX through the Table View Settings standard, including server-derived columns (consumption, kWh conversion); the remote view over 7 days, 3 months, the last year or everything.
• Request consumption recalculation for every period a changed reading affects.
• Audit every creation, change and deletion of an entry, its values and document links, with before and after; the reading's history is the audit log's shared per-record history.

Situation	Rule
Value breaks continuity on save	The user picks: typo (correct it), meter replacement — also a counter that ran over its maximum (record it), or the override with a note
Same identity, same value	Skipped as a duplicate
Same identity, different value	Rejected
Gauge also reads remotely	Card Automatizované odečty shows the latest remote value and the one closest to the entered moment, for comparison
File import	Same identity, duplicate and continuity rules; analysed separately
Anomaly tolerance	Resolved after saving: gauge, then tenant and medium, then ±20 %
Source priority	Resolved after saving: gauge, then tenant, then remote before manual before invoice

Internationalization & Localization

Labels come from the product's labelling mechanism — see GUI Labelling. Series headings use the name of the gauge's measured parameter. Dates and times are shown in the tenant's time zone and stored in UTC; numbers use the user's locale. The note is free text and is not translated.

Non-Functional Requirements

• Integrity. A reading entry and its values are never partially stored, changed or deleted.
• Traceability. Every change is attributable to an actor and reversible by hand from the audit trail.

Performance

The remote view reads up to 35 000 rows per gauge and year. It pages by moment rather than by offset, and computes consumption with one window over the series, including the one row before the page. The manual view stays small (tens of rows per year) and pages by number. An export of everything is bounded by the export row limit.

Transactional Operations

Entry, value rows and document links are written, changed and deleted in one transaction with their audit entries. Moving a reading to another moment removes and re-inserts its rows in the same transaction. Concurrent entry of the same moment is stopped by the unique key. Concurrent edits of one entry are not locked: the later write wins and both writes are in the audit trail.

Processes & Related Systems / Components

Trigger	Owner of the trigger	What this feature does
A reading is entered, changed or deleted	this feature	Requests recalculation from Consumption Calculation
A value goes backwards and the user picks meter replaced, or Upravit is used on a replacement reading	this feature	Hands over to the Meter Replacement Flow
A file is attached from the computer	Document Management	Registers the file as a document; this feature links it
The datalogger delivers values	Remote Connection Management	Shows them in the remote view
The gauge's reading method changes	Gauge Management	Shows or hides the form
Readings are imported from a file	Reading import	Shows the imported readings; entries are created for them

Diagrams & Models

Saving a manual reading whose value goes backwards:

sequenceDiagram
    actor U as Energy manager
    participant F as Readings tab
    participant R as Reading entries
    participant C as Consumption Calculation
    U->>F: Enter moment, values, note
    F->>F: Value below previous, warn
    U->>F: Save
    F->>R: Create entry
    R-->>F: Continuity broken, offending series
    F->>U: Ask for the reason
    alt Typo
        U->>F: Correct the value and save again
    else Meter replaced
        F->>U: Open the meter replacement
    else Value is correct
        U->>F: Confirm the value is correct
        F->>R: Create entry with the override
        R->>C: Recalculate the affected period
    end

API Analysis

See api-a.md.

Domain Model (ER diagram) & Data Attribute Table

erDiagram
    GAUGE ||--o{ READING : "is read as"
    GAUGE ||--o{ READING_ENTRY : "is read manually as"
    READING_ENTRY ||--|{ READING : "groups (same gauge, moment, manual)"
    READING_ENTRY ||--o{ READING_ENTRY_DOCUMENT : "is supported by"
    DOCUMENT ||--o{ READING_ENTRY_DOCUMENT : "supports"

• readingEntry — one manual reading as entered; note.
• readingEntryDocument — a document supporting a reading.
• reading — one value per series; carries its unit.
• gauge — parameter, reading method, tariffSeries rule; gaugeSourceSetting — unit and coefficient of the manual source, valid from a date.
• Audit Log — the per-record history shown from the row and the detail.

Data

No reference data. reading.value is the figure read from the display; the source coefficient of gaugeSourceSetting is applied by the consumption computation, never to the stored value, and reading.format follows the matrix on the reading page. A representative manual reading of a two-tariff meter with feed-in:

INSERT INTO reading_entry (id, tenant_id, gauge_id, read_at, note, created_by, updated_by) VALUES
    ('019247a1-5c3e-7d10-8a2b-1f4c6e8d9a01', '018f6e2a-1b2c-7d3e-9f40-5a6b7c8d9e0f',
     '018f7a10-2c3d-7e4f-8a5b-6c7d8e9f0a1b', '2026-05-04T08:40:00Z',
     'Displej špatně čitelný, ověřeno fotkou.', 'user:018ed0b3-0000-7000-8000-000000000001',
     'user:018ed0b3-0000-7000-8000-000000000001');

INSERT INTO reading (id, tenant_id, gauge_id, read_at, type, direction, tariff, source, format, lifecycle_state, value, unit, created_by, updated_by) VALUES
    ('019247a1-5c40-7a11-9c2d-3e5f7a9b1c02', '018f6e2a-1b2c-7d3e-9f40-5a6b7c8d9e0f', '018f7a10-2c3d-7e4f-8a5b-6c7d8e9f0a1b', '2026-05-04T08:40:00Z', 'energy', 'import', 'high', 'manual', 'cumulative', 'reading', 192054, 'kWh', 'user:018ed0b3-0000-7000-8000-000000000001', 'user:018ed0b3-0000-7000-8000-000000000001'),
    ('019247a1-5c41-7a11-9c2d-3e5f7a9b1c03', '018f6e2a-1b2c-7d3e-9f40-5a6b7c8d9e0f', '018f7a10-2c3d-7e4f-8a5b-6c7d8e9f0a1b', '2026-05-04T08:40:00Z', 'energy', 'import', 'low', 'manual', 'cumulative', 'reading', 73787, 'kWh', 'user:018ed0b3-0000-7000-8000-000000000001', 'user:018ed0b3-0000-7000-8000-000000000001'),
    ('019247a1-5c42-7a11-9c2d-3e5f7a9b1c04', '018f6e2a-1b2c-7d3e-9f40-5a6b7c8d9e0f', '018f7a10-2c3d-7e4f-8a5b-6c7d8e9f0a1b', '2026-05-04T08:40:00Z', 'energy', 'export', 'total', 'manual', 'cumulative', 'reading', 3410, 'kWh', 'user:018ed0b3-0000-7000-8000-000000000001', 'user:018ed0b3-0000-7000-8000-000000000001');

Test Data

Use the Test Data location named in the overlay. Search the demo-gauge seed for gauges with a parameter whose readingMethod is manual or both; the cases worth having are a two-tariff meter with feed-in, a single-tariff meter, a VN meter with the peak tariff (three series), a remote-only gauge, and a series whose last value is higher than a planned test value.

Logging

• .info — reading entry created, changed or deleted: gauge, moment, number of series, whether the continuity override was used, actor, requestId.
• .info — export produced: gauge, view, row count.
• .warn — entry rejected for continuity: gauge, moment, offending series.
• .error — recalculation request could not be queued: gauge, period.

Monitoring

One feature-level need: the rate of saves with the continuity override. It is normally rare; a rise means either meters being replaced without the replacement flow or a data problem in a tenant.

Caching

None. Readings are read after every change and a stale overview would hide the change the user just made.

Backward Compatibility and Migration

Historical readings without a time of day are stored at 12:00 of their day. Recalculation of history keeps each tenant's previous "from midnight" convention, so figures do not silently move. Manual readings already stored get one reading entry per gauge and moment, created with a migration actor and no note. Values already stored keep the unit of their EM2 record, mapped per source by the Gauge Management migration (segment mapping), not the unit of the gauge. The previous per-reading action log is carried into the audit trail, so history before the migration stays visible in the reading detail.

Legal Context

Readings are the customer's operational data and may be used as evidence against a supplier's invoice. No licence or regulation governs this feature itself; what makes a reading usable as evidence is that it keeps its original value, its supporting documents and a complete record of every change, which the audit trail provides. Retention follows the customer's contract for their data.

Cybersecurity Considerations

Reading, entering, changing and overriding continuity are separate permissions; which roles hold them is defined by Users & Access. Every query is tenant-scoped. Attached documents are handled by Document Management, including its file checks, and a link never exposes a document the user could not open there.

Data Privacy. A note may contain a person's name; it is shown only to users who may read the gauge's readings. The actor of every change is recorded, as on every record.

Risk Assessment

Business Risks

A wrong reading produces plausible but wrong consumption for two periods and every report on them. Mitigations: the warning while typing, the reason dialog on save, the photo as evidence, and a history that shows what was changed and by whom. The override is restricted to a separate permission and recorded as such in the audit trail.

Technical Risks

Risk	Consequence	Mitigation
Moving a reading to another moment fails halfway	Values split between two moments	One transaction for removal and re-insertion
Two users enter the same moment	Duplicate reading	Unique key on gauge and moment
Two users edit the same reading	The later write silently replaces the earlier	Both writes in the audit trail with before and after; the history shows what happened
A source's unit changes	Old values read in the wrong unit	Unit stored on every value; a change is a new source setting valid from a date
Remote view over a long window	Slow page	Keyset paging, window at most 366 days
Recalculation request lost	Consumption not updated after a change	Logged as error and retried by the queue
Cascade — Document Management unavailable	Documents cannot be attached	The reading can be saved without documents and documents attached later

Auditing, Reporting & Measurement

Every creation, change and deletion of a reading entry, its values and its document links is filed in the audit trail against the entry, with actor, time and the values before and after; the audited field sets are on the entity pages. The row and the reading detail open this trail through the shared per-record history. The feature reports nothing else; readings reach reports through the consumption derived from them.