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), `0d0b3e2` (regresie - poarta finala),
`9a83e36` (mutarea in `date/`, `iesiri/`, `sablon/`).

## 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 urmeaza - de aici incepe sesiunea urmatoare

In ordinea in care le-as face:

1. **Proba pe un client real** - singurul lucru care mai conteaza acum. Cere unui client cu SAGA
   noua copia bazei (`docs/procedura_copie_fdb_client.md`) **si** exportul lui de balanta pe
   aceeasi luna. Ruleaza poarta cititoarelor pe datele lui: daca cele doua CSV-uri coincid pe o
   firma cu analitice si cu volum, cititorul FDB inceteaza sa mai fie "verificat partial". Daca
   nu coincid, diferenta este livrabilul - nu se ajusteaza nimic ca sa treaca.
2. **Al doilea import real, capat-la-capat**, pe o firma noua: `extrage.py` -> corectii in
   `corectii_<FIRMA>.xlsx` -> `genereaza.py` -> import in ROACONT. Asta exerseaza pasul de mapare
   pe date pe care nu le-a vazut nimeni si e primul test adevarat al lui `.TOATE`/`.RESTUL`.
3. **Pasul 5b (cautarea pe ANAF)** devine inutil pe drumul FDB, unde codul fiscal e real.
   Verifica pe date reale si, daca se confirma, scoate-l din flux pentru sursa Firebird.
4. Marunt, cand se nimereste: portul **4296** nu e trecut in tabelul din
   `D:\ROA\ROACONT\COMUN\docs\opencode_agenti_orchestrare.md` (COMUN cere aprobare
   inainte de commit).

**Nu incepe** prin a reface cercetarea sau a redeschide deciziile din sectiunea 5 a planului:
sunt platite si validate. Daca ceva pare gresit, cere dovada, nu reinvestiga.

## 7. Riscuri asumate, nu uitate

- **Firebird prin retea** nu merge cu parola implicita: la un client care nu poate trimite
  fisierul, cere credentiale. Nu e rezolvat, e ocolit prin copia locala.
- **Un singur analitic cu sold pe latura opusa** (`5121.01` la MASTER, -20.80 D) trece azi
  prin regula de la `decizii_import.md` pct. 15. E validat in productie pe un caz; al doilea
  client il va pune la incercare.
- `docs/verificare_*.md` din git sunt cele ale importurilor validate; rularile noi scriu in
  `iesiri/` si nu le ating.

## 8. 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/`).

## 9. 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/`.

Numele intermediarului urmeaza intotdeauna `--firma`: `date/balanta_<FIRMA>.csv`. Firma se
cheama in acte MASTERJOB, dar peste tot in unealta si in ROA e `MASTER`, deci balanta ei e
`date/balanta_MASTER.csv` (redenumita 21.09.2026; inainte era `balanta_MASTERJOB.csv` si
cerea `--balanta` explicit).

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.