Přeskočit na hlavní obsah

Load Sessions API

API pro správu nakládacích sessions a zpracování skenů během nakládky.

Přehled​

Load Sessions umožňují řídit proces nakládky pro konkrétní projekt. Každá session má:

  • Plán nakládky - seznam položek, které mají být naloženy
  • Realitu - co je skutečně naloženo (skeny, qty operace)
  • Missing/Extra - kalkulace chybějících a navíc naložených položek

Endpointy​

POST /projects/:id/load-sessions​

Vytvoří novou load session pro projekt.

Oprávnění: Loader, Producer, Admin

Request:

{}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "project_id": 5,
    "status": "OPEN",
    "started_at": 1704067200,
    "started_by_user_id": 1
  }
}

GET /load-sessions​

Seznam load sessions s volitelným filtrem podle statusu.

Oprávnění: Bearer token (vyžaduje autentizaci)

Query parametry:

  • status (volitelné): Filtr podle statusu (OPEN, CLOSED)
  • page (volitelné): Číslo stránky (výchozí: 1)
  • pageSize (volitelné): Počet položek na stránku (výchozí: 50)

Response:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "project_id": 5,
        "status": "OPEN",
        "started_at": 1704067200,
        "closed_at": null,
        "project_name": "Summer Festival 2024",
        "project_date_from": 1704067200,
        "project_date_to": 1704153600
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "pageSize": 50,
      "totalPages": 1
    }
  }
}

GET /load-sessions/:id​

Získá detail load session.

Oprávnění: Bearer token (vyžaduje autentizaci)

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "project_id": 5,
    "status": "OPEN",
    "started_at": 1704067200,
    "closed_at": null,
    "started_by_user_id": 1,
    "closed_by_user_id": null
  }
}

GET /load-sessions/:id/plan​

Získá plán nakládky s rozřešenými daty (assets, items, kits).

Oprávnění: Bearer token (vyžaduje autentizaci)

Response:

{
  "success": true,
  "data": {
    "lines": [
      {
        "id": 1,
        "session_id": 1,
        "line_type": "ASSET",
        "ref_id": 5,
        "qty": null,
        "section": "Sekce A",
        "created_at": 1704067200,
        "asset": {
          "id": 5,
          "scan_id": 12345,
          "item_name": "Microphone Shure SM58"
        }
      },
      {
        "id": 2,
        "session_id": 1,
        "line_type": "ITEM_QTY",
        "ref_id": 10,
        "qty": 5,
        "section": null,
        "created_at": 1704067200,
        "item": {
          "id": 10,
          "name": "XLR Cable 10m"
        }
      }
    ]
  }
}

GET /load-sessions/:id/status​

Získá status load session včetně missing/extra kalkulace.

Oprávnění: Bearer token (vyžaduje autentizaci)

Response:

{
  "success": true,
  "data": {
    "planned": {
      "assets": 10,
      "items": 5,
      "globalKits": 2,
      "projectKits": 1
    },
    "loaded": {
      "assets": 8,
      "items": 3
    },
    "missing": {
      "assets": 2,
      "items": 2
    },
    "extra": {
      "assets": 0,
      "items": 0
    }
  }
}

POST /load-sessions/:id/scan​

Zpracuje sken QR kódu během nakládky.

Oprávnění: Loader, Producer, Admin

Podporuje 3 typy skenů:

  1. Asset (konkrétní kus) - podle zadani.md sekce 6.3
  2. Global Kit - podle zadani.md sekce 6.4
  3. Project Kit - podle zadani.md sekce 6.5

Request:

{
  "scan_id": 12345
}

Response - Asset v plánu:

{
  "success": true,
  "data": {
    "message": "Asset naložen",
    "asset": {
      "id": 1,
      "scan_id": 12345,
      "item_id": 5,
      "functional_status": "OK_100",
      "availability_status": "AVAILABLE"
    },
    "loaded": true
  }
}

Response - Asset mimo plán (vyžaduje potvrzení):

{
  "success": true,
  "data": {
    "requiresConfirmation": true,
    "confirmationType": "asset_not_in_plan",
    "message": "Asset není v nakládce. Opravdu naložit?",
    "asset": {
      "id": 1,
      "scan_id": 12345,
      "item_id": 5
    },
    "collision": {
      "hasCollision": true,
      "reasons": [
        "Asset je plánovaný na jiné akci: Koncert Praha",
        "Asset is not 100% functional"
      ],
      "requiresOverride": true
    }
  }
}

Response - Global Kit kompletní:

{
  "success": true,
  "data": {
    "requiresConfirmation": true,
    "confirmationType": "global_kit_bulk",
    "message": "Kit je kompletní. Naložit všechny položky?",
    "kit": {
      "id": 1,
      "name": "ADJ spoty #1",
      "scan_id": 67890
    },
    "completeness": {
      "isComplete": true,
      "missingAssets": [],
      "missingItems": []
    }
  }
}

Response - Global Kit nekompletní:

{
  "success": true,
  "data": {
    "requiresConfirmation": false,
    "kitType": "global",
    "message": "Kit je rozebraný. Naskenujte zbývající konkrétní kusy.",
    "kit": {
      "id": 1,
      "name": "ADJ spoty #1"
    },
    "completeness": {
      "isComplete": false,
      "missingAssets": [
        {
          "asset_id": 5,
          "scan_id": 12345,
          "name": "ADJ Spot 1"
        }
      ],
      "missingItems": [
        {
          "item_id": 10,
          "name": "XLR kabel",
          "required": 5,
          "available": 3
        }
      ]
    }
  }
}

Response - Project Kit:

{
  "success": true,
  "data": {
    "requiresConfirmation": false,
    "kitType": "project",
    "message": "Project kit detail",
    "kit": {
      "id": 1,
      "name": "Kabelovka pro akci",
      "scan_id": 11111
    },
    "lines": [
      {
        "id": 1,
        "asset_id": 5,
        "asset_scan_id": 12345,
        "item_id": null,
        "item_name": null,
        "qty": null
      },
      {
        "id": 2,
        "asset_id": null,
        "asset_scan_id": null,
        "item_id": 10,
        "item_name": "XLR kabel",
        "qty": 5
      }
    ],
    "note": "Project kit nelze naložit hromadně. Naskenujte jednotlivé položky."
  }
}

POST /load-sessions/:id/scan/confirm​

Potvrdí scan assetu mimo plán nebo bulk loading global kitu.

Oprávnění: Loader, Producer, Admin

Request - Asset mimo plán:

{
  "confirmType": "asset_not_in_plan",
  "asset_id": 1,
  "override_reason": "Nouzová situace - asset je potřeba na této akci"
}

Request - Global Kit bulk:

{
  "confirmType": "global_kit_bulk",
  "kit_id": 1
}

Response:

{
  "success": true,
  "data": {
    "message": "Asset přidán do plánu a naložen",
    "asset": {
      "id": 1,
      "scan_id": 12345
    }
  }
}

POST /load-sessions/:id/plan/add​

Přidá položku do plánu nakládky.

Oprávnění: Loader, Producer, Admin

Podporuje 4 typy položek:

  • ASSET - konkrétní kus
  • ITEM_QTY - nekonkrétní položka s množstvím
  • GLOBAL_KIT - globální kit
  • PROJECT_KIT - akcový kit

Request:

{
  "line_type": "ASSET",
  "ref_id": 1,
  "section": "Sekce A"
}

Response:

{
  "success": true,
  "data": {
    "message": "Položka přidána do plánu",
    "planLine": {
      "id": 1,
      "session_id": 1,
      "line_type": "ASSET",
      "ref_id": 1,
      "qty": null,
      "section": "Sekce A",
      "created_at": 1704067200
    }
  }
}

POST /load-sessions/:id/plan/remove​

Odebere položku z plánu nakládky.

Oprávnění: Loader, Producer, Admin

Request:

{
  "plan_line_id": 1,
  "unload": true
}

Response:

{
  "success": true,
  "data": {
    "message": "Položka odebrána z plánu"
  }
}

Poznámka: Pokud je položka už naložena a unload je false, endpoint vrátí requiresConfirmation: true s dotazem, zda označit k vyložení.

POST /load-sessions/:id/qty​

Změní množství nekonkrétní položky v session.

Oprávnění: Loader, Producer, Admin

Request - Přidat množství:

{
  "item_id": 10,
  "operation": "add",
  "qty": 5
}

Request - Odebrat množství:

{
  "item_id": 10,
  "operation": "remove",
  "qty": 2
}

Request - Nastavit přesné množství:

{
  "item_id": 10,
  "operation": "set",
  "qty": 10
}

Response:

{
  "success": true,
  "data": {
    "message": "Množství přidáno",
    "item_id": 10,
    "qty_delta": 5
  }
}

POST /load-sessions/:id/close​

Uzavře load session.

Oprávnění: Producer, Admin

Request:

{
  "reason": "Nakládka dokončena"
}

Response:

{
  "success": true,
  "data": {
    "message": "Session uzavřena",
    "closed_at": 1704067200
  }
}

Business pravidla​

Tok skenování assetu​

  1. Asset v plánu:

    • Pokud není naložen → SCAN_LOAD
    • Pokud už je naložen → info "už naloženo"

  2. Asset mimo plán:

    • Potvrzení 1: "Není v nakládce. Opravdu naložit?"
    • Pokud Ano → collision check
    • Pokud kolize → potvrzení 2: "Je plánovaný jinde nebo není 100% OK. Přesto naložit?"
    • Pokud Ano → PLAN_ADD + SCAN_LOAD s override_reason

Skenování globálního kitu​

  • Kompletní kit: Může být naložen hromadně (všechny assety + qty pro items)
  • Nekompletní kit: Vrátí seznam chybějících položek, nelze naložit hromadně

Skenování projektového kitu​

  • Vždy pouze detail: Project kit nelze naložit hromadně
  • Uživatel musí naskenovat jednotlivé položky

Detekce kolizí​

Asset je v kolizi pokud:

  1. Je plánovaný na jinou akci v časovém překryvu
  2. Nemá funkčnost OK_100

Kolize vždy vyvolá druhé potvrzení s možností override.

GET /load-sessions​

Seznam load sessions s volitelným filtrem podle statusu. Používá se hlavně pro wallboard.

Oprávnění: Bearer token (vyžaduje autentizaci)

Query parametry:

  • status (volitelné): Filtr podle statusu (OPEN, CLOSED)
  • page (volitelné): Číslo stránky (výchozí: 1)
  • pageSize (volitelné): Počet položek na stránku (výchozí: 50)

Response:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 1,
        "project_id": 5,
        "status": "OPEN",
        "started_at": 1704067200,
        "closed_at": null,
        "project_name": "Summer Festival 2024",
        "project_date_from": 1704067200,
        "project_date_to": 1704153600
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "pageSize": 50,
      "totalPages": 1
    }
  }
}

Kódy chyb​

  • VALIDATION_ERROR - Neplatné parametry
  • NOT_FOUND - Session, asset nebo kit nenalezen
  • INVALID_STATE - Session není otevřená
  • ALREADY_IN_PLAN - Položka už je v plánu
  • KIT_INCOMPLETE - Kit není kompletní
  • INTERNAL_ERROR - Vnitřní chyba serveru