jappel/leistungsbilanz-ts
1
0
Fork 1
Code Issues Pull requests 2 Projects Releases Packages Wiki Activity Actions
leistungsbilanz-ts/docs/cable-sizing-module.md

13 KiB
Raw Blame History

Cable Sizing Module (Proposal)

Status: proposal, not yet reviewed or merged by the project owner. This document and the accompanying src/cable-sizing/, src/db/schema/cable-sizing-calculations.ts, src/server/{controllers,routes}/cable-sizing.* and src/frontend/components/cable-sizing-* files were written by a third party (see git history/authorship) against the project's own stated direction in docs/spec/06-future-sizing-and-calculations.md ("The app should later support rule-based protection and cable sizing") and AGENTS.md ("... and later electrical sizing logic"). Nothing here has been pushed to the project's own repository; it exists as a local branch for review, testing and discussion.

Why a separate module instead of extending core domain code

AGENTS.md is explicit that critical multi-write commands, the revision/undo system and the Circuit-First domain model are the supported architecture, and that changes should be small and reviewable. A cable-sizing calculation is not a project mutation - it doesn't need expectedRevision, doesn't belong in the undo/redo stack, and shouldn't grow the circuit.update command's switch statement or the DTOs it doesn't already have.

So this module is built exactly like the existing src/external-model/ adapter (the Revit/CSV import foundation): a one-way dependency boundary.

src/cable-sizing/domain/     <- pure functions and types, zero imports from
                                 db/, server/ or frontend/
src/db/schema/                <- one new, fully additive table
src/db/repositories/          <- one plain repository (no revision semantics)
src/server/{controllers,routes}/cable-sizing.*  <- one new, isolated route
                                 group, mounted with a single app.use() line
src/frontend/components/cable-sizing-*          <- one new modal + one small
                                 API client, following the existing
                                 FormModal / CircuitProtectionModal pattern

Nothing outside these files imports from them except the two required one-line hooks described below. If this module is rejected or needs to move out again, removing it is a matter of deleting these files, the two one-line hooks, and running a DROP TABLE migration - it never touches circuits, project_revisions or any command/history table.

The two required hooks into existing code

  1. src/server/index.ts: one import + one app.use("/api/cable-sizing", cableSizingRouter) line, next to the existing app.use("/api/projects", ...) etc.
  2. src/frontend/components/circuit-tree-editor.tsx: one new useState for the open modal, one new trigger condition (mirroring the existing isProtectionTrigger / protectionEditorCircuit pattern almost exactly), and one new conditionally-rendered <CableSizingModal /> alongside the existing <CircuitProtectionModal />. See the diff for the exact lines.

No changes to circuit-project-command.model.ts, project-command.service.ts, any Zod command schema, any migration for circuits/project_revisions, or any existing test.

Coupling to the grid UI (the one fragile point)

Everything described above - the calculation, the audit table, applying a result via circuit.update - depends only on stable, explicitly documented domain fields (cableType/cableCrossSection/cableLength/ circuitTotalPower/voltage/protectionDevice.ratedCurrentA), the same ones AGENTS.md already treats as protected ("Protection and cable data belong to the circuit"). None of that breaks if the grid UI changes.

The one place that is coupled to a UI implementation detail: the click trigger in circuit-tree-editor.tsx matches grid column keys (cableSummary and cableCrossSection, defined in circuit-grid-model.ts) to decide where to show the calculator icon. Column visibility and order in this app are a per-browser user preference, not fixed - so this is checked against both known cable-related columns to reduce (not eliminate) the chance a user's personal column layout hides the trigger entirely. If a future column rename removes both keys, the failure mode is purely cosmetic: the calculator icon/click stops appearing on that cell, nothing crashes, no data is affected, and the rest of the app (including manual cable-field editing) is completely unaffected - the module's actual logic and persistence never depend on this column key.

Feature overview

  • Calculate a recommendation: laying method, insulation, conductor material, ambient temperature, grouping, cos phi and max voltage drop - same VDE 0298-4 reference-method model as the sibling Kabelliste tool (see Verification status below).
  • Breaker-aware sizing: if the circuit already has a protection device (circuit.protectionDevice), the cross-section is selected against designCurrentA = max(operatingCurrentA, protectionDevice.ratedCurrentA), not the load current alone - the standard In <= Iz rule (a breaker only trips at its own rated current, so a cable sized for the actual load alone could overheat under sustained current below that threshold). If no cross-section can cover an oversized breaker, that is reported as the limiting factor by name, not a generic capacity error.
  • Maximum length for the voltage-drop limit: each cross-section option also reports the longest single run that still meets the requested maxVoltageDropPercent at the given load - the inverse of the voltage-drop check, shown for the recommended cross-section.
  • Practical minimum for socket circuits: single_phase-category circuits are raised to at least 2.5 mm² if the calculation alone would recommend less - see the dedicated note under Verification status. Never lowers a calculation that already needs more.
  • Manual entry, always available: the modal has a plain text Kabeltyp/ Querschnitt field. Running a calculation pre-fills it as a suggestion, but the field is the single source of truth for what gets applied, and stays freely editable - satisfying docs/spec/06-future-sizing-and-calculations.md's explicit requirement that "users must remain able to manually override suggestions" without requiring a calculation to have been run first. A non-blocking warning appears if the typed value is not a standard cross-section, is smaller than the last calculation, or is below the practical minimum above - informational only, never forced, matching the same spec doc's "shown as a warning or status indicator, not as an automatic forced change."

How a suggestion or manual entry is applied

