Funkcionalni zahtev - Balans5 CBA sistem

10 min

Ovaj dokument definiše funkcionalne zahteve za Balans 5 CBA (Cluster Based Authentication) sistem - centralizovani sistem za autentifikaciju i autorizaciju za multi-tenant sistem.

1. Uvod

1.1 Svrha dokumenta

Ovaj dokument definiše funkcionalne zahteve za Balans 5 CBA (Cluster Based Authentication) sistem - centralizovani sistem za autentifikaciju i autorizaciju za multi-tenant sistem.

1.2 Opseg

CBA (Cluster Based Authentication) je centralizovani sistem za autentifikaciju i autorizaciju za multi-tenant ERP sistem Balans5. Sistem omogućava korisnicima da pristupe više firmi sa jednim setom kredencijala, umesto da imaju odvojen nalog u svakoj firmi.Sistem omogućava korisnicima sa više firmi da im pristupaju sa jedinstvenim nalogom, umesto da imaju odvojene naloge za svaku zasebnu firmu

1.3 Definicije

• Cluster - Ovde se podrazumeva jedna aktivna instanca PostgreSQL servera koja može sadržati više raznih Balans baza podataka i obavezno sadrži bazu blfpub. U širem smislu u Cluster spadaju i servisi za autentifikaciju i autorizaciju.
• CSA - Cluster Super Admin (Super Administrator Cluster-a)
• CGA - Cluster Group Admin (Administrator Grupe)
• USER - Redovan korisnik sistema
• Firma - Pojedinačna kompanija/tenant u sistemu
• Firma - Pojedinačna kompanija (baza podataka) u sistemu
• Grupa - Kolekcija firmi koje pripadaju istom klasteru
• Grupa - Grupa Firmi koje pripadaju istom Cluster-u
• Tenant - Baza podataka unutar Cluster-a sa podacima jedne Firme. Izolovana od baza drugih Firmi.
• Prefix - Prefiks za korisničko ime koji se automatski dodaje na osnovu grupe (npr. bjn.petar_petrovic)
• Prefiks - Prefiks za korisničko ime koji se automatski dodaje na osnovu Grupe (npr. bjn.petar_petrovic)
• Cluster Token - access JWT token RFC 7519 koji se generiše nakon login-a (24h važnosti); služi za izbor Firme sa kojom će Korisnik raditi
• Firm Token - access JWT token koji se generiše nakon izbora Firme (8h važnosti); služi za rad sa izabranom Firmom
• Refresh Token - Token za obnavljanje oba access tokena (7 dana važnosti)

1.4 Glavne karakteristike

• Jedinstveni nalog za više Firmi
• Grupa-baziran pristup Pristup baziran na Grupama (Korisnici → Grupe → Firme)
• Centralizovano upravljanje Korisnicima
• JWT token-based autentifikacija Autentifikacija bazirana na JWT tokenima
• Multi-tenant izolacija podatakaIzolacija podataka na nivou Tenanta

2. Pregled sistema

2.1 Arhitektura sistema

Sistem se sastoji od tri glavna sloja:

• Autentifikacioni sloj - JWT token-based autentifikacija sa refresh token mehanizmom.
• Autorizacioni sloj - Role-based access control (RBAC) sa grupama.
• Tenant sloj - Izolacija podataka po firmama.

• Autentifikacioni sloj - Autentifikacija, bazirana na JWT tokenima sa refresh token mehanizmom.
• Autorizacioni sloj - Autorizacija autentifikovanih Korisnika u skladu sa ulogama koje su im dodeljene unutar njihove Grupe (RBAC).
• Tenant sloj - Pristup podacima, izolovanim po Firmama.

2.2 Akteri sistema

Akter	Uloga	Odgovornosti
Super Admin	CSA	Kreiranje grupa, dodela firmi, upravljanje svim korisnicima.
Group Admin	CGA	Upravljanje korisnicima unutar dodeljenih grupa.
End User	USER	Pristup dodeljenim firmama, izvršavanje poslovnih operacija.

Akter	Uloga	Odgovornosti
Super Admin	CSA	Kreiranje Grupa, dodela Firmi Grupama, upravljanje svim Korisnicima.
Group Admin	CGA	Upravljanje Korisnicima unutar dodeljenih Grupa.
End User	Korisnik	Pristup dodeljenim Firmama, izvršavanje poslovnih operacija.

2.3 Token sistem

Sistem koristi tri tipa tokena:

• Cluster Token (24 sata) - generiše se nakon uspešnog login-a i sadrži listu dostupnih Firmi.
• Firm Token (8 sati) - generiše se nakon izbora Firme i sadrži informacije o Firmi i profilu Korisnika.
• Refresh Token (7 dana) - koristi se za obnavljanje oba access tokena bez ponovnog login-a.

3. Uloge korisnika i dozvole

3.1 Matrica dozvola

Funkcija	CSA	CGA	USER
Kreiranje Grupa	✓	-	-
Dodela Firme Grupi	✓	-	-
Kreiranje Korisnika	✓	✓*	-
Pristup podacima Firme	✓	✓	✓
Upravljanje Grupama	✓	-	-
Masovno kreiranje Korisnika	✓	✓	-
CSV import Korisnika	✓	✓	-
Mapiranje Korisnika na Tenant	✓	✓	-
Pristup arhivi arhiviranim podacima Firme?	-	-	✓**

* CGA može kreirati Korisničke naloge samo unutar svojih Grupa.
** Korisnik može pristupiti arhivi samo svojih Firmi.

3.2 Ograničenja po ulogama

• CSA: Ima pristup svim Grupama, Firmama i Korisnicima.
• CGA: Može upravljati samo Korisnicima u svojim dodeljenim Grupama.
• Korisnik: Može pristupiti samo Firmama koje su dodeljene njegovim Grupama.

4. Funkcionalni zahtevi

4.1 Modul autentifikacije

Nedostaje treći slučaj

Imamo 4.1.1 Login Korisnika, imamo 4.1.2 Izbor Firme. Nedostaje scenario za Korisnika koji radi samo sa jednom Firmom (nema šta da bira). On ne vidi stranu /api/auth/select-firm ali dobija Firm Token.
Ko mu vraća Firm Token - /api/auth/login ili /api/auth/select-firm?

4.1.1 Login Korisnika

• REQ-1: Sistem MORA obezbediti login ekran sa poljima za korisničko ime i lozinku.
• REQ-2: Sistem MORA validirati kredencijale koristeći centralnu CBA bazu podataka.centralna CBA baza podataka = blfpub?
• REQ-3: Sistem MORA zaključati nalog nakon 5 neuspešnih pokušaja login-a u kom vremenskom periodu su tih 5 neuspešnih? Ili nema vremenske odrednice već pratimo 5 uzastopnih?.
• REQ-4: Sistem MORA generisati cluster_token Cluster Token (24h) ili firm_token Firm Token (8h) nakon uspešnog login-a.
• REQ-5: Sistem MORA logovati sve uspešne pokušaje login-a (vreme, IP, rezultat).
• REQ-6: Sistem MORA automatski selektovati Firmu ako Korisnik ima pristup samo jednoj Firmi.

Ulaz:

• Korisničko ime (string, obavezno, min 3 karaktera).
• Lozinka (string, obavezno, min 8 karaktera).

Izlaz:

• Uspeh: JWT token + Korisnički profil + dostupne Firme (ili automatski izabrana Firma).
• Neuspeh: Error kod + poruka.

Poslovna pravila:

• BR-001: Lozinka mora sadržati velika slova, mala slova, broj (specijalni karakteri opciono) Šta znači opciono? Ako klijent traži ili nešto drugo?.
• BR-002: Neaktivni nalozi ne mogu da se uloguju.
• BR-003: Zaključani nalozi ne mogu da se uloguju dok se ne otključaju.

Neko pojašnjenje za aktivne/neaktivne, otključane/zaključane naloge... ili nema potrebe?

4.1.2 Izbor firme

• REQ-7: Sistem MORA prikazati listu dostupnih Firmi nakon login-a (ako Korisnik ima pristup u više Firmi).
• REQ-8: Sistem MORA automatski selektovati Firmu ako Korisnik ima pristup samo jednoj.
• REQ-9: Sistem MORA generisati firm_token Firm Token (8h validan) nakon izbora Firme.
• REQ-10: Sistem MORA učitati firm-specifični profil i dozvole nakon izbora firme nakon izbora Firme učitati Korisnički profil i prava za izabranu Firmu.

prava ili dozvole za permissions?

4.1.3 Obnavljanje tokena (Refresh Token)

• REQ-11: Sistem MORA obezbediti endpoint za obnavljanje access tokena.
• REQ-12: Sistem MORA rotirati generisati novi Refresh Token pri svakom refresh-u obnavljanju access tokena.
• REQ-13: Refresh Token MORA biti važeći 7 dana.
• REQ-14: Sistem MORA validirati Refresh Token pre obnavljanja access tokena.

4.1.4 Logout

• REQ-15: Sistem MORA obezbediti logout funkcionalnost koja revokuje sesiju. opoziva sesiju? anulira sesiju?
• REQ-16: Sistem MORA invalidirati da poništi Refresh Token nakon logout-a.

