# .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.