flora2roa/CLAUDE.md

# CLAUDE.md

Ghid pentru agenti (Claude Code / Jcode) care lucreaza in acest repo.

## Ce este

FLORA2ROA e o aplicatie Visual FoxPro 9 care importa facturile si vanzarile din **Fidelio**
(hotel, XML) si **BIZ** (restaurant, XML) si genereaza note contabile in **ROA** (Oracle).
Un singur formular, `frm_import.scx`, face tot fluxul: citeste XML-urile din interval,
completeaza nomenclatorul de parteneri, construieste notele si le scrie in ROA.

Radacina: `D:\PROIECTE\FLORA\FLORA2ROA`. Nu are folder `COMUN\` (doar `comun.h` local), deci
scripturile partajate ROA au echivalente locale in `Teste\`.

## Reguli de lucru: OBLIGATORIU inainte de orice modificare

**Citeste `D:\ROA\ROACONT\COMUN\docs\reguli_lucru.md`.** Nu e context optional, e contractul de
livrare. Ce se incalca cel mai usor daca nu-l citesti:

- **Nu se comite fara aprobare.** Livrezi diff ca FISIER (`docs\diff_runda<N>_<subiect>.patch`),
  iar write-back-ul in binar si commit-ul se fac dupa ce utilizatorul aproba. Patch-urile de
  review nu se comit niciodata (sunt in `.gitignore`).
- **Comentarii minime, fara jurnal.** O linie, descriind comportamentul CURENT. Interzis inline:
  istoricul modificarii ("inlocuieste...", "nu mai depinde de..."), nume de agent, referinte la
  runde/decizii. Istoricul sta doar in antetul fisierului, cumulativ, semnat de om.
- **Modificari minime**: doar ce s-a cerut, fara refactorizari din oficiu.
- Punctul 7 din acel fisier e un index de conventii per zona atinsa (encoding cp1252, UX
  formulare, `GO` pe `Recno()`, `goExecutor` + `ALTER TABLE`, testare UI, export Oracle).

## Documentatia proprie a proiectului

- `docs\depanare_testare_flora2roa.md` - harnessul de testare headless, ce contine `Teste\`,
  comenzile uzuale si capcanele confirmate aici. **De citit inainte de a rula sau scrie teste.**
- `docs\flux_git_flora2roa.md` - fluxul SVN + git: cine e sursa de adevar, cand se cere
  aprobarea, ce se comite si unde, `roa_sync.bat`. Adaptarea locala a lui
  `COMUN\docs\fluxul_svn_git.md`.

## Versionare

**SVN** e sursa de adevar, inclusiv pentru binarele VFP. **git** urmareste versiunile TEXT
(`.sc2`, `.pj2`) generate de FoxBin2Prg in arbore, plus `.prg`, `Teste\`, `docs\`. Binarele sunt
git-ignored, ca diff-urile sa fie lizibile. `roa_sync.bat` se ruleaza in exact doua momente:
la inceput de sesiune si imediat dupa `svn commit`.

`svn commit` (care atinge binarele) se face **doar cu acordul explicit al utilizatorului**.

## Editarea formularului

`frm_import.scx` se editeaza pe text, byte-safe in Windows-1252:

```powershell
powershell -ExecutionPolicy Bypass -File Teste\text_din_bin.ps1       # binar -> frm_import.sc2
# editezi frm_import.sc2 cu [IO.File]::ReadAllText/WriteAllText + GetEncoding(1252)
powershell -ExecutionPolicy Bypass -File Teste\bin_din_text.ps1 -TextFile frm_import.sc2
powershell -ExecutionPolicy Bypass -File Teste\recompileaza_binare.ps1
```

Ultimul pas nu e optional: write-back-ul reface `.scx/.sct` fara cod obiect, deci formularul
ruleaza fara `#INCLUDE "comun.h"` si constantele (`CT_SUCCES`) crapa in RUNTIME, desi
verificarea de sintaxa trece.

## Testare

Nu exista IDE in flux. Totul headless, din PowerShell:

```powershell
powershell -ExecutionPolicy Bypass -File Teste\ruleaza_teste.ps1        # suita + sinteza
powershell -ExecutionPolicy Bypass -File Teste\verifica_sintaxa.ps1     # dupa orice editare .prg
```

Un `.fxp` vechi ascunde modificarile din `.prg`: daca un test da acelasi rezultat dupa o
corectie evidenta, sterge `.fxp`-ul si reia.

## Cod

- Punct de intrare `main.prg`; `myutils.prg` = biblioteca de functii utilitare; `capp/app/myapp.prg`
  = obiectele globale (`goApp`, `goConn`, `goExecutor`, `goLog`).
- Constantele din `comun.h` (`CT_SUCCES = 1`, `CT_INSUCCES`) sunt conventia de retur.
- Cod si mesaje in **romana, fara diacritice** (fisierele sunt cp1252).
- Functiile utilitare partajate se copiaza din `D:\ROA\ROACONT\COMUN\programe\oproceduri_comune.prg`,
  nu se rescriu.

## Reguli de domeniu (contabil) de stiut

- In ROA, `RO12345678` (platitor de TVA) si `12345678` sunt **doi parteneri diferiti**: prefixul
  `RO` se pastreaza exact cum vine din import si nu se adauga niciodata automat.
- La D394/D406 o **persoana fizica** poate fi raportata fara CNP, deci un CNP invalid se goleste.
  O **persoana juridica** trebuie sa aiba cod fiscal: codul ei nu se sterge niciodata, ca eroarea
  sa fie semnalata la validarea declaratiei si corectata la sursa, in Fidelio.
- Algoritmul romanesc de validare (CNP/CUI) nu se aplica partenerilor straini; codurile lor pot fi
  si numai din cifre, de orice lungime.

## Changelog

`changelog_flora2roa.txt`, blocuri de comentariu HTML, cel mai nou primul:

```
<!--
DD/MM/YYYY
FLORA2ROA - X.Y.Z

:modificare:
  Ce vede utilizatorul.
-->
```

Taguri: `:nou:`, `:modificare:`, `:eroare:`. Text **pentru utilizator**, scurt, netehnic, o fraza
per idee. Erorile introduse si reparate in aceeasi versiune nelivrata nu se trec: `:eroare:` e
doar pentru ce a fost in productie. La bump de versiune se actualizeaza si `flora2roa.txt`
(fisierul pe care `update.bat` il compara cu cel de pe server).

## Stil de raspuns

Scurt si concret. Ce e gata (fisier:linie), ce urmeaza, ce trebuie decis. Fara naratiunea
drumului pana la rezultat, fara reluari, fara justificari necerute. Detaliile lungi (dovezi,
iesiri de test) se scriu in fisier si se trimite link.