Přeskočit na hlavní obsah

Projects API

API pro správu projektů (akcí/eventů).

Přehled​

Projekty reprezentují akce nebo produkce, které vyžadují nakládku vybavení. Každý projekt má:

  • Název a datumy
  • Load sessions
  • Project kits

Endpointy​

GET /projects​

Seznam všech projektů s paginací.

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

Query parametry:

  • page (volitelné): Číslo stránky (výchozí: 1)
  • pageSize (volitelné): Počet položek na stránku (výchozí: 50)

Response:

{
  "success": true,
  "data": {
    "projects": [
      {
        "id": 1,
        "name": "Summer Festival 2024",
        "date_from": 1704067200,
        "date_to": 1704153600,
        "notes": "Outdoor event",
        "created_at": 1703980800
      }
    ],
    "pagination": {
      "total": 10,
      "page": 1,
      "pageSize": 50,
      "totalPages": 1
    }
  }
}

GET /projects/:id​

Získá detail projektu.

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

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Summer Festival 2024",
    "date_from": 1704067200,
    "date_to": 1704153600,
    "notes": "Outdoor event",
    "created_at": 1703980800
  }
}

POST /projects​

Vytvoří nový projekt.

Oprávnění: Producer, Admin

Request:

{
  "name": "Summer Festival 2024",
  "date_from": 1704067200,
  "date_to": 1704153600,
  "notes": "Outdoor event"
}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Summer Festival 2024",
    "date_from": 1704067200,
    "date_to": 1704153600,
    "notes": "Outdoor event",
    "created_at": 1703980800
  }
}

PUT /projects/:id​

Upraví existující projekt.

Oprávnění: Producer, Admin

Request:

{
  "name": "Summer Festival 2024 Updated",
  "date_from": 1704067200,
  "date_to": 1704153600,
  "notes": "Updated notes"
}

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Summer Festival 2024 Updated",
    "date_from": 1704067200,
    "date_to": 1704153600,
    "notes": "Updated notes",
    "created_at": 1703980800
  }
}

Error Response (project has open sessions):

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Project has open load sessions. Close them first."
}

DELETE /projects/:id​

Smaže projekt.

Oprávnění: Producer, Admin

Response:

{
  "success": true,
  "data": {
    "message": "Project deleted"
  }
}

Error Response (project has open sessions):

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Project has open load sessions. Close them first."
}

Error Response (project not found):

{
  "success": false,
  "error": "NOT_FOUND",
  "message": "Project not found"
}

GET /projects/:id/plan​

Získání plánu gearu pro projekt.

Oprávnění: Producer, Admin

Response:

{
  "success": true,
  "data": {
    "lines": [
      {
        "id": 1,
        "line_type": "ITEM_QTY",
        "ref_id": 5,
        "qty": 10,
        "item": {
          "id": 5,
          "name": "Cable XLR 10m"
        }
      },
      {
        "id": 2,
        "line_type": "GLOBAL_KIT",
        "ref_id": 3,
        "qty": 1,
        "globalKit": {
          "id": 3,
          "name": "Sound Kit A"
        }
      }
    ]
  }
}

POST /projects/:id/plan​

Přidání položky do plánu gearu.

Oprávnění: Producer, Admin

Změny v verzi 0.2.0:

  • Opravena chyba při použití nesprávného názvu sloupce v SQL dotazu
  • Přidán lepší error handling s detailním logováním
  • Přidány toast notifikace pro vizuální feedback

Request:

{
  "line_type": "ITEM_QTY",
  "ref_id": 5,
  "qty": 10
}

Typy line_type:

  • ITEM_QTY - Item s množstvím (ref_id = item_id)
  • GLOBAL_KIT - Globální kit (ref_id = kit_id)
  • PROJECT_KIT - Projektový kit (ref_id = kit_id)

Response:

{
  "success": true,
  "data": {
    "id": 1,
    "project_id": 123,
    "line_type": "ITEM_QTY",
    "ref_id": 5,
    "qty": 10,
    "created_at": 1704067200
  }
}

PUT /projects/:id/plan/:lineId​

Aktualizace položky v plánu gearu.

Oprávnění: Producer, Admin

Změny v verzi 0.2.0:

  • Přidán sloupec updated_at do tabulky project_plan_lines (migrace 0029)
  • Přidán lepší error handling s detailním logováním

Request:

{
  "qty": 15
}

DELETE /projects/:id/plan/:lineId​

Odebrání položky z plánu gearu.

Oprávnění: Producer, Admin

Response:

{
  "success": true,
  "data": {
    "message": "Plan line deleted"
  }
}

GET /projects/:id/loading/status​

Získá status nakládky pro projekt (planned, loaded, missing, extra, progress).

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

Response:

{
  "success": true,
  "data": {
    "planned": 50,
    "loaded": 35,
    "missing": 15,
    "extra": 0,
    "progress": 70.0
  }
}

POST /projects/:id/loading/click​

Označí položku v plánu jako naloženou (+1).

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

Request:

{
  "plan_line_id": 123
}

Response:

{
  "success": true,
  "data": {
    "planned": 50,
    "loaded": 36,
    "missing": 14,
    "extra": 0,
    "progress": 72.0
  }
}

POST /projects/:id/loading/unload​

Označí položku v plánu jako nenaloženou (-1).

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

Request:

{
  "plan_line_id": 123
}

Response:

{
  "success": true,
  "data": {
    "planned": 50,
    "loaded": 35,
    "missing": 15,
    "extra": 0,
    "progress": 70.0
  }
}

Business pravidla​

Mazání projektu​

  • Projekty s otevřenými load sessions nelze smazat
  • Nejdřív musí být všechny load sessions uzavřeny
  • Po smazání projektu se smažou i všechny související data (load sessions, project kits, plan lines)

Validace datumů​

  • date_from musí být před date_to
  • Oba datumy jsou povinné

Plánování gearu​

  • Plán gearu definuje, jaké vybavení má být naloženo na projekt
  • Plán může obsahovat items s množstvím, globální kity a projektové kity
  • Plán je přímo spojen s projektem (project_plan_lines)

Nakládka​

  • Nakládka je nyní přímo spojena s projektem (žádné samostatné load sessions)
  • Použijte /projects/:id/loading/status pro získání statusu
  • Použijte /projects/:id/loading/click pro naložení položky
  • Použijte /projects/:id/loading/unload pro vrácení položky zpět
  • Status se počítá z scan_events s project_id

Kódy chyb​

  • VALIDATION_ERROR - Neplatné parametry (chybějící name, date_from, date_to)
  • NOT_FOUND - Projekt nenalezen
  • INVALID_ID - Neplatné project ID
  • INTERNAL_ERROR - Vnitřní chyba serveru