asdasd

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