acn-documentatie-roris/CLAUDE.md

# CLAUDE.md

Context pentru asistarea pe acest folder. Citește înainte de a relua lucrul.

## Ce este acest folder

Folder de lucru pentru o **documentație de modernizare RoRIS** cerută de ACN. Autorul/clientul
este **Marius Mutu (ROMFAST SRL)** — firma care a dezvoltat ERP-ul de facturare **ROA**
(aplicația `ROAACNPRO`). ACN a depus cerere de finanțare pentru modernizarea sistemului **RoRIS**
și are nevoie de o specificație cu datele de care depinde facturarea, ca să o impună în caietul de
sarcini către firma care va face modernizarea.

## Arhitectura sistemelor (de reținut)

- **RoRIS** = sistemul sursă (date operaționale tranzit barje/nave, ecluzări, acostări).
  Bază de date **SQL Server**.
- **ROA** (`ROAACNPRO`, dezvoltat de ROMFAST) = ERP-ul de facturare. Bază de date **Oracle**,
  aplicație Visual FoxPro 9.
- ROA (Oracle) preia datele din RoRIS (SQL Server) printr-un **database link** (gateway heterogen
  Oracle → SQL Server, `RORISSQL`). Importul e o copiere (`merge`) în tabele Oracle `ips_*`.
  **Nu există API/REST** — clientul vrea explicit să păstreze acest model, nu să-l înlocuiască.

## Fișierele din acest folder

- `PACK_ACN_IMPORT.pck` — pachetul Oracle care importă din RoRIS în ROA (sursa analizei).
- `DOCUMENTATIE_DATE_FACTURARE_RORIS.md` — **livrabilul principal** (specificație minimă, în
  română, ton impersonal). Structură: 1) Principiu integrare; 2) Entități + nomenclatoare (2.1);
  3) Câmpuri esențiale; 4) Impact asupra facturării (tabel de riscuri).
- `DOCUMENTATIE_DATE_FACTURARE_RORIS.docx` — versiunea Word, **generată din .md** (vezi mai jos).
- `dictionar_date_facturare.csv` — anexă tehnică, dicționar complet de câmpuri (delimitator `;`,
  se deschide nativ în Excel România).

## Sursa de adevăr (codul ROA real)

Programul de facturare e în `D:\ROA\ROAACNPRO`. Pentru detalii de cod, relevante:
- `D:\ROA\ROAACNPRO\PACK_ACN_IMPORT.pck` (copie și aici) — ce entități se importă.
- `D:\ROA\ROAACNPRO\Programe\proceduri_acnpro.prg` — calcul/salvare facturare; rapoarte de
  indicatori `vizualizare_tranzit_nave` (~linia 228) și `vizualizare_cheiaj_nave` (~383);
  distribuția pe ecluze (`completeaza_regdoc_tranzit`, ~2259–2606); tarife `ips_tarife_tranzit`
  (`vizualizare_tarife_tranzit`, ~4820).
- `D:\ROA\ROAACNPRO\database.txt` — sinonime/granturi RoRIS.
- `D:\ROA\ROAACNPRO\docs\fluxuri_calcul_facturare.md` și `docs\facturare.md` — fluxuri de calcul.
- `D:\ROA\ROAACNPRO\CLAUDE.md` — ghidul aplicației ROA.

## Constatări cheie (deja încorporate în documentație)

1. **Ecluzele se potrivesc pe DENUMIRE, nu pe `id_lock`.** Codul filtrează `lock_name LIKE
   '%AGIGEA%'/'%CERNAVODA%'/'%OVIDIU%'/'%NAVODARI%'` și `chamber_name` exact `SAS1`/`SAS2` (canal
   principal CDMN) sau `C1`/`C2` (canal PAMN, Năvodari). `id_lock` poate fi orice. Camera trebuie
   **obligatoriu completată** (există `verificare_roris_ecluze.exe` care semnalează lipsurile).
2. **ID-urile entităților din RoRIS trebuie stabile în timp.** Sunt folosite ca FK în tarife,
   contracte și vânzările deja facturate → relistarea facturilor istorice depinde de ele.
3. **Nomenclatoarele de grupare/tarifare NU există în RoRIS — sunt create în ROA** și referă prin
   ID entitățile RoRIS: grupe tip navă (`ips_grup_tip_nave`), grupe marfă (`ips_goods_groups`),
   UM (`ips_vas_um`), echivalențe (`ips_vas_echivalent`), dane (`ips_dane`), tarifele
   (`ips_tarife_tranzit`). Tariful de tranzit se alege pe combinația **grupă tip navă + grupă/tip
   marfă + rută + capacitate**, totul pe ID-uri RoRIS. Dacă RoRIS schimbă ID-urile de bază,
   configurarea din ROA se desincronizează.
4. **Entități importate din RoRIS** (12): contacts, countries, goods (RISGOODS), vessels,
   vessel_types (RIS_VES_TYPES), route_points, voyages, voyage_members, cargoes, voyage_locks
   (VOYAGE_LOCK), berthings; `ips_routes` e generat în ROA din voyage_members + route_points.

## Cum se regenerează DOCX din MD

Nu există pandoc; există Word 2010 (COM). Workflow: MD → HTML curat → Word salvează ca .docx.
Scriptul convertor (`_md2docx.ps1`) se creează ad-hoc, se rulează și **se șterge după** (e temporar,
nu se păstrează în folder). Pași:
1. Scrie `_md2docx.ps1` (convertor MD→HTML cu suport pentru titluri, tabele, **bold**, `cod`,
   blockquote, liste; apoi Word COM `SaveAs` format 16 = .docx).
2. Salvează întâi într-un `_doc_new.docx`, apoi `Move-Item` peste cel final (dacă fișierul final e
   deschis în Word, e blocat — anunță utilizatorul să închidă Word).
3. Șterge fișierele temporare `_md2docx.ps1`, `_doc_new.docx`, `_doc_tmp.html`.

Verificare: documentul Word este uneori deschis în IDE/Word și blochează suprascrierea.

## Preferințe ale utilizatorului (din interacțiuni)

- Documentație **minimă, lizibilă pentru oameni**, nu restrictivă/verbose.
- **Ton impersonal** — fără adresare cu „tu".
- Folosește terminologia din sistem (ex. `TRN`, nu „NRT").
- Accent pe **afectarea cât mai mică a facturării** și pe **păstrarea modelului actual** (import
  din vederi RoRIS, fără API/REST); dacă e nevoie de strat de compatibilitate, de menționat că
  trebuie prevăzut în **buget**.
- Limba documentelor: **română**.