Queen Tracker

Opis projekta

Queen Tracker je fullstack web aplikacija za praćenje kvaliteta matica. Aplikacija ima deo koji korisnik vidi i koristi u pretraživaču (frontend — React + TypeScript), i serverski deo koji obrađuje zahteve i podatke čuva u MySQL bazi podataka (backend — Node.js + Express + mysql2).

Aplikacija funkcioniše kao dnevnik za evidenciju kvaliteta matica: pčelar kreira nalog, dodaje košnice, unosi matice, vezuje svaku maticu za košnicu i kroz kontrole ocenjuje leglo, intenzitet zaleganja, mirnoću, produktivnost, zdravlje i unosi preporuku za dalji rad.

I.1 - Tehničke karakteristike

U tehničkom smislu, ovo je CRUD sistem sa autentifikacijom, hijerarhijom uloga i jednom M:N relacijom. Administrator popunjava kataloge za tipove košnica i rase matica, pčelari vode sopstvene košnice i matice, evidentiraju dodele matica košnicama i kroz redovne kontrole prate kvalitet svake matice.

I.2 - Korisničke uloge

Funkcionalni zahtevi

Funkcionalni zahtevi opisuju šta aplikacija mora da omogući korisniku. Svaki zahtev se može shvatiti kao konkretna stranica, forma, tabela, filter ili akcija koju treba implementirati na frontendu i backendu.

II.1 — Registracija i prijava (Autentifikacija)

Korisnik se registruje, lozinka se čuva heširana u bazi podataka korišćenjem bcrypt biblioteke. Prijava vraća JSON Web Token (JWT) koji klijent čuva u localStorage pretraživača putem useAuth hook-a unutar autentifikacionog kontekstualnog prostora.

• Forma za registraciju: korisničko ime, ime i prezime, email, lozinka i profilna slika (base64 ili binarna datoteka putem multer biblioteke)
• Prijava vraća JWT koji se čuva u localStorage; token se čita pri svakom učitavanju stranice
• Odjava briše token i šalje POST /api/auth/logout koji beleži odjavu u audit log
• Zaštićene rute nedostupne bez važećeg tokena — automatski preusmeravanje na /login
• Validacija svakog polja na klijentskoj i na serverskoj strani

II.2 — Vodič za matice (javno dostupan)

Javni deo aplikacije služi da gost pre registracije razume čemu sistem služi. Ovaj deo ne prikazuje košnice, matice, kontrole kvaliteta niti bilo kakve privatne podatke pčelara.

• Početna stranica prikazuje naziv aplikacije, kratak opis i dugmad za prijavu i registraciju
• Stranica "Vodič za matice" prikazuje osnovne informacije o obeležavanju matica po godini
• Prikaz pet vrednosti za boju obeležavanja: bela, žuta, crvena, zelena i plava
• Prikaz primera izračunavanja boje obeležavanja na osnovu godine izleganja
• Gost može pregledati vodič, ali ne može kreirati maticu, košnicu ili kontrolu kvaliteta

II.3 — Upravljanje Košnicama

Svaka košnica pripada jednom pčelaru, a podaci o pčelinjaku čuvaju se direktno u tabeli hive.

• Pčelar može dodati košnicu unosom sledećih polja: oznaka košnice, tip košnice, naziv pčelinjaka, lokacija i napomena
  • Oznaka košnice mora biti jedinstvena za jednog korisnika
  • Tip košnice se bira iz padajućeg menija koji se puni iz tabele hive_types
  • Naziv pčelinjaka gde se košnica nalazi
  • Lokacija označava mesto, adresu ili kratak opis gde se košnica nalazi
  • Napomena je opciono polje za dodatni opis košnice
  • Primer za oznaku košnice: A-01 ili B-12; oznaka koju pčelar koristi da za razlikovanje svojih košnica, treba da prati format SLOVO-BROJ
• Prikaz košnica u obliku kartica sa oznakom košnice, lokacijom, aktivnom maticom i poslednjom ocenom kvaliteta
• Filtriranje košnica po lokaciji, tipu košnice i trenutno aktivnoj matici
• Stranica detalja košnice prikazuje osnovne podatke, aktivnu maticu i zapise iz queen_quality_checks vezane za tu košnicu
• Košnica se može arhivirati ako više nije u upotrebi; arhiviranje predstavlja logičko brisanje, tako da se zapis ne uklanja fizički iz baze

II.4 — Upravljanje Maticama

Matica je centralni entitet aplikacije. Kroz ovaj deo pčelar vodi osnovne podatke o matici, njen status i kasnije prati njen kvalitet kroz unos evidencija.

• Pčelar može dodati novu maticu unosom sledećih polja: oznaka matice, rasa matice, godina izleganja, boja oznake, poreklo, status i napomena
  • Oznaka matice mora biti jedinstvena za jednog pčelara
  • Primer za oznaku matice: Q-2026-001; oznaka treba da prati format Q-GODINA-BROJ
  • Rasa matice se bira iz padajućeg menija koji se puni iz tabele queen_breeds
  • Poreklo može biti: kupljena, rojena, selekcionisana ili nepoznatog porekla
  • Aplikacija automatski predlaže boju oznake na osnovu godine izleganja
  • Status matice može biti: aktivna, uginula ili prodata
  • Trenutna košnica se ne unosi u ovoj formi, već se postavlja kada se matica dodeli košnici
• Svaka matica pripada tačno jednom pčelaru
• Stranica detalja matice prikazuje trenutnu košnicu, starost iz godine izleganja, boju oznake, poreklo i poslednju ocenu

II.5 — Dodela matice košnici

Pčelar može dodeliti maticu košnici kroz tabelu queen_hive_assignments. Ovo je glavna M:N relacija u sistemu: jedna matica kroz vreme može biti u više košnica, a jedna košnica kroz vreme može imati više matica, ali samo jedna dodela sme biti aktivna u jednom trenutku.

• Kreiranje dodele: matica, košnica, datum dodele, datum završetka, status dodele i napomena
• Izabrana matica i izabrana košnica moraju pripadati istom korisniku; matica se ne može prebaciti u košnicu drugog pčelara
• Jedna košnica može imati samo jednu aktivnu maticu
• Jedna matica može imati samo jednu aktivnu dodelu u jednom trenutku
• Promena matice u košnici zatvara staru dodelu kroz datum završetka i kreira novi zapis u queen_hive_assignments
• Istorija dodela omogućava da se vidi gde se matica nalazila i kada je premeštena

II.6 — Kontrole kvaliteta matice

Kontrola kvaliteta je zapis koji pčelar pravi kada proverava kako matica radi. Ova funkcionalnost je srce aplikacije i čuva se u tabeli queen_quality_checks.

• Pčelar može kreirati kontrolu kvaliteta za izabranu dodelu matice košnici
• Izabrana dodela matice košnici pokazuje na zapis iz tabele queen_hive_assignments, koji već zna koja je matica u kojoj košnici
• Forma kontrole sadrži: dodelu matice košnici, datum kontrole, da li je matica viđena, da li su jaja viđena, ocenu kvaliteta legla, ocenu zaleganja, ocenu mirnoće, ocenu produktivnosti, ocenu zdravlja i napomenu
• Pčelar koji je uneo kontrolu se ne bira ručno, već se automatski uzima iz prijavljenog korisnika
• Svaka ocena kvaliteta u poljima ocena kvaliteta legla, ocena zaleganja, ocena mirnoće, ocena produktivnosti i ocena zdravlja je ceo broj od 1 do 5
• Aplikacija izračunava ukupnu ocenu kao prosek pet pojedinačnih ocena: kvaliteta legla, zaleganja, mirnoće, produktivnosti i zdravlja
• Kontrole se prikazuju hronološki, najnovije prve
• Stranica detalja matice prikazuje poslednji ukupni rezultat, prosečnu ocenu i trend kvaliteta
• Preporuka se računa automatski na osnovu prisutnosti matice i ukupne ocene
  • Dodati novu maticu ako matica nije prisutna u košnici
  • Zadržati ako je ukupna ocena 4.0 ili veća
  • Pratiti ako je ukupna ocena od 3.0 do 3.9
  • Zameniti ako je ukupna ocena od 2.0 do 2.9
  • Hitno zameniti ako je ukupna ocena manja od 2.0
• Izmena kontrole je dozvoljena samo korisniku koji je vlasnik izabrane dodele matice košnici

II.7 — Dashboard pčelara

Dashboard je prva stranica nakon prijave. Njegov cilj je da pčelar na jednom mestu vidi stanje svog pčelinjaka i brzo uoči košnice ili matice koje zahtevaju reakciju.

