Add optional cable-sizing module

Per-circuit cross-section recommendation as a separate module attached to the circuit list. It never writes project data itself: "Übernehmen" applies cable type, cross-section and length through the regular circuit.update command, so revisions and Undo/Redo stay intact. - Pure domain module (src/cable-sizing) with IEC 60364-5-52:2009 Annex B tables for PVC and XLPE, copper and aluminium, methods A1, A2, B1, B2, C, D1, D2 and E. Every value was cross-checked against public reproductions; where sources differ the lower value is used (docs/cable-sizing-module.md). - Temperature and grouping between table values round to the safer value; values outside the tables return no result instead of a factor of 1. Ground methods use B.52.18 (D2) and B.52.19 A (D1). - Overload protection: circuit-breakers In <= Iz; gG fuses additionally I2 <= 1.45 Iz with I2 = 1.6/1.9/2.1 In. - Inputs prefilled from the circuit: power, phase (group or device rows), project voltage, power-weighted cos phi, length and protective device. - Opened from a "Leitungsberechnung" button in the row actions, not from a grid cell, so cable cells keep the spreadsheet behavior. - Stateless API under /api/cable-sizing; no database table or migration. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 10:59:41 +02:00 · 2026-09-26 10:59:41 +02:00 · 49488f4e1b
commit 49488f4e1b
parent d95f0bf5c0
17 changed files with 1999 additions and 4 deletions
--- a/docs/README.md
+++ b/docs/README.md
@ -15,6 +15,8 @@ ausdrücklich getrennt und dürfen nicht als bereits implementiert verstanden we
 - [Editor-API](circuit-list-editor-api.md) – unterstützte Circuit-First-Endpunkte
 - [Bekannte Einschränkungen](circuit-list-editor-known-limitations.md) –
  bewusst noch nicht implementierte oder begrenzte Funktionen
+- [Leitungsberechnung](cable-sizing-module.md) – optionales Rechenmodul,
+  Rechenweg, Datenbasis und Prüfnachweis der Tabellen

 ## Entwicklung und Betrieb

