acn-documentatie-roris/DOCUMENTATIE_DATE_FACTURARE_RORIS.md

Date necesare pentru facturare — modernizare RORIS (specificație minimă)

Beneficiar: ACN — facturare tranzit/ecluzare barje și nave, cheiaj Sistem sursă (actual): RORIS — bază de date SQL Server Sistem care consumă datele: ROA (aplicația de facturare) — bază de date Oracle Scop: stabilirea datelor minime pe care noul RORIS trebuie să le pună la dispoziția facturării. Autor: ROMFAST SRL — dezvoltatorul ERP-ului ROA și al programului de facturare. Data: 24.06.2026

---

1. Principiu de integrare (mod actual, de păstrat)

Facturarea ROA (Oracle) preia astăzi datele din RORIS (SQL Server) prin vederi/tabele expuse de RORIS, citite de Oracle printr-un database link (gateway heterogen Oracle → SQL Server, RORISSQL). Importul este o simplă copiere (merge) din aceste surse în tabelele Oracle ale ROA, fără API sau servicii web. Vederile/tabelele relevante poartă prefixul ips_* (date) și ips_v* (vederi de calcul).

Cerința de bază a modernizării: noul RORIS trebuie să expună în continuare, pe partea sa de SQL Server, aceleași vederi/tabele, cu aceleași denumiri de coloane și aceeași semnificație, accesibile prin database link din Oracle, astfel încât importul actual să funcționeze neschimbat sau cu adaptări minime.

De prevăzut în buget: dacă noul RORIS este construit pe altă platformă sau cu altă structură de date (alte tabele/coloane, alt model), modernizarea trebuie să includă un strat de compatibilitate pe partea RORIS (vederi SQL Server / tabele intermediare / replicare) care să reproducă structura de mai jos și să rămână accesibil prin database link Oracle. Nu se dorește rescrierea importului pe API/REST — aceasta ar însemna refacerea integrală a mecanismului de facturare și costuri suplimentare nejustificate.

---

2. Entitățile necesare facturării (12)

#	Sursă RORIS	Conținut	Folosită la
1	IPS_CONTACTS	Firme (transportatori, plătitori)	Client/plătitor pe factură
2	IPS_COUNTRIES	Țări	Atribut navă/voiaj/marfă
3	IPS_RISGOODS	Mărfuri (NSTR, IMO, periculos)	Încadrare tarifară pe marfă
4	IPS_VESSELS	Nave/barje (tonaj, putere, LBD, tip)	Cantitate facturată tranzit/cheiaj
5	IPS_RIS_VES_TYPES	Tipuri de navă	Încadrare tarifară pe tip/grupă
6	IPS_ROUTE_POINTS	Puncte de rută (km/porturi/dane)	Rută, distanță, dană
7	IPS_VOYAGES	Voiaje/convoaie (avizare, declarație)	Antet tranzit; perioadă facturare
8	IPS_VOYAGE_MEMBERS	Membri convoi (navă + traseu + distanță)	Linia de bază a tranzitului
9	IPS_CARGOES	Marfă pe membru convoi (cantitate, UM)	Cantitate și încadrare marfă
10	IPS_VOYAGE_LOCK	Ecluzări (ecluză, cameră, durată)	Repartiția valorii pe ecluze
11	IPS_BERTHINGS	Acostări/staționări la dană	Baza facturării cheiajului
12	Nomenclatoare de config (în ROA)	Grupă tip navă, grupă marfă, UM, dane — pe baza ID-urilor RORIS	Selecția tarifului (vezi 2.1 și cap. 4)

Detaliul complet pe câmpuri (toate coloanele, tip, obligativitate) se află în anexa dictionar_date_facturare.csv. Mai jos sunt doar câmpurile esențiale pentru facturare.

2.1. Nomenclatoare folosite la facturare (listă completă)

Nomenclatoarele sunt listele de clasificare/referință de care depinde facturarea (în special selecția tarifelor — vezi cap. 4). Toate trebuie furnizate de noul sistem, cu ID-uri stabile.

Coloana „Mod de populare" arată dacă nomenclatorul este importat din RORIS (copiat într-o tabelă ROA), creat și întreținut în ROA (nu există în RORIS; configurarea lui — grupări, tarife, echivalențe — se bazează pe ID-urile din RORIS) sau generat în ROA din date importate.

