Water on Airports — System Documentation v2.0

Water on Airports

Ztokenizowany system dystrybucji wody pitnej na lotniskach. Cyfrowe tokeny (QR code) umozliwiaja sprawna, bezgotowkowa dystrybucje wody dla pasazerow i pracownikow.

Problem

Dostep do wody pitnej na lotniskach jest ograniczony i kosztowny. Pasazerowie opoznionych lotow, uczestnicy eventow czy pracownicy lotniska czesto nie maja wygodnego sposobu na otrzymanie wody bez stania w kolejkach czy szukania automatow.

Lotniska i linie lotnicze potrzebuja systemu, ktory pozwoli im szybko, masowo i kontrolowanie dystrybuowac wode do uprawnionych osob — z pelna sciezka audytu.

Rozwiazanie

Water on Airports to platforma tokenowa, w ktorej cyfrowy token (kod QR) jest wymieniany na butelke wody przy dystrybutorze. System obsluguje pelny cykl zycia tokena:

1
Emisja Instytucja (lotnisko, airline, sponsor) emituje tokeny — pojedynczo lub masowo (np. 150 tokenow dla opoznionego lotu).
2
Dystrybucja QR Beneficjent otrzymuje kod QR — w aplikacji, emailem, SMS-em lub jako wydruk przy gate.
3
Realizacja Beneficjent okazuje QR przy dystrybutorze. System waliduje token, dekrementuje licznik i wydaje wode.
4
Audyt Kazda transakcja jest rejestrowana. Audytor ma pelny wglad w statystyki — per instytucja, per dystrybutor, w czasie rzeczywistym.

Jak uzyskac dostep

Kazda rola (oprocz beneficjenta) wymaga klucza API do autoryzacji. Klucze sa generowane automatycznie przez system i przekazywane w lancuchu zaufania:

Rola Skad dostaje klucz API Gdzie go uzywa
Admin Klucz ustawiony w konfiguracji serwera (.env). Znany tylko administratorowi systemu. GUI → zakladka Admin → pole "Admin API Key"
Institution Admin tworzy instytucje w panelu Admin → system generuje klucz API → Admin kopiuje go i przekazuje instytucji (emailem, w umowie, etc.). GUI → zakladka Institution → pole "Institution API Key"
Operator Admin tworzy dystrybutor w panelu Admin → system generuje klucz API → Admin konfiguruje terminal/automat tym kluczem lub przekazuje operatorowi. GUI → zakladka Operator → pole "Distributor API Key"
Beneficiary Nie potrzebuje klucza API. Otrzymuje kod QR od instytucji (wydruk, email, SMS, w aplikacji). QR code = jedyny "klucz". GUI → zakladka Beneficiary → pole "Your QR Code"
Auditor Admin tworzy audytora w panelu Admin → system generuje klucz API → Admin przekazuje audytorowi. GUI → zakladka Auditor → pole "Auditor API Key"

Lancuch wydawania kluczy

Konfiguracja serwera (.env)
    │
    ▼
Admin (klucz z .env)
    │
    ├──▶ Tworzy instytucje → klucz API → przekazuje Institution
    │                                          │
    │                                          └──▶ Emituje tokeny → QR code → przekazuje Beneficiary
    │
    ├──▶ Tworzy dystrybutor → klucz API → konfiguruje Operator
    │
    └──▶ Tworzy audytora → klucz API → przekazuje Auditor

Pierwszy krok po uruchomieniu systemu:

  1. Admin loguje sie kluczem z .env i tworzy co najmniej jedna instytucje i jeden dystrybutor
  2. Admin kopiuje wygenerowane klucze API i przekazuje je odpowiednim osobom
  3. Institution loguje sie swoim kluczem i emituje tokeny
  4. Operator loguje sie kluczem dystrybutora i jest gotowy do wydawania wody
  5. Beneficjenci otrzymuja QR kody od instytucji i moga korzystac z systemu

Role w systemie — szczegoly

System definiuje 5 rol, kazda z dedykowanym interfejsem i uprawnieniami.

Admin

Administrator systemu — zarzadza cala platforma.

Klucz API: Zdefiniowany w konfiguracji serwera (.env). Tylko administrator ma do niego dostep.

Co robi:

  • Rejestruje instytucje (lotniska, airlines, sponsorow)
  • Tworzy punkty dystrybucji (automaty, stanowiska)
  • Nadaje uprawnienia audytorom
  • Wydaje klucze API kazdej roli

Jak uzywa: Panel Admin w GUI → wpisuje klucz administratora → CRUD instytucji, dystrybutorow, audytorow. Przy kazdym utworzeniu encji system generuje unikalny klucz API — Admin kopiuje go i przekazuje odpowiedniej osobie.

Institution (Sponsor)

Lotnisko, linia lotnicza, firma sponsorska — podmiot fundujacy wode.

Klucz API: Otrzymany od Admina po rejestracji instytucji w systemie.

Co robi:

  • Emituje tokeny — pojedynczo lub masowo (batch do 1000 szt.)
  • Grupuje tokeny (np. per lot: group_id="LO1234")
  • Uniewaznieni tokeny (revoke) — pojedynczo lub cala grupe
  • Monitoruje zuzycie swoich tokenow

