asdasd

2026-05-15 22:15:31 +02:00
parent c7d96bec85
commit 98dd388fda
9 changed files with 747 additions and 83 deletions
--- a/docs/rack-planner/architecture.md
+++ b/docs/rack-planner/architecture.md
@@ -0,0 +1,122 @@
+# System Architecture
+
+## Overview
+
+The system should be built as a web platform with a thin, responsive client and a server-side core for persistence, catalog management, plugin validation, and export generation.
+
+## Main building blocks
+
+### Frontend
+
+- browser-based single-page application
+- visual rack editor
+- component library browser
+- BOM and cable views
+- import/export screens
+
+### Backend API
+
+- project CRUD
+- component catalog API
+- plugin upload and validation
+- bill of materials generation
+- cable estimation service
+- authentication and authorization
+
+### Database
+
+- users
+- projects
+- rack definitions
+- component instances
+- cable links
+- plugin manifests
+- catalog components
+
+### Asset storage
+
+- component `SVG` files
+- optional `glTF` assets
+- import files
+- generated exports such as `CSV` and `PDF`
+
+## Recommended domain model split
+
+### Planning domain
+
+- racks
+- placements
+- connections
+- validation rules
+
+### Catalog domain
+
+- components
+- manufacturers
+- plugin packs
+- pricing metadata
+
+### Output domain
+
+- BOM
+- exports
+- printable documentation
+
+## Rendering approach
+
+For V1, prefer a 2D editor based on `SVG`.
+
+Reasons:
+
+- precise snap and measurement handling
+- easier labeling and overlays
+- simpler hit-testing for drag and resize interactions
+- lower implementation cost than a full 3D editor
+
+3D can be added later as a secondary visualization layer using `glTF` assets and `Three.js`.
+
+## Plugin ingestion approach
+
+Do not load arbitrary CAD files directly into the editor runtime.
+
+Use a controlled import pipeline:
+
+1. user uploads a plugin package
+2. backend validates manifest and metadata
+3. backend validates assets and dimensions
+4. optional CAD conversion creates internal preview assets
+5. approved components become available in the catalog
+
+This keeps the editor stable and the plugin model secure.
+
+## Deployment model
+
+### Public SaaS mode
+
+- hosted centrally
+- user accounts and teams
+- shared component packs
+- subscription or usage-based pricing possible later
+
+### Self-hosted mode
+
+- optional future enterprise offering
+- internal catalogs
+- private component packs
+
+## Security considerations
+
+- signed or verified plugin packs if third-party distribution is allowed
+- strict asset and file-type validation
+- no execution of untrusted code in plugins
+- server-side permission checks for project access
+- rate limits on public endpoints
+
+## Scaling considerations
+
+- stateless API instances
+- database-backed persistence
+- object storage for assets
+- asynchronous jobs for heavy imports and exports
+
+This is enough for an internet-facing product without overengineering the first release.
--- a/docs/rack-planner/cable-length.md
+++ b/docs/rack-planner/cable-length.md
@@ -0,0 +1,113 @@
+# Cable Length Calculation
+
+## Goal
+
+Estimate practical cable lengths from the physical arrangement of devices in a rack so users can preselect realistic patch and power cable variants.
+
+The result should support planning, not exact installation certification.
+
+## Use cases
+
+- patch cable length between patch panel and switch
+- DAC or fiber estimate between devices in the same rack
+- power cable estimate from PDU to active device
+- BOM generation for preconfigured cable sets
+
+## V1 approach
+
+Cable length should be estimated from:
+
+- rack unit position of both components
+- side of connection: front or rear
+- optional port offsets
+- route style
+- slack factor
+
+## Suggested routing model
+
+For V1, use a rule-based path estimate instead of full geometric routing.
+
+### Inputs
+
+- source component `U` position
+- target component `U` position
+- source and target side
+- rack depth
+- routing preference
+- slack percentage or fixed reserve
+
+### Routing preferences
+
+- `front_vertical`
+- `rear_vertical`
+- `front_to_rear`
+- `shortest_practical`
+
+## Example calculation logic
+
+Estimate length as:
+
+1. vertical distance between source and target mounting positions
+2. plus horizontal or side transition allowance
+3. plus front/rear traversal allowance
+4. plus slack reserve
+
+Illustrative formula:
+
+```text
+estimated_length =
+  vertical_distance_mm
+  + side_transition_mm
+  + front_rear_allowance_mm
+  + service_loop_mm
+```
+
+Then round up to the next marketable cable length, for example:
+
+- `0.25 m`
+- `0.5 m`
+- `1.0 m`
+- `1.5 m`
+- `2.0 m`
+- `3.0 m`
+
+## Accuracy strategy
+
+The tool should display:
+
+- raw estimated length
+- recommended order length
+- confidence note such as `estimate only`
+
+## Data requirements
+
+Better cable estimation becomes possible if components expose ports with offsets.
+
+Minimum V1:
+
+- component `U` position only
+
+Better V1:
+
+- per-port offsets in the component metadata
+
+## BOM integration
+
+Cable entries can be generated as:
+
+- one line per connection
+- or aggregated by cable type and recommended order length
+
+Example:
+
+- `12 x RJ45 patch cable Cat6A, 0.5 m`
+- `4 x C13 to C14 power cable, 1.5 m`
+
+## Future improvements
+
+- front and rear cable manager objects
+- reserved routing channels
+- left/right side path selection
+- bend radius constraints
+- color-coded cable groups
+- cross-rack cable planning
--- a/docs/rack-planner/data-model.md
+++ b/docs/rack-planner/data-model.md
@@ -0,0 +1,139 @@
+# Data Model
+
+## Design principles
+
+- components are metadata-driven
+- placement data is separate from catalog data
+- plugin-imported components must behave like built-in components
+- cable links are first-class entities
+
+## Core entities
+
+### RackTemplate
+
+Describes a rack type that can be instantiated in projects.
+
+Suggested fields:
+
+- `id`
+- `name`
+- `rack_standard` as `10_inch` or `19_inch`
+- `total_u`
+- `usable_depth_mm`
+- `max_weight_kg`
+- `mounting_style`
+
+### Project
+
+- `id`
+- `name`
+- `owner_id`
+- `created_at`
+- `updated_at`
+- `status`
+
+### RackInstance
+
+- `id`
+- `project_id`
+- `rack_template_id`
+- `label`
+- `position_index`
+
+### ComponentDefinition
+
+Catalog entry for a reusable part.
+
+- `id`
+- `source_type` as `builtin` or `plugin`
+- `plugin_id`
+- `manufacturer`
+- `part_number`
+- `name`
+- `category`
+- `rack_standard`
+- `height_u`
+- `width_mm`
+- `depth_mm`
+- `weight_kg`
+- `power_w`
+- `price_net`
+- `currency`
+- `front_svg_asset_id`
+- `preview_3d_asset_id`
+
+### ComponentInstance
+
+Placed component inside a rack.
+
+- `id`
+- `project_id`
+- `rack_instance_id`
+- `component_definition_id`
+- `start_u`
+- `orientation`
+- `notes`
+
+### PortDefinition
+
+Optional port model for cable planning.
+
+- `id`
+- `component_definition_id`
+- `name`
+- `side` as `front` or `rear`
+- `offset_x_mm`
+- `offset_y_mm`
+- `offset_z_mm`
+- `port_type`
+
+### CableLink
+
+- `id`
+- `project_id`
+- `from_component_instance_id`
+- `from_port_definition_id`
+- `to_component_instance_id`
+- `to_port_definition_id`
+- `cable_type`
+- `estimated_length_mm`
+- `slack_percent`
+- `manual_override_length_mm`
+
+### PluginPack
+
+- `id`
+- `name`
+- `version`
+- `vendor`
+- `manifest_version`
+- `status`
+- `imported_at`
+
+## Validation rules
+
+- `ComponentDefinition.rack_standard` must match `RackTemplate.rack_standard`
+- `ComponentInstance.start_u` plus `height_u` must not exceed rack height
+- placed components must not overlap
+- cable links should only reference valid ports belonging to the selected components
+
+## BOM generation logic
+
+The BOM should aggregate by:
+
+- `manufacturer`
+- `part_number`
+- optional variant attributes such as color or length
+
+The BOM should be able to combine:
+
+- placed components
+- accessory parts
+- calculated cables
+
+## Future extensions
+
+- multi-rack room coordinates
+- thermal zones
+- separate front and rear accessories
+- stock and supplier integration
--- a/docs/rack-planner/mvp.md
+++ b/docs/rack-planner/mvp.md
@@ -0,0 +1,79 @@
+# MVP Scope
+
+## Objective
+
+Release a public web application that solves the core planning workflow for `10"` and `19"` racks without waiting for full CAD-grade capabilities.
+
+## MVP features
+
+### 1. Rack editor
+
+- create a rack project
+- choose rack type: `10"` or `19"`
+- define rack height in `U`
+- define depth and optional width variant
+- front view editor with occupied `U` grid
+- drag-and-drop placement of components
+- move and reorder components
+- remove and duplicate components
+
+### 2. Component library
+
+- built-in catalog with common rack elements
+- categories such as patch panel, switch, server, PDU, shelf, UPS, blank panel
+- searchable component picker
+- component detail panel with dimensions and metadata
+
+### 3. Validation
+
+- enforce rack width compatibility
+- enforce `U` occupancy
+- warn on depth overflow
+- warn on weight limit overflow if rack limits are defined
+
+### 4. Bill of materials
+
+- aggregate identical parts
+- export as `CSV`
+- show quantity, part number, manufacturer, description, unit price, total price
+- optionally list accessories separately
+
+### 5. Plugin support
+
+- import component packs based on a defined manifest
+- metadata-driven components
+- 2D visuals via `SVG`
+- optional 3D visual asset reference for future use
+
+### 6. Cable planning V1
+
+- define cable links between two ports or two devices
+- estimate route length using rack positions
+- allow manual slack factor
+- include cables in bill of materials
+
+## Deliberately excluded from MVP
+
+- freeform 3D editing
+- native browser editing of `STEP` or `DXF`
+- multi-rack room layout
+- thermal simulation
+- live collaboration
+- advanced permission and approval workflows
+- ERP integration
+
+## Recommended MVP stack
+
+- frontend: `React` + `TypeScript`
+- editor rendering: `SVG` or `Canvas` for 2D rack view
+- backend: `Node.js` or `PHP` API, depending on preferred team stack
+- database: `PostgreSQL`
+- storage: object storage for plugin assets and exports
+
+## Success criteria
+
+- a user can build a rack layout in under 10 minutes
+- the system prevents invalid `U` placement
+- the generated bill of materials is usable for procurement
+- plugin packs can be added without code changes in the editor
+- cable length estimates are close enough for practical preselection
--- a/docs/rack-planner/plugin-spec.md
+++ b/docs/rack-planner/plugin-spec.md
@@ -0,0 +1,138 @@
+# Plugin Specification
+
+## Goal
+
+The plugin system should allow additional rack components to be imported without changing application code.
+
+Plugins should be data packages, not executable extensions.
+
+## Principles
+
+- no arbitrary code execution
+- manifest-based validation
+- stable schema versioning
+- internal conversion of optional CAD-derived assets
+
+## Package structure
+
+Example:
+
+```text
+vendor-pack-1/
+  manifest.json
+  components/
+    switch-24p.json
+    patchpanel-24p.json
+  assets/
+    front/
+      switch-24p.svg
+      patchpanel-24p.svg
+    preview3d/
+      switch-24p.gltf
+```
+
+## Manifest example
+
+```json
+{
+  "manifestVersion": 1,
+  "name": "Example Network Pack",
+  "vendor": "Example Vendor",
+  "version": "1.0.0",
+  "components": [
+    "components/switch-24p.json",
+    "components/patchpanel-24p.json"
+  ]
+}
+```
+
+## Component definition example
+
+```json
+{
+  "name": "24-Port Patch Panel",
+  "manufacturer": "Example Vendor",
+  "partNumber": "PP-24-1U",
+  "category": "patch_panel",
+  "rackStandard": "19_inch",
+  "heightU": 1,
+  "depthMm": 95,
+  "weightKg": 1.2,
+  "priceNet": 79.0,
+  "currency": "EUR",
+  "assets": {
+    "frontSvg": "assets/front/patchpanel-24p.svg"
+  },
+  "ports": [
+    {
+      "name": "Port 1",
+      "side": "front",
+      "offsetXmm": 18,
+      "offsetYmm": 10,
+      "offsetZmm": 0,
+      "portType": "rj45"
+    }
+  ]
+}
+```
+
+## Supported file formats
+
+### V1 mandatory
+
+- `JSON` for manifest and component metadata
+- `SVG` for 2D visuals
+
+### V1 optional
+
+- `glTF` for future 3D preview assets
+
+### Later import formats
+
+These should be handled through an import pipeline, not as runtime-native editor formats:
+
+- `DXF`
+- `STEP`
+- `OBJ`
+
+## Validation rules
+
+- schema version must be supported
+- required metadata fields must exist
+- asset references must resolve inside the package
+- all dimensions must be plausible and positive
+- category values must match allowed enums
+- unsupported formats are rejected or ignored
+
+## Security model
+
+Plugins must never contain executable JavaScript for the editor.
+
+Allowed plugin content:
+
+- metadata
+- images
+- vector graphics
+- optional validated model assets
+
+Rejected:
+
+- scripts
+- external network callbacks
+- embedded active content
+
+## Import workflow
+
+1. upload package
+2. unpack in isolated temporary storage
+3. validate manifest
+4. validate component schema
+5. validate assets
+6. register catalog entries
+7. make components available to selected users or globally
+
+## Versioning strategy
+
+- application schema versioning is independent from plugin pack version
+- manifest schema must be explicitly versioned
+- deprecated fields should have a migration path where possible
--- a/docs/rack-planner/product-concept.md
+++ b/docs/rack-planner/product-concept.md
@@ -0,0 +1,71 @@
+# Product Concept
+
+## Problem
+
+There is no widely available, lightweight online tool focused on practical planning of `10"` and `19"` racks with a visual workflow, reusable components, and a usable bill of materials.
+
+Existing workflows are often split across:
+
+- CAD tools that are too heavy for simple planning
+- spreadsheets for the bill of materials
+- manual sketches for positioning
+- separate notes for cabling
+
+## Vision
+
+`code.it Rack Planner` should be a browser-based planning platform where users can:
+
+- create and save rack layouts online
+- visually place and move rack components
+- load manufacturer-specific or custom components as plugins
+- generate a bill of materials automatically
+- estimate cable lengths between ports or devices
+
+## Target users
+
+- system integrators
+- installers
+- IT administrators
+- AV and media technicians
+- control cabinet / small infrastructure planners
+- organizations documenting existing rack installations
+
+## Primary use cases
+
+1. Plan a new `19"` network rack with switch, patch panel, PDU, UPS, shelves, and servers.
+2. Plan a compact `10"` wall rack for small office or edge installations.
+3. Compare multiple rack variants with different hardware selections.
+4. Export a bill of materials for ordering.
+5. Estimate patch cable and power cable lengths based on mounting positions.
+
+## Functional goals
+
+- visual rack editor
+- component catalog
+- drag-and-drop placement
+- snap-to-unit positioning
+- collision and fit validation
+- bill of materials generation
+- import of additional component packs
+- optional cable planning and length estimation
+
+## Non-functional goals
+
+- runs in a modern browser
+- usable on desktop first, tablet second
+- clean project persistence
+- suitable for public internet deployment
+- secure plugin loading model
+- scalable enough for many concurrent users
+
+## Scope boundary
+
+The product should not try to replace full mechanical CAD in the first versions. The planning focus is:
+
+- layout
+- occupancy
+- compatibility
+- documentation
+- ordering support
+
+Mechanical precision modeling, freeform CAD editing, and simulation should remain outside the initial scope.
--- a/docs/rack-planner/roadmap.md
+++ b/docs/rack-planner/roadmap.md
@@ -0,0 +1,56 @@
+# Roadmap
+
+## Phase 0: Product foundation
+
+- finalize terminology and target market
+- define core rack and component schemas
+- prepare UX wireframes for the editor
+- prepare initial built-in component catalog
+
+## Phase 1: MVP
+
+- project creation
+- rack editor for `10"` and `19"`
+- drag-and-drop placement
+- `U` grid and collision checks
+- built-in catalog
+- BOM export as `CSV`
+- plugin pack import with `JSON` plus `SVG`
+- simple cable estimation
+
+## Phase 2: Public beta
+
+- user accounts
+- project persistence
+- shareable project links
+- improved BOM formatting
+- printable rack reports
+- better plugin management UI
+
+## Phase 3: Professional planning
+
+- 3D preview
+- manufacturer packs
+- advanced validation rules
+- richer cable routing logic
+- multi-rack projects
+- PDF export packages
+
+## Phase 4: Commercial maturity
+
+- team workspaces
+- access control
+- audit log
+- supplier and ERP exports
+- private catalogs
+- self-hosted deployment option
+
+## Product recommendation
+
+The strongest path is:
+
+1. ship a narrow and useful browser editor first
+2. prove demand with real planners and installers
+3. expand catalogs, exports, and collaboration after usage feedback
+
+The public internet goal is realistic, but only if V1 stays disciplined and does not start as a generalized CAD platform.