Nomenclator	Conținut	Rol la facturare	Mod de populare
IPS_CONTACTS	Firme (transportatori, plătitori, armatori)	Client/plătitor pe factură	Importat din RORIS
IPS_COUNTRIES	Țări	Pavilion navă, țară marfă/voiaj	Importat din RORIS
IPS_RISGOODS	Mărfuri (cu NSTR, clasă IMO, indicator periculos)	Încadrare tarifară pe marfă	Importat din RORIS
IPS_GOODS_GROUPS	Grupe de marfă	Încadrare tarifară pe grupă de marfă	Creat în ROA (config pe baza ID-urilor RORIS — nu există în RORIS)
IPS_RIS_VES_TYPES	Tipuri de navă	Atribut navă; bază pentru grupa de tip navă	Importat din RORIS
IPS_GRUP_TIP_NAVE	Grupe de tip navă	Încadrare tarifară (tariful se definește pe grupă)	Creat în ROA (config pe baza ID-urilor RORIS — nu există în RORIS)
IPS_ARAMIS_TIP_NAVE	Tipuri de navă — clasificare ARAMIS	Clasificarea navei la cheiaj	Creat în ROA (config pe baza ID-urilor RORIS — nu există în RORIS)
IPS_ROUTE_POINTS	Puncte de rută (km, porturi, dane)	Definirea rutei, distanței și danei	Importat din RORIS
IPS_ROUTES	Rute (pereche punct plecare–sosire + distanță)	Încadrare tarifară pe rută	Generat în ROA din date RORIS (din voyage_members + route_points)
IPS_VAS_UM	Unități de măsură ale tarifelor (TC, TRN, LBD, CP, ZI)	Selecția unității de măsură a tarifului	Creat în ROA (config pe baza ID-urilor RORIS — nu există în RORIS)
IPS_VAS_ECHIVALENT	Echivalențe între unitățile de măsură	Conversii de UM la calcul	Creat în ROA (config pe baza ID-urilor RORIS — nu există în RORIS)
IPS_DANE	Dane	Identificarea danei la cheiaj	Creat în ROA (config pe baza ID-urilor RORIS — nu există în RORIS)

Observații:

• IPS_CONTACTS, IPS_COUNTRIES, IPS_RISGOODS, IPS_RIS_VES_TYPES și IPS_ROUTE_POINTS apar și în tabelul entităților (1-6) — sunt în același timp date de tranzacție și nomenclatoare. Acestea trebuie furnizate de noul sistem, cu ID-uri stabile.
• Nomenclatoarele marcate „Creat în ROA" NU există în RORIS și nu trebuie furnizate de noul sistem. Ele sunt configurate manual în ROA (de exemplu: gruparea tipurilor de navă în grupe tarifare, gruparea mărfurilor, echivalențele de unități de măsură, danele) și referă prin ID entitățile din RORIS (tip navă, marfă, punct de rută). La fel, IPS_ROUTES este construit în ROA din datele importate.
• Consecință critică: deoarece aceste configurări din ROA sunt legate de ID-urile din RORIS, dacă noul sistem schimbă ID-urile entităților de bază (tip navă, marfă, punct de rută, navă, firmă), toate grupările și tarifele configurate în ROA se desincronizează și trebuie refăcute manual. De aceea stabilitatea ID-urilor din RORIS este esențială (vezi cap. 4).
• Tarifele propriu-zise (IPS_TARIFE_TRANZIT și similare) sunt tot în ROA și referă prin ID nomenclatoarele de mai sus (vezi cap. 4, pct. 5).

---

3. Câmpuri esențiale per entitate

„ID" = identificator unic; toate ID-urile sunt text (uzual ≤36 caractere). Câmpurile marcate sunt cele fără de care facturarea nu funcționează. Restul câmpurilor — în CSV.

Firme (IPS_CONTACTS): id, name.

Mărfuri (IPS_RISGOODS): id, name, dangerous (periculos → coeficient).

Nave (IPS_VESSELS): id, name, gross_tonn (capacitate), trn (tonaj registru net), lbd, horsepower, vtp_id (tip navă).

