roacontracte/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

ROACONTRACTE is a Visual FoxPro 9 desktop application (Romanian-language) for **contracte** —
client/supplier contracts with rate (scadentar), facturare din contract, incasari, garantii si
alerte. Thick client: VFP source (`.prg`, `.scx`, `.vcx`, `.mnx`, `.frx`) compiled to
`roacontracte.exe`, on an Oracle backend reached through the shared `goExecutor`/`goConn`
pass-through objects (`gcS` = schema, primita in parametrul de lansare).

It is one product in the ROA suite built by ROA Romfast SRL; this directory
(`D:\ROA\ROACONTRACTE`) is one working copy inside the `D:\ROA` tree that holds the siblings
(ROACONT, ROAGEST, ROAIMOB, ROAFACTURARE, ...) plus the suite-wide shared library
`D:\ROA\COMUNROA`.

Cod, comentarii, meniuri si changelog sunt in romana — pastreaza limba la editari.

## Version control

Primarily an **SVN** working copy (`^/ROACONTRACTE/Trunk`, repository root
`http://svnroa:3001/svn/ROA`) — `svn status`, `svn diff`, `svn commit` raman fluxul legacy.
`COMUN\` e external SVN (`^/COMUN/Trunk`). A **git** mirror runs in parallel
(`gitea.romfast.ro:romfast/roacontracte.git`), synced from SVN; SVN stays the source of truth.

Git tracks the **FoxBin2Prg text versions** of the VFP binaries (`.vc2/.sc2/.fr2/.mn2/.pj2/.db2`),
generated in-tree next to each binary — not the binaries themselves. Refresh them with
`git_sync.ps1` at the start of every session and before any `git commit`:

```
powershell -ExecutionPolicy Bypass -File D:\ROA\UTIL\foxbin2prg\git_sync.ps1 -ProjectRoot D:\ROA\ROACONTRACTE
```

Sau, mai simplu, `roa_sync.bat` din radacina proiectului: face svn update -> git_sync -> commit
`sync SVN rN` pe `main` (proiect + COMUN) -> push.

`git_sync` converteste intr-un staging temp si copiaza inapoi doar textul (binarele din working
copy-ul SVN nu sunt atinse niciodata), continua peste esecurile per fisier si iese cu cod nenul
daca a esuat ceva: **nu comite cat timp `git_sync` raporteaza esecuri neexplicate.**

Then search the `.??2` files in-tree with Grep, citing `file:line`. Write-back text->binary via
`txt2vcx.ps1` is supported **only for `.vc2`/`.sc2`**; `.frx/.mnx/.pjx/.dbf` are editable only in
the VFP IDE. See `D:\ROA\UTIL\foxbin2prg\CLAUDE.md` si `COMUN\docs\flux-editare-vfp-text.md`.

Grep can't tell **which class/method** a hit inside a `.vc2` belongs to (the class header may be
thousands of lines above it, and ~2/3 of the file is properties/metadata). `vfp_symbols.ps1`
indexes the line range of every class/method/procedure and labels hits with their owner — use it
before any `txt2vcx.ps1` edit to get the exact line range of the method you are changing. Its
built-in defaults target ROAACNPRO, so always pass this project's paths:

```powershell
$s = 'D:\ROA\UTIL\foxbin2prg\vfp_symbols.ps1'
$c = @('-CacheRoot', 'D:\ROA\ROACONTRACTE', '-ProjectRoot', 'D:\ROA\ROACONTRACTE', '-IndexFile', 'D:\ROA\_vfp_textcache\roacontracte\_symbols.tsv')