The module never writes to circuits directly. The modal's "Übernehmen" button calls the existing, unmodified frontend helper with whatever is currently in the Kabeltyp/Querschnitt fields, calculated or hand-typed:

updateCircuitById(projectId, expectedRevision, circuitId, {
  cableCrossSection: "4 mm²",
  cableType: "NYM-J 3x2.5",
  cableLength: 30,
});

which is the same circuit.update command the grid already uses for manual cell edits. This means:

  • optimistic concurrency (expectedRevision) is respected automatically
  • the change appears in the project's revision history and is undoable/ redoable exactly like a manual edit
  • nothing is ever written automatically - calculating only fills the modal's own fields, applying is always an explicit, separate click

API contract

POST /api/cable-sizing/calculate

{
  "phase": 1,                    // 1 | 3
  "mode": "power",                // "power" | "current"
  "powerKw": 4.2,                  // circuit.circuitTotalPower, when mode="power"
  "cosPhi": 1,
  "voltage": 230,                  // circuit.voltage (already project-derived, read-only)
  "lengthM": 23.5,                 // circuit.cableLength
  "layingMethod": "C",             // DIN VDE 0298-4 reference method, A1|A2|B1|B2|C|D1|D2|E|F|G
  "conductorMaterial": "copper",   // "copper" | "aluminum"
  "insulation": "pvc",             // "pvc" | "xlpe"
  "ambientTemperatureC": 30,
  "groupingCircuits": 1,
  "maxVoltageDropPercent": 3,
  "harmonicNeutralLoad": "none",   // "none" | "15to33Percent" | "over33Percent", three-phase only
  "existingProtectionRatedCurrentA": 16,  // optional, from circuit.protectionDevice
  "circuitCategory": "single_phase",      // optional, from the circuit's section.category -
                                            // enables the practical-minimum convention below
  "context": { "projectId": "...", "circuitId": "...", "equipmentIdentifier": "-1F1.1" }
}

Response: { calculationId, result: CableSizingResult, alerts: CableSizingAlert[] } (see src/cable-sizing/domain/cable-sizing-calculation.ts for the exact shape). GET /api/cable-sizing/laying-methods and .../insulation-materials expose the pick-list metadata (including which combinations are verified) so a future non-modal UI could build its own form without hard-coding the enum.

Verification status - important

The reference current-carrying-capacity tables are ported from a sibling project's Kabelliste module, which was itself only verified against ~8 public sources for six of the ten DIN VDE 0298-4 reference laying methods (A1, B2, C, E, D1, D2) and PVC insulation only. The other four methods (A2, B1, F, G) and XLPE/VPE insulation could not be verified without contradiction across sources during that earlier work, so calculateCableSizing deliberately returns dataVerified: false and no numeric recommendation for those combinations, rather than a guessed value. The UI surfaces this as a plain critical alert. Anyone with access to the actual norm text can extend LAYING_METHOD_VERIFIED and CURRENT_CAPACITY_A in src/cable-sizing/domain/cable-sizing-calculation.ts once the missing tables are confirmed.

The protection-coordination check (existingProtectionRatedCurrentA vs. the recommended cross-section's corrected capacity) is a simplified In <= Iz check only - it is not a full IEC 60364-4-43 overload (I2 <= 1.45 x Iz) or short-circuit withstand check.

PRACTICAL_MINIMUM_CROSS_SECTION_MM2 (2.5 mm² for single_phase) is not a verified norm value at all - it is a named planning convention, sourced directly from this project's own docs/spec/06-future-sizing-and-calculations.md ("Standard Single-Phase Circuits ... usually use ... cable cross-section: 2.5 mm²"), applied as a floor on top of the calculated recommendation. It intentionally only covers the one category and one convention that document already states; it is not a general substitute for norm-compliant calculation.

Relationship to the project's own future-sizing spec

docs/spec/06-future-sizing-and-calculations.md separately describes simple category-based defaults (e.g. lighting circuits -> 10 A / 1.5 mm²) as "common planning defaults, not a replacement for full norm-compliant calculation". This module is the latter: an on-demand, norm-referenced calculation for one circuit at a time, not a bulk default-filling tool. The two are complementary and could later be wired together (e.g. the category defaults pre-fill this module's laying-method/insulation fields), but that integration is out of scope here.

The spec's isPublicBuilding halogen-free rule and the Control Requirement (DALI/KNX/core-count) field are not implemented by this module - both concern cable type selection, not cross-section sizing, and the latter isn't in the current schema yet. They're natural follow-ups once this module is reviewed.

Maintenance plan

The src/cable-sizing/domain/ folder has zero imports from the rest of the app by design (see the dependency-direction note above), so it can be extracted into an independently versioned/published package later (e.g. a private npm package or a git subtree) without touching anything outside the five files/folders listed above - "separately maintained but part of the app for now", per the intent of this proposal.

Local testing

Deployed and manually exercised end-to-end on an internal test host at http://192.168.0.133:3220 (own docker deployment, own subnet/ports to avoid clashing with ~50 other containers on that host - see the two commits marked "Local-only" in this branch, which are not part of this proposal and should not be carried over if it is ever proposed upstream). Exercised against seeded real project/circuit data created through the actual command API (not direct DB writes), including a deliberately long (85 m) circuit to trigger the voltage-drop-critical path.

npm test, npm run build:api, npm run build:web and npm run typecheck:scripts all pass with this module included at every commit in this branch.

This branch (feature/cable-sizing-module) is pushed to a mirror of this repository under this homelab's own Forgejo instance, not to git.jappel.io - no write access to the upstream repository was available or used. See the branch's commit history for the incremental history of this module, including fixes made during manual testing (trigger column, icon rendering, breaker-aware sizing).