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 |

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 `init_FUNDATIA_2025_12.xlsx` si `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`).

## 8. Cum rulezi acum unealta

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

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.