roafacturare/CLAUDE.md

# CLAUDE.md

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

## What this is

ROAFACTURARE is a Visual FoxPro 9 desktop invoicing application, one product in the ROA
business-software suite built by ROA Romfast SRL. Thick client: VFP source (`.prg`, `.scx`,
`.vcx`, `.mnx`, `.frx`) compiled to `roafacturare.exe`, talking to an Oracle backend. No web
front-end, no package-manager-based build.

This directory (`D:\ROA\ROAFACTURARE`) is one working copy inside the larger `D:\ROA` tree that
holds the sibling ROA products (ROACONT, ROAGEST, ROAIMOB, ROAACNPRO, ...) plus the suite-wide
shared library `D:\ROA\COMUNROA`.

## Version control

Primarily an **SVN** working copy (`^/ROAFACTURARE/Trunk`, repository root
`http://svnroa:3001/svn/ROA`) — use `svn status`, `svn diff`, `svn commit` for the day-to-day
legacy workflow. A **git** mirror runs in parallel (`gitea.romfast.ro:romfast/roafacturare.git`),
synced manually from SVN; SVN stays the source of truth.

Git tracks the **FoxBin2Prg text versions** of the VFP binaries (`.vc2/.sc2/.fr2/.mn2/.lb2/.pj2`),
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\ROAFACTURARE
```

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/.lbx/.pjx/.dbc/.dbf` are editable
only in the VFP IDE. See `D:\ROA\UTIL\foxbin2prg\CLAUDE.md` and
`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\ROAFACTURARE', '-ProjectRoot', 'D:\ROA\ROAFACTURARE', '-IndexFile', 'D:\ROA\_vfp_textcache\roafacturare\_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`.

`COMUN/` is excluded from this repo's git — it is 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.

## Building / running

No CLI build tool. Compiled from inside the VFP 9 IDE: open `roafacturare.PJX`, then
Project > Build / Rebuild. Entry point is `Programe/roafacturare.prg` (`PARAMETERS tparam` — a
connection string passed by the ROA "Start" launcher); it sets the VFP environment
(`SET PATH`, `SET CLASSLIB`, `SET PROCEDURE ... ADDITIVE`), so new shared `.prg`/`.vcx` files must
be registered there to be reachable app-wide. Always edit the source file, never its compiled
sibling (`.FXP`/`.SCT`/`.VCT`/`.MPR`). No automated tests.

## Directory layout

`Programe/` top-level business-logic modules · `Clase/` `.vcx` class libraries · `Ferestre/` and
`Formulare/` `.scx` forms · `Meniuri/` menus · `Rapoarte/` `.frx` reports · `Locale/` DBF-based
i18n · `COMUN/` this project's copy of the shared assets (clase, ferestre, programe, rapoarte,
utile) · `Utile/`, `Include/`, `Grafice/`, `Ajutor/`, `Mesaje/` support assets.
`versiune_db.txt` is a manually bumped `YYYY_MM_DD_NN` marker for the last applied DB migration.

## Changelog convention

`changelog_roafacturare.txt` is a flat file of HTML-comment blocks, newest first:

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

:modificare:
  <what changed>
-->
```

Tags: `:nou:` (new feature), `:modificare:` (change), `:eroare:` (bug fix), `:adaugare:`
(addition). Bump `MAJOR.MINOR.PATCH` per entry (current series `2.11.x`).

## Comments

Change history goes in the **file header only**, never inline — one cumulative entry per feature
(`*!* DD.MM.YYYY` / `*!* author` / `*!* what it does, 1-2 sentences`), rewritten rather than appended
on revisit. Same in `.prg`, in `.sql` migration scripts and in PL/SQL.

In-code comments are short and strictly functional, and only where they earn their place: a branch
or a filter that isn't self-evident. One line as a rule. No references to plans, stories, decisions,
bug reports or `docs/` reports, no justification of the choice made, no history of the change, no
dates or authors on new code. Full rule and the list of prohibitions:
`COMUN\docs\reguli_lucru.md`, point 2.

## Localization

Romanian is the built-in default. Keep new user-facing strings and code comments in Romanian to
match the existing codebase unless told otherwise.

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

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

- **Predarea contextului e OBLIGATORIE, si pentru sesiunea principala, si pentru subagenti.**
  Nu e o optimizare, e o conditie de corectitudine. Declansatoare: **~50% din fereastra**
  (sesiunea principala / orchestrator), **~200-250k tokens** (subagent), anuntul de compactare
  automata al harness-ului, semnalul utilizatorului, sau **terminarea unui bloc de lucru**.
  La oricare dintre ele, in ordine: **opreste lucrul** (adu editarile in curs la o stare
  consistenta pe disc, nu incepe nimic nou) -> **scrie handoff-ul PE DISC**
  (`docs\handoff_<subiect>.md`, nu doar in mesaj) -> **confirma in doua randuri** ce ramane si ce e
  intr-o stare periculoasa (fisier editat fara write-back, tranzactie deschisa, proces viu, date de
  test consumate) -> **opreste-te**; blocul urmator il ia un agent proaspat. *"Mai am putin"* nu e
  motiv de amanare — exact acolo se pierd lucrurile. Un subagent care se apropie de prag **anunta
  singur**, nu asteapta sa fie oprit. Procedura completa si ce intra in handoff:
  `COMUN\docs\orchestrare-subagenti.md`, sectiunea **Regula zero**.
- **Orchestrare pe misiuni lungi**: niciodata un singur subagent care acumuleaza context pe multe
  sarcini inlantuite — sesiunea principala orchestreaza subagenti proaspeti per sarcina, cu handoff
  compact pe disc.
- **Delegare**: modificarile de cod 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 — diff-ul se livreaza intai ca fisier in `docs/`, iar commit-ul vine dupa aprobare.