Luncher/types/api.yml

openapi: 3.0.4
info:
  title: Luncher API
  version: 1.0.0
servers:
  - url: /api
paths:
  /login:
    post:
      summary: Přihlášení uživatele
      security: [] # Nevyžaduje autentizaci
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                login:
                  type: string
                  description: Přihlašovací jméno uživatele. Vyžadováno pouze pokud není předáno pomocí hlaviček.
      responses:
        "200":
          description: Přihlášení bylo úspěšné
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JWTToken"
  /qr:
    get:
      summary: Získání QR kódu pro platbu za Pizza day
      security: [] # Nevyžaduje autentizaci
      parameters:
        - in: query
          name: login
          schema:
            type: string
          required: true
          description: Přihlašovací jméno uživatele, pro kterého bude vrácen QR kód
      responses:
        "200":
          description: Vygenerovaný QR kód pro platbu
          content:
            image/png:
              schema:
                type: string
                format: binary
  /data:
    get:
      summary: Načtení klientských dat pro aktuální nebo předaný den
      parameters:
        - in: query
          name: dayIndex
          description: Index dne v týdnu. Pokud není předán, je použit aktuální den.
          schema:
            type: integer
            minimum: 0
            maximum: 4
      responses:
        "200":
          $ref: "#/components/responses/ClientDataResponse"
  /addChoice:
    post:
      summary: Přidání či nahrazení volby uživatele pro zvolený den/podnik
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - locationKey
              allOf:
                - locationKey:
                  $ref: "#/components/schemas/LunchChoice"
                - dayIndex:
                  $ref: "#/components/schemas/DayIndex"
                - foodIndex:
                  $ref: "#/components/schemas/FoodIndex"
      responses:
        "200":
          $ref: "#/components/responses/ClientDataResponse"
  /removeChoices:
    post:
      summary: Odstranění volby uživatele pro zvolený den/podnik, včetně případných jídel
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - locationKey
              allOf:
                - locationKey:
                  $ref: "#/components/schemas/LunchChoice"
                - dayIndex:
                  $ref: "#/components/schemas/DayIndex"
      responses:
        "200":
          $ref: "#/components/responses/ClientDataResponse"
components:
  schemas:
    # --- OBECNÉ ---
    JWTToken:
      type: object
      description: Klientský JWT token pro autentizaci a autorizaci
      required:
        - login
        - trusted
        - iat
      properties:
        login:
          type: string
          description: Přihlašovací jméno uživatele
        trusted:
          type: boolean
          description: Příznak, zda se jedná o uživatele ověřeného doménovým přihlášením
        iat:
          type: number
          description: Časové razítko vydání tokenu
    ClientData:
      description: Klientská data pro jeden konkrétní den. Obsahuje menu všech načtených podniků a volby jednotlivých uživatelů.
      type: object
      additionalProperties: false
      required:
        - todayDayIndex
        - date
        - isWeekend
        - choices
      properties:
        todayDayIndex:
          description: Index dnešního dne v týdnu
          $ref: "#/components/schemas/DayIndex"
        date:
          description: Human-readable datum dne
          type: string
        isWeekend:
          description: Příznak, zda je tento den víkend
          type: boolean
        dayIndex:
          description: Index dne v týdnu, ke kterému se vztahují tato data
          $ref: "#/components/schemas/DayIndex"
        choices:
          $ref: "#/components/schemas/LunchChoices"
        menus:
          $ref: "#/components/schemas/RestaurantDayMenuMap"
        pizzaDay:
          $ref: "#/components/schemas/PizzaDay"
        pizzaList:
          description: Seznam dostupných pizz pro předaný den
          type: array
          items:
            $ref: "#/components/schemas/Pizza"
        pizzaListLastUpdate:
          description: Datum a čas poslední aktualizace pizz
          type: string
          format: date-time

    # --- OBĚDY ---
    UserLunchChoice:
      description: Konkrétní volba stravování jednoho uživatele v konkrétní den. Může se jednat jak o stravovací podnik, tak možnosti "budu objednávat", "neobědvám" apod.
      additionalProperties: false
      properties:
        # TODO toto je tu z dost špatného důvodu, viz použití - mělo by se místo toho z loginu zjišťovat zda je uživatel trusted
        trusted:
          description: Příznak, zda byla tato volba provedena uživatelem ověřeným doménovým přihlášením
          type: boolean
        selectedFoods:
          description: Pole indexů vybraných jídel v rámci dané restaurace. Index představuje pořadí jídla v menu dané restaurace.
          type: array
          items:
            type: integer
        departureTime:
          description: Čas preferovaného odchodu do dané restaurace v human-readable formátu (např. 12:00)
          type: string
        note:
          description: Volitelná, veřejně viditelná uživatelská poznámka k vybrané volbě
          type: string
    LocationLunchChoicesMap:
      description: Objekt, kde klíčem je možnost stravování ((#/components/schemas/LunchChoice)) a hodnotou množina uživatelů s touto volbou ((#/components/schemas/LunchChoices)).
      type: object
      additionalProperties:
        $ref: "#/components/schemas/UserLunchChoice"
    LunchChoices:
      description: Objekt, představující volby všech uživatelů pro konkrétní den. Klíčem je (#/components/schemas/LunchChoice).
      type: object
      properties:
        SLADOVNICKA:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        TECHTOWER:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        ZASTAVKAUMICHALA:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        SENKSERIKOVA:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        SPSE:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        PIZZA:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        OBJEDNAVAM:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        NEOBEDVAM:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
        ROZHODUJI:
          $ref: "#/components/schemas/LocationLunchChoicesMap"
    Restaurant:
      description: Stravovací zařízení (restaurace, jídelna, hospoda, ...)
      type: string
      enum:
        - Sladovnická
        - TechTower
        - Zastávka u Michala
        - Šenk Šeříková
      x-enum-varnames:
        - SLADOVNICKA
        - TECHTOWER
        - ZASTAVKAUMICHALA
        - SENKSERIKOVA
    LunchChoice:
      description: Konkrétní možnost stravování (konkrétní restaurace, pizza day, objednání, neobědvání, rozhodování se, ...)
      type: string
      enum:
        - Sladovnická
        - TechTower
        - Zastávka u Michala
        - Šenk Šeříková
        - SPŠE
        - Pizza day
        - Budu objednávat
        - Mám vlastní/neobědvám
        - Rozhoduji se
      x-enum-varnames:
        - SLADOVNICKA
        - TECHTOWER
        - ZASTAVKAUMICHALA
        - SENKSERIKOVA
        - SPSE
        - PIZZA
        - OBJEDNAVAM
        - NEOBEDVAM
        - ROZHODUJI
    DayIndex:
      description: Index dne v týdnu (0 = pondělí, 4 = pátek)
      type: integer
      minimum: 0
      maximum: 4
    FoodIndex:
      description: Pořadový index jídla v menu konkrétní restaurace
      type: integer
      minimum: 0
    Food:
      description: Konkrétní jídlo z menu restaurace
      type: object
      additionalProperties: false
      required:
        - name
        - isSoup
      properties:
        amount:
          description: Množství standardní porce, např. 0,33l nebo 150g
          type: string
        name:
          description: Název/popis jídla
          type: string
        price:
          description: Cena ve formátu '135 Kč'
          type: string
        isSoup:
          description: Příznak, zda se jedná o polévku
          type: boolean
    RestaurantDayMenu:
      description: Menu restaurace na konkrétní den
      type: object
      additionalProperties: false
      properties:
        lastUpdate:
          description: UNIX timestamp poslední aktualizace menu
          type: integer
        closed:
          description: Příznak, zda je daný podnik v daný den zavřený
          type: boolean
        food:
          description: Seznam jídel pro daný den
          type: array
          items:
            $ref: "#/components/schemas/Food"
    RestaurantDayMenuMap:
      description: Objekt, kde klíčem je podnik ((#/components/schemas/Restaurant)) a hodnotou denní menu daného podniku ((#/components/schemas/RestaurantDayMenu))
      type: object
      additionalProperties: false
      properties:
        SLADOVNICKA:
          $ref: "#/components/schemas/RestaurantDayMenu"
        TECHTOWER:
          $ref: "#/components/schemas/RestaurantDayMenu"
        ZASTAVKAUMICHALA:
          $ref: "#/components/schemas/RestaurantDayMenu"
        SENKSERIKOVA:
          $ref: "#/components/schemas/RestaurantDayMenu"
    WeekMenu:
      description: Pole týdenních menu jednotlivých podniků. Indexem je den v týdnu (0 = pondělí, 4 = pátek), hodnotou denní menu daného podniku.
      type: array
      minItems: 5
      maxItems: 5
      items:
        $ref: "#/components/schemas/RestaurantDayMenuMap"
    DepartureTime:
      description: Preferovaný čas odchodu na oběd
      type: string
      enum:
        - "10:00"
        - "10:15"
        - "10:30"
        - "10:45"
        - "11:00"
        - "11:15"
        - "11:30"
        - "11:45"
        - "12:00"
        - "12:15"
        - "12:30"
        - "12:45"
        - "13:00"
      x-enum-varnames:
        - T10_00
        - T10_15
        - T10_30
        - T10_45
        - T11_00
        - T11_15
        - T11_30
        - T11_45
        - T12_00
        - T12_15
        - T12_30
        - T12_45
        - T13_00

    # --- HLASOVÁNÍ ---
    FeatureRequest:
      type: string
      enum:
        - Ruční generování QR kódů mimo Pizza day (např. při objednávání)
        - Možnost označovat si jídla jako oblíbená (taková jídla by se uživateli následně zvýrazňovala)
        - Možnost úhrady v podniku za všechny jednou osobou a následné generování QR ostatním
        - Zrušení \"užívejte víkend\", místo toho umožnit zpětně náhled na uplynulý týden
        - Umožnění zobrazení vygenerovaného QR kódu i po následující dny (dokud ho uživatel ručně \"nezavře\", např. tlačítkem \"Zaplatil jsem\")
        - Zobrazování náhledů (fotografií) pizz v rámci Pizza day
        - Statistiky (nejoblíbenější podnik, nejpopulárnější jídla, nejobjednávanější pizzy, nejčastější uživatelé, ...)
        - Vylepšení responzivního designu
        - Zvýšení zabezpečení aplikace
        - Zvýšená ochrana proti chybám uživatele (potvrzovací dialogy, překliky, ...)
        - Celkové vylepšení UI/UX
        - Zlepšení dokumentace/postupů pro ostatní vývojáře
      x-enum-varnames:
        - CUSTOM_QR
        - FAVORITES
        - SINGLE_PAYMENT
        - NO_WEEKENDS
        - QR_FOREVER
        - PIZZA_PICTURES
        - STATISTICS
        - RESPONSIVITY
        - SECURITY
        - SAFETY
        - UI
        - DEVELOPMENT

    # --- EASTER EGGS ---
    EasterEgg:
      description: Data pro zobrazení easter eggů
      type: object
      additionalProperties: false
      required:
        - path
        - url
        - startOffset
        - endOffset
        - duration
      properties:
        path:
          type: string
        url:
          type: string
        startOffset:
          type: number
        endOffset:
          type: number
        duration:
          type: number
        width:
          type: string
        zIndex:
          type: integer
        position:
          type: string
          enum:
            - absolute
        animationName:
          type: string
        animationDuration:
          type: string
        animationTimingFunction:
          type: string

    # --- STATISTIKY ---
    LocationStats:
      description: Objekt, kde klíčem je zvolená možnost a hodnotou počet uživatelů, kteří tuto možnosti zvolili
      type: object
      additionalProperties: false
      properties:
        # Bohužel OpenAPI neumí nadefinovat objekt, kde klíčem může být pouze hodnota existujícího enumu :(
        SLADOVNICKA:
          type: number
        TECHTOWER:
          type: number
        ZASTAVKAUMICHALA:
          type: number
        SENKSERIKOVA:
          type: number
        SPSE:
          type: number
        PIZZA:
          type: number
        OBJEDNAVAM:
          type: number
        NEOBEDVAM:
          type: number
        ROZHODUJI:
          type: number
    DailyStats:
      description: Statistika vybraných možností pro jeden konkrétní den
      type: object
      additionalProperties: false
      required:
        - date
        - locations
      properties:
        date:
          description: Datum v human-readable formátu
          type: string
        locations:
          $ref: "#/components/schemas/LocationStats"
    WeeklyStats:
      description: Pole statistik vybraných možností pro jeden konkrétní týden. Index představuje den v týdnu (0 = pondělí, 4 = pátek)
      type: array
      minItems: 5
      maxItems: 5
      items:
        $ref: "#/components/schemas/DailyStats"

    # --- PIZZA DAY ---
    PizzaDayState:
      description: Stav pizza day
      type: string
      enum:
        - Pizza day nebyl založen
        - Pizza day je založen
        - Objednávky uzamčeny
        - Pizzy objednány
        - Pizzy doručeny
      x-enum-varnames:
        - NOT_CREATED
        - CREATED
        - LOCKED
        - ORDERED
        - DELIVERED
    # TODO toto je jen rozšířená varianta PizzaVariant - sloučit do jednoho objektu
    PizzaSize:
      description: Údaje o konkrétní variantě pizzy
      type: object
      additionalProperties: false
      required:
        - varId
        - size
        - pizzaPrice
        - boxPrice
        - price
      properties:
        varId:
          description: Unikátní identifikátor varianty pizzy
          type: integer
        size:
          description: Velikost pizzy, např. "30cm"
          type: string
        pizzaPrice:
          description: Cena samotné pizzy v Kč
          type: number
        boxPrice:
          description: Cena krabice pizzy v Kč
          type: number
        price:
          description: Celková cena (pizza + krabice)
          type: number
    Pizza:
      description: Údaje o konkrétní pizze.
      type: object
      additionalProperties: false
      required:
        - name
        - ingredients
        - sizes
      properties:
        name:
          description: Název pizzy
          type: string
        ingredients:
          description: Seznam obsažených ingrediencí
          type: array
          items:
            type: string
        sizes:
          description: Dostupné velikosti pizzy
          type: array
          items:
            $ref: "#/components/schemas/PizzaSize"
    PizzaVariant:
      description: Konkrétní varianta (velikost) jedné pizzy.
      type: object
      additionalProperties: false
      required:
        - varId
        - name
        - size
        - price
      properties:
        varId:
          description: Unikátní identifikátor varianty pizzy
          type: integer
        name:
          description: Název pizzy
          type: string
        size:
          description: Velikost pizzy (např. "30cm")
          type: string
        price:
          description: Cena pizzy v Kč, včetně krabice
          type: number
    PizzaOrder:
      description: Údaje o objednávce pizzy jednoho uživatele.
      type: object
      additionalProperties: false
      required:
        - customer
        - totalPrice
        - hasQr
      properties:
        customer:
          description: Jméno objednávajícího uživatele
          type: string
        pizzaList:
          description: Seznam variant pizz k objednání (typicky bývá jen jedna)
          type: array
          items:
            $ref: "#/components/schemas/PizzaVariant"
        fee:
          description: Příplatek (např. za extra ingredience)
          type: object
          properties:
            text:
              description: Popis příplatku (např. "kuřecí maso navíc")
              type: string
            price:
              description: Cena příplatku v Kč
              type: number
        totalPrice:
          description: Celková cena všech objednaných pizz daného uživatele, včetně krabic a příplatků
          type: number
        hasQr:
          description: |
            Příznak, pokud je k této objednávce vygenerován QR kód pro platbu. To je typicky pravda, pokud:
            - objednávající má v nastavení vyplněno číslo účtu
            - pizza day je ve stavu DELIVERED (Pizzy byly doručeny)
        note:
          description: Volitelná uživatelská poznámka pro objednávajícího (např. "bez oliv")
          type: string
    PizzaDay:
      description: Data o Pizza day pro konkrétní den
      type: object
      additionalProperties: false
      properties:
        state:
          $ref: "#/components/schemas/PizzaDayState"
        creator:
          description: "Jméno zakladatele pizza day"
          type: string
        orders:
          description: Pole objednávek jednotlivých uživatelů
          type: array
          items:
            $ref: "#/components/schemas/PizzaOrder"

    # --- NOTIFIKACE ---
    UdalostEnum:
      type: string
      enum:
        - Zahájen pizza day
        - Objednána pizza
        - Jdeme na oběd
      x-enum-varnames:
        - ZAHAJENA_PIZZA
        - OBJEDNANA_PIZZA
        - JDEME_NA_OBED
    NotifikaceInput:
      type: object
      required:
        - udalost
        - user
      properties:
        udalost:
          $ref: "#/components/schemas/UdalostEnum"
        user:
          type: string
    NotifikaceData:
      type: object
      required:
        - input
      properties:
        input:
          $ref: "#/components/schemas/NotifikaceInput"
        gotify:
          type: boolean
        teams:
          type: boolean
        ntfy:
          type: boolean
    GotifyServer:
      type: object
      required:
        - server
        - api_keys
      properties:
        server:
          type: string
        api_keys:
          type: array
          items:
            type: string
  responses:
    ClientDataResponse:
      description: Aktuální data pro klienta
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ClientData"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []