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:

$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.