4.2 Modul upravljanja Korisnicima

4.2.1 Kreiranje Korisnika

• REQ-17: Sistem MORA obezbediti formu sa obaveznim poljima: korisničko ime, email, lozinka, uloga (CSA, CGA, Korisnik).
• REQ-18: Sistem MORA validirati format email-a i jedinstvenost.
• REQ-19: Sistem MORA automatski dodati Prefiks Korisničkom imenu na osnovu Grupe.šta ako nije u grupi, ako radi samo sa jednom firmom? A inače u 8.2 piše da username_prefix nije obavezno polje
• REQ-20: Sistem MORA omogućiti CGA-u eksplicitni izbor Grupe za Prefiks ako se Korisnik nalazi u više Grupa.
• REQ-21: Sistem MORA automatski koristiti Prefiks iz prve Grupe ako nije eksplicitno izabran.

Ulaz:

• Korisničko ime (bez prefiksa).
• Email.
• Lozinka (ili generisana privremena).
• Uloga (CSA, CGA, Korisnik).
• Lista Grupa (groupIds).
• Grupa za Prefiks (prefixGroupId) - opciono.

groupIds i prefixGroupId su neke kolone iz neke tabele iz neke baze ili promenljive iz neke forme?

Izlaz:

• Kreiran Korisnik sa Prefiksom u korisničkom imenu.
• Dodeljene Grupe. kome, kuda?
• Status kreiranja. a statusi su?

4.2.2 Masovno kreiranje Korisnika

• REQ-24: Sistem MORA prihvatiti CSV fajl sa podacima Korisnika.
• REQ-25: Sistem MORA validirati sve zapise pre obrade.
• REQ-26: Sistem MORA kreirati maksimalno 100 Korisnika po batch-u. (transakcija application.properties cba.bulk.timeout-seconds=300 / cba.bulk.batch-size=100 ) šta je ovo u zagradi i čemu služi?
• REQ-27: Sistem MORA generisati izveštaj sa uspehom/neuspehom za svaki zapis za svakog Korisnika iz CSV fajla.
• REQ-28: Sistem MORA rollback-ovati ceo batch u slučaju kritične greške (all-or-nothing sve ili ništa).
  • Ako bilo koji korisnik ne prođe validaciju ili procesiranje, cela transakcija se rollback-uje
  • Sve greške se prikazuju sa pozicijama Korisnika
  • Format greške: "Greška na poziciji #X br. x (Korisnik 'username'): detaljna poruka"
• REQ-29: Sistem MORA omogućiti eksplicitni izbor Grupe za Prefiks u bulk masovnim operacijama.
• REQ-30: Sistem MORA podržati različite profile po Firmama za istog Korisnika (profilePerFirm - kolona u CSV-u).

srpska reč za rollback?

CSV Format:

• Email (obavezno).
• Username (obavezno, bez prefiksa).
• GroupId (obavezno).
• ProfilePerFirm (JSON mapa: {"firmId": profileId}).

4.2.3 Upravljanje Korisnicima

• REQ-31: Sistem MORA omogućiti pregled svih Korisnika (CSA vidi sve, CGA vidi samo svoje Grupe).
• REQ-32: Sistem MORA omogućiti ažuriranje korisničkih podataka.
• REQ-33: Sistem MORA omogućiti otključavanje zaključanih naloga.
• REQ-34: Sistem MORA omogućiti reset lozinke.
• REQ-35: Sistem MORA omogućiti deaktivaciju Korisnika.

4.3 Modul upravljanja Grupama

4.3.1 Kreiranje Grupe

• REQ-36: Sistem MORA omogućiti kreiranje Grupe sa nazivom i Prefiksom za korisničko ime.
• REQ-37: Sistem proverava jedinstvenost Prefiksa. Ako Prefiks već postoji, sistem vraća grešku i sprečava kreiranje Grupe. Na nivou Cluster-a postoji UNIQUE constraint koji garantuje jedinstvenost.
• REQ-38: Sistem automatski kreira posebnu Grupu sa nazivom "ALL" koja sadrži sve Korisnike iz Firmi koje su joj dodeljene. Ova Grupa se kreira pri inicijalizaciji sistema ili kada se prva Firma dodeli ovoj Grupi. "ALL" grupa nema Prefiks jer se koristi samo za organizaciju Korisnika.
• REQ-39: Sistem sinhronizuje "ALL" Grupu hibridnim pristupom:
  • Instant Sync: Automatski se pokreće kada se Firma dodeli "ALL" Grupi ili kada se Korisnici kreiraju/ažuriraju
  • Scheduled Job: Izvršava se automatski svakih 6 sati kao backup/cleanup mehanizam

