Rețeaua companiilor din transportul de lemn

Descriere

Obiectivul este dezvoltarea unei aplicații web care vizualizează rețeaua de relații dintre companii implicate în transportul de lemn (emitenti și destinatari). Utilizatorul pornește de la o companie, vede cu cine este conectată, ce volum de lemn circulă pe fiecare relație și ce specii sunt implicate, explorând graficul ca pe o hartă de conexiuni.

Datele provin din ZebraHack3.0 Data API, în special din endpoint‑urile:

• GET /companies – pentru sugestii la căutarea companiilor;
• GET /network/company – vecinii (companii conectate) pentru o companie și rolul lor;
• GET /network/edge – transporturile și speciile asociate unei muchii (pereche emitent–destinatar).

Aplicația ar trebui să ajute utilizatorul să observe „hub-uri” (companii centrale), legături puternice (volum mare, multe transporturi) și diversitatea speciilor care circulă între doi actori.

Funcționalități:

1. Pagină de introducere care explică ideea de „rețea a companiilor” și de ce e utilă pentru transparență.
2. Căutare de companie după nume și rol (emitent/destinatar), cu sugestii ajutate de API.
3. Grafic interactiv care afișează companii drept noduri și relațiile dintre ele drept muchii.
4. Panou cu vecini direcți și detalii agregate pe relații (număr de transporturi, volume, specii).
5. Detalii pentru o muchie selectată, cu lista transporturilor și speciilor implicate.
6. Interfață modernă și explorabilă, care încurajează experimentarea cu layout-ul și stilul graficului.

[!IMPORTANT]

• Se va implementa exclusiv partea de front‑end: fișiere statice HTML, CSS și JavaScript + librării încărcate prin <script src="...">.
• Nu se folosesc backend propriu, server‑side rendering, bundlers sau transpileri (fără Webpack, Vite, Babel, TypeScript etc.).
• Pentru date se folosește ZebraHack3.0 Data API:
  • Documentație interactivă: https://zebrahack.iqnox.tech/api-docs/
• Autentificare: cheia de acces este numele echipei și se trimite ca header X-App-Key la fiecare request.

[!TIP] Librării recomandate (fără bundler, direct din CDN):

• Pentru grafic:
  • ForceGraph sau chiar 3d-force-graph;
  • D3 Sankey sau Plotly Sankey pentru diagrame Sankey (fluxul volumelor între emitent și destinatar) – util dacă vreți să puneți accent pe cantități, nu pe poziționarea nodurilor.
  • D3.js pentru force‑layout custom (SVG/canvas);
  • Cytoscape.js sau Sigma.js pentru grafuri interactive, toate încărcabile via <script src="...">.
  • Altele care pot fi utilizate direct în browser fără toolchain suplimentar.
• Fără librărie dedicată, rețeaua poate fi desenată și manual (SVG sau <canvas>) folosind poziționări proprii (ex.: nivel pe orizontală pentru emitent/destinatar, matrice de adiacență, chord diagram, listă de legături cu mini‑vizualizări).
• Pentru UI: componente CSS minimale sau framework-uri ușoare, atâta timp cât nu necesită toolchain suplimentar.
• Echipele pot ajusta culorile, dimensiunile și animațiile nodurilor/muchiilor sau pot propune complet alt tip de vizualizare a relațiilor, atât timp cât este clar ce companii și ce volume sunt implicate.

Task 1: Pagina de introducere și context

Construiți o pagină de tip landing care descrie conceptul de „rețea a companiilor” în contextul transportului de lemn.

Criterii de acceptare:

• Pagina explică, pe scurt, cum pot fi legate companiile prin lanțurile de transport (emitent → destinatar) și de ce merită investigate aceste relații (ex.: dependență de un singur partener, concentrarea volumelor).
• Sunt incluse referințe la SUMAL 2.0 și la rolul datelor publice pentru transparență.
• Se descrie, în termeni simpli, ce reprezintă nodurile (companiile) și muchiile (relațiile/transporturile) din grafic.
• Pagina conține un buton „Intră în rețea” care duce spre pagina principală cu graficul.
• Conținutul este static (doar HTML și CSS), fără apeluri la API.

Task 2: Header-ul aplicației și navigarea

Adăugați un header comun și un meniu de navigare între introducere și pagina cu rețeaua.

Criterii de acceptare:

• Header-ul include:
  • un logo sau semn vizual al aplicației;
  • titlul aplicației, de exemplu „Rețeaua companiilor din transportul de lemn”.