Tipuri navă (IPS_RIS_VES_TYPES): id, name.

Puncte rută (IPS_ROUTE_POINTS): id, name.

Voiaje (IPS_VOYAGES): id, data avizării, data declarației, convoy_name, declaration, ctt_id (firmă), origin, destination.

Membri convoi (IPS_VOYAGE_MEMBERS): id, vye_id (voiaj), vsl_id (navă), rstart_id/rfin_id (plecare/sosire), distance, distance_cdmn (distanța pe canalul principal).

Marfă (IPS_CARGOES): id, vms_id (membru), risgds_id (marfă), quantity, unit.

Ecluzări (IPS_VOYAGE_LOCK): id, vye_id, fk_voyage_member (membru), chamber_nr, chamber_name, lock_name, date. (vezi cap. 4 — denumiri și camere obligatorii)

Acostări (IPS_BERTHINGS): id, ves_id (navă), arrival_time, departure_time, tip (1=port, 2=dană așteptare, 9=altele), rpt_id (dană).

---

4. Impact asupra facturării

Tariful unei tranzitări se alege în ROA după ID-urile din RORIS, nu după denumiri — în funcție de combinația grupă de tip navă + grupă/tip de marfă + rută + capacitate. Gruparea (tip navă → grupă, marfă → grupă) și tarifele se configurează în ROA; din RORIS se folosesc doar ID-urile de tip navă, marfă și punct de rută, plus atributele de calcul ale navei (capacitate, cuplat/necuplat, distanțe pe canale).

Următoarele modificări ale noului sistem afectează direct facturarea. Pentru fiecare, dacă nu se respectă regula, va fi nevoie de un adaptor la nivelul importului/calculului ROA, care trebuie prevăzut ca efort și buget.

#	Risc / modificare	Efect asupra facturării	Cerință / adaptor necesar
1	ID-uri schimbate la migrare (voiaje, nave, mărfuri, puncte rută, firme)	Se rup legăturile cu tarifele/contractele și relistarea facturilor istorice	ID-uri păstrate identic, sau tabel de echivalență ID_vechi↔ID_nou pentru remapare
2	Denumiri ecluze modificate	Repartiția valorii pe ecluze devine 0; valoarea trece greșit pe „senal"	lock_name trebuie să conțină AGIGEA / CERNAVODA / OVIDIU / NAVODARI
3	Coduri cameră ecluză modificate	Aceeași problemă ca mai sus, pe cameră	chamber_name exact: SAS1 / SAS2 (canal principal), C1 / C2 (canal Năvodari)
4	Camera ecluzei necompletată	Ecluzarea nu se poate factura corect (caz deja problematic azi)	Completarea camerei obligatorie la fiecare ecluzare
5	ID-uri de bază RORIS schimbate (tip navă, marfă, punct de rută)	Grupările și tarifele configurate în ROA (pe baza acestor ID-uri) nu se mai potrivesc → tranzitul nu se facturează	ID-uri RORIS stabile, ca să rămână valide configurările din ROA (gruparea tip→grupă/marfă→grupă se întreține în ROA)
6	Structură/denumiri coloane diferite în vederi	Importul actual din vederi nu mai rulează	Păstrarea acelorași vederi și denumiri de coloane (cap. 1)
7	Date fără oră (avizare/declarație, sosire/plecare)	Perioada de facturare și durata la cheiaj sunt greșite	Livrare ca dată + oră completă
8	Unități de măsură marfă/navă inconsistente	Cantitățile facturate se denaturează	UM stabile și consecvente în timp

Notă privind responsabilitatea: ERP-ul ROA și programul de facturare sunt dezvoltate și întreținute de ROMFAST SRL. Adaptările de pe partea de import/calcul ROA pot fi realizate de ROMFAST, dar numai dacă noul sistem respectă regulile de mai sus. Orice abatere (în special ID-uri instabile, denumiri de ecluze/camere schimbate, sau lipsa vederilor) transferă efort suplimentar și risc asupra facturării și trebuie evitată sau, după caz, prevăzută explicit în buget.

---

Anexă tehnică: dictionar_date_facturare.csv — lista completă a câmpurilor pe fiecare entitate.