solduri2roa/docs/handoff_etapa2_convertor.md

Handoff - etapa 2, convertorul reutilizabil SAGA -> ROA

Actualizat 21.09.2026, la finalul executiei. Versiunea anterioara a acestui fisier descria starea inainte de lansarea lane-urilor; toate lane-urile au rulat intre timp.

Stare: etapa 2 este terminata. Toate cele sase lane-uri din plan au trecut portile lor, 33 de teste trec fara niciun skip, totul e comis si impins pe origin/main.

---

1. Ce exista acum

fisier	ce face
extrage.py	punctul de intrare: --sursa pdf/xlsx/fdb (dedus din extensie) -> contractul intern
genereaza.py	punctul de intrare: contractul intern + mapare -> init_<FIRMA>_<an>_<luna>.xlsx
extract_balanta.py	cititorul PDF, nemodificat (era validat in productie)
citire_xlsx.py	cititorul de foaie SAGA .xls (xlrd) si .xlsx (openpyxl)
citire_fdb.py	cititorul Firebird: balanta, parteneri, facturi
mapare.py	propunere automata, corectii_<FIRMA>.xlsx, .TOATE/.RESTUL, redenumire sintetic
genereaza_xlsx.py	biblioteca de generare, acum parametrizata pe an/luna
config/conturi_parteneri.csv	conturile cu parteneri - autoritatea
tools/divergenta_parteneri.py	raporteaza divergenta fata de CONFIG_CONT_IREG, nu o aplica
tests/	33 de teste, unittest din stdlib
docs/procedura_copie_fdb_client.md	cum isi face clientul copia bazei
docs/raport_lane_*.md	raportul fiecarui lane
date/, iesiri/, sablon/	intrari de la client / xlsx-uri generate / sablonul ROA

Commit-uri: 15bb26a (plan + etalon), f23b336 (contract), ba4cbbf (citire-xlsx + mapare), 6b37d37 (citire-fdb), 82511c8 (integrare), plus commit-ul final de regresie.

2. Portile care au trecut, si ce dovedesc

1. Regresia pe etalon (tests/test_regresie.py): biblioteca reproduce celula cu celula cele doua xlsx-uri importate in ROACONT. Verificat ca poarta e reala: scoaterea lui 5311 din config o face sa pice.
2. Poarta cititoarelor (tests/test_citire_fdb.py): CSV-ul din CONT_BAZA.FDB e identic la octet cu cel din exportul xlsx, pe firma de joaca, 09/2026. Plus SUM(REGISTRU) pe fiecare latura = netul balantei.
3. Poarta finala (tests/test_regresie_capat_la_capat.py): extrage.py + genereaza.py rulate ca subprocese, pornind de la PDF-urile originale, reproduc etalonul cu 0 diferente.

3. Ce NU e dovedit - citeste inainte sa duci asta la un client

• Cititorul FDB e verificat doar pe cazul sintetic. Firma de joaca are 10 conturi, toate sintetice, niciun analitic, 2 furnizori, 0 clienti, 1 factura. Rollup-ul analitic -> sintetic si periodizarea sunt dovedite doar acolo. Scris si in docstring-ul lui citire_fdb.py. Nu se foloseste la un client fara rerularea portii pe datele lui.
• Conectarea la Firebird prin retea nu merge cu parola implicita: cere credentiale clientului.
• Drumul cu parteneri si facturi reale (un FACTURA per document, cod fiscal din FURNIZORI) a fost exersat doar pe o singura factura a firmei de joaca.

4. Doua defecte prinse la verificare, nu de lane-uri

Amandoua erau tacute - ar fi trecut testele si ar fi stricat date:

1. .xls-ul SAGA nu are inregistrare CODEPAGE, deci xlrd cadea pe iso-8859-1 si strica denumirile (FURNIZORI \x97 DEBITORI). Reparat cu encoding_override="cp1250", cu asertie in tests/test_citire_xlsx.py care pica daca revine.
2. Redenumirea unui cont cu parteneri lua primul analitic ca sa afle contul sintetic. Cu analitice mapate pe conturi diferite, BALANTA agregat si randurile FACTURA cadeau pe conturi diferite. Acum ridica Stop; colapsarea prin .TOATE ramane legala.

Morala pentru sesiunea urmatoare: raportul unui lane nu tine loc de verificare. Ambele lane-uri raportasera "GATA" corect dupa criteriile lor.

5. Divergenta fata de Oracle, constatata si scrisa

CONFIG_CONT_IREG listeaza 27 de conturi pe care codul validat nu le trateaza ca parteneri, si nu listeaza 5121, 5124, 5311, pe care le trateaza. Confirma decizia din plan: Oracle e consultativ. Detaliile in docs/decizii_import.md.

6. Ce ramane pentru mai tarziu

• o baza .FDB reala + exportul ei de balanta, ca sa se reruleze poarta pe date cu analitice si cu volum;
• portul 4296 al acestui proiect nu e inca trecut in tabelul din D:\ROA\ROACONT\COMUN\docs\opencode_agenti_orchestrare.md (COMUN cere aprobare inainte de commit);
• docs/plan_solduri2roa.md descrie inca etapele 1-6; nu a fost rescris dupa etapa 2.

7. Starea pe disc

Totul comis si impins pe origin/main. Nimic periculos: niciun proces ramas viu (serverul opencode de pe 4296 a fost oprit), D:\ROA\ROACONT, D:\SAGA250909 si saga2roa* neatinse, baza firmei de joaca deschisa numai prin copie in temporar, tests/_corespondenta_anonimizare.json ramasa ignorata de git.

Fisierele iesiri/init_FUNDATIA_2025_12.xlsx si iesiri/init_MASTER_2025_12.xlsx sunt pe disc dar nu in git; sunt necesare doar daca vrei sa regenerezi etalonul (py tests\anonimizeaza_etalon.py, care le citeste din iesiri/).

8. Cum rulezi acum unealta

py extrage.py --fisier "date\IBB 31.12.2025.pdf" --firma FUNDATIA --an 2025 --luna 12
py genereaza.py --firma FUNDATIA --an 2025 --luna 12

Implicit extrage.py scrie in date/, iar genereaza.py citeste din date/ si scrie in iesiri/ (--dir / --dir-iesire le schimba). Sablonul e in sablon/.

Capcana de nume: balanta firmei MASTER se numeste balanta_MASTERJOB.csv, nu balanta_MASTER.csv, deci pentru ea trebuie dat explicit --balanta date\balanta_MASTERJOB.csv. Eroarea e clara, nu tacuta.

Sursa se deduce din extensie (.pdf, .xls/.xlsx, .fdb); o extensie necunoscuta da eroare. Pentru Firebird, da calea catre o copie a bazei, niciodata baza vie a clientului.