pakAGdocs
pakAGdocs

Frontend dokumentazioa

Tech stack

  • Next.js App Router
  • React 19
  • TanStack React Query
  • Axios
  • Tailwind CSS v4
  • HERE Maps integrazioa
  • boneyard-js skeleton loader osagaiak

App egitura

Karpeta nagusiak frontend-app/app azpian:

  • (auth) route group-a: login esperientzia.
  • (main) route group-a: autentikatutako dashboard fluxuak.
  • lib/api: Axios bezeroak eta API helper-ak.
  • hooks: query/mutation hook-ak domeinuka.
  • providers: React Query eta tutorial provider-ak.
  • utils/types/api: request eta response kontratu tipatuak.

Layout eta providers

app/layout.tsx-ek edukia honekin biltzen du:

  • AppProviders -> ReactQueryProvider
  • RouteGuard (auth atea)

(main)/layout.tsx-ek hau gehitzen du:

  • SessionKeepAlive (saioa freskatzeko background query-a)
  • PreferencesSync
  • AsideMenu + Header + footer
  • TutorialProvider

React Query erabilera

  • Query key-ak app/query/keys/* barruan antolatuta daude.
  • Query options app/query/options/* barruan daude.
  • Retry-ak desgaituta daude ohiko HTTP egoera ez-errepikagarrietarako (400/401/403/404/409).

Axios API bezeroa

apiClient konfigurazioak hau dauka:

  • withCredentials: true.
  • request interceptor bat Authorization: Bearer <access_token> injektatzeko.
  • response interceptor bat 401 jasotzean refresh egiteko (login/refresh/forgot-password/tracking endpoint-ak izan ezik), behin berriro saiatzeko eta huts eginez gero token-a garbitzeko.

Auth token biltegiratzea

  • Frontend-ak access token-a access_token cookiean gordetzen du (SameSite=Strict, max-age=15m).
  • Refresh token-a backend-ak kudeatutako HTTP-only cookiean geratzen da.

Refresh-token fluxua

  • Background refresh query-a (refreshTokenQueryOptions) 12 minuturo exekutatzen da.
  • Axios interceptor-ak refresh-a pizten du ustekabeko 401ean eta jatorrizko request-a behin berriro bidaltzen du.

RouteGuard portaera

  • Ruta publikoen zerrendak gaur egun /login bakarrik dauka.
  • Erabiltzaileak token baliorik gabe ruta babestu bat irekitzen badu, app-ak /login-era birbideratzen du.
  • Erabiltzaileak token baliozkoa badu eta /login irekitzen badu, app-ak /-era birbideratzen du.

Orri/pantaila nagusiak

  • /dashboard: profilaren laburpena, estatistikak, hurrengo entregak eta mapa panela.
  • /myPackages: paketeen list/grid ikuspegiak, bilaketa eta filtratzea esleitutako paketeetarako.
  • /myPackages/[packageId]: paketearen xehetasuna, helbidea, uneko egoera eta log historia.
  • /myRoute: eguneroko ruta exekutatzeko ikuspegia, progresua, stop ordenatuak eta mapa.
  • /history: pakete jardueraren historikoa eta analitika.
  • /settings: profila, segurtasuna eta itxura kontrolak.
  • /login: autentikazioa eta password berreskuratze modala.

Hooks eta API moduluak

Hook-ak domeinuka taldekatuta daude:

  • hooks/auth/*
  • hooks/packages/*
  • hooks/routes/*
  • hooks/tracking/*

API moduluak:

  • lib/api/auth-api.ts
  • lib/api/packages-api.ts
  • lib/api/routes-api.ts
  • lib/api/logs-api.ts
  • lib/api/tracking-api.ts

Motak

API modelo kanonikoak app/utils/types/api/*.ts barruan daude.

Estiloen ikuspegia eta PakAG identitatea

app/globals.css-ek PakAG paleta eta token semantikoak definitzen ditu (more iluneko gainazalak, violet accents, egoera koloreak). /docs-eko theme-ak paleta hori nahita islatzen du.

Skeleton/loading estrategia

Orriek Skeleton wrapper osagaiak erabiltzen dituzte domeinuaren araberako loader osagaiekin (adibidez dashboard, my-route eta history loader-ak).

Tracking UI

Frontend-ak tracking API bezeroa (tracking-api.ts) eta TRACKING_PATH_PREFIX konstanteak ditu. Tracking publikoaren portaerak backend-eko /api/tracking/:trackingToken endpoint-a erabiltzen du.

Dashboard/distributor/admin fluxuak

Uneko frontend ruta multzoa banatzaileari begira dago (dashboard, myPackages, myRoute, history, settings). Admin gaitasunak batez ere backend API-en bidez daude eskuragarri eta UI azalera bereiziak behar izan ditzakete.

[!NOTE] Admin-erako web pantailak ez dira argi agertzen frontend-app/app rutetan eta produktu irismenaren osotasunerako Needs verification gisa tratatu behar dira.