Driveoskatalog platforme

Arhitektura i sigurnost

Od kojih se dijelova sustav sastoji i što ga čuva — običnim riječima, bez tehničkog rječnika.

Većinu ovoga ne morate znati da biste radili u sustavu. Ali kad nešto zapne, korisno je znati gdje se što događa — zašto cijena nastaje na poslužitelju, zašto podaci jedne tvrtke ne mogu iscuriti u drugu i zašto se neka promjena vidi odmah, a neka tek u novoj verziji aplikacije.

Dijelovi sustava

DioTehnologijaČemu služi
APINestJS + PrismaJedan poslužitelj za sve kanale; prefiks /api
BazaPostgreSQL + PostGISPodaci svih tvrtki, RLS po tvrtki, geometrija zona
Red za ograničenjaRedisBrojanje zahtjeva po ključu i po adresi
Web kanaliBez okvira, statikaKonzola tvrtke, vozački i putnički web te interna konzola platforme
AplikacijeFlutter (Android, iOS)Vozačka i putnička aplikacija pod brendom tvrtke
DatotekeS3-kompatibilna pohrana (R2)Dokumenti flote i tvrtke; u bazi ostaje samo ključ
KarteMapbox, Google, OSRMKarta, adrese i ruta; pružatelj je postavka tvrtke
PlaćanjeStripe, Nexi, Viva.comKartično plaćanje u aplikaciji i SoftPOS na terminalu
FiskalizacijaCIS (HR), eRačunFiskalni račun prema pravilima zemlje
PushFCM (Android), APNs (iOS)Obavijesti vozačima i putnicima

Sesije i prijava

  • Prijava vraća kratkotrajni pristupni token i osvježni token; osvježni se izdaje jednom i rotira pri svakoj upotrebi.
  • Lozinka ima pravila koja se provjeravaju i na klijentu i na poslužitelju; prva lozinka vlasnika je privremena i mora se promijeniti.
  • Dvofaktorska prijava (TOTP) je dostupna na platformskim računima; prijava bez drugog faktora ne dobiva token.
  • Svaka promjena sigurnosno osjetljivog podatka završava u reviziji s korisnikom, vremenom i adresom.

Ograničenja prometa

ŠtoOgraničenjeIzvor
Svi zahtjevi (zadano)120 u 60 sekundiapi/src/app.module.ts
Partner API /api/v1120 u minuti po ključuapi-v1.controller.ts
Prijava i oporavak lozinkestrože, po adresi i računuauth/*

Kad se ograničenje prijeđe, odgovor je 429 s kodom errors.tooManyRequests i zaglavljem Retry-After. Klijent koji ponavlja zahtjev mora poštovati to zaglavlje — u protivnom samo produljuje blokadu.

Događaji u stvarnom vremenu

Tri su kanala događaja (Server-Sent Events). Svi su jednosmjerni: poslužitelj šalje, klijent sluša.

KanalKomeŠto nosi
GET /api/driver/events/streamVozačka aplikacijaNove ponude, promjena vožnje, poruke dispečera
GET /api/company/events/streamKonzola tvrtkeNove vožnje, promjene stanja, dolazak vozača
GET /api/public/rides/:token/eventsPutnička stranica praćenjaPoložaj vozila i status vožnje za jedan token
Zašto SSE, a ne WebSocketPraćenje vožnje mora raditi i kroz posrednike koji ne podržavaju nadogradnju protokola. SSE je običan HTTP odgovor koji teče, pa ga posrednik ne prekida, a klijent ga može ponovno otvoriti bez posebnog koda.

Jedan oblik greške

Svaka greška, bez obzira na to dolazi li iz provjere polja ili iz poslovnog pravila, ima isti oblik. message je za čovjeka, key za kod — i key se nikad ne prevodi.

json400 — tipičan odgovor
{
  "statusCode": 400,
  "message": "Ovaj modul nije uključen za tvrtku.",
  "key": "errors.moduleDisabled",
  "locale": "hr"
}

Katalog ima 739 različitih ključeva grešaka u kodu. Popis najvažnijih, s nacionalnim prijevodom i HTTP statusom, je na stranici Greške i ograničenja.

Izolacija i revizija

  • tenantId se nikad ne čita iz zahtjeva; dolazi iz sesije ili iz API ključa.
  • RLS u PostgreSQL-u je drugi sloj: upit bez konteksta tvrtke ne vraća ništa.
  • Revizija bilježi tko je što promijenio, kada i odakle — uključujući platformske radnje nad tuđom tvrtkom.
  • Dokumenti se ne drže u bazi: baza pamti ključ, sadržaj je u privatnoj pohrani s pristupom na potpisani link.

Vanjski pružatelji

Pružatelje bira tvrtka; platforma ih podržava bez izmjene koda. Ključevi se drže na poslužitelju tvrtke, a u konzoli se vidi samo je li pružatelj povezan.

PodručjePodržanoNapomena
Karte i adreseMapbox, Google Maps, OSRMToken po tvrtki; javni token karte odvojen je od tajnog
Kartično plaćanjeStripe, Nexi, Viva.comWebhook po pružatelju; potpis se provjerava prije knjiženja
FiskalizacijaCIS (HR), eRačunNačin rada (test/proizvodnja) je eksplicitna postavka
PushFCM, APNsKonfiguracija po tvrtki, ne zajednička
E-poštaSMTPPredlošci po tvrtki, pošiljatelj je tvrtka
TelefonijaPBX / pozivni centarMaskiranje broja i transfer poziva; modul addon.operator_console