Jak uzywa: Portal Institution w GUI → wpisuje klucz instytucji → emituje tokeny, sprawdza saldo, revoke.

Przykladowy scenariusz: Lot LO1234 opozniony o 4h → instytucja emituje 150 tokenow x 2 butelki z group_id="LO1234" i data wygasniecia. QR kody drukowane i rozdawane przy gate.

Operator

Osoba lub automat przy punkcie wydawczym wody.

Klucz API: Otrzymany od Admina po utworzeniu dystrybutora. Konfigurowany w terminalu/automacie.

Co robi:

  • Skanuje lub wpisuje kod QR beneficjenta
  • System natychmiast waliduje token i zwraca decyzje: wydaj / odmow
  • Widzi ile uzyc pozostalo na tokenie

Jak uzywa: Terminal Operator w GUI → wpisuje klucz dystrybutora → skanuje QR → przycisk "DISPENSE WATER" → system odpowiada w <1s.

Zabezpieczenia: Rate limit 60s miedzy uzyciam tego samego tokena (ochrona przed fraudem). Walidacja typu produktu (token na wode nie zadziala na automacie z kawa).

Beneficiary (Odbiorca)

Pasazer, pracownik, gosc — osoba ktora otrzymala QR code.

Klucz API: Nie wymaga. Jedyne "uprawnienie" to kod QR otrzymany od instytucji (wydruk, email, SMS, aplikacja).

Co robi:

  • Sprawdza saldo tokena (ile butelek pozostalo)
  • Przglada historie swoich transakcji
  • Okazuje QR przy dystrybutorze aby otrzymac wode

Jak uzywa: Strona Beneficiary w GUI → wpisuje swoj kod QR → widzi saldo i historie. Nie wymaga logowania ani klucza — token jest typu bearer (kto ma QR, ten korzysta).

Auditor

Kontroler, zarzad lotniska, regulator — rola read-only.

Klucz API: Otrzymany od Admina po utworzeniu konta audytora.

Co robi:

  • Przeglada globalne statystyki systemu
  • Analizuje dane per instytucja i per dystrybutor
  • Identyfikuje anomalie (np. dystrybutor z zerowym ruchem)

Jak uzywa: Dashboard Auditor w GUI → wpisuje klucz audytora → "Load Reports" → kafelki z podsumowaniem + tabele per instytucja/dystrybutor.

Scenariusze uzycia

Opozniony lot

Lot opozniony o 4h. Lotnisko emituje 150 tokenow (po 2 butelki kazdy) z group_id = numer lotu i data wygasniecia = czas odlotu + 2h. QR kody drukowane i rozdawane przy gate. Gdy lot odwolany — batch revoke uniewaznieni wszystkie tokeny jednym kliknieciem.

Airline — pakiet wody w bilecie

Pasazer kupuje bilet z dodatkiem "water package" (3 butelki). System airline automatycznie emituje token z max_uses=3. QR pojawia sie w aplikacji obok boarding pass. Pasazer korzysta z dowolnego dystrybutora na lotnisku.

Event sponsorowany

Firma X sponsoruje event na lotnisku — chce rozdac 500 butelek wody. Rejestruje sie jako instytucja, emituje 500 tokenow jednorazowych. QR kody na ulotkach lub ekranach. Po evencie niewykorzystane tokeny automatycznie wygasaja. Audytor generuje raport: 387/500 wykorzystanych.

VIP Lounge

Pasazer VIP wchodzi do lounge — system wydaje token z max_uses=99 i wygasnieciem o polnocy. Pasazer korzysta z dystrybutora wielokrotnie przez caly dzien.

Kluczowe cechy systemu

Bearer

Tokeny domyslnie anonimowe — zero RODO, pelna prywatnosc

Batch

Emisja do 1000 tokenow jednym wywolaniem API

Grupy

Tokeny grupowane per lot/event — latwiejszy revoke i raportowanie

Multi‑product

Gotowe na rozszerzenie: woda, kawa, snack — jedno API

Rate limit

60s cooldown — ochrona przed fraudem

Real‑time

Walidacja <100ms, raporty na zywo

Technologia

BackendPython / FastAPI (async)
Baza danychSQLite (PoC) → PostgreSQL (produkcja)
FrontendHTML + vanilla JS + Pico CSS
InfrastrukturaDocker Compose + Caddy (reverse proxy)
BezpieczenstwoAPI key per rola, rate limiting, WireGuard VPN
DocelowoDjango + PostgreSQL + HTTPS + domena

Macierz uprawnien

Akcja Admin Institution Operator Beneficiary Auditor
Zarzadzanie instytucjami✔
Zarzadzanie dystrybutorami✔
Emisja tokenow✔✔ (swoje)
Uniewaznieni tokenow✔✔ (swoje)
Realizacja tokena (wydanie)✔
Sprawdzenie salda✔✔✔✔✔
Historia transakcji✔✔✔✔✔
Raporty globalne✔✔

Wyprobuj system

Kliknij ponizej aby przejsc do interfejsu operacyjnego.

Otworz system API Reference

Water on Airports v2.0 — PoC Documentation

Wygenerowano: