solduri2roa/docs/handoff_etapa2_convertor.md

# Handoff - etapa 2, convertorul reutilizabil SAGA -> ROA

Scris 21.09.2026. Sesiunea urmatoare este **orchestrator**, nu executant: imparte pe lane-uri,
trimite sarcinile la agenti opencode, verifica portile. Nu scrie ea codul.

**Stare: planul e gata si aprobat pe decizii; nu s-a scris nicio linie de cod pentru etapa 2.**
Marius nu a dat inca "porneste" pe lane-uri. Intreaba-l inainte sa lansezi primul lane.

---

## 1. Ce sa citesti, in ordine, si de ce

| fisier | de ce |
|---|---|
| `docs/plan_etapa2_convertor.md` | **contractul de lucru, v3.** Tot ce urmeaza se masoara fata de el |
| `docs/raport_sursa_saga_xlsx.md` | SAGA veche (VFP); conventiile `conturi_roa.dbf` (`.TOATE`, `.RESTUL`) |
| `docs/raport_exporturi_saga_noua.md` | SAGA noua (Firebird); structura exporturilor si a bazei |
| `docs/decizii_import.md` | regulile de mapare, **validate in productie - nu se redeschid** |
| `docs/review_ceo_etapa2.md`, `docs/review_eng_etapa2.md` | de unde vin corectiile din v3; reciteste doar daca vrei sa redeschizi o decizie |

Nu reface cercetarea. Cele doua rapoarte au costat doua lane-uri si contin dovezi cu fisier si linie.

## 2. Ce e gata

- Etapele 1-6 din `docs/plan_solduri2roa.md`: cele doua xlsx au fost **importate in ROACONT si au
  trecut**; scripturile `sql/update_cod_fiscal_*.sql` au fost **executate** de Marius.
- Cercetarea pe ambele formate SAGA + conectarea la Firebird, verificata live.
- Planul v3, dupa review de strategie si de arhitectura.
- `.gitignore` + `git rm --cached` pe iesirile de productie (fisierele raman pe disc).

- **Etalonul de regresie este facut si pus in git** (21.09.2026): `tests/golden/` cu
  `golden_FUNDATIA_2025_12.xlsx` si `golden_MASTER_2025_12.xlsx`, produse de
  `tests/anonimizeaza_etalon.py`. Verificat: structura, numarul de randuri si sumele sunt
  identice cu originalele (`SUM(totdeb) = SUM(totcred)` neatins), au fost schimbate doar
  coloanele 10-14 pe randurile FACTURA plus IBAN-urile; zero IBAN si zero cod fiscal real
  ramase. Tabela de corespondenta (`tests/_corespondenta_anonimizare.json`) e ignorata de git -
  nu o comite, cu ea anonimizarea se desface.

## 3. Ce NU e facut

Tot ce e in tabelul de lane-uri din plan, mai putin etalonul. Niciun fisier de cod nou pentru
conversie, niciun test, niciun `config/conturi_parteneri.csv`.

## 4. Deciziile deja luate - nu le redeschide

1. **Conturile cu parteneri**: setul validat din `genereaza_xlsx.py:46-50` este autoritatea, tinut
   in `config/conturi_parteneri.csv`. `CONFIG_CONT_IREG` e consultativ; unealta **raporteaza**
   divergentele, nu le aplica. Motivul, cu dovada, e in plan - Oracle nu listeaza 5121/5124/5311.
2. **`acont` pentru conturi cu parteneri** ramane decis de `genereaza_xlsx.py`; maparea doar
   suprascrie explicit. Randurile de diferenta raman calculate in cod.
3. **Maparea = doua fisiere**: `mapare_<FIRMA>.xlsx` scris doar de unealta (regenerat complet),
   `corectii_<FIRMA>.xlsx` scris doar de Marius.
4. **Cititorul FDB se face acum**, marcat explicit "verificat doar pe cazul sintetic".
5. **Etalonul de regresie**: xlsx-uri intregi, **anonimizate** (sume si structura neatinse), in
   `tests/golden/`. Tabela de corespondenta nume real -> nume fals **nu se comite**.
