solduri2roa/docs/plan_etapa2_convertor.md

Plan etapa 2 - convertorul reutilizabil SAGA -> xlsx initializare ROA

Stare: v3, deciziile luate, lansarea lane-urilor neaprobata inca. Versiunea v2 a trecut prin review de strategie si de arhitectura (docs/review_ceo_etapa2.md, docs/review_eng_etapa2.md); ce urmeaza include corectiile.

Premise: importurile FUNDATIA + MASTER au trecut in ROACONT, scripturile de coduri fiscale au fost executate (confirmat 21.09.2026). Regulile din decizii_import.md sunt validate in productie si nu se redeschid.

Cercetarea pe care se sprijina planul:

• docs/raport_sursa_saga_xlsx.md - SAGA veche (VFP), conventiile tabelei conturi_roa.dbf;
• docs/raport_exporturi_saga_noua.md - SAGA noua (Firebird), exporturile xlsx si baza .FDB.

Ce ramane in scop si ce nu

IN scop: initializarea soldurilor la o luna, adica fisierul pe care il inghite frm_initializare_facturi_balanta din ROACONT.

IN AFARA scopului (asta faceau programele saga2roa* vechi, noi nu): importul registrului jurnal, generarea balantelor de verificare lunare, generarea nomenclatorului de parteneri la fiecare luna.

Corectia cea mai importanta fata de v2: cine decide conturile cu parteneri

v2 spunea ca CONFIG_CONT_IREG din Oracle e sursa de adevar. Este gresit si ar fi produs o regresie tacuta. Dovada:

• genereaza_xlsx.py:46-50 trateaza ca parteneri 5121, 5124 (banca, cu analitic) si 5311 (casa, fara analitic);
• in docs/config_cont_ireg.md:89 (lista CU_INREGISTRARI = 1) niciunul dintre ele nu apare;
• invers, Oracle listeaza 404, 408, 409, 4091, 4093, 4094, 418, 419, 471, 472, 456, 457... pe care codul validat nu le trateaza ca parteneri.

Daca unealta ar fi decis din Oracle, 5121.01 PIRAEUS BANK de la MASTER - cazul din decizii_import.md pct. 15, cu sold creditor pe cont de trezorerie - ar fi devenit cont obisnuit, fara rand FACTURA, fara ca nimic sa dea eroare.

Regula, de acum: setul operational este cel validat in productie, tinut intr-un fisier in repo, config/conturi_parteneri.csv, cu o coloana de categorie (BANCA / SINTETIC / FARA_ANALITICE) si una de motiv. CONFIG_CONT_IREG ramane consultativ: un script mic il exporta alaturi, iar unealta raporteaza divergentele la fiecare rulare (cont in Oracle si nu la noi, sau invers) - le raporteaza, nu le aplica. Divergenta constatata azi se scrie in docs/decizii_import.md, ca sa nu fie redescoperita.

Arhitectura: un contract intern, trei cititoare

  PDF balanta   --\
  xlsx/xls SAGA --+--> [cititor] --> contractul intern --> mapare --> init_<FIRMA>_<an>_<luna>.xlsx
  CONT_BAZA.FDB --/

Contractul intern - fixat aici, nu lasat la latitudinea cititoarelor

Trei fisiere, nume si coloane exacte. Potrivirea numelor de coloana la citire este exacta si case-insensitive, niciodata pe substring (TOTAL_DEB vs TOTAL_DEB_1 se confunda usor).

fisier	coloane	scris de
balanta_<FIRMA>.csv	pagina, cont, denumire, prec_d, prec_c, rulaj_d, rulaj_c, total_d, total_c, sold_d, sold_c, este_total, tip	toate cele 3 cititoare
parteneri_<FIRMA>.csv	cont_analitic, cod, denumire, cod_fiscal	xlsx (fara cod_fiscal), FDB (complet)
facturi_<FIRMA>.csv	cont_analitic, numar, data, scadent, sold	xlsx (fara scadent), FDB (complet)

Coloanele pe care o sursa nu le poate da raman goale, niciodata inventate. tip (A/P) exista doar pe drumurile xlsx si FDB; consumatorul ei e stabilirea laturii soldului, in locul deducerii dupa clasa contului. Ultimele doua fisiere lipsesc cu totul cand sursa e doar balanta - atunci se cade pe comportamentul de azi (un FACTURA per partener, sold total).

Cititorul 1 - PDF (exista, nemodificat)

extract_balanta.py, pdfplumber pe coordonate. Singura sursa care merge pe orice versiune SAGA, fiind raportul tiparit. Nu se atinge: e validat pe FUNDATIA si MASTER.

Cititorul 2 - foaie de calcul SAGA (.xls sau .xlsx), nou

.xlsx cu openpyxl, .xls cu xlrd (openpyxl nu citeste BIFF). Acelasi cititor pentru SAGA veche si noua: au aceleasi 35 de coloane, in aceeasi ordine. Maparea: DEB_PREC/CRED_PREC -> prec_d/prec_c, RULAJ_D/RULAJ_C -> rulaj_d/rulaj_c, TOTAL_DEB/TOTAL_CRED -> total_d/total_c, FIN_D/FIN_C -> sold_d/sold_c, TIP -> tip. pagina si este_total raman goale (exportul nu are rand de totaluri). Foaia: prima foaie a registrului - numele difera (balanta la VFP, xl la .xls nou, Sheet1 la .xlsx), deci nu se cauta dupa nume. CONT se citeste ca text: 401.00002 citit ca numar se strica.

Cititorul 3 - Firebird, nou

Parametru: calea catre o copie de CONT_BAZA.FDB. Niciodata baza vie a clientului. Conexiune embedded (pe TCP 3060 parola implicita nu merge), access_mode=READ, no_gc=True, doar SELECT, rollback la final. Charset WIN1250.

Algoritmul balantei, specificat aici pentru ca e inima corectitudinii. Soldurile stocate in CONTURI sunt 0 (raport_exporturi_saga_noua.md C.4); cifrele vin din agregarea REGISTRU. Sunt necesare trei intervale de data, nu unul - exportul are patru marimi distincte:

marime	interval
DEB_INIT/CRED_INIT	tot ce e anterior inceputului anului fiscal
prec_d/prec_c	de la inceputul anului pana la inceputul lunii cerute
rulaj_d/rulaj_c	in luna ceruta
total_*	prec + rulaj ; sold_d - sold_c = total_d - total_c

Rollup la sintetic: REGISTRU.CONT_D/CONT_C contin analiticul (401.00002), iar exportul SAGA are sinteticul (401) - raport_exporturi_saga_noua.md C.4. Agregarea grupeaza pe partea din stanga punctului si emite si randul analitic, si sinteticul. Randul % din CONTURI este cont colector si se exclude.

Mai produce: parteneri_<FIRMA>.csv din FURNIZORI + CLIENTI (codul fiscal real vine de aici, deci pe acest drum etapa 5b - cautarea pe ANAF - dispare) si facturi_<FIRMA>.csv din INTRD/INTRARI si IESIRI/IES_DET, toate deodata, nu per partener.

Garzi pe NULL, nu presupuneri: INTRD.SCADENT a fost NULL pe singurul rand existent, iar FURNIZORI.COD_FISCAL era gol la unul din doi. Deci "scadenta reala" si "cod fiscal real" inseamna cand exista: scadenta lipsa cade pe ultima zi a lunii (ca azi), codul fiscal lipsa cade pe codul provizoriu <cont>.<analitic> si partenerul intra in lista pentru cautarea ANAF.

Poarta de verificare a cititoarelor

Cititorul 3 (FDB) si cititorul 2 (xlsx) trebuie sa produca acelasi balanta_<FIRMA>.csv pentru firma de joaca D:\SAGA250909\0001\CONT_BAZA.FDB, luna 09/2026, al carei export este in exemple\. Daca difera, e bug de cititor, nu date gresite. Acesta inchide lane-ul citire-fdb, nu "ruleaza fara eroare".

Limitele acestei porti, scrise si in raport, nu ascunse: firma de joaca are 10 conturi, toate sintetice, niciun analitic, 2 furnizori, 0 clienti, 1 factura. Deci poarta dovedeste rollup-ul si periodizarea pe cazul sintetic si nimic despre analitice - exact partea grea. Pana la o baza reala, cititorul FDB este verificat partial si se marcheaza ca atare in ajutorul uneltei; nu se foloseste la un client fara rerularea portii pe datele lui.

