Contract Loading

Status: deprecated. The background contract preload and its Redis cache described under Status quo are scheduled for removal. Do not build new features on them. New code loads contract data on demand, as described under Target architecture. This page documents the current state (verified against the code on 2026-10-12) for the team taking over KBP, and the migration plan in Migration roadmap.

Why a preload exists

KBP has always loaded full commodity contracts from EnWiCore through the legacy client interface (VertraegeFuerKundeHolen service consumer). That interface returns the contract list and then fetches tariffs, prices, meters, products and IMS data per contract. For customers with many contracts (for example housing companies, Wohnungswirtschaft), one load takes from several seconds up to minutes.

To hide that latency, KBP starts a full load in the background as soon as an agent opens a customer, stores the result in Redis and lets every feature read from that cache. Features that need contract details either wait for the preload or fall back to overview data.

Status quo (deprecated)

Building blocks

Runtime: session start and preload

Runtime: a feature reads contract details

Any GetCustomerContractsQuery with includeDetails: true (the default) ends in the orchestrator. What happens there depends on the Redis flags and the request options:

Redis keys

All keys are scoped by {agent e-mail}_{tenant}_{default reference id}.

Write-back. When an agent changes contract data in KBP, the change is sent to EnWiCore. The cached contracts in Redis are not deleted and reloaded afterwards. Instead, KBP copies the new values into the cached contracts itself, so that other features see the change without a new full load:

Consequences:

• The cache only matches EnWiCore if every command copies exactly what EnWiCore changed. Values that EnWiCore changes as a side effect are not updated in the cache.
• Any new command that changes contract data must also update the cache. Otherwise features show the old values until the cache expires (60 minutes) or the next session start.
• Changes made outside KBP never reach the cache.

Invalidation. None of the upstream systems KBP consumes (EnWiCore, APA and others) send cache headers or change notifications. KBP therefore never knows whether cached data is still current. It relies on fixed TTLs and on clearing the cache at points where a change is likely:

• EntryPointController.LoadCustomerInfo clears the customer’s cache on every session start.
• KBP’s own write commands patch the cache (see Write-back above).
• For APA account balances, KontodatenController deletes all cached balances of the customer whenever api/kontodaten is called with a contract number. The frontend makes that call after every change to APA data in KBP. As a side effect, the cache is also cleared when an agent only switches to another contract in Kontodaten. If the frontend stops making that call, KBP shows stale balances without any error.

Changes made outside KBP (directly in EnWiCore, APA or another system) become visible only when the TTL expires or the cache is cleared at one of these points.

Where the preloaded data is used

The contract overview endpoint already delivers these fields per contract (ContractOverview): contract number, sector, contract type, status / active flag, start date, delivery address and current tariff name. Everything else needs the full load. The tables below list, per use case, only the fields that are not in the overview — these are the reason the use case depends on the preload.

Claims management (Forderungsmanagement)

Claims management builds lists of selectable contracts for a task. It loads all contracts of the customer with details and filters them, because eligibility depends on detail data.

Account data (Kontodaten)

Kontodaten combines APA account data with EnWiCore contract data. The cross-contract overview takes its contract list from APA (balances per contract); the contract selection is built from EnWiCore contracts. The UI waits for the preload before contracts can be opened.

Frontend gating

Other consumers of contract details

Tariff change offers (GetTariffChangeOffersCommand: meters, tariffs, market location), warnings (GetWarnhinweiseQuery), payment data (GetPaymentDataQuery: bank account), owner management (OwnerController, UpdateOwnerCommand: market location), permissions, PIN phone numbers, contact and address data, paper option cancellation and order capture. Overview-only pages (contract list, contract count, relocations, NBA, tariff change entry, self-service) already use GetCustomerContractOverviewsQuery and do not depend on the preload.

Known problems

• Latency is only hidden, not removed. Features that need details still wait — through the orchestrator’s polling and wait loops on a request thread — until the full load is done.
• Silent degradation. With reloadDetailsFromSourceIfMissing: false the orchestrator returns overview data while the preload is still running. Detail fields (tariffs, meters, notes) are then empty without any error.
• Multi-tab race. Opening the same customer in two tabs clears the cache of the first; the short-lived contracts_successfully_pre_loaded flag forces a reload (bug 827678).
• Cached failures. Both Cacheable repositories can cache an upstream failure as “no contracts” for 60 minutes (bug audit 2026-09-08, finding H-05).
• Overfetching and coupling. One Contract entity carries tariffs, prices, meters, notes, products and documents for all features; every feature pays for all of it.
• Blocking calls. TasksUtils.RunSync around contract loading in two claims-management controllers.

Target architecture

The target removes the preload, the orchestrator and the Redis contract cache. Each feature calls the query that returns exactly what it needs:

• Contract lists come from the lightweight EnWiCore endpoint getContractOverviewsByCustomerId (optional current tariff name) via GetCustomerContractOverviewsQuery. The endpoint supports paging (limit, offset), but KBP currently requests all contracts in one call (limit = int.MaxValue).
• Contract details come from domain-based application queries — tariffs, prices, notes, flexible tariff flag and working price type, meter, documents (Endia), products — that are independent of each other and return a ContractDetailsNew entity (final name to be decided).
• Controllers and frontend contracts stay unchanged during migration: a combined DTO in the Web project replaces the legacy Contract + ContractDetails shape.
• No preload state in the frontend. Views show their own loading state per request.

Impact on claims management and Kontodaten

Without a cache, loading details for all contracts on every request is as slow as the preload itself. The features therefore have to change when they need details, not only where they get them from. Three patterns are possible and can be combined:

Pattern A is the default proposal: it removes the dependency on caches and the N calls, and many KBP processes already work on one selected contract. Pattern C is needed where information must be visible before selection, for example legal warnings.

Claims management

Kontodaten

Kontodaten already has the natural pre-selection: APA returns the contracts with balances, and most pages work on one selected contract (/kontodaten/:vertragsnummer).

Open questions for the spikes

• Which detail fields does the business really need before selection? Everything else can move behind a pre-selection.
• Can EnWiCore extend the overview or offer customer-level flags (active meter, forced-access and legal-file notes, payment type)? This decides between pattern B and C for legal warnings.
• Does APA already deliver payment type and dunning state, so that Kontodaten does not need EnWiCore details for its selection list?
• UX changes (pre-selection step, moved columns) need agreement with the product owner and the claims-management and account-data users.

Migration roadmap

Parent: 1341022 — KBP: 2026 Technical maintenance. States as of 2026-10-12.

Step 1 states that preloading stops, but the frontend still triggers the preload on every session start and the endpoint Vertraege_Preload is active. Removing it is part of step 7; until then the preload must keep working, because claims management and Kontodaten still depend on it.