6. **Teste**: `unittest` din stdlib. Fara dependinte noi de test.
7. Sursa: PDF, foaie de calcul SAGA si Firebird, toate trei, egale.

## 5. Ordinea lane-urilor

`contract` singur, primul -> apoi `citire-xlsx` si `mapare` in paralel -> `citire-fdb` ->
`integrare` -> `regresie`. Criteriile de terminare sunt in plan, in tabelul de lane-uri si in cel de
testare. Etalonul din `tests/golden/` a fost fixat **inainte** sa se schimbe vreo linie de cod -
asta e tot rostul ordinii. Daca vreun lane modifica `genereaza_xlsx.py` si regresia incepe sa pice,
etalonul are dreptate, nu codul nou.

## 6. Cum lansezi un lane (verificat azi, functioneaza)

Ghidul complet: `D:\ROA\ROACONT\COMUN\docs\opencode_agenti_orchestrare.md`.

- **Port pentru acest proiect: 4296.** Nu-l folosi pe 4196 (ROACONT) sau 4096 (ROAFACTURARE) -
  oprirea serverului dintr-un proiect omoara lane-urile celuilalt. Portul 4296 **nu e inca trecut in
  tabelul din ghid** - adauga-l acolo (COMUN are nevoie de aprobare inainte de commit).
- Pornire, din directorul proiectului: `opencode serve --port 4296`
- Model: `{"providerID":"opencode-go","modelID":"deepseek-v4.1-flash"}`
- Promptul de sistem, obligatoriu la fiecare sesiune, in campul `system`:
  `D:\ROA\ROACONT\COMUN\docs\opencode_prompt_initial.md`
- Sesiune noua: `POST /session {title}` -> `id`;
  sarcina: `POST /session/:id/prompt_async?directory=D:\ROA\IMPORT2ROA\solduri2roa`
- Stare: `GET /session/status` - sesiunea lipseste cand e libera, `{}` = toate libere.
- Oprire la final:
  `Stop-Process -Id (Get-NetTCPConnection -LocalPort 4296 -State Listen).OwningProcess`

Sablon PowerShell pentru trimitere (JSON pe UTF-8, altfel se strica diacriticele si ghilimelele):

```powershell
$u='http://127.0.0.1:4296'
$sys = [IO.File]::ReadAllText('D:\ROA\ROACONT\COMUN\docs\opencode_prompt_initial.md')
$m = @{providerID='opencode-go'; modelID='deepseek-v4.1-flash'}
$sid = (Invoke-RestMethod -Method Post "$u/session" -ContentType 'application/json' -Body '{"title":"lane-X"}').id
$b = @{model=$m; system=$sys; parts=@(@{type='text';text=$task})} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post "$u/session/$sid/prompt_async?directory=D:\ROA\IMPORT2ROA\solduri2roa" `
  -ContentType 'application/json; charset=utf-8' -Body ([Text.Encoding]::UTF8.GetBytes($b))
```

Asteptarea: nu face `Start-Sleep` lung in foreground (harness-ul il blocheaza). Foloseste Bash in
fundal: `until curl -s http://127.0.0.1:4296/session/status | grep -qv busy; do sleep 20; done`.

**Ce trebuie sa contina fiecare sarcina de lane**: numele lane-ului, fisierele exacte de atins,
criteriul de terminare luat din plan, interdictiile (fara commit, fara `sed -i`, fara modificari in
`D:\ROA\ROACONT`, `D:\SAGA250909`, `saga2roa*`), unde scrie raportul, si ultimul mesaj
`GATA <lane>` / `BLOCAT <lane>: motiv`. Agentii respecta asta; doi lane-uri au mers azi asa.

## 7. Capcane deja platite - nu le redescoperi

- `openpyxl` **nu** citeste `.xls` (BIFF). Pentru `.xls`: `xlrd` (instalat, 2.0.2) sau conversie
  `soffice --headless --convert-to xlsx`. Ambele verificate.
- Firebird: **numai embedded**. `firebird-driver` (instalat, 2.0.3) + `fdb.load_api` catre
  `C:\Program Files\Firebird\Firebird30_Saga\fbclient.dll`, SYSDBA/masterkey, charset `WIN1250`,
  `access_mode=READ`, `no_gc=True`. Pe TCP 3060 parola implicita **nu** merge.
- In `CONTURI` **soldurile stocate sunt 0**; balanta se obtine agregand `REGISTRU`. Cine citeste
  `CONTURI.DEB_PREC` scoate o balanta goala fara nicio eroare.
- Coloanele `_1` din export (S..AF) seamana cu cele principale. Potrivirea numelor de coloana se
  face **exact**, niciodata pe substring: `TOTAL_DEB` vs `TOTAL_DEB_1`.
- Numele foii difera intre surse (`balanta` / `xl` / `Sheet1`) - ia prima foaie, nu cauta dupa nume.
- `CONT` se citeste ca text. `401.00002` citit ca numar se strica.
- Heredoc-urile lungi in Bash au esuat pe fisierele mari de documentatie; scrie-le cu tool-ul de
  scriere de fisiere.
- `python` direct din Bash e stub Windows Store si nu scrie nimic (iese 0 si fisierul ramane
  neatins). Foloseste `py`, sau PowerShell.

## 8. Starea pe disc - nimic periculos, dar necomis

`git status` la predare (HEAD = `ceab089`, branch `main`):

```
M  .gitignore
D  balanta_FUNDATIA.csv
D  balanta_MASTERJOB.csv
 M docs/parteneri_cui_gasite.md
 M docs/plan_solduri2roa.md
D  export_balanta_fundatia_12_2025.xlsx
D  init_FUNDATIA_2025_12.xlsx
D  init_MASTER_2025_12.xlsx
 M sql/update_cod_fiscal_FUNDATIA.sql
 M sql/update_cod_fiscal_MASTER.sql
A  tests/anonimizeaza_etalon.py
A  tests/golden/golden_FUNDATIA_2025_12.xlsx
A  tests/golden/golden_MASTER_2025_12.xlsx
?? docs/handoff_etapa2_convertor.md
?? docs/plan_etapa2_convertor.md
?? docs/raport_exporturi_saga_noua.md
?? docs/raport_sursa_saga_xlsx.md
?? docs/review_ceo_etapa2.md
?? docs/review_eng_etapa2.md
?? exemple/
```

Verificari inainte de orice altceva:
- `init_FUNDATIA_2025_12.xlsx` si `init_MASTER_2025_12.xlsx` sunt pe disc dar nu mai sunt in git.
  Etalonul anonimizat e deja generat din ele si comis, deci poarta de regresie nu mai depinde de
  ele. Sunt necesare doar daca vrei sa **regenerezi** etalonul (`py testsnonimizeaza_etalon.py`).
- Nu se da commit fara ca Marius sa vada diff-ul (regula proiectului).
- Niciun proces ramas viu: serverul opencode de pe 4296 a fost oprit la predare. Il pornesti tu,
  cu comanda din sectiunea 6.
- `D:\ROA\ROACONT`, `D:\SAGA250909` si `saga2roa*` nu au fost modificate si nu se modifica.

## 9. Primul lucru de facut in sesiunea noua

1. Citeste planul v3.
2. Intreaba-l pe Marius daca pornesti (nu a dat inca "da" pe lansarea lane-urilor).
3. La "da": lanseaza **doar** lane-ul `contract`. Etalonul exista deja, deci lane-ul are de facut
   `config/conturi_parteneri.csv` + scriptul de divergenta Oracle, si de scris testul de regresie
   care compara iesirea codului de azi cu `tests/golden/`, pe valori de celula (nu pe hash: un
   xlsx rescris de alta versiune de openpyxl are alti octeti cu acelasi continut). Testul trebuie
   sa treaca **cu codul de conversie neschimbat**. Daca nu trece, e bug in test sau in etalon, nu
   in cod, si restul lane-urilor nu au voie sa porneasca.