--- a/docs/cable-sizing-module.md
+++ b/docs/cable-sizing-module.md
@ -0,0 +1,159 @@
+# Leitungsberechnung (Cable-Sizing-Modul)
+
+Optionales, abgegrenztes Rechenmodul für die Querschnittsempfehlung eines
+Stromkreises. Es wurde als eigenständiges Modul vereinbart, das an die
+Stromkreisliste angedockt ist. Es **schreibt keine Projektdaten selbst**: Ein
+Ergebnis wird erst durch ausdrückliches „Übernehmen“ über den bestehenden
+Befehl `circuit.update` in den Stromkreis geschrieben. Revisionen und
+Undo/Redo bleiben damit unverändert gültig.
+
+Die vollständige, automatische Bemessung aller Stromkreise (siehe
+`docs/spec/06-future-sizing-and-calculations.md`) ist weiterhin **nicht**
+Teil dieses Moduls.
+
+## Aufbau und Andockpunkte
+
+```
+src/cable-sizing/domain/cable-sizing-calculation.ts   reine Berechnung + Tabellen
+src/cable-sizing/domain/cable-sizing-contracts.ts     Zod-Schema der API
+src/server/controllers/cable-sizing.controller.ts     zustandslose Endpunkte
+src/server/routes/cable-sizing.routes.ts              Router unter /api/cable-sizing
+src/frontend/components/cable-sizing-api.ts           Fetch-Client
+src/frontend/components/cable-sizing-defaults.ts      Vorbelegung aus dem Stromkreis
+src/frontend/components/cable-sizing-modal.tsx        Dialog
+tests/cable-sizing-calculation.test.ts                Tabellen, Rechnung, Vorbelegung
+```
+
+Das Domänenmodul importiert nichts aus `db/`, `server/` oder `frontend/`.
+Außerhalb dieser Dateien gibt es genau zwei Andockpunkte:
+
+1. `src/server/index.ts`: `app.use("/api/cable-sizing", cableSizingRouter)`.
+2. `src/frontend/components/circuit-tree-editor.tsx`: Zustand für den
+   geöffneten Dialog, ein Button **Leitungsberechnung** (Rechner-Icon) in der
+   Aktionsspalte jeder Stromkreiszeile, der Dialog selbst und
+   `handleApplyCableSizing`, das über `updateCircuitById` den regulären
+   `circuit.update`-Befehl ausführt.
+
+Der Aufruf liegt bewusst **nicht** auf einer Tabellenzelle: Klick, Doppelklick,
+Enter, F2 und Tippen in den Kabelspalten verhalten sich wie in jeder anderen
+Zelle (Spreadsheet-Regel in `AGENTS.md`). Es gibt keine eigene Datenbanktabelle
+und keine Migration.
+
+## Eingaben und Vorbelegung
+
+| Eingabe | Vorbelegung |
+|---|---|
+| Leistung | `circuitTotalPower` des Stromkreises (mit Geräte-GZF), nicht editierbar |
+| Phasen | 3~, wenn die Stromkreisgruppe 3-phasig ist oder eine Gerätezeile `three_phase` hat, sonst 1~ |
+| Spannung | `circuit.voltage` (aus den Projekteinstellungen abgeleitet); bei manuell abweichender Phasenzahl die jeweilige Projektspannung |
+| cos φ | leistungsgewichtet aus den Gerätezeilen: P / Σ(P_Zeile / cos φ_Zeile), fehlendes cos φ = 1; änderbar |
+| Länge | `cableLength` des Stromkreises |
+| Schutzorgan | Schutzgerät des Stromkreises: LS, FI/LS, AFDD = Leitungsschutzschalter; D0/NH = Sicherung gG; FI ohne Überstromauslöser wird nicht berücksichtigt |
+| Verlegeart, Isolierstoff, Leitermaterial, Temperatur, Häufung, max. ΔU, Oberschwingungen | Planereingaben |
+
+Kabeltyp und Querschnitt lassen sich im Dialog auch ohne Berechnung direkt
+eintragen. Weicht der Eintrag von der Empfehlung oder dem
+Praxis-Mindestquerschnitt ab, erscheint nur ein Hinweis.
+
+## Rechenweg
+
+1. Betriebsstrom I_B aus Leistung, Spannung, cos φ und Phasenzahl.
+2. Erforderliche Belastbarkeit: ohne Schutzorgan I_B; mit Schutzorgan
+   max(I_B, I_n, I₂/1,45) nach IEC 60364-4-43 (I_n ≤ I_z und I₂ ≤ 1,45 · I_z).
+   I₂/I_n: Leitungsschutzschalter 1,45; Sicherung gG 2,1 (I_n ≤ 4 A),
+   1,9 (4 A < I_n < 16 A), 1,6 (I_n ≥ 16 A).
+3. Tabellenwert I_z je Querschnitt × Temperaturfaktor × Häufungsfaktor
+   (× 0,86 bei 15–33 % 3. Harmonischer im Drehstromkreis).
+4. Spannungsfall ΔU = k · L · I_B · cos φ / (κ · A · U) mit k = 2 (1~) bzw.
+   √3 (3~), κ = 48 (Cu) bzw. 30 (Al) m/(Ω·mm²) bei Betriebstemperatur;
+   Reaktanz wird vernachlässigt.
+5. Empfehlung = größerer Querschnitt aus Belastbarkeit und Spannungsfall;
+   1-phasige Stromkreise werden auf den Praxis-Mindestquerschnitt 2,5 mm²
+   angehoben (Planungskonvention aus `docs/spec/06-…`, keine Rechenanforderung).
+6. Zusätzlich: maximale Länge für den zulässigen Spannungsfall.
+
+Temperaturen und Häufungen **zwischen** Tabellenwerten werden auf den nächsten
+ungünstigeren Tabellenwert gerundet (höhere Temperatur, mehr Stromkreise).
+Werte **außerhalb** der Tabellen liefern kein Ergebnis und eine Meldung – es
+wird nie stillschweigend mit Faktor 1 gerechnet.
+
+## Datenbasis und Prüfnachweis
+
+Grundlage ist **IEC 60364-5-52:2009, Anhang B**. Alle Werte wurden am
+26.09.2026 zeilenweise mit öffentlich zugänglichen Wiedergaben abgeglichen:
+TiSoft ElectricalDesign-Hilfe zu IEC 60364-5-52
+(`ti-soft.com/en/support/help/electricaldesign/standards/iec-60364-5-52/…`)
+und ECalPro (`ecalpro.com/standards/iec-60364/…`). Wo die Quellen voneinander
+abweichen, ist der kleinere, sichere Wert eingetragen.
+
+| Tabelle | Inhalt | Abgleich | Abweichungen |
+|---|---|---|---|
+| B.52.2 | PVC, 2 belastete Adern, Cu/Al, A1–D2 | TiSoft; Cu A1–C zusätzlich ECalPro | Cu A1 240 mm²: 321 / 320 → 320 |
+| B.52.3 | VPE, 2 belastete Adern, Cu/Al, A1–D2 | TiSoft | – |
+| B.52.4 | PVC, 3 belastete Adern, Cu/Al, A1–D2 | TiSoft | – |
+| B.52.5 | VPE, 3 belastete Adern, Cu/Al, A1–D2 | TiSoft | – |
+| B.52.10 / .11 | PVC, Verlegeart E, mehradrig, Cu / Al | TiSoft; Cu 2 Adern zusätzlich ECalPro | Cu 3 Adern 70 / 120 mm²: 198 / 278 bzw. 196 / 276 → 196 / 276 |
+| B.52.12 / .13 | VPE, Verlegeart E, mehradrig, Cu / Al | TiSoft | – |
+| B.52.14 | Temperatur Luft, PVC / VPE | TiSoft, ECalPro | – |
+| B.52.15 | Temperatur Erde, PVC / VPE | TiSoft | – |
+| B.52.17 | Häufung Luft, Zeile 1 (gebündelt) | TiSoft, ECalPro | – |
+| B.52.18 | Häufung Erde direkt, Kabel berührend | TiSoft | – |
+| B.52.19 A | Häufung mehradrige Kabel in berührenden Rohren im Erdreich | TiSoft | – |
+
+Anwendung der Tabellen:
+
+- Verlegearten A1, A2, B1, B2, C, E in Luft (Bezug 30 °C), D1 und D2 im
+  Erdreich (Bezug 20 °C, Bodenwärmewiderstand 2,5 K·m/W). Nach Tabelle B.52.1
+  ist **D1 = Leitung im Rohr/Kabelschutzrohr im Erdreich** und **D2 = Kabel
+  direkt im Erdreich**.
+- Häufung in Luft immer nach B.52.17 Zeile 1, auch für Verlegeart E; das ist
+  die ungünstigste Anordnung (einlagig auf Pritschen wären höhere Faktoren
+  zulässig). D1 nach B.52.19 A, D2 nach B.52.18 jeweils „berührend“.
+- Aluminium nur mit den echten Aluminiumwerten (ab 2,5 mm², D2 ab 16 mm²);
+  Querschnitte ohne Tabellenwert werden nie empfohlen.
+- Die Verlegearten F und G (Einzeladern mit Abstand) sind nicht enthalten.
+
+**Vor produktivem Einsatz:** Die nationalen Tabellen der DIN VDE 0298-4
+können in einzelnen Werten abweichen. Der Planer muss die Tabellen gegen den
+Normtext prüfen. Die Prüfung ist in `tests/cable-sizing-calculation.test.ts`
+über Stichwerte und eine Monotonieprüfung jeder Tabellenzeile abgesichert.
+
+## Nicht enthalten
+
+- Kurzschlussfestigkeit, Abschaltbedingungen (Schleifenimpedanz) und
+  Selektivität
+- Bodenwärmewiderstand ≠ 2,5 K·m/W, Häufung mit Abstand, Verlegearten F/G
+- Bemessung des Neutralleiters bei > 33 % 3. Harmonischer (nur Hinweis)
+- automatische Bemessung oder Prüfung aller Stromkreise
+
+## API
+
+`POST /api/cable-sizing/calculate` – zustandslos, liest und schreibt keine
+Projektdaten.
+
+```jsonc
+{
+  "phase": 1,                       // 1 | 3
+  "mode": "power",                  // "power" | "current"
+  "powerKw": 4.2,                   // bei mode "power"
+  "currentA": 18.3,                 // bei mode "current"
+  "cosPhi": 0.95,                   // 0,1 … 1
+  "voltage": 230,
+  "lengthM": 23.5,
+  "layingMethod": "C",              // A1 | A2 | B1 | B2 | C | D1 | D2 | E
+  "conductorMaterial": "copper",    // copper | aluminum
+  "insulation": "pvc",              // pvc | xlpe
+  "ambientTemperatureC": 30,        // Luft; bei D1/D2 Bodentemperatur
+  "groupingCircuits": 1,            // 1 … 100, Tabellen bis 20
+  "maxVoltageDropPercent": 3,
+  "harmonicNeutralLoad": "none",    // none | 15to33Percent | over33Percent
+  "existingProtection": { "ratedCurrentA": 16, "kind": "breaker" }, // optional; kind: breaker | fuse
+  "circuitCategory": "single_phase" // optional
+}
+```
+
+Antwort: `{ "result": CableSizingResult, "alerts": CableSizingAlert[] }`.
+`result.supported = false` mit `unsupportedReason` (`temperature` oder
+`grouping`), wenn die Eingaben außerhalb der Tabellen liegen.
+`GET /api/cable-sizing/laying-methods` und `GET /api/cable-sizing/insulation-materials`
+liefern die Auswahllisten.
--- a/docs/circuit-list-editor-api.md
+++ b/docs/circuit-list-editor-api.md
@ -391,6 +391,28 @@ inverse command. The former direct restore/reconnect endpoints are removed.
 `displayName` is included in the comparison but is not selected by default in the UI. Updating a
 project device never triggers synchronization implicitly.