• Prikaz osnovnih brojeva: broj košnica, broj matica i broj košnica bez matica
• Poseban prikaz košnica bez aktivne matice, kako bi pčelar odmah znao gde treba dodati ili dodeliti novu maticu
• Upozorenje za matice starije od dve godine, jer starije matice češće zahtevaju praćenje ili zamenu
• Upozorenje za matice čija je prosečna ukupna ocena ispod 3
• Prikaz poslednjih pet kontrola kvaliteta, sortiranih od najnovije ka starijima
• Prikaz preporuka za rad sa maticama: zadržati, pratiti, zameniti, hitno zameniti ili dodati novu maticu
• Rang lista najboljih matica po prosečnoj oceni kvaliteta

II.8 — Administrativni panel

Administrator ima poseban panel dostupan samo korisnicima sa ulogom admin. Pokušaj pristupa običnog korisnika mora biti blokiran i na frontendu i na backendu.

• Pregled svih registrovanih korisnika
• Promena polja role: pčelar ili admin
• Deaktiviranje naloga kroz polje is_active
• Upravljanje osnovnim katalozima: hive_types za tipove košnica i queen_breeds za rase matica
• Pregled statistike sistema: broj korisnika, košnica, matica i kontrola kvaliteta
• Pregled evidencije aktivnosti sistema

II.9 — Pregled funkcionalnosti po ulogama

Relacije i atributi matice

III.1 - Klucni atributi matice

III.2 - Relacije sistema i vlasništvo

Matica ne može biti kod više korisnika. Vlasništvo se čuva direktno u tabeli queens, a backend pri svakoj dodeli proverava da queens.owner_id i hive.owner_id imaju istu vrednost.

III.3 - Boja oznake matice

Boja oznake se može čuvati kao obična ENUM vrednost, ali aplikacija može predložiti boju na osnovu godine izleganja:

• Godine koje se završavaju na 1 ili 6: bela
• Godine koje se završavaju na 2 ili 7: žuta
• Godine koje se završavaju na 3 ili 8: crvena
• Godine koje se završavaju na 4 ili 9: zelena
• Godine koje se završavaju na 5 ili 0: plava

III.4 - Profil kvaliteta matice

Profil matice je frontend logika koja pomaže pčelaru da brzo razume stanje matice. Ne mora biti posebna tabela u bazi.

Profil se izračunava iz sledećih podataka:

• Starost matice na osnovu godine izleganja
• Da li je matica viđena u poslednjoj kontroli
• Da li su u poslednjoj kontroli viđena jaja
• Prosečna ocena iz poslednjih nekoliko kontrola kvaliteta
• Status matice

Primer prikaza:

Aktivna matica - 1 godina - bela oznaka - poslednji put viđena pre 8 dana - leglo 4/5

REST API rute

Rute označene sa 🔐 user zahtevaju validan JWT token, a rute označene sa ⭐ admin zahtevaju i administratorsku ulogu.

Auth - /api/auth

POST /register - registracija novog korisnika

POST /login - prijava korisnika, vraća JWT token

POST /logout - 🔐 user odjava korisnika

GET /me - 🔐 user vraća podatke trenutno prijavljenog korisnika

Katalozi - /api/dictionaries

GET /hive-types - 🔐 user lista aktivnih tipova košnica za dropdown meni

GET /queen-breeds - 🔐 user lista aktivnih rasa matica za dropdown meni

Košnice - /api/hive

GET / - 🔐 user lista košnica sa filterima: apiary_name, location, hive_type_id

GET /:id - 🔐 user detalji košnice sa aktivnom maticom i poslednjim kontrolama kvaliteta

POST / - 🔐 user dodavanje nove košnice; owner_id se uzima iz tokena

PUT /:id - 🔐 user izmena košnice

DELETE /:id - 🔐 user arhiviranje košnice

Matice - /api/queens

GET / - 🔐 user lista matica sa filterima: status, breed_id, marking_color, birth_year, current_hive_id

GET /:id - 🔐 user detalji matice sa prosečnom ocenom i istorijom kontrola kvaliteta

POST / - 🔐 user dodavanje nove matice; owner_id se uzima iz tokena

PUT /:id - 🔐 user izmena matice

DELETE /:id - 🔐 user arhiviranje matice

Dodele matica košnicama - /api/queen-hive-assignments

GET / - 🔐 user istorija dodela sa filterima: queen_id, hive_id, assignment_status

GET /queen/:queenId - 🔐 user sve košnice u kojima je matica bila