Inlocuitorul verificarii "Totaluri:". Pe drumul PDF, poarta era randul "Totaluri:" din raport. Exportul xlsx si baza nu au asa ceva. Nu se sterge verificarea, se inlocuieste cu una reala: SUM(REGISTRU) pe fiecare latura, la data ceruta, = netul balantei generate. Pe drumul xlsx, unde REGISTRU nu e disponibil, ramane SUM(sold_d) = SUM(sold_c) pe frunze plus relatiile total = prec + rulaj si sold_d - sold_c = total_d - total_c pe fiecare cont (au trecut 341/341 pe DANUBE si 10/10 pe firma de joaca).

Pasul de mapare

Fiecare firma are propriile analitice, deci fiecare firma are propriul fisier. Implicit merge pe propunerile automate; corectiile sunt posibile oricand, fara sa fie obligatorii.

Doua fisiere, cu proprietari diferiti - asa regenerarea nu-ti poate distruge corectiile:

fisier	cine scrie	ce contine
mapare_<FIRMA>.xlsx	doar unealta, regenerat complet la fiecare rulare	toate conturile din balanta, cu propunerea automata: cont_saga, denumire, sold, cont, acont, sursa (AUTO sau CORECTAT)
corectii_<FIRMA>.xlsx	doar tu	numai randurile pe care le schimbi: cont_saga, cont, acont, exclus, motiv

La rulare: se citeste balanta, se propune automat, se suprapun corectiile, se scrie maparea completa ca sa vezi rezultatul final. Fisierul de corectii se creeaza gol, cu antet si un exemplu comentat, doar la prima rulare a firmei - pentru o firma simpla nu-l deschizi niciodata.

Propunerea automata, cu regula de azi din decizii_import.md: cont = primele max 4 caractere, acont = cifrele analiticului concatenate, max 4.

Conventii preluate din conturi_roa.dbf (raport_sursa_saga_xlsx.md 2.3), ca sa nu ai sute de randuri de corectat - se scriu in corectii_<FIRMA>.xlsx:

• <sintetic>.TOATE - toate analiticele sinteticului merg pe acelasi cont/acont ROA;
• <sintetic>.RESTUL - la fel, dar doar pentru analiticele fara rand propriu.

Ordinea de cautare: potrivire exacta -> .RESTUL -> .TOATE. PLANCONT nu se preia: era fallback pentru planul de conturi, noi nu generam plan de conturi.

Maparea acopera si redenumirea sinteticului (409 -> 4091, 431 -> 4311), nu doar analiticul - era jumatate din ce facea conturi_roa.dbf si lipsea din v2.

Ce NU se configureaza aici: care conturi merg pe parteneri (vezi sectiunea de mai sus - fisierul config/conturi_parteneri.csv).

Cine detine forma lui acont (corectie fata de v2)

v2 spunea ca genereaza ia cont/acont din mapare in loc sa le calculeze. Prea larg, si ar fi dublat o regula deja validata. Doua lucruri nu pot veni din mapare:

• randurile de diferenta nu exista in balanta, sunt calculate (genereaza_xlsx.py:204-212, :243-249) - raman in cod;
• forma lui acont pentru conturile cu parteneri depinde de categorie: 401 cere acont gol pe ambele randuri, 5121 cere acont completat identic pe BALANTA si FACTURA (decizii_import.md pct. 16). O regula generica de pre-completare ar pune acont pe 401 -> chei diferite -> dublare tacuta a sumei, exact capcana din pct. 16.

Regula: genereaza_xlsx.py ramane singurul care decide forma pentru conturile cu parteneri; maparea doar suprascrie ce ii dai explicit. Restul fisierului - randuri BALANTA / FACTURA, sume negative pe latura opusa, verificarile din etapa 5 - ramane neatins.

Opreste-te cu eroare, nu cu ghicit, daca: cont sau acont depaseste 4 caractere; doua conturi SAGA diferite produc acelasi (cont, acont) fara sa fie acoperite de un .TOATE/.RESTUL comun (colapsarea intentionata e legala, coliziunea accidentala nu); un rand din corectii nu corespunde niciunui cont din balanta (typo tacut).