+## Cable Sizing (optional module)
+
+Stateless calculator endpoints mounted at `/api/cable-sizing`. They neither
+read nor write project data; applying a result uses `circuit.update` through
+`POST /projects/:projectId/commands`.
+
+- `POST /cable-sizing/calculate`
+  - request: phase, mode (`power` | `current`), powerKw or currentA, cosPhi,
+    voltage, lengthM, layingMethod (`A1` | `A2` | `B1` | `B2` | `C` | `D1` |
+    `D2` | `E`), conductorMaterial, insulation (`pvc` | `xlpe`),
+    ambientTemperatureC, groupingCircuits, maxVoltageDropPercent,
+    harmonicNeutralLoad, optional `existingProtection`
+    (`{ ratedCurrentA, kind: "breaker" | "fuse" }`) and circuitCategory
+  - returns `{ "result": { ... }, "alerts": [ ... ] }`; `result.supported`
+    is `false` with `unsupportedReason` when temperature or grouping lie
+    outside the tables
+  - unknown fields are rejected (`400`)
+- `GET /cable-sizing/laying-methods`
+- `GET /cable-sizing/insulation-materials`
+
+Full request example and calculation rules: `docs/cable-sizing-module.md`.
+
 ## Revit CSV Foundation

 - `GET /projects/:projectId/external-csv/configuration`
