web-cad/docs/LIBRARY_SPEC.md

.wcadlib – Block-Bibliotheks-Paket-Spezifikation

WebCAD-Block-Bibliotheken können als .wcadlib-Paket geteilt werden. Es gibt zwei Formate:

Format 1: JSON-Paket (F1)

Ein einzelnes JSON-File mit folgender Struktur:

{
  "format": "wcadlib",
  "version": 1,
  "exported_at": "2026-08-29T00:00:00.000Z",
  "folders": [
    { "id": "f1", "name": "Veranstaltungstechnik", "parent_id": null }
  ],
  "blocks": [
    {
      "name": "Stuhl-Reihe",
      "folder_id": "f1",
      "block_data": "[{...CADElement-Array als JSON-String...]}",
      "svg_data": "<svg ...>"
    }
  ]
}

• block_data = JSON-String eines CADElement-Arrays
• svg_data = eigenständiges SVG (Thumbnail), optional
• Ordner-Hierarchie via parent_id (Import ordnet IDs neu zu)

Endpoints: GET /api/global-blocks/export, POST /api/global-blocks/import (schreibend: nur library-admin/Rolle admin, siehe H3)

Format 2: ZIP-Paket (F7)

Ein echtes ZIP-Archiv mit fester Struktur:

library.wcadlib.zip
├── manifest.json      { "format": "wcadlib-zip", "version": 1,
│                       "exported_at": "...", "block_count": N, "folder_count": M }
├── blocks.json        { "folders": [...], "blocks": [
│                        { "name", "folder_id", "block_data",
│                          "thumbnail": "thumbs/<id>.svg" } ] }
└── thumbs/
    └── <blockId>.svg   Thumbnails, Referenz aus blocks.json

• manifest.format MUSS wcadlib-zip sein (sonst 400)
• blocks.json MUSS vorhanden sein (sonst 400); blocks-Array Pflicht
• thumbnail verweist relativ auf thumbs/<id>.svg

Endpoints:

• GET /api/global-blocks/export-zip → application/zip
• POST /api/global-blocks/import-zip (Body = ZIP als application/zip; schreibend: nur library-admin)

Validierungsregeln (Import)

Fehler	HTTP
Kein valides ZIP (Format 2)	400
blocks.json fehlt / invalides JSON	400
manifest.format unbekannt	400
Kein JSON/blocks-Array (Format 1)	400
Nicht authentifiziert	401
Rolle != admin (schreibend)	403

CAD-Element-Konventionen (block_data)

• rect: x/y = Zentrum der BBox
• circle/arc: el.x/el.y = Zentrum, Winkel in Grad (0° = 3 Uhr, CCW)
• line: properties.x1/y1/x2/y2
• polyline/polygon: properties.points
• block_instance: properties.blockId + optional attrValues (D12)

Beim Drop auf die Zeichenfläche werden Element-IDs neu generiert und die Position per Drop-Punkt übersetzt – der Bestand bleibt unverändert.