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 Korisnika.
• Refresh Token (7 dana) - koristi se za obnavljanje access tokena bez ponovnog login-a.

Pitanje: i Cluster Token i Firm Token su access tokeni. Nama Refresh Token radi update oba?

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 kojoj arhivi?	-	-	✓**

* 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

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.
• 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.

REQ-12: ako sistem rotira/menja Refresh Token pri svakom osvežavanju access tokena da li to znači da Refresh Token tom prilikom dobija novih 7 dana validnosti? Username i password će koristiti samo oni koji više od 7 dana nisu ulazili u Balans?

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.
• 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?
• REQ-20: Sistem MORA omogućiti CGA-u eksplicitni izbor Grupe za Prefiks ako se Korisnik nalazi u više Grupa. Ako je Korisnik u više Grupa, onda ga administriraju razni CGA?
• 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</spam> (groupIds).
• Grupa za Prefiks (prefixGroupId) - opciono.

groupIds i groupIds 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 i čemu služi? transakcija
• REQ-27: Sistem MORA generisati izveštaj sa uspehom/neuspehom za svaki zapis za svakog Korisnika.
• 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 Prefiks u bulk 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 firminog Balansa 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.

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).
• 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, 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 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?