Documentatie date facturare pentru modernizare RoRIS

Specificatie minima cu datele de care depinde facturarea ROA, pentru
caietul de sarcini al modernizarii RoRIS. Include:
- DOCUMENTATIE_DATE_FACTURARE_RORIS.md/.docx (livrabil)
- dictionar_date_facturare.csv (anexa tehnica)
- PACK_ACN_IMPORT.pck (sursa analizata)
- CLAUDE.md (context)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

DOCUMENTATIE_DATE_FACTURARE_RORIS.md

@@ -0,0 +1,160 @@
+# 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.*