238 lines
5.3 KiB
Markdown
238 lines
5.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Goal
|
|
|
|
Build a spreadsheet-like electrical distribution board circuit list editor.
|
|
|
|
The editor is used for electrical planning in execution design.
|
|
|
|
It must support circuits, device rows, project devices, drag-and-drop restructuring, stable equipment identifiers and later electrical sizing logic.
|
|
|
|
## Critical Domain Rules
|
|
|
|
- A circuit is not the same thing as one device row.
|
|
- A circuit contains zero, one or multiple device rows.
|
|
- A single-device circuit may be displayed as one compact row.
|
|
- A multi-device circuit must be displayed with a circuit summary row and indented device rows.
|
|
- Equipment identifiers belong to circuits, not to every device row.
|
|
- Device rows inside a circuit do not have their own equipment identifiers.
|
|
- Protection and cable data belong to the circuit, not to individual devices.
|
|
- Device-level values include quantity, power per unit, simultaneity factor, cosPhi, room data, cost group and category.
|
|
- Circuit total power is the sum of all device rows in that circuit.
|
|
- Existing equipment identifiers must never be changed automatically.
|
|
- Renumbering is always an explicit user action.
|
|
|
|
## Existing Codebase Rule
|
|
|
|
There is an existing codebase.
|
|
|
|
Do not blindly continue old assumptions.
|
|
|
|
Do not blindly delete the codebase.
|
|
|
|
First audit current code against the specification.
|
|
|
|
Keep working parts if they match the target model.
|
|
|
|
Refactor or replace parts that conflict with the target model.
|
|
|
|
Before large changes, summarize:
|
|
|
|
- what is kept
|
|
- what is changed
|
|
- what is removed
|
|
- why
|
|
|
|
## Implementation Discipline
|
|
|
|
Work in phases.
|
|
|
|
Do not implement unrelated future features while working on a phase.
|
|
|
|
Before coding, briefly state:
|
|
|
|
- files to change
|
|
- data model impact
|
|
- UI impact
|
|
- risks
|
|
|
|
Prefer small, reviewable changes.
|
|
|
|
Do not rewrite the whole app unless the current architecture blocks the required domain model.
|
|
|
|
## Naming
|
|
|
|
Use English names in code.
|
|
|
|
Use clear domain names:
|
|
|
|
- `ProjectDevice`
|
|
- `DistributionBoard`
|
|
- `CircuitSection`
|
|
- `Circuit`
|
|
- `CircuitDeviceRow`
|
|
- `equipmentIdentifier`
|
|
- `displayName`
|
|
- `phaseType`
|
|
- `quantity`
|
|
- `powerPerUnit`
|
|
- `simultaneityFactor`
|
|
- `cosPhi`
|
|
- `rowTotalPower`
|
|
- `circuitTotalPower`
|
|
|
|
Avoid ambiguous names like:
|
|
|
|
- `item`
|
|
- `thing`
|
|
- `entry`
|
|
- `rowData`
|
|
|
|
Use them only for local UI variables where the context is obvious.
|
|
|
|
## Numbering Rules
|
|
|
|
Default sections:
|
|
|
|
- Lighting: prefix `-1F`
|
|
- Single-phase circuits: prefix `-2F`
|
|
- Three-phase circuits: prefix `-3F`
|
|
|
|
New circuit identifier:
|
|
|
|
- highest existing number in the section + 1
|
|
|
|
Do not fill gaps automatically.
|
|
|
|
Do not renumber after insert, delete, move, sort or drag-and-drop.
|
|
|
|
Renumber only when the user explicitly triggers "Renumber section".
|
|
|
|
## UI Rules
|
|
|
|
The circuit list table should behave like a spreadsheet.
|
|
|
|
Cells show static text by default.
|
|
|
|
Inline edit starts by:
|
|
|
|
- double click
|
|
- Enter
|
|
- typing
|
|
- F2
|
|
|
|
Keyboard behavior:
|
|
|
|
- Enter confirms
|
|
- Escape cancels
|
|
- Tab / Shift+Tab navigates editable cells
|
|
- Arrow keys navigate cells when not editing
|
|
|
|
Support Ctrl+Plus and Ctrl+Shift+Plus for insertion.
|
|
|
|
## Drag-and-Drop Rules
|
|
|
|
Dragging from the circuit identifier / circuit handle moves the whole circuit.
|
|
|
|
Dragging from the device area moves device rows.
|
|
|
|
Project devices can be dragged from a sidebar into the circuit list.
|
|
|
|
Drop onto a free placeholder creates a new circuit.
|
|
|
|
Drop onto an existing circuit adds the device to that circuit.
|
|
|
|
Moving a device recalculates affected circuit totals.
|
|
|
|
Moving rows never renumbers circuits automatically.
|
|
|
|
Show clear visual drop indicators.
|
|
|
|
Reject invalid drop targets or require confirmation.
|
|
|
|
## Sorting and Filtering
|
|
|
|
Filtering should work through column headers.
|
|
|
|
Sorting should work through column headers.
|
|
|
|
Sorting moves complete circuits as blocks.
|
|
|
|
Sorting must not split device rows away from their circuit.
|
|
|
|
Sorting does not renumber.
|
|
|
|
The user may explicitly renumber after sorting.
|
|
|
|
## Linked Project Devices
|
|
|
|
Circuit device rows may be linked to project devices.
|
|
|
|
`displayName` is copied on insert but not synchronized automatically.
|
|
|
|
When a project device changes, show affected linked rows and let the user choose which fields to sync.
|
|
|
|
Never silently overwrite local changes.
|
|
|
|
Allow disconnecting linked rows from project devices.
|
|
|
|
## Manual Rows
|
|
|
|
Manual rows are allowed and common.
|
|
|
|
Manual rows can later be saved as project devices.
|
|
|
|
After saving, the row becomes linked to the new project device.
|
|
|
|
## Undo / Redo
|
|
|
|
Implement undo/redo for structural and destructive operations.
|
|
|
|
Required operations:
|
|
|
|
- insert circuit
|
|
- insert device
|
|
- delete circuit
|
|
- delete device
|
|
- move circuit
|
|
- move device
|
|
- multi-row move
|
|
- renumber section
|
|
- edit cell value
|
|
- edit equipment identifier
|
|
- synchronization changes
|
|
|
|
## Future Sizing
|
|
|
|
Do not implement full cable/protection sizing unless explicitly requested.
|
|
|
|
Keep the structure ready for it.
|
|
|
|
Future sizing will need:
|
|
|
|
- circuit total power
|
|
- phase type
|
|
- voltage
|
|
- cosPhi
|
|
- cable length
|
|
- cable type
|
|
- cable cross-section
|
|
- protection rated current
|
|
- control requirement such as DALI
|
|
|
|
Users must be able to override sizing suggestions.
|
|
|
|
## Response Style for Codex
|
|
|
|
Be concise.
|
|
|
|
Do not restate the whole specification.
|
|
|
|
Reference the relevant file and section.
|
|
|
|
When uncertain, choose the simplest implementation that preserves the domain model.
|
|
|
|
Do not add libraries unless there is a clear reason.
|
|
|
|
Do not introduce global state management unless needed.
|