• Meniul de navigare permite accesul la cel puțin paginile: Introducere și Rețea.
• Pagina curentă este evidențiată vizual.
• Header-ul este reutilizat între pagini (copiat sau extras prin JS simplu).
• Layout-ul este la alegerea echipei, atâta timp cât navigarea rămâne clară.

Task 3: Căutare și sugestii pentru companii (endpoint /companies)

Implementați zona de căutare a companiilor, cu sugestii ajutate de API.

Criterii de acceptare:

• Utilizatorul alege rolul companiei (emitent sau destinatar) dintr-un control dedicat.
• Există un câmp de căutare pentru numele companiei.
• Pe măsură ce utilizatorul tastează, aplicația poate apela GET /companies cu parametrii role și search pentru a propune nume posibile (autocomplete).
• Sugestiile sunt afișate într-un mod integrat cu formularul (ex.: datalist, listă custom etc.).
• La submit, compania este folosita ca punct de pornire pentru explorarea rețelei (apel către /network/company).
• Se afișează mesaje clare când nu se găsește nicio companie sau când input-ul este invalid.

Task 4: Graficul rețelei (endpoint /network/company)

Construiți graficul interactiv care arată companiile și relațiile dintre ele.

Criterii de acceptare:

• La selectarea sau adăugarea unei companii, aplicația apelează GET /network/company cu parametrii name și role.
• Răspunsul conține compania centrală și neighbors (vecinii direcți), inclusiv:
  • direction (de ex. „destinatar” pentru muchii emitent → destinatar),
  • transport_count,
  • total_volume,
  • species agregate.
• Graficul afișează fiecare companie ca nod, iar relațiile ca muchii între noduri.
• Nodurile sunt stilizate diferit în funcție de rol (emitent / destinatar).
• Forța graficului (pozitionarea, animațiile) poate fi controlată cu parametrii librăriei alese; se urmărește să fie ușor de înțeles și de explorat.
• Este posibilă extinderea rețelei: de exemplu, click pe un nod sau pe un buton dedicat pentru a încărca vecinii unei alte companii și a o adăuga în grafic.

Task 5: Vecini direcți și detalii de relație

Construiți panoul de vecini și interacțiunea cu graficul.

Criterii de acceptare:

• După încărcarea datelor din /network/company, aplicația afișează o listă de „parteneri direcți” (vecinii).
• Pentru fiecare vecin, se afișează:
  • numele companiei;
  • transport_count;
  • total_volume;
  • lista de species și volumele aferente.
• Din acest panou, utilizatorul poate declanșa explorarea mai departe (ex.: un buton „Explorează …” care apelează din nou /network/company pentru vecinul selectat).
• Se mențin sincronizate panoul și graficul (de ex.: selecția unui vecin evidențiază muchia corespunzătoare în grafic sau invers).

Task 6: Detalii pentru o muchie (endpoint /network/edge)

Permiteți utilizatorului să inspecteze lista de transporturi dintre două companii.

Criterii de acceptare:

• La click pe o muchie din grafic (sau prin alt mecanism de selecție), aplicația apelează GET /network/edge cu parametrii emitent și destinatar.
• Răspunsul conține transports, iar pentru fiecare:
  • transport_id,
  • first_position și last_position,
  • total_volume,
  • lista de species și volumele aferente.
• Aplicația afișează aceste informații într-un panou dedicat (de ex. carduri sau listă de „transport X → detalii”), într-un mod ușor de parcurs.
• Dacă nu există transporturi între cele două companii, se afișează un mesaj clar (nu un panou gol).

Task 7: Design interfață utilizator (UI) și responsive

Asigurați o experiență de explorare plăcută a rețelei, pe orice dispozitiv.

Criterii de acceptare:

• Aplicația folosește o paletă de culori coerentă, cu distincție clară între roluri și/sau între muchii puternice vs. slabe.
• Nodurile și muchiile au feedback vizual la hover/selecare (culori, grosime, particule etc.).
• Panourile text (căutare, vecini, detalii muchie) sunt organizate astfel încât graficul și informațiile să se completeze reciproc, fără a se aglomera.
• Layout-ul este responsive:
  • pe ecrane mari, graficul are spațiu suficient, iar panourile de detalii sunt clar vizibile;
  • pe dispozitive mobile, interfața se adaptează (grafic redimensionat, panouri repoziționate) astfel încât interacțiunea să rămână confortabilă.
• Sunteți încurajați să experimentați cu animații, tranziții și stiluri proprii de vizualizare a rețelei, atâta timp cât păstrați claritatea și accesibilitatea informațiilor.