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