docs(I2): plugin guide (API v2 + example), library spec (wcadlib JSON+ZIP), changelog 2.0, readme rewrite

2026-08-29 03:36:45 +02:00
parent a3d3732f85
commit 7eedddbc3f
4 changed files with 335 additions and 9 deletions
@@ -0,0 +1,80 @@
+# .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:
+
+```json
+{
+  "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.