Šta se sa čim sinhronizuje? Korisnici iz Firmine baze/Tenanta sa blfpub tabelom ALL kada se ta firma doda nekoj Grupi?

Ulaz:

• Naziv Grupe.
• Prefiks za korisničko ime (2-20 karaktera, lowercase alphanumeric alfnumerički sa malim slovima).
• Opis (opciono).

Izlaz:

• Kreirana Grupa sa ID-jem.

4.3.2 Dodela firmi Grupi

• REQ-40: Sistem MORA omogućiti dodelu Firme Grupi.
• REQ-41: Sistem MORA omogućiti uklanjanje Firme iz Grupe.
• REQ-42: Sistem MORA omogućiti bulk masovnu dodelu Firmi Grupi.
• REQ-43: Sistem MORA logovati ko je dodelio Firmu Grupi i kada.

bulk dodela - masovna dodela ili grupna dodela?

4.3.3 Dodela Korisnika Grupi

• REQ-44: Sistem MORA omogućiti dodelu Korisnika Grupi (M:N veza).
• REQ-45: Sistem MORA omogućiti uklanjanje Korisnika iz Grupe.
• REQ-46: Sistem MORA omogućiti bulk masovnu dodelu Korisnika Grupama.
• REQ-47: Sistem MORA logovati ko je dodelio Korisnika Grupi i kada.

4.4 Modul mapiranja Korisnika

4.4.1 Mapiranje na Tenant

• REQ-48: Sistem MORA omogućiti mapiranje CBA Korisnika na Tenant korisnika (korid, profile_id - kolone iz koje tabele / kojih tabela?).
• REQ-49: Sistem MORA omogućiti bulk masovno mapiranje Korisnika.
• REQ-50: Sistem MORA omogućiti automatsko mapiranje na osnovu email-a ili korisničkog imena.
• REQ-51: Sistem MORA prikazati nemapirane Korisnike.
• REQ-52: Sistem MORA omogućiti različite profile po Firmama za istog Korisnika.

5. Korisničke priče

5.1 Autentifikacione priče

US-001: Osnovni Login

Kao Korisnik, želim da se ulogujem sa jednim setom kredencijala nalogom, tako da mogu pristupiti svim dodeljenim Firmama bez više lozinki.

Kriterijumi prihvatanja:

• Login stranica prikazuje polja za korisničko ime i lozinku.
• Uspešan login preusmerava na izbor Firme (više Firmi) ili direktno u Firmu (jedna Firma).
• Neuspešan login prikazuje specifičnu poruku o grešci.
• Nalog se zaključava nakon 5 neuspešnih pokušaja.Uzastopnih ili tokom nekog vremenskog perioda?

US-002: Automatski izbor Firme

Kao Korisnik sa pristupom samo jednoj Firmi, želim da budem automatski ulogovan u tu Firmu, tako da ne moram da prolazim kroz dodatni korak izbora.

US-003: Obnavljanje sesije

Kao Korisnik, želim da moja sesija bude automatski obnovljena bez ponovnog login-a, tako da ne gubim radni tok.

Kao Korisnik, ja nemam pojma ni šta je sesija ni šta su kredencijali.

Kao Korisnik, želim da tokom rada menjam Firme sa kojima radim bez unošenja korisničkog imena i lozinke prilikom svake promene.

5.2 Admin priče

US-004: Masovno kreiranje Korisnika

Kao CGA, želim da kreiram više Korisnika odjednom, tako da mogu efikasno da onboardujem brzo da dodajem nove timove.

US-005: Izbor Prefiksa za korisničko ime

Kao CGA sa više Grupa, želim da eksplicitno izaberem iz koje Grupe želim Prefiks za korisničko ime, da imam kontrolu nad generisanim korisničkim imenima. Koja je razlika između "eksplicitno izaberem" i samo "izaberem"?

US-006: Različiti profili po Firmama

Kao CGA, želim da dodelim različite profile Korisniku u različitim Firmama, tako da Korisnik ima različite dozvole u različitim Firmama.

6. Scenariji korišćenja

UC-001: Tok login-a prijavljivanja?

Primarni akter: End User krajnji Korisnik.

Preduslovi: Korisnik ima aktivan nalog.

Postuslovi: Korisnik je autentifikovan i ima važeći access token.

Glavni tok:

