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.

PRIVREMENO UKUNUT SADRŽAJ. Smeta prilikom editovanja.

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 - Jedna aktivna instanca PostgreSQL servera koja može sadržati više raznih 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
• Korisnik - 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 - JWT token RFC 7519 koji se generiše nakon login-a (24h važnosti)
• Firm Token - JWT token koji se generiše nakon izbora Firme (8h važnosti)
• Refresh Token - Token za obnavljanje access tokena (7 dana važnosti)

login ~ logovanje ~ prijavljivanje ?

1.4 Glavne karakteristike

• Jedinstveni nalog za više Firmi
• Grupa-baziran pristup Pristup baziran na Grupama (Korisnici → Grupe → Firme) Šta sa firmama koje nisu ni u jednog grupi? (Korisnici → 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 grupama, 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.
• Refresh Token (7 dana) - koristi se za obnavljanje access tokena bez ponovnog login-a.

3. Uloge korisnika i dozvole

3.1 Matrica dozvola

U '1.3 Definicije' smo naveli USER, Firma, Grupa... te bi trebali toga da se držimo u daljem tekstu.

Funkcija	CSA	CGA	USER
Kreiranje grupe Kreiranje Grupa	✓	-	-
Dodela firme grupi Firme Grupi	✓	-	-
Kreiranje korisnika USER-a	✓	✓*	-
Pristup firmi podacima Firme	✓	✓	✓
Upravljanje grupama Grupama	✓	-	-
Masovno kreiranje korisnika USER-a	✓	✓	-
CSV import korisnika User-a	✓	✓	-
Mapiranje korisnika USER-a na tenant svoju Firmu?	✓	✓	-
Pristup arhivi kojoj arhivi?	-	-	✓**

* CGA može kreirati samo USER naloge unutar svojih Grupa.

** USER može pristupiti arhivi samo svojih Firmi.

3.2 Ograničenja po ulogama

• CSA: Ima pristup svim grupama, firmama i korisnicima. Grupama, Firmama i USER-ima.
• CGA: Može upravljati samo korisnicima USER-ima u svojim dodeljenim grupama Grupama.
• USER: Može pristupiti samo firmama Firmama koje su dodeljene njegovim grupama Grupama.

4. Funkcionalni zahtevi

4.1 Modul autentifikacije

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 šta je CBA? bazu podataka.
• 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? Meni nejasno.
• REQ-4: Sistem MORA generisati cluster_token (24h) ili firm_token (8h) nakon uspešnog login-a. meni za sada nejasno 'ili'
• REQ-5: Sistem MORA logovati sve uspešne pokušaje login-a (vreme, IP, rezultat). a neuspešne? Šta je 'rezultat' ako loguje samo uspešne?
• REQ-6: Sistem MORA automatski selektovati firmu ako korisnik ima pristup samo jednoj firmi. A ako ima pristup raznim firmama da li postoji mogućnost da izabere jednu za default login, ili da mu se daje poslednja u kojoj je bio? Razmišljam naglas.

Ulaz:

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

Izlaz:

• Uspeh: JWT token + korisnički profil šta je u profilu? dark tema? izabrani jezik? vidim da su dostupne firme van profila. + 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?

4.1.2 Izbor firme

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

4.1.3 Obnavljanje tokena (Refresh Token)

• REQ-11: Sistem MORA obezbediti endpoint za obnavljanje access tokena.
• REQ-12: Sistem MORA rotirati refresh token pri svakom refresh-u. Rotirati?
• 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

U 1.3 nemamo 'korisnik' već 'USER'

4.2.1 Kreiranje korisnika

• REQ-17: Sistem MORA obezbediti formu sa obaveznim poljima: korisničko ime, email, lozinka, uloga. da li jedan USER može da ima više uloga?
• REQ-18: Sistem MORA validirati format email-a i jedinstvenost. sumnja
• REQ-19: Sistem MORA automatski dodati prefix korisničkom imenu na osnovu grupe.
• REQ-20: Sistem MORA omogućiti CGA-u eksplicitni izbor grupe za prefix ako korisnik pripada više grupa. Grupe za Prefix ako USER učestvuje u više Grupa. Potpuno nejasno. Ako je USER u više Grupa, onda ga administriraju razni CGA?
• REQ-21: Sistem MORA automatski koristiti prefix iz prve grupe ako nije eksplicitno izabran.

Ulaz:

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

Izlaz:

• Kreiran korisnik sa prefiksom u korisničkom imenu.
• Dodeljene Grupe.
• Status kreiranja. a statusi su?

4.2.2 Masovno kreiranje korisnika

• REQ-24: Sistem MORA prihvatiti CSV fajl sa podacima korisnika. Pitanje: da li se kao separator prihvata samo zarez? Ako USER ima pravo pristupa raznim Firmama kako se razdvajaju Firme u njihovom polju u formi?
• REQ-25: Sistem MORA validirati sve zapise pre obrade. Šta konkretno podleže validaciji? Prezimena?
• REQ-26: Sistem MORA kreirati maksimalno 100 korisnika po batch-u. (transakcija application.properties cba.bulk.timeout-seconds=300 / cba.bulk.batch-size=100 )
• REQ-27: Sistem MORA generisati izveštaj sa uspehom/neuspehom za svaki zapis.
• 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 (korisnik 'username'): detaljna poruka"
• REQ-29: Sistem MORA omogućiti eksplicitni izbor grupe za prefix u bulk operacijama. Šta ovo znači? Da u CSV imamo kolonu default Grupa. Zbunjuje me, treba razgovarati.
• REQ-30: Sistem MORA podržati različite profile po firmama za istog korisnika (profilePerFirm).

CSV Format:

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

Nejasno.

4.2.3 Upravljanje korisnicima

• REQ-31: Sistem MORA omogućiti pregled svih korisnika (CSA vidi sve, CGA vidi samo svoje grupe). Grupe ili Grupu? Zar CGA nije nadležan samo za jednu Grupu?
• 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 prefixom za korisničko ime.Valjda je normalno da Grupa ima ime? I USER ima username.
• REQ-37: Sistem proverava jedinstvenost prefiksa. Ako prefix već postoji, sistem vraća grešku i sprečava kreiranje grupe. Na nivou clustera 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 prefix jer se koristi samo za organizaciju korisnika. Ovo je jedinstvena tabela u kojoj su svi korisnici sistema, i u njoj je UNIQUE constraint? Nemamo tabele sa korisnicima po Grupama, Firmama?
• 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 izvršava? Update?

Ulaz:

• Naziv grupe.
• Prefix za korisničko ime (2-20 karaktera, lowercase alphanumeric).
• 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 dodelu firmi grupi.
• REQ-43: Sistem MORA logovati ko je dodelio firmu grupi i kada.

4.3.3 Dodela korisnika grupi

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

4.4 Modul mapiranja korisnika

4.4.1 Mapiranje na tenant na Firmu?

Povezujemo kreirane USER-e sa postojećim u bazi Firmama? U uslovnoj tabeli 'users' pišemo kojim firmama može da pristupa i sa kojim pravima, ili u nekoj tabeli Firme pišemo ko sme da pristupi Firmi i sa kojim pravima?

• REQ-48: Sistem MORA omogućiti mapiranje CBA korisnika na tenant korisnika (korid, profile_id). Šta je CBA? Šta je tenant USER-a? Što navodimo nazive kolona bez naziva tabele?
• REQ-49: Sistem MORA omogućiti bulk 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 USER, želim da se ulogujem sa jednim setom kredencijala, 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 dana?

US-002: Automatski izbor firme

Kao USER 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 USER, želim da moja sesija bude automatski obnovljena bez ponovnog login-a logovanja, tako da ne gubim radni tok.

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 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 prefix za korisničko ime, da imam kontrolu nad generisanim korisničkim imenima u svim Grupama koje su mi dodeljene?.

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? logovanja?

Primarni akter: End User.

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).
4. Sistem vraća token i listu firmi (ili automatski izabranu firmu).

UC-002: Kreiranje korisnika sa prefix grupom

Primarni akter: CGA.

CGA unosi podatke, bira jednu ili više grupa i opciono bira grupu za prefix; sistem dodaje prefix, 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 prefix, inače prefix prve grupe u listi. Da li je moguć update liste? Šta ako se obriše prva grupa u listi? Ako se obriše Grupa da li ostaju živi prefiksi?

7.2 Pravila za grupe

ID	Naziv	Opis
BR-006	Jedinstvenost prefiksa	Svaka grupa mora imati jedinstven prefix.
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.

Da li ovo znači da će USER nakon što mu se naknadno promene prava morati da čeka max 6 sati da nova prava 'prorade'? Mislim na update korisnika.

7.3 Pravila za korisnike

ID	Naziv	Opis
BR-009	Ograničenje CGA	CGA može kreirati samo USER 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.

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.

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.

Bode oči. acc_id, group_id... ALI firid. Ne može firm_id?