184 lines
9.3 KiB
Markdown
184 lines
9.3 KiB
Markdown
# 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.
|
|
|
|
## How a suggestion is applied
|
|
|
|
The module never writes to `circuits` directly. The modal's "Empfehlung
|
|
übernehmen" button calls the **existing, unmodified** frontend helper:
|
|
|
|
```ts
|
|
updateCircuitById(projectId, expectedRevision, circuitId, {
|
|
cableCrossSection: "4 mm²",
|
|
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
|
|
- manually typing a value into the `cableCrossSection` cell keeps working
|
|
unchanged - the module only adds a small calculator trigger next to the
|
|
cell, per `docs/spec/06-future-sizing-and-calculations.md`'s explicit
|
|
requirement that "users must remain able to manually override suggestions"
|
|
|
|
## API contract
|
|
|
|
`POST /api/cable-sizing/calculate`
|
|
|
|
```jsonc
|
|
{
|
|
"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
|
|
"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.
|
|
|
|
## 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 on an internal test host at
|
|
`http://192.168.0.133:3220` (a fork of this repository's `main` branch, not
|
|
pushed anywhere). `npm test`, `npm run build:api`, `npm run build:web` and
|
|
`npm run typecheck:scripts` all pass with this module included; see the
|
|
accompanying diff/branch for the exact commit.
|