powershell -ExecutionPolicy Bypass -File $s @c -Grep '<expresie>' -CodeOnly   # hits labeled class.method, code only
powershell -ExecutionPolicy Bypass -File $s @c -Where '<fisier>.vc2:<linie>'  # who owns this line
powershell -ExecutionPolicy Bypass -File $s @c -Find '<nume>'                 # where it is DEFINED
powershell -ExecutionPolicy Bypass -File $s @c -Class '<nume_clasa>'          # inheritance chain + methods
```

The index (`_symbols.tsv`) rebuilds itself when the text is newer, so refresh the text first — it
can't see IDE edits that were never converted. Full search guide: `COMUN\docs\cautare_vcx_vct.md`.

Curatare orfani: la fiecare rulare completa `git_sync` sterge textul `.??2` al carui binar a
disparut din SVN si raporteaza restul (ex. stub-uri de test doar-git, fara binar) fara sa le stearga.

SVN ignora fisierele `.??2` prin `global-ignores` din configul local
(`%APPDATA%\Subversion\config`, `[miscellany]`), impreuna cu `*.dbf.cfg`. Limitare: global-ignores
acopera doar fisierele *neversionate* — daca un `.??2` ajunge `svn add`-ed, scoate-l cu
`svn rm --keep-local`.

O modificare facuta doar in text si comisa in git, fara write-back in binar si fara `svn commit`,
se pierde la urmatorul `git_sync` (textul se regenereaza din binar). Ordinea corecta:
text -> `txt2vcx.ps1` -> `svn commit` -> sync git.

`COMUN/` is excluded from this repo's git — shared by every ROA product and versioned by its
**own git repo**, `gitea.romfast.ro:romfast/comun.git`. Run git commands for `COMUN/` from inside
that directory, and treat any change there as cross-project (fara `push --force`).

### Branching (git)

Doua benzi in oglinda git: **`main`** primeste DOAR commit-uri `sync SVN rN`, facute din stare
curata (imediat dupa `svn update`, inainte de lucru local); **Claude lucreaza pe branch**
`claude/<subiect>` si comite doar acolo, ca `git diff main..claude/<subiect>` sa arate exact si
numai munca lui. Branch-ul se inchide dupa ce modificarile intra in SVN (`svn commit` facut de
utilizator). Model complet: `COMUN\docs\fluxul_svn_git.md`.

## Building / running

No CLI build. Compiled from the VFP 9 IDE: open `roaContracte.pjx`, then Project > Build.
Entry point is `Programe/roacontracte.prg` (`PARAMETERS tparam` — sir cu `;` trimis de launcher-ul
ROA Start: host, user, parola, idutil, idprogram, ..., an, luna, schema, idfirma; altfel intra pe
valorile de dezvoltare din cod).

`roacontracte.exe` refuza sa porneasca daca numele fisierului nu incepe cu `ROACONTRACTE`.
Startup-ul e procedural (nu `RoaApp`): `SET PATH` peste folderele proprii + `COMUN\*` + `..\COMUNROA\`,
zeci de `SET CLASSLIB/PROCEDURE ... ADDITIVE` (ordinea conteaza — inregistrarile ulterioare umbresc),
apoi `goApp = CREATEOBJECT("wzApplication")` (AppWizard, `COMUN\clase\appwiz.vcx`) cu
`goApp.cStartupMenu = meniuri\roacontracte.mpr` si `goApp.cStartupForm = COMUN\ferestre\frm_login.scx`.
Fisiere `.prg`/`.vcx` noi comune trebuie inregistrate acolo ca sa fie vizibile in aplicatie.
`config.fpw` da mediul de rulare; `versiune_db.txt` (`YYYY_MM_DD_NN`) e marcajul ultimei migrari DB.
Editeaza intotdeauna sursa, nu compilatul (`.FXP`/`.SCT`/`.VCT`/`.MPR`).

## Directory layout

`Programe/` logica de business proprie (`oproceduri_roacontracte.prg`, `oproceduri_roaclienti.prg`,
`oparteneri_contracte.prg`, `oproceduri_registretva.prg`, `oproceduri_preluari.prg`, `pmenu.prg`,
`refverif.prg`, `verifica.prg`) · `Clase/` `.vcx` proprii (`ferestre_contracte.vcx`,
`onom_clienti.vcx`, `roaclienti.vcx`, `ofundal*.vcx`, `outlook2003bar.vcx`) · `Ferestre/` formulare
(`frm_dg_*.scx` = paginile din datele generale ale contractului, `fundal.scx`, `startfirma.scx`) ·
`Meniuri/` (`roacontracte.mnx` = meniul de start, `rapIncasari.mnx`) · `Rapoarte/` `.frx`
(`rcontracte`, `rcontracte_centralizator`, `rRate`, `rrate_facturi`, `rRate_facturi_extins`,
`rincasari`, `rap_facturat_incasat`, `rctrrestdefact`, `ratedefacturat`, `ralerte`,
`fisa_contractului`) · `Grafice/`, `datemenu/`, `Locale/`, `Teste/` · `COMUN/` biblioteca partajata.

Ca la ROAGEST, o buna parte din logica efectiva vine din `COMUN\programe\` si `COMUN\clase\`
rezolvate prin `SET PATH` (login, nomenclatoare, parteneri, eFactura ANAF, listari, oracle).

## Domain quick reference

Obiecte Oracle uzuale (vezi `Programe/oproceduri_roacontracte.prg`): `vcontracte`,
`vcontracte_toate`, `vtipuri_contracte`, `vctr_scadentar` (ratele contractului),
`vctr_rate_facturi` (legatura rata-factura), `vctr_articole`, `vctr_selectii`,
`ctr_facturi_garantii`, `vireg_parteneri`/`ireg_parteneri`, `vnom_valute`, `vnom_sectii`,
`vatas_referinte` (atasamente), `vcrm_politici_preturi`, `vcrm_note_vanzari`.

TVA e sensibil la perioada documentului (19/9/5% inainte de 01.08.2025, 21/11% dupa) — foloseste
cota din perioada documentului, nu "cota curenta".

## Changelog convention

`changelog_roacontracte.txt`, blocuri de comentariu HTML, cea mai noua intrare **prima**:

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

:modificare:
  <ce s-a schimbat>
-->
```

Tag-uri: `:nou:` (functie noua), `:modificare:` (schimbare de comportament), `:eroare:`
(corectie), `:adaugare:`. Se bumpeaza `MAJOR.MINOR.PATCH` (seria curenta `2.3.x`).

