pakAGdocs
pakAGdocs

Backend dokumentazioa

Tech stack

  • Next.js Route Handlers (src/app/api/*)
  • TypeScript
  • MySQL mysql2/promise bidez
  • JWT (jsonwebtoken)
  • Emaila Resend-en bidez
  • Google Maps Directions + Geocoding

API route antolaketa

Domeinu karpetak backend-js/src/app/api azpian:

  • auth
  • users
  • packages
  • routes
  • stops
  • logs
  • tracking

Use-case bakoitzak geruzatutako patroia jarraitzen du:

  • route.ts (transport)
  • dto/dtos (balidazioa)
  • service (negozio logika)
  • repository (SQL sarbidea)

DTO balidazio patroia

DTO moduluek query/body input-ak balidatzen dituzte service-a exekutatu aurretik eta ValidationError botatzen dute balio ez dutenean. Route handler-ek erroreak lib/response.ts-eko handleError bidez zentralizatzen dituzte.

Service eta repository patroiak

  • Service-ek arauak, trantsizioak eta albo-efektuak koordinatzen dituzte.
  • Repository-ek SQL kontsultak kapsulatzen dituzte eta row-mapped objektuak itzultzen dituzte.
  • Domeinuen arteko portaera partekatua erauzten da (adibidez pakete egoeren albo-efektuak).

Error handling eta response helper-ak

  • Error pertsonalizatuak: ValidationError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError.
  • handleError(tag, error)-ek erroreak HTTP status-etara eta { error } forma koherentera mapatzen ditu.
  • res.ok-ek cookieak ezartzea/ezabatzea onartzen du.

Autentikazioa eta baimena

  • Access token-a: Bearer JWT behar da endpoint babestuetarako.
  • requireAuth(request, allowedRoles?)-ek token-a eta aukerako rol murrizketak egiaztatzen ditu.
  • Rolak src/app/types/index.ts-n definituta daude: admin eta distributor.

MySQL konexioa

connect()-ek pool bat modu lazy-an sortu eta cacheatzen du, connection limit 10 erabilita. SSL gaituta dago rejectUnauthorized: false ezarpenarekin uneko inplementazioan.

Email bidalketa

Resend bezeroa honetarako erabiltzen da:

  • kontu aktibazioa,
  • password reset-a,
  • login jakinarazpenak,
  • pakete egoera emailak (pending/assigned/in_transit/delivered/undelivered/failed).

Google Directions integrazioa

mapsService.optimizeRoute:

  • Google Directions-era deitzen du waypoint optimization erabilita,
  • stop ordenatuak + ETA kalkulatzen ditu,
  • total duration eta distance itzultzen ditu.

mapsService.geocodeAddress-ek testuzko helbidea koordenatu bihurtzen du pakete sortze/eguneratze fluxuetarako.

Pakete egoeren albo-efektuak

applyPackageStatusSideEffects-ek hau egiten du:

  1. log txertaketa package_status_logs taulan,
  2. tracking token lookup-a,
  3. distributor name lookup-a,
  4. egoera emaila hartzaileei bidaltzea.

Tracking token-ak tokens taulan gordetzen dira tracking_token motarekin, paketeari lotuta, eta endpoint publikoak erabiltzen ditu:

  • GET /api/tracking/:trackingToken

Reset password fluxua

  1. POST /api/auth/forgotPassword-ek reset token-a sortu/ezeztatu eta emaila bidaltzen du.
  2. PATCH /api/auth/changePwd:
    • token-arekin bakarrik: balidazio check-a,
    • newPassword-ekin: password-a eguneratzen du, erabiltzailea aktibatzen du, reset/activation token-ak ezeztatzen ditu.

Kontu aktibazio fluxua

Erabiltzailea sortzeak aktibazio emailaren sorrera pizten du sendActivationEmailService bidez. Aktibazio token mota activate_account_token da eta changePwd token-verification mekanismo berak balidatzen du.

[!WARNING] Aktibazio URL-ak une honetan RESET_BASE_URL berrerabiltzen du kodean. Kontuan hartu email link-ak konfiguratzean.

Logak

Egoera aldaketak package_status_logs-en idazten dira eta honen bidez agertzen dira:

  • GET /api/logs/listAll (admin)
  • GET /api/logs/listByPackage (admin/distributor)

Routes/stops/packages domeinu fluxuak

Ruta sorrera

  • Distributor user-a eta eguneko-ruta-bakarra constraint-a balidatzen ditu.
  • Carryover package-ak bateratzen ditu.
  • Stop ordena Google Directions bidez optimizatzen du.
  • Ruta + route stops txertatzen ditu eta paketeen estimated delivery eguneratzen du.

Iraganeko rutatik jarraitzea

  • Azken iraganeko ruta pendientea aurkitzen du.
  • Stop pendienteak egungo eguneko rutara migratzen ditu.
  • Pending pakete egoerak in_transit-era mugitzen ditu albo-efektuekin.

Stop operazioak

  • PATCH /api/stops/reorder (admin) stop ordena eguneratzen du.
  • PATCH /api/stops/updateArrival (distributor) bere stop-aren actual_arrival zigilatzen du.

Package operazioak

  • Paketea + helbidea + tracking token-a + hasierako log-a + tracking emaila sortzen ditu.
  • Pakete xehetasunak/helbidea eta lotutako albo-efektuak eguneratzen ditu.
  • Distributor egoera trantsizioak allowed-transition matrix eta route-order constraint-ekin behartzen dira.