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
| Dio | Tehnologija | Čemu služi |
|---|---|---|
| API | NestJS + Prisma | Jedan poslužitelj za sve kanale; prefiks /api |
| Baza | PostgreSQL + PostGIS | Podaci svih tvrtki, RLS po tvrtki, geometrija zona |
| Red za ograničenja | Redis | Brojanje zahtjeva po ključu i po adresi |
| Web kanali | Bez okvira, statika | Konzola tvrtke, vozački i putnički web te interna konzola platforme |
| Aplikacije | Flutter (Android, iOS) | Vozačka i putnička aplikacija pod brendom tvrtke |
| Datoteke | S3-kompatibilna pohrana (R2) | Dokumenti flote i tvrtke; u bazi ostaje samo ključ |
| Karte | Mapbox, Google, OSRM | Karta, adrese i ruta; pružatelj je postavka tvrtke |
| Plaćanje | Stripe, Nexi, Viva.com | Kartično plaćanje u aplikaciji i SoftPOS na terminalu |
| Fiskalizacija | CIS (HR), eRačun | Fiskalni račun prema pravilima zemlje |
| Push | FCM (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
| Što | Ograničenje | Izvor |
|---|---|---|
| Svi zahtjevi (zadano) | 120 u 60 sekundi | api/src/app.module.ts |
Partner API /api/v1 | 120 u minuti po ključu | api-v1.controller.ts |
| Prijava i oporavak lozinke | strože, po adresi i računu | auth/* |
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.
| Kanal | Kome | Što nosi |
|---|---|---|
GET /api/driver/events/stream | Vozačka aplikacija | Nove ponude, promjena vožnje, poruke dispečera |
GET /api/company/events/stream | Konzola tvrtke | Nove vožnje, promjene stanja, dolazak vozača |
GET /api/public/rides/:token/events | Putnička stranica praćenja | Položaj vozila i status vožnje za jedan token |
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.
{
"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
tenantIdse 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čje | Podržano | Napomena |
|---|---|---|
| Karte i adrese | Mapbox, Google Maps, OSRM | Token po tvrtki; javni token karte odvojen je od tajnog |
| Kartično plaćanje | Stripe, Nexi, Viva.com | Webhook po pružatelju; potpis se provjerava prije knjiženja |
| Fiskalizacija | CIS (HR), eRačun | Način rada (test/proizvodnja) je eksplicitna postavka |
| Push | FCM, APNs | Konfiguracija po tvrtki, ne zajednička |
| E-pošta | SMTP | Predlošci po tvrtki, pošiljatelj je tvrtka |
| Telefonija | PBX / pozivni centar | Maskiranje broja i transfer poziva; modul addon.operator_console |