Regula de continut: changelog-ul e pentru utilizatori — se scrie **doar ce vede utilizatorul**,
scurt si compact. O singura intrare consolidata per livrare (versiunea o da Marius), fara pasi
intermediari, runde sau mecanisme interne; erorile introduse si reparate in aceeasi versiune
nelivrata **nu se trec** (clientul nu le-a vazut) — intrarea versiunii curente se rescrie, nu se
acumuleaza.

Comentariile de modificare in cod urmeaza conventia `*!* DD.MM.YYYY` + autor + descriere scurta,
direct deasupra codului schimbat.

## Reguli de lucru si testare

**Inainte de orice modificare de cod sau testare, citeste `COMUN\docs\reguli_lucru.md`.**
Nu e optional si nu e doar context: contine regulile de livrare (diff ca fisier + aprobare
inainte de write-back), comentariile (max o linie), modificarile minime, harnessul de testare
headless si — la punctul 7 — lista de conventii obligatorii per zona atinsa (encoding cp1252 la
editarea `.vc2`/`.sc2`, UX formulare/griduri, `GO` pe `Recno()`, `goExecutor` + `ALTER TABLE`,
testare UI, export Oracle). Fisierul e index: urmeaza linkurile relevante pentru sarcina curenta.
Depanare detaliata: `COMUN\docs\depanare_testare_vfp.md`.

Foloseste **PowerShell**, nu Bash (bash.exe crapa pe aceste masini si lasa stackdump-uri).

## Mod de lucru: delegare catre subagenti + review inainte de commit

- **Orchestrare pe misiuni lungi**: niciodata un singur subagent care acumuleaza context pe multe
  sarcini inlantuite — sesiunea principala orchestreaza subagenti proaspeti per sarcina (max
  ~200-250k tokens per subagent, apoi handoff + agent nou), cu handoff compact pe disc:
  `COMUN\docs\orchestrare-subagenti.md`.
- **Delegare**: modificarile de volum/rutina (aplicarea unei propuneri aprobate din `docs/`,
  editari pe versiunile text `.??2` + write-back, actualizari de documentatie, rulari de teste) se
  delega catre **subagenti Sonnet care lucreaza in background** (Agent tool cu `model: sonnet`),
  iar sesiunea principala doar orchestreaza si verifica rezultatele.
- **Fara commit fara review**: nu da commit (git sau svn) din proprie initiativa pe modificari de
  cod — Marius vrea intai sa **vada diff-ul**, ca fisier in `docs/`. Pentru binarele VFP
  (`.vcx`/`.scx`) diff-ul lizibil se face pe forma text `.vc2`/`.sc2` regenerata cu
  `git_sync.ps1`, inainte de write-back cu `txt2vcx.ps1`.
- **Curatenie inainte de commit**: `powershell -File COMUN\utile\curatenie.ps1` (`-DryRun` doar
  listeaza) sterge patch-urile de review, handoff-urile/planurile de runda, backup-urile
  `*.pre_runda*.bak` si artefactele de test. Faptul ca sunt in `.gitignore` nu le scuteste.

## Stil de raspuns: scurt si concret

Marius vrea raspunsuri **clare, concise, fara vorbarie**. Regula, nu preferinta.

- **Starea si ce urmeaza, nu povestea.** Ce e gata, ce e stricat, ce trebuie decis, ce urmeaza —
  in liste scurte, cu fisier si linie. Fara reconstituirea drumului pana la rezultat.
- **Fara naratiune de proces**: ce a raportat fiecare agent, cine ce a corectat, cum au fost
  coordonate benzile. Intra in `docs/`, nu in raspuns.
- **Fara laude si fara reluari.** Nu repeta ce s-a spus deja in conversatie.
- Detaliile tehnice lungi (dovezi, iesiri de test, metodologie) se scriu in fisier si se
  **trimite la el**, nu se copiaza in raspuns.

**Formatul obligatoriu al raspunsului**, in aceasta ordine, maxim cateva randuri fiecare:

1. **Am facut:** ce e gata (fisier:linie).
2. **Urmeaza:** ce fac mai departe.
3. **De la tine:** intrebarea, clar si simpla, cu recomandarea mea.

## Skill routing

When the user's request matches an available skill, invoke it via the Skill tool. When in doubt,
invoke the skill.

- Product ideas/brainstorming -> /office-hours · Strategy/scope -> /plan-ceo-review
- Architecture -> /plan-eng-review · Full review pipeline -> /autoplan
- Bugs/errors -> /investigate · Code review/diff check -> /review
- Ship/deploy/PR -> /ship or /land-and-deploy
- Save progress -> /context-save · Resume context -> /context-restore

## Project insights (docs/)

`docs/` tine notite scurte si concrete descoperite in timpul lucrului (fluxuri ascunse, capcane,
proceduri/tabele cheie) — vezi `docs/README.md`. Ofera-te proactiv sa actualizezi `docs/` cand
descoperi ceva neevident, ca sesiunile viitoare sa nu reinvestigheze.