Appearance
Gauge Management — Creation Flow Dependencies
Supplementary analysis to Gauge Management. It lists everything the gauge creation form reads from, writes to or sets in motion, and says, for each one, what origin/main does today and what is missing. Business confirmation sheet: use-cases.md.
Sources (2026-09-15): Figma e-manažer UI (✅ Approved: Majetek — Objekt · Měřidla 583:9751, Majetek — měřidlo · Odečet 1392:24110, · Fakturace 1392:23066), EM3 staging /gauges/new and /gauges/:id, EM3 code origin/main @ 899d20ca (apps/frontend/components/gauges/gauge-form*.tsx, lib/gauge-applicability.ts, CreateGaugeDto, CreateGaugeUseCase, gauge-field-applicability.rules.ts, supply-point.rules.ts), live catalogue GET /v1/gauge-purpose-options on staging.
1. Where things stand
| Layer | State |
|---|---|
| Figma | No creation screen. The building's gauge tab has an "+ Nové měřidlo" button that leads nowhere; the gauge card (tabs Karta OM · Detail · Odečty · Fakturace · Dokumenty · Provoz) is designed only for readings and invoicing. The list shows a level badge (Hlavní · Podružné · Výroba · Kontrolní) that mixes kind with purpose — there is no field that yields "Kontrolní". |
| Staging | /gauges/new is a working single-page form (sections Identifikace · Klasifikace · Technické údaje · Obchodní údaje · Vazby · Chování), shared with edit. Sections appear once kind and medium are chosen. Entry points: gauge list, building gauge tab (?building=), "+ Add channel" (?source=). |
| Backend | POST /v1/gauges is complete for the applicability matrix, purpose derivation, supply point format and uniqueness, channel grouping and serial history — all in one transaction, followed by building-total re-evaluation. |
The form works; the gaps are in what it offers, what it hides and what it does not tell the user after saving.
2. Upstream — what the form needs
| # | Dependency | Owner | Today | Gap | Proposal |
|---|---|---|---|---|---|
| U1 | Building to attach to | Building Management | Flat select from GET /v1/buildings?pageSize=100 (active only). Staging tenant has 85. | A tenant with more than 100 buildings cannot pick the rest. No tree context, so two buildings with the same name are indistinguishable. | Tree picker over GET /v1/buildings/tree with state=active — the same source and filter the building creation flow already requires. Show the ancestor path as the value. |
| U2 | Purpose catalogue gaugePurposeOption | Platform (superadmin) | 17 active options. Standard electricity offers only consumedFromGrid (import/include) and production (export/reportOnly). | Missing combinations the feature text promises: returned to grid (export/include), battery charging (import/reportOnly), battery discharging (export/reportOnly). No option targets subtract or exclude at all. The export channel of a 4Q meter therefore cannot be modelled correctly. Translation keys are gauge.purpose.*, the feature text says gauge.purposeOption.*. | Extend the seed (developer work only where the target combination is new). Align the key prefix in the doc. |
| U3 | Sub-gauge default purpose | Platform seed | Every subGauge option targets include. | The recognised pattern in the feature text is "INCLUDE standard + REPORT_ONLY sub-gauges in the same building". A sub-gauge created with the default is added a second time unless it sits in another building. | Business decision (use-cases row 4): default sub-gauge purpose = reportOnly; offer include explicitly for the third-party-building case. |
| U4 | Subscriber (subscriberId) | Client Management — organisation registry | Accepted by CreateGaugeDto, validated by assertSubscriberExists, shown on the gauge card. The form never renders it — it is only in the hidden-field lists. | New gauges have no subscriber, so the "Karta OM" subscriber card stays empty; only migrated gauges have one (staging: 89 of 100 sampled). | Render an organisation combobox (name + IČO) for physical non-KVP gauges. |
| U5 | Supplier (supplierOrganisationId) | Contract Management | In DTO and form; locked when a contract holds the gauge. | Not in the gauge entity DAT. | Add the attribute to the DAT (source of truth is the repo). |
| U6 | Distributors (electricityDistributorId, gasDistributorId) | Organisation Distribution Registry | In the DAT. | Absent from DTO, form and migration. | Decide: add to the form, or drop from the DAT and derive from the supply point (EAN prefix / distribution area). |
| U7 | Organisation list | Client Management | GET /v1/organisations?pageSize=100, flat. | Same 100-row cap as U1. Staging shows eight entries whose name is only an IČO — a migration data issue that makes the select unreadable. | Search-as-you-type combobox; data fix for name-less organisations. |
| U8 | Parent gauge (sub-gauge) | Gauge Management | Options = non-virtual gauges of the same building. | (a) Sub-gauges are offered as parents, the backend rejects them with a generic error. (b) Cross-building parents are valid in the domain but impossible in the UI. (c) No medium match is enforced anywhere. (d) An archived parent is accepted by the backend. | Options = active standard gauges of the same medium, current building first, then "other buildings" via search. Backend: add medium and archived checks. |
| U9 | Supply point identifier | Gauge Management | Format per medium (EAN 18 digits / EIC 16 / free ≤ 50); required only for standard electricity import; unique among active holders. | Label is always "EAN / číslo OM" whatever the medium. The DAT says "unique per tenant" without the active qualifier — the code is the more useful rule (meter replacement), the doc should follow. | Medium-aware label and inline format hint; update the DAT wording. |
| U10 | Unit | Gauge Management / enum Unit | Free text 1–20 characters. Form pre-fills from medium: electricity kWh, gas m³, water m³, heat GJ, fuel l, phm l, kvp kWh. | The DAT requires a unit compatible with the medium; nothing enforces it. KVP defaults to an energy unit. | Select filtered by medium; KVP units follow the purpose (°C, %, ppm). Backend compatibility check. |
| U11 | Primary source | enum PrimarySource | Number input 1–28; the card shows the raw number. | Unusable without the code list. | Select of named values filtered by medium (EM2 splits them per gauge type). |
| U12 | "Show in reports after archiving" | Gauge Management | Form default false; backend and DAT default true. | A gauge created in the UI silently disappears from historical reports once archived. | Form default true. |
| U13 | Permissions | Users & Access | tenant.gauges.write covers create; building reassignment has its own code. | Fine for creation. | — |
3. Downstream — what creation sets in motion
| # | Dependency | Owner | Today | Gap | Proposal |
|---|---|---|---|---|---|
| D1 | Building total formula (one per building × medium) | Gauge Management (building total) | Re-evaluated inside the create transaction for the gauge's building and, for a sub-gauge, the parent's building. | POST /v1/gauges returns only id; the form redirects to the gauge card. An alert (cross-building dependency, no INCLUDE gauge) is raised but the user is never shown the suggested formula at the moment the decision is theirs — the acceptance criterion "no option to dismiss without deciding" is met only if they later open the building. | Return the evaluation outcome with the 201 (per affected building: autoApplied / alertRaised / unchanged); the form opens the confirmation dialog when an alert was raised. Show the expected effect in the form before saving (canvas, variant A side panel). |
| D2 | Virtual gauge formula | Gauge Management | Set through the separate formula endpoint after creation. | Create does not lead the user there; a computed gauge without a formula is a silent empty series. | For virtual/computed, redirect to the formula editor after save. |
| D3 | Channel grouping (physicalMeter) | Gauge Management | ?source= pre-fills building, medium, reading mode and electrical fields; backend groups in one transaction. | The purpose auto-selects the catalogue default (consumedFromGrid), which is wrong for the second channel of a 4Q meter; and the needed returned to grid option is missing (U2). | Pre-select the complement of the source channel's direction; lock inherited fields visibly. |
| D4 | Volume coefficient | Gauge Management (volumeCoefficient) | Added from the card after creation; no record = factor 1. | None for creation. Mention it in the "after saving" hint. | — |
| D5 | Calorific value | Calorific Value Management | Resolved at calculation time from gauge → client → platform scope. | EM2 e-mailed admins "new gauge without calorific value" at creation. EM3 relies on the gap indicator only. | Confirm the gap indicator is enough (use-cases row 9). Show the resolved value and scope in the form for gas, fuel, phm. |
| D6 | Contracts | Contract Management | Supplier lock by contract; contract gauge eligibility checks kind/medium. | None for creation. | — |
| D7 | Remote reading pairing | Remote Connection / Aggregator Connectors | Paired later on the card's API konektory tab. allowsManualReading defaults true. | For a remote-only channel the user must remember to switch manual readings off. | Offer the toggle in the channel flow (canvas) with a remote-only hint. |
| D8 | Readings | Reading Management | readingMode is copied onto every energy/volume reading as format. | Reading mode is editable after creation, which re-interprets history. | Out of scope here; flag to Reading Management. |
| D9 | Consumption calculation (Epic 3.1) | Consumption Calculation | groupBy=usageType reads gauge.purpose. | Purpose is not versioned — editing it regroups history. | Keep purpose effectively fixed after creation (as kind/medium) or version it — decision for 3.1 owner. |
| D10 | Serial number history | Gauge Management | First gaugeSerialHistory row written in the create transaction. | — | — |
| D11 | Labels | GUI Labelling | Purpose labels via translation keys. | Key prefix mismatch (U2). | — |
| D12 | Audit | Audit Log | Create is audited through the controller. | — | — |
4. Design variants
Canvas Založení měřidla (Claude Design), screenshots in design/:
| Variant | Shape | For | Against |
|---|---|---|---|
| A — single page with progressive sections (recommended) | Today's page, reordered: Co měříte → Umístění → Identifikace → Elektrické parametry → Obchodní údaje a chování (collapsed); right panel with derived values, effect on the building total and "after saving". | Same component for create and edit (as today); smallest change to shipped code; the building-total effect is visible before saving. | Long page for electricity. |
| B — four-step wizard | Co měříte → Umístění a identifikace → Parametry → Kontrola. | Irreversible choices isolated up front; guided for occasional users. | Needs a separate edit form; more clicks for administrators who create dozens of gauges during onboarding. |
| C — quick side panel on the building gauge tab | Required fields only, "Uložit a přidat další". | Matches the Figma entry point; fast for series. | Electrical and business data completed later; poor fit for virtual gauges. |
Shared by all three: Přidat kanál (inherited fields locked, complement purpose pre-selected) and Potvrzení celkové spotřeby (dialog with Použít návrh / Upravit vzorec ručně, no dismiss).
5. Proposed work split
| Ticket (proposed) | Scope |
|---|---|
| BE — Gauge creation contract hardening | U8 backend checks; U10 unit compatibility; D1 evaluation outcome in the 201; U2/U3 catalogue seed. |
| FE — Gauge creation form (variant chosen) | U1, U4, U7, U8, U9, U10, U11, U12 in the form; D1 dialog; D2 redirect; D3 pre-selection. |
| DOC — Gauge DAT alignment | U5, U6, U9 wording, purpose key prefix. |