Testare

unittest din stdlib, fara dependinte noi. Proiectul nu are azi niciun test; fiecare lane lasa in urma cel putin unul, altfel lane-ul nu e gata:

lane	testul pe care il lasa
citire-xlsx	citeste exemple\saga-sqlite-balanta-09-2026.xlsx si saga2roa_danube\balanta.xls; relatiile de sume trec pe toate randurile; CONT ramane text
mapare	o corectie supravietuieste regenerarii; .TOATE/.RESTUL se aplica in ordinea ceruta; un cont_saga inexistent in corectii da eroare
citire-fdb	CSV-ul din FDB identic cu cel din xlsx pe firma de joaca; SCADENT NULL cade pe ultima zi a lunii
integrare	rulare capat-la-capat pe firma de joaca, din ambele surse
regresie	FUNDATIA + MASTER reproduc etalonul

Poarta de regresie si etalonul

tests/golden/ primeste copii anonimizate ale celor doua xlsx importate in productie: sumele, conturile, structura randurilor si numarul lor raman neatinse; denumirile de parteneri devin PARTENER 001... si codurile fiscale CF000001..., stabil (acelasi nume real -> acelasi nume fals, ca relatiile dintre randuri sa se pastreze). Asa poarta compara orice celula si in git nu intra numele niciunui client. Scriptul de anonimizare se comite; tabela de corespondenta nu.

Comparatia se face pe valori de celula, nu pe hash de fisier: un xlsx rescris de alta versiune de openpyxl are alti octeti cu acelasi continut.

Regresia ruleaza dupa fiecare lane care atinge generatorul, nu doar la final - e cel mai ieftin test care protejeaza zona deja validata in productie.

Git

.gitignore ignora init_*.xlsx, export_*.xlsx, mapare_*.xlsx, balanta_*.csv. Se adauga: *.fdb, *.FDB (copii de baze de client, zeci de MB), parteneri_*.csv, facturi_*.csv, corectii_*.xlsx. Exceptii explicite: sablonul si tests/golden/. PDF-urile sursa raman in git: sunt datele pe care ruleaza regresia. exemple\ ramane in git - firma de joaca, nu date de client.

Dependintele noi (xlrd, firebird-driver) se trec in CLAUDE.md, la Mediu.

Ordinea de lucru (lane-uri opencode)

lane	livrabil	criteriu de terminare	depinde de
contract	config/conturi_parteneri.csv + scriptul de divergenta Oracle; anonimizatorul + tests/golden/	regresia ruleaza si trece pe etalonul anonimizat, cu codul de azi neschimbat	-
citire-xlsx	cititorul de foaie de calcul SAGA	vezi tabelul de testare	contract
mapare	propunerea automata + corectii_<FIRMA>.xlsx + .TOATE/.RESTUL + redenumirea sinteticului	vezi tabelul de testare	contract
citire-fdb	balanta + parteneri + facturi din Firebird	CSV identic cu drumul xlsx pe firma de joaca	citire-xlsx
integrare	extrage.py / genereaza.py cu parametri	rulare capat-la-capat din ambele surse	toate
regresie	rerularea pe FUNDATIA + MASTER	identice cu etalonul, pe valori de celula	integrare

Lane-ul contract merge primul si singur: fixeaza etalonul inainte ca vreo linie de cod sa se schimbe, altfel regresia masoara fata de un rezultat deja mutat.

Poarta finala: regresie. Daca noul flux nu reproduce randurile celor doua xlsx-uri validate in productie, nu e gata - indiferent cat de curat e codul.

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. Pana atunci cititorul FDB e verificat partial (vezi mai sus);
• procedura pentru client: cum isi face copia bazei (gbak da o copie consistenta si mai mica decat fisierul brut) si ca trebuie sa opreasca SAGA daca trimite fisierul direct. Se scrie odata cu lane-ul citire-fdb, altfel livram un cititor care nu se poate folosi in teren;
• conectarea la un Firebird prin retea - azi nu merge cu parola implicita (raport_exporturi_saga_noua.md C.1), deci cere credentiale de la client.