--- a/docs/circuit-list-editor-known-limitations.md
+++ b/docs/circuit-list-editor-known-limitations.md
@ -17,8 +17,12 @@
 - Persistence currently targets local SQLite; PostgreSQL is an architectural option, not an implemented runtime.
 - The global device library supports basic CRUD and copy operations, but has no
  versioning, permissions or controlled synchronization model.
- Final electrical sizing logic is not implemented yet.
- No full norm-compliant voltage-drop and protection-dimensioning calculation flow yet.
+- There is no automatic sizing of all circuits. The optional cable sizing
+  module suggests a cross-section for one circuit on demand (IEC 60364-5-52
+  Annex B tables; no short-circuit, disconnection-time or selectivity checks,
+  no methods F/G, soil resistivity fixed at 2.5 K·m/W) and does not validate
+  manually entered cable values. National tables (DIN VDE 0298-4) must be
+  checked by the planner; see `docs/cable-sizing-module.md`.
 - Sorting is view-only until users explicitly apply sorted order.
 - Complete-circuit drag supports one circuit at a time between groups of the
  same category. Cross-category moves and multi-circuit moves across group
--- a/docs/current-architecture.md
+++ b/docs/current-architecture.md
@ -452,6 +452,18 @@ werden als Diff angezeigt und nur für ausdrücklich gewählte Felder und Zeilen
 Die globale Gerätebibliothek ist ein einfacher, datenbankweiter Vorlagenbestand.
 Kopieren in ein Projekt erzeugt ein eigenständiges Projektgerät.

+## Leitungsberechnung
+
+Das optionale Modul `src/cable-sizing` berechnet auf Anforderung eine
+Querschnittsempfehlung für einen Stromkreis (IEC 60364-5-52 Anhang B:
+Belastbarkeit, Temperatur, Häufung, Spannungsfall, Schutzorgan). Die
+Domänenlogik ist rein, `POST /api/cable-sizing/calculate` ist zustandslos und
+es gibt keine eigene Tabelle. Der Editor öffnet den Dialog über den Button
+„Leitungsberechnung“ in der Aktionsspalte; „Übernehmen“ schreibt Kabeltyp,
+Querschnitt und Länge über den regulären `circuit.update`-Befehl, also mit
+Revision und Undo/Redo. Details, Rechenweg und Prüfnachweis der Tabellen:
+`docs/cable-sizing-module.md`.
+
 ## Persistenz und Migration

 - SQLite ist die aktuell unterstützte Datenbank.
--- a/docs/spec/08-current-product-backlog.md
+++ b/docs/spec/08-current-product-backlog.md
@ -46,7 +46,9 @@ requirements and intended sequencing, not proof of implementation.
 - [x] Phase E: editor projection and editing.
 - [x] Phase F: documentation and full GUI verification.
 - [ ] Keep full electrical sizing and cable-dimensioning rules separate until
-  the planner supplies the calculation requirements.
+  the planner supplies the calculation requirements. The optional per-circuit
+  cable sizing module (`docs/cable-sizing-module.md`) exists; its tables must
+  be confirmed by the planner against DIN VDE 0298-4.
 - Detailed specification:
  `docs/spec/09-distribution-board-components-and-protection-groups.md`