GET /hive/:hiveId - 🔐 user istorija matica u jednoj košnici

POST / - 🔐 user dodela matice košnici istog korisnika

PUT /:id/end - 🔐 user zatvaranje aktivne dodele matice

Kontrole kvaliteta - /api/queen-quality-checks

GET / - 🔐 user lista kontrola sa filterima: assignment_id, checked_by, date_from, date_to, recommendation

GET /:id - 🔐 user detalji jedne kontrole kvaliteta

GET /assignment/:assignmentId - 🔐 user sve kontrole kvaliteta jedne dodele matice košnici

POST / - 🔐 user kreiranje nove kontrole za svoju aktivnu dodelu matice košnici

PUT /:id - 🔐 user izmena kontrole kvaliteta

DELETE /:id - 🔐 user brisanje pogrešno unete kontrole

Dashboard - /api/dashboard

GET /summary - 🔐 user zbirni prikaz: košnice, matice, prosečne ocene i upozorenja

GET /warnings - 🔐 user matice sa niskom ocenom, stare matice i matice bez skorašnje kontrole

GET /quality-ranking - 🔐 user rang lista matica po prosečnom kvalitetu

Admin korisnici - /api/admin/users

GET / - ⭐ admin lista svih korisnika

GET /:id - ⭐ admin detalji korisnika

PUT /:id/role - ⭐ admin promena uloge korisnika

PUT /:id/status - ⭐ admin aktiviranje ili deaktiviranje naloga

Admin katalozi - /api/admin/dictionaries

GET /hive-types - ⭐ admin lista tipova košnica

POST /hive-types - ⭐ admin dodavanje novog tipa košnice

PUT /hive-types/:id - ⭐ admin izmena tipa košnice

DELETE /hive-types/:id - ⭐ admin deaktiviranje tipa košnice koji se više ne koristi

GET /queen-breeds - ⭐ admin lista rasa matica

POST /queen-breeds - ⭐ admin dodavanje rase matice

PUT /queen-breeds/:id - ⭐ admin izmena rase matice

DELETE /queen-breeds/:id - ⭐ admin deaktiviranje rase matice koja se više ne koristi

Stranice u okviru klijentske aplikacije

Javno dostupno:

• Početna stranica
• Vodič za obeležavanje matica
• Prijava
• Registracija

Prijavljeni pčelar:

• Dashboard
• Moje košnice
• Detalji košnice
• Moje matice
• Detalji matice
• Nova matica
• Nova košnica
• Dodele matica košnicama
• Nova kontrola kvaliteta
• Kontrole kvaliteta
• Rang lista matica
• Profil korisnika

Administrator:

• Admin Dashboard
• Upravljanje korisnicima
• Upravljanje katalozima
• Statistika sistema
• Evidencija aktivnosti

Pravila validacije

Celokupna validacija mora biti implementirana troslojno: klijentska validacija u React aplikaciji, serverska validacija u Express middleware sloju i ograničenja u bazi podataka.

Primer korisničkog toka

Pčelar se registruje i prijavljuje u aplikaciju. Nakon toga dodaje košnicu A-01, upisuje naziv pčelinjaka "Bagremova pasa 2026" i lokaciju. Zatim unosi maticu Q-2026-001, aplikacija joj automatski predlaže belu oznaku, upisuje pčelara kao vlasnika kroz queens.owner_id, a zatim maticu dodeljuje svojoj košnici A-01 kreiranjem zapisa u tabeli queen_hive_assignments.

Nakon sedam dana pčelar otvara novu kontrolu kvaliteta za aktivnu dodelu matice Q-2026-001 košnici A-01. Sistem u kontroli čuva assignment_id, pčelar označava da je matica viđena, da su jaja prisutna i unosi ocene: leglo 4/5, zaleganje 5/5, mirnoća 4/5, produktivnost 4/5 i zdravlje 5/5. Sistem izračunava ukupnu ocenu i čuva zapis u tabeli queen_quality_checks.

Ako kasnije prosečna ocena padne ispod 3, preporuka postane "zameniti" ili matica nije prisutna, dashboard prikazuje upozorenje da je potrebna reakcija pčelara.

Kada pčelar ukloni maticu iz upotrebe, njen status menja u "uginula" ili "prodata", a novoj aktivnoj matici dodeljuje istu košnicu kroz novi zapis u tabeli queen_hive_assignments.