specs for rewrite
This commit is contained in:
@@ -1,452 +1,237 @@
|
|||||||
# AGENTS.md
|
# AGENTS.md
|
||||||
## Project Context
|
|
||||||
This repository contains a web application for creating, editing, calculating, and documenting electrical power balances for building-services electrical planning.
|
|
||||||
|
|
||||||
The application is intended for small internal use by approximately 2–3 concurrent users. It should support practical planning workflows, not an over-engineered enterprise architecture.
|
## Project Goal
|
||||||
|
|
||||||
The domain is electrical building planning, especially German TGA / ELT planning. Important concepts include:
|
Build a spreadsheet-like electrical distribution board circuit list editor.
|
||||||
|
|
||||||
- Power balance / Leistungsbilanz
|
The editor is used for electrical planning in execution design.
|
||||||
- Distribution boards / Verteilungen
|
|
||||||
- Electrical consumers / Verbraucher
|
|
||||||
- Installed power / installierte Leistung
|
|
||||||
- Demand factor / Gleichzeitigkeitsfaktor
|
|
||||||
- Calculated demand power / berechnete Leistung
|
|
||||||
- Voltage, current, phases, cos phi
|
|
||||||
- Device groups and individual devices
|
|
||||||
- Project-based calculation and documentation
|
|
||||||
|
|
||||||
Use English identifiers in code, database fields, interfaces, classes, and file names. German wording is allowed and preferred in UI labels, reports, and domain-facing text.
|
It must support circuits, device rows, project devices, drag-and-drop restructuring, stable equipment identifiers and later electrical sizing logic.
|
||||||
|
|
||||||
## Main Goal
|
## Critical Domain Rules
|
||||||
|
|
||||||
Build a maintainable web application that allows users to:
|
- 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.
|
||||||
|
|
||||||
- Create and manage projects
|
## Existing Codebase Rule
|
||||||
- Define electrical distributions or calculation areas
|
|
||||||
- Add individual electrical consumers
|
|
||||||
- Add grouped consumers with quantity
|
|
||||||
- Assign technical parameters to consumers
|
|
||||||
- Calculate installed and demand power
|
|
||||||
- Structure consumers by project, distribution, area, system, or category
|
|
||||||
- Export or print a usable power-balance report later
|
|
||||||
|
|
||||||
The application should be practical for electrical planners and should keep the data model understandable.
|
There is an existing codebase.
|
||||||
|
|
||||||
## Technology Direction
|
Do not blindly continue old assumptions.
|
||||||
|
|
||||||
Preferred stack:
|
Do not blindly delete the codebase.
|
||||||
|
|
||||||
- TypeScript
|
First audit current code against the specification.
|
||||||
- Node.js backend
|
|
||||||
- SQLite database for the initial version
|
|
||||||
- ORM is allowed and preferred if it improves type safety and maintainability
|
|
||||||
- Drizzle ORM is preferred for a more explicit SQL-oriented approach
|
|
||||||
- Prisma is acceptable if the project already uses it
|
|
||||||
- Frontend may be React-based if a UI is implemented
|
|
||||||
- Docker support for local development is desired
|
|
||||||
|
|
||||||
Do not introduce unnecessary infrastructure such as PostgreSQL, Redis, Kubernetes, microservices, message queues, or complex event systems unless explicitly requested.
|
Keep working parts if they match the target model.
|
||||||
|
|
||||||
SQLite is sufficient for the expected initial workload.
|
Refactor or replace parts that conflict with the target model.
|
||||||
|
|
||||||
## Architecture Principles
|
Before large changes, summarize:
|
||||||
|
|
||||||
Keep the application modular, but avoid excessive abstraction.
|
- what is kept
|
||||||
|
- what is changed
|
||||||
|
- what is removed
|
||||||
|
- why
|
||||||
|
|
||||||
Preferred structure:
|
## Implementation Discipline
|
||||||
|
|
||||||
```text
|
Work in phases.
|
||||||
src/
|
|
||||||
├─ domain/
|
|
||||||
│ ├─ models/
|
|
||||||
│ ├─ services/
|
|
||||||
│ └─ calculations/
|
|
||||||
├─ db/
|
|
||||||
│ ├─ schema/
|
|
||||||
│ ├─ migrations/
|
|
||||||
│ └─ repositories/
|
|
||||||
├─ server/
|
|
||||||
│ ├─ routes/
|
|
||||||
│ ├─ controllers/
|
|
||||||
│ └─ middleware/
|
|
||||||
├─ frontend/
|
|
||||||
│ ├─ components/
|
|
||||||
│ ├─ pages/
|
|
||||||
│ └─ utils/
|
|
||||||
└─ shared/
|
|
||||||
├─ types/
|
|
||||||
└─ validation/
|
|
||||||
```
|
|
||||||
|
|
||||||
The exact structure may be simplified if the project is still small.
|
Do not implement unrelated future features while working on a phase.
|
||||||
|
|
||||||
Use object-oriented design where it is useful for domain behavior, but do not force everything into classes.
|
Before coding, briefly state:
|
||||||
|
|
||||||
Good candidates for classes:
|
- files to change
|
||||||
|
- data model impact
|
||||||
|
- UI impact
|
||||||
|
- risks
|
||||||
|
|
||||||
- Project
|
Prefer small, reviewable changes.
|
||||||
- PowerBalance
|
|
||||||
- DistributionBoard
|
|
||||||
- Consumer
|
|
||||||
- ConsumerGroup
|
|
||||||
- CalculationService
|
|
||||||
- ReportGenerator
|
|
||||||
|
|
||||||
Good candidates for interfaces/types:
|
Do not rewrite the whole app unless the current architecture blocks the required domain model.
|
||||||
|
|
||||||
- DTOs
|
## Naming
|
||||||
- API request/response shapes
|
|
||||||
- ORM result types
|
|
||||||
- Configuration objects
|
|
||||||
- Form data
|
|
||||||
- Validation schemas
|
|
||||||
|
|
||||||
Avoid duplicating the same model excessively across domain, database, API, and frontend. Some separation is acceptable, but keep mappings simple and explicit.
|
|
||||||
|
|
||||||
## Naming Conventions
|
|
||||||
|
|
||||||
Use English names in code.
|
Use English names in code.
|
||||||
|
|
||||||
Examples:
|
Use clear domain names:
|
||||||
|
|
||||||
- `Project`
|
- `ProjectDevice`
|
||||||
- `PowerBalance`
|
|
||||||
- `DistributionBoard`
|
- `DistributionBoard`
|
||||||
- `Consumer`
|
- `CircuitSection`
|
||||||
- `ConsumerGroup`
|
- `Circuit`
|
||||||
- `installedPower`
|
- `CircuitDeviceRow`
|
||||||
- `demandFactor`
|
- `equipmentIdentifier`
|
||||||
- `demandPower`
|
- `displayName`
|
||||||
- `ratedCurrent`
|
- `phaseType`
|
||||||
- `powerFactor`
|
|
||||||
- `quantity`
|
- `quantity`
|
||||||
- `voltage`
|
- `powerPerUnit`
|
||||||
- `phaseCount`
|
- `simultaneityFactor`
|
||||||
|
- `cosPhi`
|
||||||
|
- `rowTotalPower`
|
||||||
|
- `circuitTotalPower`
|
||||||
|
|
||||||
Use PascalCase for classes, interfaces, React components, and types.
|
Avoid ambiguous names like:
|
||||||
|
|
||||||
Use camelCase for variables, properties, functions, and methods.
|
- `item`
|
||||||
|
- `thing`
|
||||||
|
- `entry`
|
||||||
|
- `rowData`
|
||||||
|
|
||||||
Use kebab-case for file names unless the local framework convention requires otherwise.
|
Use them only for local UI variables where the context is obvious.
|
||||||
|
|
||||||
Examples:
|
## Numbering Rules
|
||||||
|
|
||||||
```text
|
Default sections:
|
||||||
power-balance.service.ts
|
|
||||||
consumer.model.ts
|
|
||||||
distribution-board.repository.ts
|
|
||||||
calculation-utils.ts
|
|
||||||
```
|
|
||||||
|
|
||||||
## Domain Model Guidelines
|
- Lighting: prefix `-1F`
|
||||||
|
- Single-phase circuits: prefix `-2F`
|
||||||
|
- Three-phase circuits: prefix `-3F`
|
||||||
|
|
||||||
A consumer must still have a quantity. This allows the same structure to represent either a single device or a grouped device entry.
|
New circuit identifier:
|
||||||
|
|
||||||
Example:
|
- highest existing number in the section + 1
|
||||||
|
|
||||||
```ts
|
Do not fill gaps automatically.
|
||||||
type Consumer = {
|
|
||||||
id: string;
|
|
||||||
projectId: string;
|
|
||||||
distributionBoardId?: string;
|
|
||||||
name: string;
|
|
||||||
category?: string;
|
|
||||||
quantity: number;
|
|
||||||
installedPowerPerUnit: number;
|
|
||||||
installedPowerTotal: number;
|
|
||||||
demandFactor: number;
|
|
||||||
demandPower: number;
|
|
||||||
voltage?: number;
|
|
||||||
phaseCount?: 1 | 3;
|
|
||||||
powerFactor?: number;
|
|
||||||
note?: string;
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
The calculated fields may either be persisted or calculated dynamically. Prefer dynamic calculation first unless persistence is needed for reporting, auditability, or performance.
|
Do not renumber after insert, delete, move, sort or drag-and-drop.
|
||||||
|
|
||||||
## Calculation Rules
|
Renumber only when the user explicitly triggers "Renumber section".
|
||||||
|
|
||||||
Keep calculation logic centralized.
|
## UI Rules
|
||||||
|
|
||||||
Do not spread electrical formulas across route handlers, UI components, or database repositories.
|
The circuit list table should behave like a spreadsheet.
|
||||||
|
|
||||||
Use dedicated calculation services or pure functions.
|
Cells show static text by default.
|
||||||
|
|
||||||
Examples:
|
Inline edit starts by:
|
||||||
|
|
||||||
```text
|
- double click
|
||||||
src/domain/calculations/power-calculation.ts
|
- Enter
|
||||||
src/domain/services/power-balance.service.ts
|
- typing
|
||||||
```
|
- F2
|
||||||
|
|
||||||
Typical calculation concepts:
|
Keyboard behavior:
|
||||||
|
|
||||||
- Installed power total = quantity × installed power per unit
|
- Enter confirms
|
||||||
- Demand power = installed power total × demand factor
|
- Escape cancels
|
||||||
- Current calculation depends on voltage, phase count, and power factor
|
- Tab / Shift+Tab navigates editable cells
|
||||||
|
- Arrow keys navigate cells when not editing
|
||||||
|
|
||||||
When implementing formulas, add comments for the electrical meaning, especially where three-phase and single-phase calculations differ.
|
Support Ctrl+Plus and Ctrl+Shift+Plus for insertion.
|
||||||
|
|
||||||
Always be careful with units.
|
## Drag-and-Drop Rules
|
||||||
|
|
||||||
Preferred base units:
|
Dragging from the circuit identifier / circuit handle moves the whole circuit.
|
||||||
|
|
||||||
- Power: kW
|
Dragging from the device area moves device rows.
|
||||||
- Current: A
|
|
||||||
- Voltage: V
|
|
||||||
- Demand factor: decimal number from 0 to 1
|
|
||||||
|
|
||||||
If other units are added later, implement explicit conversion helpers.
|
Project devices can be dragged from a sidebar into the circuit list.
|
||||||
|
|
||||||
## Database Guidelines
|
Drop onto a free placeholder creates a new circuit.
|
||||||
|
|
||||||
Use SQLite initially.
|
Drop onto an existing circuit adds the device to that circuit.
|
||||||
|
|
||||||
Keep schema clear and readable.
|
Moving a device recalculates affected circuit totals.
|
||||||
|
|
||||||
Avoid premature normalization. Normalize where it prevents real inconsistency, not just for theoretical purity.
|
Moving rows never renumbers circuits automatically.
|
||||||
|
|
||||||
Recommended core tables:
|
Show clear visual drop indicators.
|
||||||
|
|
||||||
- projects
|
Reject invalid drop targets or require confirmation.
|
||||||
- power_balances
|
|
||||||
- distribution_boards
|
|
||||||
- consumers
|
|
||||||
- consumer_categories or system_types, if needed later
|
|
||||||
|
|
||||||
Use migrations. Do not manually modify the database schema without creating a migration.
|
## Sorting and Filtering
|
||||||
|
|
||||||
Use repositories or database access modules. Do not place raw database queries directly in UI components or high-level route handlers.
|
Filtering should work through column headers.
|
||||||
|
|
||||||
## API Guidelines
|
Sorting should work through column headers.
|
||||||
|
|
||||||
Keep API routes resource-oriented.
|
Sorting moves complete circuits as blocks.
|
||||||
|
|
||||||
Example routes:
|
Sorting must not split device rows away from their circuit.
|
||||||
|
|
||||||
```text
|
Sorting does not renumber.
|
||||||
GET /api/projects
|
|
||||||
POST /api/projects
|
|
||||||
GET /api/projects/:projectId
|
|
||||||
PUT /api/projects/:projectId
|
|
||||||
DELETE /api/projects/:projectId
|
|
||||||
|
|
||||||
GET /api/projects/:projectId/power-balances
|
The user may explicitly renumber after sorting.
|
||||||
POST /api/projects/:projectId/power-balances
|
|
||||||
|
|
||||||
GET /api/power-balances/:powerBalanceId/consumers
|
## Linked Project Devices
|
||||||
POST /api/power-balances/:powerBalanceId/consumers
|
|
||||||
PUT /api/consumers/:consumerId
|
|
||||||
DELETE /api/consumers/:consumerId
|
|
||||||
```
|
|
||||||
|
|
||||||
Validate all incoming API data.
|
Circuit device rows may be linked to project devices.
|
||||||
|
|
||||||
Use shared validation schemas if possible.
|
`displayName` is copied on insert but not synchronized automatically.
|
||||||
|
|
||||||
## UI Guidelines
|
When a project device changes, show affected linked rows and let the user choose which fields to sync.
|
||||||
|
|
||||||
The UI should be practical and data-entry friendly.
|
Never silently overwrite local changes.
|
||||||
|
|
||||||
Prioritize:
|
Allow disconnecting linked rows from project devices.
|
||||||
|
|
||||||
- Tables for consumers
|
## Manual Rows
|
||||||
- Inline editing where useful
|
|
||||||
- Clear grouping by distribution board or area
|
|
||||||
- Totals at group and project level
|
|
||||||
- German UI labels
|
|
||||||
- Consistent units in column headers
|
|
||||||
- Minimal clicks for adding multiple consumers
|
|
||||||
|
|
||||||
Use German labels such as:
|
Manual rows are allowed and common.
|
||||||
|
|
||||||
- Projekt
|
Manual rows can later be saved as project devices.
|
||||||
- Leistungsbilanz
|
|
||||||
- Verteilung
|
|
||||||
- Verbraucher
|
|
||||||
- Anzahl
|
|
||||||
- Leistung je Stück
|
|
||||||
- Installierte Leistung
|
|
||||||
- Gleichzeitigkeitsfaktor
|
|
||||||
- Berechnete Leistung
|
|
||||||
- Bemerkung
|
|
||||||
|
|
||||||
Code identifiers must remain English.
|
After saving, the row becomes linked to the new project device.
|
||||||
|
|
||||||
## Testing Guidelines
|
## Undo / Redo
|
||||||
|
|
||||||
Add tests for calculation logic.
|
Implement undo/redo for structural and destructive operations.
|
||||||
|
|
||||||
Calculation tests are more important than superficial UI tests.
|
Required operations:
|
||||||
|
|
||||||
At minimum, test:
|
- 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
|
||||||
|
|
||||||
- Total installed power calculation
|
## Future Sizing
|
||||||
- Demand power calculation
|
|
||||||
- Quantity handling
|
|
||||||
- Single-phase current calculation, if implemented
|
|
||||||
- Three-phase current calculation, if implemented
|
|
||||||
- Edge cases such as quantity 0, demand factor 0, and missing optional values
|
|
||||||
|
|
||||||
Do not change formulas without updating or adding tests.
|
Do not implement full cable/protection sizing unless explicitly requested.
|
||||||
|
|
||||||
## Docker and Development
|
Keep the structure ready for it.
|
||||||
|
|
||||||
The project should be runnable in a local development environment, including on Windows with Docker Desktop.
|
Future sizing will need:
|
||||||
|
|
||||||
If Docker is used, provide:
|
- circuit total power
|
||||||
|
- phase type
|
||||||
|
- voltage
|
||||||
|
- cosPhi
|
||||||
|
- cable length
|
||||||
|
- cable type
|
||||||
|
- cable cross-section
|
||||||
|
- protection rated current
|
||||||
|
- control requirement such as DALI
|
||||||
|
|
||||||
- `Dockerfile`
|
Users must be able to override sizing suggestions.
|
||||||
- `docker-compose.yml`
|
|
||||||
- clear volume handling for SQLite database files
|
|
||||||
- documented development commands
|
|
||||||
|
|
||||||
Avoid configurations that only work on Linux unless explicitly documented.
|
## Response Style for Codex
|
||||||
|
|
||||||
## Documentation Expectations
|
Be concise.
|
||||||
|
|
||||||
Keep documentation short but useful.
|
Do not restate the whole specification.
|
||||||
|
|
||||||
Document:
|
Reference the relevant file and section.
|
||||||
|
|
||||||
- How to install dependencies
|
When uncertain, choose the simplest implementation that preserves the domain model.
|
||||||
- How to start the dev server
|
|
||||||
- How to run migrations
|
|
||||||
- How to run tests
|
|
||||||
- Basic domain assumptions
|
|
||||||
- Important formulas
|
|
||||||
|
|
||||||
Prefer concise Markdown documentation.
|
Do not add libraries unless there is a clear reason.
|
||||||
|
|
||||||
## Development Progress Documentation
|
Do not introduce global state management unless needed.
|
||||||
|
|
||||||
Document the current implementation status in dedicated Markdown files whenever regular status updates are requested.
|
|
||||||
|
|
||||||
- Keep status tracking explicit with `TODO`, `WIP`, and `DONE` sections.
|
|
||||||
- For each relevant module or feature area, document:
|
|
||||||
- what it does,
|
|
||||||
- how it works,
|
|
||||||
- which files/functions are involved,
|
|
||||||
- why important design choices were made,
|
|
||||||
- current limitations or open points.
|
|
||||||
- Break larger features into small sub-sections so someone new can read through and understand the flow.
|
|
||||||
- Update these Markdown status documents incrementally during implementation so progress can be tracked clearly over time.
|
|
||||||
- Prefer understandable, step-by-step explanations over overly brief summaries when needed for clarity.
|
|
||||||
## Coding Style
|
|
||||||
|
|
||||||
Write clear, explicit TypeScript.
|
|
||||||
|
|
||||||
Prefer readability over cleverness.
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
|
|
||||||
- unnecessary generic abstractions
|
|
||||||
- magic numbers
|
|
||||||
- hidden side effects
|
|
||||||
- large files with unrelated responsibilities
|
|
||||||
- mixing UI, database, and calculation logic
|
|
||||||
|
|
||||||
Use meaningful names even if they are longer.
|
|
||||||
|
|
||||||
## Safety and Data Integrity
|
|
||||||
|
|
||||||
Do not delete user data without explicit confirmation in the UI or API design.
|
|
||||||
|
|
||||||
Use soft-delete only if the project introduces audit or recovery requirements.
|
|
||||||
|
|
||||||
Validate numeric values carefully:
|
|
||||||
|
|
||||||
- quantity must not be negative
|
|
||||||
- demand factor should normally be between 0 and 1
|
|
||||||
- installed power must not be negative
|
|
||||||
- voltage must be positive
|
|
||||||
- phase count should be limited to valid values
|
|
||||||
|
|
||||||
## Agent Behavior
|
|
||||||
|
|
||||||
When modifying this repository:
|
|
||||||
|
|
||||||
1. Inspect the existing structure before adding new files.
|
|
||||||
2. Reuse existing patterns unless they are clearly wrong.
|
|
||||||
3. Keep changes small and focused.
|
|
||||||
4. Do not introduce large framework changes without explicit instruction.
|
|
||||||
5. Do not silently change the database technology.
|
|
||||||
6. Do not silently change the ORM.
|
|
||||||
7. Keep domain terms consistent.
|
|
||||||
8. Add or update tests when changing calculation logic.
|
|
||||||
9. Update this `AGENTS.md` if a new recurring project rule is established.
|
|
||||||
10. Prefer practical implementation over theoretical perfection.
|
|
||||||
|
|
||||||
## Out of Scope Unless Explicitly Requested
|
|
||||||
|
|
||||||
Do not implement the following unless explicitly requested:
|
|
||||||
|
|
||||||
- Multi-tenant user management
|
|
||||||
- Role-based permissions
|
|
||||||
- Cloud deployment
|
|
||||||
- PostgreSQL migration
|
|
||||||
- Realtime collaboration
|
|
||||||
- Complex report designer
|
|
||||||
- Full BIM integration
|
|
||||||
- GAEB integration
|
|
||||||
- Revit integration
|
|
||||||
- Authentication providers
|
|
||||||
- Enterprise audit logging
|
|
||||||
|
|
||||||
## Preferred First Milestone
|
|
||||||
|
|
||||||
The first useful milestone should be:
|
|
||||||
|
|
||||||
- Create a project
|
|
||||||
- Create one power balance
|
|
||||||
- Add distribution boards
|
|
||||||
- Add consumers with quantity
|
|
||||||
- Calculate installed power and demand power
|
|
||||||
- Show totals in the UI
|
|
||||||
- Persist data in SQLite
|
|
||||||
- Provide basic tests for calculation logic
|
|
||||||
|
|
||||||
Do not start with advanced reporting before the core data and calculation workflow works.
|
|
||||||
|
|
||||||
## Current UI Workflow Requirements
|
|
||||||
|
|
||||||
Implement and preserve the following navigation and workflow structure:
|
|
||||||
|
|
||||||
1. A dedicated project page that lists all projects and allows creating new projects.
|
|
||||||
2. On the same project page, users can configure global devices/consumers.
|
|
||||||
3. Inside a project, users first see all distribution boards and can open a selected board.
|
|
||||||
4. Circuit lists are edited in a dedicated view where up to 3 circuit lists can be opened in parallel.
|
|
||||||
5. Users must be able to copy circuit entries/consumers between the open circuit lists with minimal clicks.
|
|
||||||
6. In the circuit-list view, exactly 1 list is open by default. Users can add/remove list panels dynamically with a minimum of 1 and a maximum of 3 open lists.
|
|
||||||
|
|
||||||
When implementing frontend changes, keep this structure as the default interaction model unless the user explicitly requests a different UX.
|
|
||||||
|
|
||||||
## Language and Text Rules
|
|
||||||
|
|
||||||
Use proper German umlauts (ä, ö, ü, Ä, Ö, Ü, ß) in all new or changed German UI texts and documentation text, unless technical constraints explicitly prevent this.
|
|
||||||
|
|
||||||
## Responsiveness Rule
|
|
||||||
|
|
||||||
Frontend implementations must remain fully responsive by default across mobile, tablet, laptop, and wide desktop breakpoints.
|
|
||||||
Layouts with dynamic panel counts (for example 1-3 parallel circuit-list panels) must adapt so available horizontal space is used appropriately instead of leaving fixed empty columns.
|
|
||||||
|
|
||||||
## Language and Text Rules (Enforced)
|
|
||||||
|
|
||||||
Use proper German umlauts (�, �, �, �, �, �, �) in all new or changed German UI texts and documentation text, unless technical constraints explicitly prevent this.
|
|
||||||
|
|
||||||
|
|
||||||
## Project Voltage and Columns Rules
|
|
||||||
|
|
||||||
- Project properties must include default single-phase and three-phase voltages. Use 230 V for single-phase and 400 V for three-phase by default, and allow users to change both values in project settings.
|
|
||||||
- In circuit lists, when a consumer is single-phase and has no explicit voltage override, calculations use the project single-phase default voltage. When a consumer is three-phase and has no explicit voltage override, calculations use the project three-phase default voltage.
|
|
||||||
- When creating a new consumer/device entry, the standard input fields should be: consumer display name, quantity, unit power, demand factor, and total power.
|
|
||||||
- By default, the table should initially hide: power factor (cos phi), phase count, and current.
|
|
||||||
- Users must be able to add any available attribute as a table column at any time, and must be able to reorder column positions.
|
|
||||||
|
|
||||||
## Encoding Rule
|
|
||||||
|
|
||||||
- All text files must be saved as UTF-8.
|
|
||||||
- German UI text must never contain mojibake artifacts (for example geöffnet, wählen, Übernehmen, ←, →).
|
|
||||||
- If such artifacts appear, they must be corrected immediately before merge or handoff.
|
|
||||||
|
|||||||
@@ -0,0 +1,68 @@
|
|||||||
|
# Anforderungs-Abgleich (Dokumentation vs. Code)
|
||||||
|
|
||||||
|
Dieses Dokument ergänzt die Hauptdokumentation und listet transparent auf:
|
||||||
|
|
||||||
|
1. Was laut Anforderungen noch nicht vollständig umgesetzt ist.
|
||||||
|
2. Was bereits im Code existiert, aber im ursprünglichen Requirements-Dokument nicht oder nur als offener Punkt erwähnt war.
|
||||||
|
|
||||||
|
Basisvergleich:
|
||||||
|
- Anforderungen: `docs/electrical-load-balance-requirements-context-dump.md`
|
||||||
|
- Ist-Stand: aktueller Code in `src/`
|
||||||
|
|
||||||
|
## A) Anforderungen, die noch nicht vollständig umgesetzt sind
|
||||||
|
|
||||||
|
### 1) Bericht/Export/Print für Leistungsbilanzen
|
||||||
|
- Erwartung: später nutzbarer Report-Export/Print.
|
||||||
|
- Stand: Noch nicht umgesetzt.
|
||||||
|
- Wirkung: Der Fokus liegt aktuell auf Erfassung, Bearbeitung und Berechnung im Web-UI.
|
||||||
|
|
||||||
|
### 2) „Keine Pflichtfelder“ vollständig im UI-Flow
|
||||||
|
- Erwartung: Einträge sollen auch ohne zwingende Felder erfassbar sein.
|
||||||
|
- Stand: Backend-seitig weitgehend erfüllt (optionale Felder + Defaults), UI-Schnellerfassung verlangt derzeit einen Namen.
|
||||||
|
- Wirkung: Fachlich ist unvollständige Speicherung möglich, aber die Standard-UI bremst diesen speziellen Fall noch.
|
||||||
|
|
||||||
|
### 3) Einheitliche Textqualität (Mojibake-frei) im gesamten Frontend
|
||||||
|
- Erwartung: saubere Umlaute/UTF-8.
|
||||||
|
- Stand: In mehreren UI-Dateien sind weiterhin fehlerhafte Kodierungsreste vorhanden (z. B. „Gerät“).
|
||||||
|
- Wirkung: Funktionalität ist gegeben, UX/Textqualität ist noch nachzuziehen.
|
||||||
|
|
||||||
|
## B) Bereits umgesetzt, aber im ursprünglichen Requirements-Dokument nicht klar ausformuliert
|
||||||
|
|
||||||
|
### 1) Feste Domänen-Auswahllisten sind final definiert
|
||||||
|
- Im Requirements-Dokument war das als „noch festzulegen“ markiert.
|
||||||
|
- Im Code jetzt vorhanden:
|
||||||
|
- `src/shared/constants/consumer-option-lists.ts`
|
||||||
|
- Validierung in `src/shared/validation/consumer.schemas.ts`
|
||||||
|
- Select-Felder in `src/app/projects/[projectId]/circuit-lists/page.tsx`
|
||||||
|
|
||||||
|
### 2) Sortieren, Filtern und Bulk-Edit sind bereits implementiert
|
||||||
|
- Im Requirements-Dokument als mögliche Zusatzfunktion erwähnt.
|
||||||
|
- Im Code umgesetzt in `src/app/projects/[projectId]/circuit-lists/page.tsx`.
|
||||||
|
|
||||||
|
### 3) Projekt-Spannungsstandards (1-phasig / 3-phasig) inkl. Berechnungsintegration
|
||||||
|
- Im Requirements-Dokument nicht so detailliert als Projekt-Feature beschrieben.
|
||||||
|
- Im Code umgesetzt:
|
||||||
|
- Projekteinstellungen im Projekt-Detail
|
||||||
|
- Verwendung in Berechnungslogik (effektive Spannung je Verbraucher)
|
||||||
|
|
||||||
|
### 4) 1–3 parallele Stromkreislisten mit responsiver Aufteilung
|
||||||
|
- Im Requirements-Dokument nicht als konkrete UI-Regel spezifiziert.
|
||||||
|
- Im Code umgesetzt in `src/app/projects/[projectId]/circuit-lists/page.tsx`.
|
||||||
|
|
||||||
|
### 5) Gerätekopie global ↔ projektbezogen in beide Richtungen
|
||||||
|
- Fachlich erwähnt, aber technisch konkretisiert im API-Design:
|
||||||
|
- `POST /api/project-devices/projects/:projectId/import-global/:globalDeviceId`
|
||||||
|
- `POST /api/global-devices/import-project/:projectId/:projectDeviceId`
|
||||||
|
|
||||||
|
## C) Offene fachliche Entscheidungen mit bereits getroffener Code-Interpretation
|
||||||
|
|
||||||
|
### 1) Verhalten beim Kopieren von Stromkreiseinträgen zwischen Listen
|
||||||
|
- Offener Punkt in den Anforderungen: Link beibehalten oder trennen?
|
||||||
|
- Aktuelle Code-Interpretation: Link-Information wird mitkopiert (`projectDeviceId`, `isLinkedToDevice`).
|
||||||
|
- Relevanz: Sollte fachlich explizit bestätigt werden, damit spätere Änderungen keine Regression verursachen.
|
||||||
|
|
||||||
|
## D) Empfehlung für nächste Dokumentationsrunde
|
||||||
|
|
||||||
|
1. Das Requirements-Dokument um die inzwischen finalen Auswahllistenwerte ergänzen.
|
||||||
|
2. Die Kopierlogik (Link beibehalten/trennen) fachlich eindeutig festschreiben.
|
||||||
|
3. Einen eigenen Abschnitt für bekannte UX-/Textqualitätspunkte (Kodierung/Umlaute) ergänzen.
|
||||||
@@ -0,0 +1,38 @@
|
|||||||
|
# Domain Context: Distribution Board Circuit List
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
In electrical building design, especially during detailed design / execution planning, a circuit list is created for each distribution board.
|
||||||
|
|
||||||
|
The circuit list documents all consumers, devices and circuits supplied by or installed in a specific distribution board. It supports:
|
||||||
|
|
||||||
|
- construction of the distribution board by the electrical contractor
|
||||||
|
- execution planning and technical coordination
|
||||||
|
- quantity takeoff for tendering and cost estimation
|
||||||
|
- determination of required protective devices, terminals, modular DIN rail devices and related components
|
||||||
|
- structured documentation of the internal electrical path inside the distribution board
|
||||||
|
|
||||||
|
Although the term "circuit list" is used, the list does not only contain final outgoing circuits. It may also contain or later support devices and functional components such as:
|
||||||
|
|
||||||
|
- main switches
|
||||||
|
- surge protection devices
|
||||||
|
- KNX devices
|
||||||
|
- control devices
|
||||||
|
- modular DIN rail devices
|
||||||
|
- reserve circuits
|
||||||
|
- other distribution board components
|
||||||
|
|
||||||
|
## Important Domain Rule
|
||||||
|
|
||||||
|
A circuit list entry is not always just a single independent circuit.
|
||||||
|
|
||||||
|
A circuit can contain one or more device rows.
|
||||||
|
|
||||||
|
If a circuit contains one device, it can be displayed as one compact row.
|
||||||
|
|
||||||
|
If a circuit contains multiple devices, the UI displays:
|
||||||
|
|
||||||
|
- one circuit summary row
|
||||||
|
- one or more indented device rows below it
|
||||||
|
|
||||||
|
Circuit-level data such as protection device, cable type and cable length belongs to the circuit, not to each individual device.
|
||||||
@@ -0,0 +1,144 @@
|
|||||||
|
# Functional Requirements: Circuit List Inside a Distribution Board
|
||||||
|
|
||||||
|
## Scope
|
||||||
|
|
||||||
|
This specification focuses only on the circuit list inside one distribution board.
|
||||||
|
|
||||||
|
Out of scope for this document:
|
||||||
|
|
||||||
|
- project management
|
||||||
|
- user accounts
|
||||||
|
- permissions
|
||||||
|
- full tender export
|
||||||
|
- CAD integration
|
||||||
|
- full norm-compliant electrical calculation
|
||||||
|
- cloud deployment
|
||||||
|
|
||||||
|
The first goal is a fast, spreadsheet-like editor for creating, editing, sorting and restructuring circuit lists.
|
||||||
|
|
||||||
|
## Sections
|
||||||
|
|
||||||
|
The circuit list is grouped into sections.
|
||||||
|
|
||||||
|
Default sections:
|
||||||
|
|
||||||
|
| Section | Default prefix |
|
||||||
|
|---|---|
|
||||||
|
| Lighting | `-1F` |
|
||||||
|
| Single-phase circuits | `-2F` |
|
||||||
|
| Three-phase circuits | `-3F` |
|
||||||
|
|
||||||
|
Sections are displayed as separator rows in the table, not as normal visible data columns.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Lighting
|
||||||
|
-1F1 Beleuchtung Flur
|
||||||
|
-1F2 Beleuchtung Außen
|
||||||
|
|
||||||
|
Single-phase circuits
|
||||||
|
-2F1 Arbeitsplatzsteckdosen Büro
|
||||||
|
-2F2 Handtrockner WC
|
||||||
|
|
||||||
|
Three-phase circuits
|
||||||
|
-3F1 Durchlauferhitzer
|
||||||
|
```
|
||||||
|
|
||||||
|
Internally, every circuit belongs to a section. In the UI, the section is shown as a grouping separator.
|
||||||
|
|
||||||
|
## Future Section Configuration
|
||||||
|
|
||||||
|
Sections and numbering prefixes should later be configurable per project.
|
||||||
|
|
||||||
|
Future project configurations may support:
|
||||||
|
|
||||||
|
- one continuous numbering sequence without lighting/single-phase/three-phase separation
|
||||||
|
- numbering grouped by RCD
|
||||||
|
- numbering grouped by functional area
|
||||||
|
- custom prefixes and suffixes
|
||||||
|
- custom section names
|
||||||
|
|
||||||
|
The first implementation may use the default sections, but the structure must not permanently hardcode them.
|
||||||
|
|
||||||
|
## Circuit Numbering / Equipment Identifiers
|
||||||
|
|
||||||
|
Each circuit has an equipment identifier.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- `-1F1`
|
||||||
|
- `-1F2`
|
||||||
|
- `-2F1`
|
||||||
|
- `-2F2`
|
||||||
|
- `-3F1`
|
||||||
|
|
||||||
|
Default convention:
|
||||||
|
|
||||||
|
- `-1Fx` = lighting circuits
|
||||||
|
- `-2Fx` = single-phase circuits
|
||||||
|
- `-3Fx` = three-phase circuits
|
||||||
|
|
||||||
|
When a new circuit is created, the next identifier is calculated as:
|
||||||
|
|
||||||
|
```text
|
||||||
|
highest existing number in the section + 1
|
||||||
|
```
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
Existing identifiers in single-phase section:
|
||||||
|
|
||||||
|
- `-2F1`
|
||||||
|
- `-2F2`
|
||||||
|
- `-2F5`
|
||||||
|
|
||||||
|
New circuit receives:
|
||||||
|
|
||||||
|
- `-2F6`
|
||||||
|
|
||||||
|
Gaps are not filled automatically.
|
||||||
|
|
||||||
|
Gaps may be closed only by:
|
||||||
|
|
||||||
|
- manually editing equipment identifiers
|
||||||
|
- explicitly using a renumbering action
|
||||||
|
|
||||||
|
## Renumbering
|
||||||
|
|
||||||
|
The app must never automatically renumber existing circuits after:
|
||||||
|
|
||||||
|
- inserting a circuit
|
||||||
|
- deleting a circuit
|
||||||
|
- moving a circuit
|
||||||
|
- moving a device
|
||||||
|
- sorting a section
|
||||||
|
- dragging rows
|
||||||
|
- changing a device
|
||||||
|
- synchronizing a linked project device
|
||||||
|
|
||||||
|
Renumbering only happens through an explicit user action.
|
||||||
|
|
||||||
|
Each section has a "Renumber section" action.
|
||||||
|
|
||||||
|
The renumbering action:
|
||||||
|
|
||||||
|
- keeps the current visual order
|
||||||
|
- updates only circuits in that section
|
||||||
|
- ignores device rows for numbering
|
||||||
|
- does not affect other sections
|
||||||
|
- uses the section prefix
|
||||||
|
|
||||||
|
## Reserve / Empty Circuits
|
||||||
|
|
||||||
|
Empty circuits are allowed.
|
||||||
|
|
||||||
|
An empty circuit may be used as a reserve circuit.
|
||||||
|
|
||||||
|
If the last device is removed from a circuit, the user may choose:
|
||||||
|
|
||||||
|
- keep empty circuit as reserve
|
||||||
|
- delete circuit completely
|
||||||
|
- cancel
|
||||||
|
|
||||||
|
Reserve circuits remain visible and keep their equipment identifier unless manually changed or explicitly renumbered.
|
||||||
@@ -0,0 +1,171 @@
|
|||||||
|
# Data Model Concept
|
||||||
|
|
||||||
|
This is a conceptual model for Codex. It is not a final database schema, but the implementation must preserve these domain relationships.
|
||||||
|
|
||||||
|
## Core Concept
|
||||||
|
|
||||||
|
A distribution board contains a circuit list.
|
||||||
|
|
||||||
|
A circuit list contains sections.
|
||||||
|
|
||||||
|
A section contains circuits.
|
||||||
|
|
||||||
|
A circuit contains zero, one or multiple device rows.
|
||||||
|
|
||||||
|
A device row may be:
|
||||||
|
|
||||||
|
- linked to a project device
|
||||||
|
- manually entered without a linked project device
|
||||||
|
|
||||||
|
## ProjectDevice
|
||||||
|
|
||||||
|
A project device is a reusable project-specific consumer or consumer group.
|
||||||
|
|
||||||
|
A project device can represent:
|
||||||
|
|
||||||
|
- one physical device
|
||||||
|
- a recurring device type
|
||||||
|
- a consumer group, for example six workstation sockets
|
||||||
|
|
||||||
|
User-facing fields:
|
||||||
|
|
||||||
|
- `name`
|
||||||
|
- `displayName`
|
||||||
|
- `phaseType`
|
||||||
|
- `connectionKind`
|
||||||
|
- `costGroup`
|
||||||
|
- `category`
|
||||||
|
- `quantity`
|
||||||
|
- `powerPerUnit`
|
||||||
|
- `simultaneityFactor`
|
||||||
|
- `cosPhi`
|
||||||
|
- `totalPower`
|
||||||
|
- `remark`
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
|
||||||
|
- `name` is the technical or product-related name, for example `E-Line Pro`.
|
||||||
|
- `displayName` is a default display name used when inserting the device into the circuit list.
|
||||||
|
- After insertion, the circuit list display name is local and not automatically synchronized.
|
||||||
|
- `quantity` is allowed on project devices because a project device may represent a consumer group.
|
||||||
|
- Project devices must not define final cable or protection data.
|
||||||
|
|
||||||
|
## Circuit
|
||||||
|
|
||||||
|
A circuit represents one outgoing circuit / equipment identifier in a distribution board section.
|
||||||
|
|
||||||
|
User-facing fields:
|
||||||
|
|
||||||
|
- `equipmentIdentifier`
|
||||||
|
- `section`
|
||||||
|
- `displayName` optional
|
||||||
|
- `circuitTotalPower`
|
||||||
|
- `protectionType`
|
||||||
|
- `protectionRatedCurrent`
|
||||||
|
- `protectionCharacteristic`
|
||||||
|
- `cableType`
|
||||||
|
- `cableCrossSection`
|
||||||
|
- `cableLength`
|
||||||
|
- `rcdAssignment` optional
|
||||||
|
- `terminalDesignation` optional
|
||||||
|
- `voltage` optional
|
||||||
|
- `status` optional
|
||||||
|
- `isReserve` optional
|
||||||
|
- `remark` optional
|
||||||
|
|
||||||
|
Circuit-level fields only:
|
||||||
|
|
||||||
|
- protection type
|
||||||
|
- protection rated current
|
||||||
|
- protection characteristic
|
||||||
|
- cable type
|
||||||
|
- cable cross-section
|
||||||
|
- cable length
|
||||||
|
- RCD assignment
|
||||||
|
- terminal designation
|
||||||
|
- circuit total power
|
||||||
|
|
||||||
|
Reason:
|
||||||
|
|
||||||
|
Protection and cable data are dimensioned for the complete circuit. They depend on the combined load, installation context, cable length, voltage drop and planning rules.
|
||||||
|
|
||||||
|
## CircuitDeviceRow
|
||||||
|
|
||||||
|
A circuit device row represents a device assigned to a circuit.
|
||||||
|
|
||||||
|
User-facing fields:
|
||||||
|
|
||||||
|
- `linkedProjectDeviceId` optional
|
||||||
|
- `name`
|
||||||
|
- `displayName`
|
||||||
|
- `phaseType`
|
||||||
|
- `connectionKind` optional
|
||||||
|
- `costGroup` optional
|
||||||
|
- `category` optional
|
||||||
|
- `level`
|
||||||
|
- `roomNumber`
|
||||||
|
- `roomName`
|
||||||
|
- `quantity`
|
||||||
|
- `powerPerUnit`
|
||||||
|
- `simultaneityFactor`
|
||||||
|
- `cosPhi`
|
||||||
|
- `rowTotalPower`
|
||||||
|
- `remark`
|
||||||
|
- `overriddenFields`
|
||||||
|
|
||||||
|
A circuit device row can be manual.
|
||||||
|
|
||||||
|
A manual row has no linked project device.
|
||||||
|
|
||||||
|
A manual row can later be saved as a project device. After saving, the row becomes linked to the newly created project device.
|
||||||
|
|
||||||
|
## Single-Device vs Multi-Device Display
|
||||||
|
|
||||||
|
If a circuit has exactly one device row, it is displayed as one compact circuit row.
|
||||||
|
|
||||||
|
If a circuit has multiple device rows, it is displayed as:
|
||||||
|
|
||||||
|
- one circuit summary row
|
||||||
|
- indented device rows below it
|
||||||
|
|
||||||
|
The circuit summary row shows:
|
||||||
|
|
||||||
|
- equipment identifier
|
||||||
|
- optional circuit display name
|
||||||
|
- circuit total power
|
||||||
|
- circuit-level protection data
|
||||||
|
- circuit-level cable data
|
||||||
|
|
||||||
|
The device rows show:
|
||||||
|
|
||||||
|
- individual device values
|
||||||
|
- quantity
|
||||||
|
- power
|
||||||
|
- cost group
|
||||||
|
- category
|
||||||
|
- room data
|
||||||
|
- remarks
|
||||||
|
|
||||||
|
## Load Calculation
|
||||||
|
|
||||||
|
Device row load:
|
||||||
|
|
||||||
|
```text
|
||||||
|
rowTotalPower = quantity × powerPerUnit × simultaneityFactor
|
||||||
|
```
|
||||||
|
|
||||||
|
Circuit total:
|
||||||
|
|
||||||
|
```text
|
||||||
|
circuitTotalPower = sum(rowTotalPower of all device rows assigned to the circuit)
|
||||||
|
```
|
||||||
|
|
||||||
|
`cosPhi` is stored even if it is not visible in the default table view.
|
||||||
|
|
||||||
|
Later apparent power calculation:
|
||||||
|
|
||||||
|
```text
|
||||||
|
apparentPower = totalActivePower / cosPhi
|
||||||
|
```
|
||||||
|
|
||||||
|
For circuits with multiple devices, apparent power should be calculated per device row and then summed. This avoids losing information when different devices have different power factors.
|
||||||
@@ -0,0 +1,304 @@
|
|||||||
|
# UI and Interaction Requirements
|
||||||
|
|
||||||
|
## UI Philosophy
|
||||||
|
|
||||||
|
The circuit list editor should feel spreadsheet-like and efficient.
|
||||||
|
|
||||||
|
The main interaction surface is the table itself.
|
||||||
|
|
||||||
|
The table should not look like a form with permanently visible input fields in every cell.
|
||||||
|
|
||||||
|
Cells are displayed as static text by default and become editable only when the user intentionally edits them.
|
||||||
|
|
||||||
|
The editor should support both:
|
||||||
|
|
||||||
|
- efficient keyboard-based editing
|
||||||
|
- low-click mouse interaction
|
||||||
|
- drag-and-drop workflows
|
||||||
|
|
||||||
|
## Cell Editing
|
||||||
|
|
||||||
|
Cells are displayed as static text by default.
|
||||||
|
|
||||||
|
A cell enters edit mode when the user:
|
||||||
|
|
||||||
|
- double-clicks it
|
||||||
|
- presses Enter while it is selected
|
||||||
|
- starts typing while it is selected
|
||||||
|
- presses F2 while it is selected
|
||||||
|
|
||||||
|
Editing behavior:
|
||||||
|
|
||||||
|
- Enter confirms the edit
|
||||||
|
- Tab confirms and moves to the next editable cell
|
||||||
|
- Shift + Tab confirms and moves to the previous editable cell
|
||||||
|
- Escape cancels the edit
|
||||||
|
- Arrow keys navigate between cells when not editing
|
||||||
|
- Arrow keys move the cursor inside text while editing
|
||||||
|
|
||||||
|
## Row Insertion Shortcuts
|
||||||
|
|
||||||
|
The editor should support fast row insertion.
|
||||||
|
|
||||||
|
Required shortcuts:
|
||||||
|
|
||||||
|
- Ctrl + Plus inserts a new row below the selected row
|
||||||
|
- Ctrl + Shift + Plus should be treated the same where keyboard layouts require Shift for `+`
|
||||||
|
- Insert may optionally insert a new row below the selected row
|
||||||
|
|
||||||
|
Insert behavior:
|
||||||
|
|
||||||
|
- if a circuit or row is selected, insert below it
|
||||||
|
- if no row is selected, insert at the end of the active section
|
||||||
|
- the new row should immediately focus the display name or device cell
|
||||||
|
|
||||||
|
## Project Device Sidebar
|
||||||
|
|
||||||
|
The distribution board editor should show the project device list near the circuit list.
|
||||||
|
|
||||||
|
Preferred layout:
|
||||||
|
|
||||||
|
- left sidebar: searchable project device list
|
||||||
|
- right main area: circuit list table
|
||||||
|
|
||||||
|
The project device sidebar should support:
|
||||||
|
|
||||||
|
- search by name
|
||||||
|
- filter by category
|
||||||
|
- filter by phase type
|
||||||
|
- filter by cost group
|
||||||
|
- showing device name
|
||||||
|
- showing default display name
|
||||||
|
- showing phase type
|
||||||
|
- showing quantity and power if available
|
||||||
|
- dragging devices into the circuit list
|
||||||
|
|
||||||
|
## Drag Project Device into Circuit List
|
||||||
|
|
||||||
|
Project devices can be dragged from the project device sidebar into the circuit list.
|
||||||
|
|
||||||
|
### Drop into a valid section or free circuit placeholder
|
||||||
|
|
||||||
|
Creates a new circuit.
|
||||||
|
|
||||||
|
The new circuit:
|
||||||
|
|
||||||
|
- receives the next equipment identifier of the target section
|
||||||
|
- is inserted at the drop position
|
||||||
|
- contains one device row linked to the dragged project device
|
||||||
|
- receives an initial display name copied from the project device
|
||||||
|
- keeps this copied display name locally
|
||||||
|
|
||||||
|
### Drop onto an existing circuit identifier / circuit target
|
||||||
|
|
||||||
|
Adds the device to that existing circuit.
|
||||||
|
|
||||||
|
The app creates another device row inside that circuit.
|
||||||
|
|
||||||
|
The device row:
|
||||||
|
|
||||||
|
- has no own equipment identifier
|
||||||
|
- is linked to the project device
|
||||||
|
- contributes to the circuit total power
|
||||||
|
- appears indented when the circuit contains multiple devices
|
||||||
|
|
||||||
|
## Free Circuit Placeholder
|
||||||
|
|
||||||
|
Each section should show a free circuit placeholder at the end.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
```text
|
||||||
|
Lighting
|
||||||
|
-1F1 Beleuchtung Flur
|
||||||
|
-1F2 Beleuchtung Außen
|
||||||
|
-frei-
|
||||||
|
```
|
||||||
|
|
||||||
|
If a device is dropped onto `-frei-`, a new circuit is created.
|
||||||
|
|
||||||
|
After creation, a new `-frei-` placeholder appears at the end of the section.
|
||||||
|
|
||||||
|
## Valid Drop Zones
|
||||||
|
|
||||||
|
A project device may only be dropped into technically valid sections.
|
||||||
|
|
||||||
|
Default rules:
|
||||||
|
|
||||||
|
| Condition | Valid section | Prefix |
|
||||||
|
|---|---|---|
|
||||||
|
| Category = Lighting | Lighting | `-1F` |
|
||||||
|
| Phase type = single-phase and not Lighting | Single-phase circuits | `-2F` |
|
||||||
|
| Phase type = three-phase and not Lighting | Three-phase circuits | `-3F` |
|
||||||
|
|
||||||
|
Invalid drop targets should visually reject the dragged item.
|
||||||
|
|
||||||
|
If the user tries to move a device into another section, show a confirmation dialog.
|
||||||
|
|
||||||
|
The dialog should explain that moving to another section may change technical classification fields such as:
|
||||||
|
|
||||||
|
- phase type
|
||||||
|
- category
|
||||||
|
- numbering section
|
||||||
|
|
||||||
|
The user can confirm or cancel.
|
||||||
|
|
||||||
|
The app must not silently change project device data.
|
||||||
|
|
||||||
|
## Drag Handle Behavior
|
||||||
|
|
||||||
|
Different drag start areas trigger different behavior.
|
||||||
|
|
||||||
|
### Drag from equipment identifier / circuit handle
|
||||||
|
|
||||||
|
Moves the entire circuit.
|
||||||
|
|
||||||
|
All device rows assigned to the circuit move together.
|
||||||
|
|
||||||
|
The equipment identifier remains unchanged.
|
||||||
|
|
||||||
|
### Drag from device area
|
||||||
|
|
||||||
|
Moves only the selected device row or selected device rows.
|
||||||
|
|
||||||
|
A device can be:
|
||||||
|
|
||||||
|
- reordered inside the same circuit
|
||||||
|
- moved to another existing circuit
|
||||||
|
- moved into the next free circuit placeholder
|
||||||
|
- moved to another valid section after confirmation
|
||||||
|
|
||||||
|
## Moving Devices Between Circuits
|
||||||
|
|
||||||
|
A device row can be moved from one circuit to another.
|
||||||
|
|
||||||
|
When moved:
|
||||||
|
|
||||||
|
- it is removed from the old circuit
|
||||||
|
- it is assigned to the new circuit
|
||||||
|
- it keeps its own device values
|
||||||
|
- it contributes to the new circuit total
|
||||||
|
- both old and new circuit totals are recalculated
|
||||||
|
- no automatic renumbering happens
|
||||||
|
|
||||||
|
## Convert Device to Own Circuit
|
||||||
|
|
||||||
|
A device row can be moved to a free circuit placeholder.
|
||||||
|
|
||||||
|
When this happens:
|
||||||
|
|
||||||
|
- a new circuit is created
|
||||||
|
- the device becomes the first device row of the new circuit
|
||||||
|
- the new circuit receives the next equipment identifier in the section
|
||||||
|
- a new free placeholder appears at the end
|
||||||
|
|
||||||
|
## Multi-Row Selection and Dragging
|
||||||
|
|
||||||
|
The table should support selecting multiple rows.
|
||||||
|
|
||||||
|
Selection behavior:
|
||||||
|
|
||||||
|
- Ctrl + click selects or deselects individual rows
|
||||||
|
- Shift + click selects a continuous row range
|
||||||
|
- selected rows can be dragged together
|
||||||
|
|
||||||
|
When multiple selected device rows are moved:
|
||||||
|
|
||||||
|
- they remain together
|
||||||
|
- their internal order is preserved
|
||||||
|
- they are inserted as one block
|
||||||
|
|
||||||
|
When multiple selected circuits are moved:
|
||||||
|
|
||||||
|
- each selected circuit moves with all assigned device rows
|
||||||
|
- internal circuit/device structure is preserved
|
||||||
|
- equipment identifiers remain unchanged unless explicitly renumbered
|
||||||
|
|
||||||
|
Dropping rows at the end of a section compacts visual row order. It does not renumber equipment identifiers.
|
||||||
|
|
||||||
|
## Delete Behavior
|
||||||
|
|
||||||
|
Deleting a device row deletes only that device.
|
||||||
|
|
||||||
|
The circuit itself remains as long as at least one device is assigned to it.
|
||||||
|
|
||||||
|
If the first visible device of a circuit is deleted and other devices remain, the next device moves up visually.
|
||||||
|
|
||||||
|
If the last device of a circuit is deleted, ask the user whether to:
|
||||||
|
|
||||||
|
- keep the empty circuit as reserve
|
||||||
|
- delete the circuit completely
|
||||||
|
- cancel
|
||||||
|
|
||||||
|
Deleting never triggers automatic renumbering.
|
||||||
|
|
||||||
|
## Filtering and Sorting
|
||||||
|
|
||||||
|
The table should support Excel-like filtering and sorting through column headers.
|
||||||
|
|
||||||
|
### Filtering
|
||||||
|
|
||||||
|
Each column header can open a filter menu.
|
||||||
|
|
||||||
|
The filter menu shows available values in that column.
|
||||||
|
|
||||||
|
The user can select one or more values.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- filter by room number
|
||||||
|
- filter by room name
|
||||||
|
- filter by cost group
|
||||||
|
- filter by category
|
||||||
|
- filter by phase type
|
||||||
|
- filter by connection type
|
||||||
|
|
||||||
|
### Sorting
|
||||||
|
|
||||||
|
Each column can be sorted ascending or descending.
|
||||||
|
|
||||||
|
Sorting via table headers sorts complete circuits as blocks.
|
||||||
|
|
||||||
|
A circuit and its assigned device rows stay together.
|
||||||
|
|
||||||
|
Sorting must not split devices away from their circuit.
|
||||||
|
|
||||||
|
Sorting changes only the visual order.
|
||||||
|
|
||||||
|
Equipment identifiers are not changed by sorting.
|
||||||
|
|
||||||
|
After sorting, the user may explicitly press "Renumber section".
|
||||||
|
|
||||||
|
## Column Configuration
|
||||||
|
|
||||||
|
The table should support configurable columns.
|
||||||
|
|
||||||
|
Users can:
|
||||||
|
|
||||||
|
- show columns
|
||||||
|
- hide columns
|
||||||
|
- reorder columns by drag and drop
|
||||||
|
- reset to default column layout
|
||||||
|
|
||||||
|
Column visibility and order should be stored per user or per project.
|
||||||
|
|
||||||
|
Hidden columns remain stored and available for calculations.
|
||||||
|
|
||||||
|
## Undo / Redo
|
||||||
|
|
||||||
|
Undo and redo should be implemented from the beginning for structural and destructive operations.
|
||||||
|
|
||||||
|
At minimum, undo / redo must support:
|
||||||
|
|
||||||
|
- insert circuit
|
||||||
|
- insert device
|
||||||
|
- delete circuit
|
||||||
|
- delete device
|
||||||
|
- move circuit
|
||||||
|
- move device
|
||||||
|
- move multiple selected rows
|
||||||
|
- renumber section
|
||||||
|
- edit equipment identifier
|
||||||
|
- edit cell value
|
||||||
|
- synchronize linked project device fields
|
||||||
|
- disconnect linked project device
|
||||||
@@ -0,0 +1,127 @@
|
|||||||
|
# Linked Project Devices and Synchronization
|
||||||
|
|
||||||
|
## Concept
|
||||||
|
|
||||||
|
Circuit device rows may be linked to project devices.
|
||||||
|
|
||||||
|
Manual rows may exist without a linked project device.
|
||||||
|
|
||||||
|
A manual row can later be saved as a project device.
|
||||||
|
|
||||||
|
## Name vs Display Name
|
||||||
|
|
||||||
|
Project devices and circuit list device rows use separate naming fields.
|
||||||
|
|
||||||
|
### ProjectDevice.name
|
||||||
|
|
||||||
|
The technical or product-related name.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- `E-Line Pro`
|
||||||
|
- `Arbeitsplatzsteckdosen`
|
||||||
|
- `Durchlauferhitzer 21 kW`
|
||||||
|
|
||||||
|
This field may be synchronized to linked circuit list rows where a technical source name is shown.
|
||||||
|
|
||||||
|
### ProjectDevice.displayName
|
||||||
|
|
||||||
|
A default display name used when inserting the device into a circuit list.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
|
||||||
|
- `Lichtband`
|
||||||
|
- `Arbeitsplatzsteckdosen`
|
||||||
|
- `Handtrockner`
|
||||||
|
|
||||||
|
### CircuitDeviceRow.displayName
|
||||||
|
|
||||||
|
The circuit-list-specific display name.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- `Lichtband Seminarraum`
|
||||||
|
- `Beleuchtung Flur`
|
||||||
|
- `Steckdosen Arbeitsplatz Büro 2.14`
|
||||||
|
|
||||||
|
When a project device is inserted, the row display name is prefilled from the project device.
|
||||||
|
|
||||||
|
After insertion, `displayName` remains local and must not be synchronized automatically.
|
||||||
|
|
||||||
|
## Default Synchronization Rule
|
||||||
|
|
||||||
|
By default, these fields may be synchronized from project device to linked circuit list rows:
|
||||||
|
|
||||||
|
- `name`
|
||||||
|
- `phaseType`
|
||||||
|
- `connectionKind`
|
||||||
|
- `costGroup`
|
||||||
|
- `category`
|
||||||
|
- `quantity`
|
||||||
|
- `powerPerUnit`
|
||||||
|
- `simultaneityFactor`
|
||||||
|
- `cosPhi`
|
||||||
|
- `totalPower`
|
||||||
|
- `remark`
|
||||||
|
|
||||||
|
Default excluded field:
|
||||||
|
|
||||||
|
- `displayName`
|
||||||
|
|
||||||
|
## Synchronization Dialog
|
||||||
|
|
||||||
|
When a project device is changed, the app should show a synchronization dialog.
|
||||||
|
|
||||||
|
The dialog should display affected linked rows.
|
||||||
|
|
||||||
|
For each affected row, show:
|
||||||
|
|
||||||
|
- distribution board
|
||||||
|
- section
|
||||||
|
- circuit identifier
|
||||||
|
- row display name
|
||||||
|
- changed fields
|
||||||
|
- current row value
|
||||||
|
- new project device value
|
||||||
|
- whether the row value was locally overridden
|
||||||
|
|
||||||
|
The user can choose:
|
||||||
|
|
||||||
|
- apply change to one linked row
|
||||||
|
- apply change to all linked rows
|
||||||
|
- exclude specific fields
|
||||||
|
- disconnect selected linked rows from the project device
|
||||||
|
- cancel synchronization
|
||||||
|
|
||||||
|
The app must not silently overwrite locally edited values without user control.
|
||||||
|
|
||||||
|
## Local Overrides
|
||||||
|
|
||||||
|
A linked circuit device row may override inherited values locally.
|
||||||
|
|
||||||
|
The implementation should track overridden fields.
|
||||||
|
|
||||||
|
If a field is locally overridden, the synchronization dialog should mark it clearly.
|
||||||
|
|
||||||
|
The user may still choose to overwrite it.
|
||||||
|
|
||||||
|
## Disconnecting a Linked Device
|
||||||
|
|
||||||
|
A linked device row can be disconnected from its source project device.
|
||||||
|
|
||||||
|
After disconnecting:
|
||||||
|
|
||||||
|
- the row remains in the circuit list
|
||||||
|
- existing local values stay unchanged
|
||||||
|
- future changes to the project device no longer affect this row
|
||||||
|
|
||||||
|
## Manual Row to Project Device
|
||||||
|
|
||||||
|
Manual rows can be saved as project devices.
|
||||||
|
|
||||||
|
When this action is used:
|
||||||
|
|
||||||
|
- create a new project device from the row data
|
||||||
|
- link the row to the new project device
|
||||||
|
- preserve the existing circuit list display name
|
||||||
|
- apply synchronization rules from that point onward
|
||||||
@@ -0,0 +1,97 @@
|
|||||||
|
# Future Sizing and Calculation Requirements
|
||||||
|
|
||||||
|
These requirements are not part of the first implementation, but the structure should support them.
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
The app should later support rule-based protection and cable sizing.
|
||||||
|
|
||||||
|
Future suggestions or checks may include:
|
||||||
|
|
||||||
|
- protection device type
|
||||||
|
- rated current
|
||||||
|
- tripping characteristic
|
||||||
|
- cable type
|
||||||
|
- number of cores
|
||||||
|
- cable cross-section
|
||||||
|
- minimum cable cross-section based on current
|
||||||
|
- maximum permissible cable length based on voltage drop
|
||||||
|
- warning messages if cable length, cross-section or protection device do not match
|
||||||
|
|
||||||
|
Users must remain able to manually override suggestions.
|
||||||
|
|
||||||
|
## Initial Design Rule Examples
|
||||||
|
|
||||||
|
These are common planning defaults, not a replacement for full norm-compliant calculation.
|
||||||
|
|
||||||
|
### Lighting Circuits
|
||||||
|
|
||||||
|
Lighting circuits in section `-1Fx` usually use:
|
||||||
|
|
||||||
|
- protection rated current: 10 A
|
||||||
|
- cable cross-section: 1.5 mm²
|
||||||
|
|
||||||
|
Typical cable type:
|
||||||
|
|
||||||
|
- non-DALI lighting: 3x1.5 mm²
|
||||||
|
- DALI-capable lighting: 5x1.5 mm²
|
||||||
|
|
||||||
|
The app should later suggest the cable type based on whether the connected luminaires require DALI or additional control cores.
|
||||||
|
|
||||||
|
### Standard Single-Phase Circuits
|
||||||
|
|
||||||
|
Standard single-phase circuits in section `-2Fx` usually use:
|
||||||
|
|
||||||
|
- protection rated current: 16 A
|
||||||
|
- cable cross-section: 2.5 mm²
|
||||||
|
|
||||||
|
This applies to many typical socket circuits and standard single-phase loads.
|
||||||
|
|
||||||
|
### Special Loads and Long Cable Runs
|
||||||
|
|
||||||
|
For non-standard loads or long cable runs, voltage drop becomes more important.
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
|
||||||
|
- instantaneous water heaters
|
||||||
|
- socket combinations with higher connected load
|
||||||
|
- outdoor circuits with long cable routes
|
||||||
|
- lighting circuits with looped-through luminaires and cable lengths of 80 to 100 m
|
||||||
|
|
||||||
|
The app should later show warnings or require review if voltage drop becomes critical.
|
||||||
|
|
||||||
|
## Future Field: Control Requirement
|
||||||
|
|
||||||
|
To support cable suggestions for lighting circuits, devices or circuits may later include a control requirement.
|
||||||
|
|
||||||
|
Example values:
|
||||||
|
|
||||||
|
- none
|
||||||
|
- DALI
|
||||||
|
- KNX
|
||||||
|
- switched only
|
||||||
|
- dimmable
|
||||||
|
- other
|
||||||
|
|
||||||
|
For lighting circuits:
|
||||||
|
|
||||||
|
- no additional control cores: suggest 3x1.5 mm²
|
||||||
|
- DALI required: suggest 5x1.5 mm²
|
||||||
|
|
||||||
|
This must be configurable and manually overridable.
|
||||||
|
|
||||||
|
## Future Voltage Drop Check
|
||||||
|
|
||||||
|
A future voltage drop check may use:
|
||||||
|
|
||||||
|
- phase type
|
||||||
|
- voltage
|
||||||
|
- circuit total power
|
||||||
|
- apparent power or current
|
||||||
|
- cable material
|
||||||
|
- cable cross-section
|
||||||
|
- cable length
|
||||||
|
- protection rated current
|
||||||
|
- allowed voltage drop
|
||||||
|
|
||||||
|
The result should be shown as a warning or status indicator, not as an automatic forced change.
|
||||||
@@ -0,0 +1,241 @@
|
|||||||
|
# Implementation Phases and Todo List
|
||||||
|
|
||||||
|
## Important Strategy
|
||||||
|
|
||||||
|
There is already an existing codebase.
|
||||||
|
|
||||||
|
Do not blindly continue with the current implementation if it conflicts with this specification.
|
||||||
|
|
||||||
|
Do not blindly delete the current codebase either.
|
||||||
|
|
||||||
|
First audit the existing code against this specification, then refactor or replace the parts that conflict with the target model.
|
||||||
|
|
||||||
|
The most important architectural correction is:
|
||||||
|
|
||||||
|
A circuit is not the same thing as one device row.
|
||||||
|
|
||||||
|
A circuit contains zero, one or multiple device rows.
|
||||||
|
|
||||||
|
## Phase 0: Audit Existing Codebase
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Determine which parts of the current codebase can be kept.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- identify current data model
|
||||||
|
- identify whether rows are modeled as circuits, devices or mixed entities
|
||||||
|
- identify hardcoded section logic
|
||||||
|
- identify current drag-and-drop implementation
|
||||||
|
- identify current table/editing implementation
|
||||||
|
- identify current project device concept
|
||||||
|
- identify persistence layer and migrations
|
||||||
|
- list conflicts with the new specification
|
||||||
|
- propose refactor plan before changing code
|
||||||
|
|
||||||
|
Deliverable:
|
||||||
|
|
||||||
|
- short audit report
|
||||||
|
- keep/refactor/delete recommendation per major module
|
||||||
|
|
||||||
|
## Phase 1: Core Data Model and Basic Table
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Implement the stable foundation.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- define sections
|
||||||
|
- define circuits
|
||||||
|
- define circuit device rows
|
||||||
|
- define project devices
|
||||||
|
- allow manual rows
|
||||||
|
- allow empty/reserve circuits
|
||||||
|
- calculate row total power
|
||||||
|
- calculate circuit total power
|
||||||
|
- display sections as separator rows
|
||||||
|
- display single-device circuits as compact rows
|
||||||
|
- display multi-device circuits with summary row and indented device rows
|
||||||
|
- implement manual equipment identifier editing
|
||||||
|
- implement next identifier generation as highest number + 1
|
||||||
|
- prevent automatic renumbering
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- a section can contain multiple circuits
|
||||||
|
- a circuit can contain zero, one or multiple device rows
|
||||||
|
- deleting a device does not automatically delete the circuit unless the user chooses so
|
||||||
|
- circuit total power is calculated from all device rows
|
||||||
|
- equipment identifiers are stable unless manually changed or explicitly renumbered
|
||||||
|
|
||||||
|
## Phase 2: Spreadsheet-Like Editing
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Make the table efficient to edit.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- static text cells by default
|
||||||
|
- inline editing on double click / Enter / typing / F2
|
||||||
|
- Enter, Tab, Shift+Tab, Escape behavior
|
||||||
|
- keyboard navigation
|
||||||
|
- Ctrl + Plus row insertion
|
||||||
|
- Ctrl + Shift + Plus support
|
||||||
|
- Delete behavior
|
||||||
|
- validation warnings for duplicate identifiers
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- common values can be edited without opening full forms
|
||||||
|
- keyboard workflow is usable for repetitive entry
|
||||||
|
- accidental edits can be cancelled
|
||||||
|
|
||||||
|
## Phase 3: Project Device Sidebar
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Allow dragging project devices into the circuit list.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- implement project device list
|
||||||
|
- search project devices
|
||||||
|
- filter project devices
|
||||||
|
- show basic technical values
|
||||||
|
- drag project device into valid section
|
||||||
|
- drop onto free placeholder to create a circuit
|
||||||
|
- drop onto existing circuit to add device
|
||||||
|
- create linked device rows
|
||||||
|
- prefill display name but keep it local after insertion
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- project devices can create new circuits
|
||||||
|
- project devices can be added to existing circuits
|
||||||
|
- invalid sections reject drops or require confirmation
|
||||||
|
- linked rows keep the source relationship
|
||||||
|
|
||||||
|
## Phase 4: Drag-and-Drop Restructuring
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Allow restructuring circuits and device assignments.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- drag from circuit handle moves whole circuit
|
||||||
|
- drag from device area moves device row
|
||||||
|
- move device between circuits
|
||||||
|
- move device to free placeholder to create new circuit
|
||||||
|
- move circuit inside section
|
||||||
|
- visual drop indicator
|
||||||
|
- valid/invalid drop zone feedback
|
||||||
|
- multi-row selection with Ctrl + click and Shift + click
|
||||||
|
- multi-row drag preserving internal order
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- circuits can be reordered without renumbering
|
||||||
|
- devices can be reassigned to other circuits
|
||||||
|
- circuit totals recalculate after moves
|
||||||
|
- multi-row movement does not break circuit/device grouping
|
||||||
|
|
||||||
|
## Phase 5: Filtering, Sorting and Columns
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Add Excel-like table management.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- filter menu per column header
|
||||||
|
- sort ascending/descending per column
|
||||||
|
- sorting circuits as complete blocks
|
||||||
|
- preserve device grouping when sorting
|
||||||
|
- column visibility configuration
|
||||||
|
- column reorder by drag and drop
|
||||||
|
- reset default column layout
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- user can filter by room, cost group, category, phase type, etc.
|
||||||
|
- user can sort within sections
|
||||||
|
- sorting does not split circuits
|
||||||
|
- sorting does not renumber
|
||||||
|
- user can renumber explicitly after sorting
|
||||||
|
|
||||||
|
## Phase 6: Undo / Redo
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Make structural editing safe.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- implement undo/redo stack
|
||||||
|
- support insert circuit
|
||||||
|
- support insert device
|
||||||
|
- support delete circuit
|
||||||
|
- support delete device
|
||||||
|
- support move circuit
|
||||||
|
- support move device
|
||||||
|
- support multi-row move
|
||||||
|
- support renumber section
|
||||||
|
- support cell edits
|
||||||
|
- support sync operations
|
||||||
|
- support disconnect linked project device
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- destructive changes can be reverted
|
||||||
|
- renumbering can be undone
|
||||||
|
- drag-and-drop restructuring can be undone
|
||||||
|
|
||||||
|
Note:
|
||||||
|
|
||||||
|
Undo/redo should be considered from the beginning. Implement technically as early as possible if the architecture allows it.
|
||||||
|
|
||||||
|
## Phase 7: Linked Device Synchronization
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Control updates from project devices to circuit list rows.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- track linked project devices
|
||||||
|
- track overridden fields
|
||||||
|
- show affected rows when a project device changes
|
||||||
|
- implement sync dialog
|
||||||
|
- allow field-level selection
|
||||||
|
- apply to one / selected / all linked rows
|
||||||
|
- allow disconnecting selected rows
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- displayName is not synchronized by default
|
||||||
|
- user sees affected distribution boards and circuits
|
||||||
|
- user controls which fields are overwritten
|
||||||
|
- local values are not silently lost
|
||||||
|
|
||||||
|
## Phase 8: Future Sizing Preparation
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
|
||||||
|
Prepare for future electrical sizing logic.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
|
||||||
|
- keep circuit-level protection and cable fields
|
||||||
|
- keep voltage and cosPhi
|
||||||
|
- support future control requirement
|
||||||
|
- structure sizing rules separately from UI
|
||||||
|
- add warning/status concept
|
||||||
|
|
||||||
|
Acceptance criteria:
|
||||||
|
|
||||||
|
- the codebase can later add rule-based sizing without redesigning circuits/devices
|
||||||
|
- users can manually override calculated suggestions
|
||||||
@@ -0,0 +1,200 @@
|
|||||||
|
# Codex Prompt Templates
|
||||||
|
|
||||||
|
Use these prompts step by step. Do not ask Codex to build the whole application in one pass.
|
||||||
|
|
||||||
|
## Prompt 1: Audit Existing Codebase
|
||||||
|
|
||||||
|
```text
|
||||||
|
Audit the existing codebase against the specification files in this repository.
|
||||||
|
|
||||||
|
Focus on the distribution board circuit list editor.
|
||||||
|
|
||||||
|
Do not write code yet.
|
||||||
|
|
||||||
|
Produce a concise audit report with:
|
||||||
|
|
||||||
|
1. current data model summary
|
||||||
|
2. current UI/editor behavior summary
|
||||||
|
3. current project device handling
|
||||||
|
4. conflicts with the new specification
|
||||||
|
5. modules/files that can be kept
|
||||||
|
6. modules/files that should be refactored
|
||||||
|
7. modules/files that should be replaced
|
||||||
|
8. recommended implementation plan
|
||||||
|
|
||||||
|
Important target model:
|
||||||
|
- a circuit is not the same thing as one device row
|
||||||
|
- a circuit contains zero, one or multiple device rows
|
||||||
|
- sections are configurable grouping separators
|
||||||
|
- equipment identifiers are stable and never automatically renumbered
|
||||||
|
- protection and cable data belong to the circuit, not to individual devices
|
||||||
|
|
||||||
|
Wait for confirmation before making code changes.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 2: Implement Core Model
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 1 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Create the core circuit list model and basic table display according to the specification.
|
||||||
|
|
||||||
|
Required:
|
||||||
|
- sections
|
||||||
|
- circuits
|
||||||
|
- circuit device rows
|
||||||
|
- project devices
|
||||||
|
- manual rows
|
||||||
|
- reserve circuits
|
||||||
|
- row total power calculation
|
||||||
|
- circuit total power calculation
|
||||||
|
- equipment identifier generation as highest existing number + 1
|
||||||
|
- no automatic renumbering
|
||||||
|
|
||||||
|
Do not implement advanced drag-and-drop yet.
|
||||||
|
Do not implement sync dialog yet.
|
||||||
|
Do not implement future cable/protection sizing yet.
|
||||||
|
|
||||||
|
Before coding, propose the files you will change and the migration/data-model changes.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 3: Spreadsheet-Like Editing
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 2 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Make the circuit list table spreadsheet-like.
|
||||||
|
|
||||||
|
Required:
|
||||||
|
- static text cells by default
|
||||||
|
- inline editing on double click, Enter, typing and F2
|
||||||
|
- Enter confirms edit
|
||||||
|
- Escape cancels edit
|
||||||
|
- Tab and Shift+Tab navigate editable cells
|
||||||
|
- Arrow keys navigate cells when not editing
|
||||||
|
- Ctrl+Plus inserts a row
|
||||||
|
- Ctrl+Shift+Plus also inserts a row
|
||||||
|
- Delete behavior must be safe
|
||||||
|
- duplicate equipment identifiers must be visually warned
|
||||||
|
|
||||||
|
Do not change the domain model unless required.
|
||||||
|
Do not implement unrelated features.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 4: Project Device Sidebar and Drag Insert
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 3 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Add the project device sidebar and drag insertion into the circuit list.
|
||||||
|
|
||||||
|
Required:
|
||||||
|
- searchable project device sidebar
|
||||||
|
- draggable project device items
|
||||||
|
- drop onto valid section/free placeholder creates a new circuit
|
||||||
|
- drop onto existing circuit adds the device to that circuit
|
||||||
|
- inserted row remains linked to the project device
|
||||||
|
- displayName is prefilled but remains local after insertion
|
||||||
|
- invalid drop zones must be rejected or require confirmation
|
||||||
|
- existing equipment identifiers must not change
|
||||||
|
|
||||||
|
Do not implement multi-row drag yet.
|
||||||
|
Do not implement sync dialog yet.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 5: Drag-and-Drop Restructuring
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 4 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Support restructuring by drag and drop.
|
||||||
|
|
||||||
|
Required:
|
||||||
|
- dragging from circuit handle moves entire circuit
|
||||||
|
- dragging from device area moves only the device row
|
||||||
|
- device rows can move between circuits
|
||||||
|
- device rows can move to the free placeholder to create a new circuit
|
||||||
|
- moving rows recalculates affected circuit totals
|
||||||
|
- no automatic renumbering
|
||||||
|
- visual drop indicator
|
||||||
|
- valid and invalid drop target feedback
|
||||||
|
|
||||||
|
Then add multi-row selection and multi-row drag:
|
||||||
|
- Ctrl+click
|
||||||
|
- Shift+click
|
||||||
|
- selected rows move together
|
||||||
|
- internal order is preserved
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 6: Filtering, Sorting, Columns
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 5 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Add Excel-like filtering, sorting and column configuration.
|
||||||
|
|
||||||
|
Required:
|
||||||
|
- filter menu per column header
|
||||||
|
- filter by values present in the column
|
||||||
|
- sort ascending/descending per column
|
||||||
|
- sorting works inside sections
|
||||||
|
- sorting moves complete circuits as blocks
|
||||||
|
- sorting must not split devices away from their circuit
|
||||||
|
- sorting must not renumber
|
||||||
|
- column visibility configuration
|
||||||
|
- column reorder by drag and drop
|
||||||
|
- reset default column layout
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 7: Undo / Redo
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 6 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Add undo/redo for structural and destructive operations.
|
||||||
|
|
||||||
|
Required undo/redo support:
|
||||||
|
- insert circuit
|
||||||
|
- insert device
|
||||||
|
- delete circuit
|
||||||
|
- delete device
|
||||||
|
- move circuit
|
||||||
|
- move device
|
||||||
|
- multi-row move
|
||||||
|
- renumber section
|
||||||
|
- edit equipment identifier
|
||||||
|
- edit cell value
|
||||||
|
- synchronize linked project device fields
|
||||||
|
- disconnect linked project device
|
||||||
|
|
||||||
|
Keep the implementation maintainable.
|
||||||
|
Do not introduce global state management unless it is justified.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Prompt 8: Linked Device Synchronization
|
||||||
|
|
||||||
|
```text
|
||||||
|
Implement Phase 7 only.
|
||||||
|
|
||||||
|
Goal:
|
||||||
|
Add controlled synchronization from project devices to linked circuit list rows.
|
||||||
|
|
||||||
|
Required:
|
||||||
|
- track linked rows
|
||||||
|
- track overridden fields
|
||||||
|
- when editing a project device, show affected linked rows
|
||||||
|
- show distribution board, circuit identifier and row display name
|
||||||
|
- show changed fields with old and new values
|
||||||
|
- displayName excluded by default
|
||||||
|
- user can apply changes to one, selected or all linked rows
|
||||||
|
- user can exclude fields
|
||||||
|
- user can disconnect linked rows
|
||||||
|
|
||||||
|
Do not silently overwrite local values.
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user