1. Korisnik otvara login stranicu i unosi korisničko ime i lozinku.
2. Sistem validira kredencijale i status naloga.
3. Sistem generiše odgovarajući token (cluster_token ili firm_token Cluster Token ili Firm Token).
4. Sistem vraća token i listu Firmi (ili automatski izabranu Firmu).

UC-002: Kreiranje Korisnika sa Prefiks Grupom

Primarni akter: CGA.

CGA unosi podatke, bira jednu ili više Grupa i opciono bira Grupu za Prefiks; sistem dodaje Prefiks, kreira Korisnika i dodeljuje ga Grupama.

UC-003: CSV import Korisnika

CGA upload-uje CSV fajl, sistem validira zapise, kreira Korisnike u transakciji i generiše izveštaj. U slučaju greške radi se rollback povratak u početno stanje?

7. Poslovna pravila

7.1 Autentifikaciona pravila

ID	Naziv	Opis
BR-001	Kompleksnost lozinke	Min 8 karaktera, 1 veliko slovo, 1 malo slovo, 1 broj (specijalni karakteri opciono).
BR-002	Zaključavanje naloga	Zaključavanje nakon 5 neuspešnih pokušaja.
BR-003	Važnost tokena	Cluster Token 24h, Firm Token 8h, Refresh Token 7 dana.
BR-004	Format korisničkog imena	{prefix}.{username} (npr. bjn.petar_petrovic).
BR-005	Prefix logika	Ako je prosleđen prefixGroupId koristi se taj Prefiks, inače Prefiks prve Grupe u listi.

7.2 Pravila za Grupe

ID	Naziv	Opis
BR-006	Jedinstvenost Prefiksa	Svaka Grupa mora imati jedinstveni Prefiks.
BR-007	ALL Grupa	Sistem automatski kreira ALL Grupu koja sadrži sve Korisnike.
BR-008	Sinhronizacija ALL Grupe	ALL Grupa se automatski sinhronizuje hibridnim pristupom: instant sync pri dodeli Firme/kreiranju Korisnika + scheduled job svakih 6 sati.

7.3 Pravila za korisnike

ID	Naziv	Opis
BR-009	Ograničenje CGA	CGA može kreirati samo Korisničke naloge unutar svojih Grupa.
BR-010	Bulk operacije	Maksimalno 100 Korisnika po batch-u.
BR-011	Transakcijski pristup	CSV import je all-or-nothing (sve ili ništa).
BR-012	Različiti profili	Korisnik može imati različite profile u različitim Firmama.

8. Zahtevi za podatke

8.1 Podaci o Korisniku

Polje	Tip	Obavezno	Validacija
acc_id	UUID	Da	Auto-generisan, jedinstven.
username	VARCHAR(50)	Da	Jedinstven, format: prefix.name.
email	VARCHAR(100)	Da	Validan email format.
password_hash	VARCHAR(255)	Da	Bcrypt hash.
role_type	ENUM	Da	CSA (2), CGA (1), USER (0).
status	INTEGER	Da	0=active, 1=inactive, 2=locked, 3=suspended.
failed_attempts	SMALLINT	Ne	Brojač neuspešnih pokušaja.
created_at	TIMESTAMP	Da	Vremenska oznaka kreiranja.
created_by	UUID	Ne	ID korisnika koji je kreirao.

Ima li smisla (potrebe) dodati TIMESTAMP status_from - informacija od kada je Korisnik u sadašnjem statusu?
Da li se failed_attempts resetuje prilikom uspešnog prijavljivanja/logovanja?

8.2 Podaci o grupi

Polje	Tip	Obavezno	Validacija
group_id	BIGINT	Da	Auto-generisan, jedinstven.
name	VARCHAR(100)	Da	Jedinstven naziv.
username_prefix	VARCHAR(20)	Ne	2-20 lowercase alphanumeric.
active	BOOLEAN	Da	Status aktivnosti.
description	TEXT	Ne	Opis grupe.

username_prefix nije obavezno polje, ali ranije je pomenuto da se u nekim slučajevima Korisniku automatski dodaje Prefiks Grupe. Kako ako nije obavezno polje?

8.3 Junction tabele

cba_user_groups (Korisnik ↔ Grupa):

• acc_id (UUID) - Referenca na Korisnika.
• group_id (BIGINT) - Referenca na Grupu.
• assigned_at (TIMESTAMP) - Vreme dodele.
• assigned_by (UUID) - Ko je dodelio.

cba_group_firms (Grupa ↔ Firma):

• group_id (BIGINT) - Referenca na Grupu.
• firid (BIGINT) - Referenca na Firmu.
• assigned_at (TIMESTAMP) - Vreme dodele.
• assigned_by (UUID) - Ko je dodelio.