# Sablon `.vc2` gol — pornire pentru o biblioteca de clase noua

`sablon_vcx_gol.vc2` e punctul de plecare cand trebuie creata o biblioteca `.vcx` noua in
proiect. Exista pentru ca `txt2vcx.ps1` **refuza permanent** sa creeze un binar `.vcx`
inexistent (`txt2vcx.ps1:203-206`, garda nu verifica provenienta binarului, doar existenta lui) —
deci fluxul text->binar nu poate produce singur un `.vcx` nou de la zero. Solutia e sa pornesti
de la un binar-purtator **copiat**, peste care aplici acest text.

Continut: antetul FoxBin2Prg (6 linii, obligatoriu identic) + **o singura clasa-exemplu
minimala** (`AS custom`, fara obiecte-copil). Am ales varianta cu o clasa, nu biblioteca goala
de-a dreptul, pentru ca n-am gasit nicaieri in proiect un `.vcx` cu 0 clase de folosit ca
referinta si n-am vrut sa presupun formatul text al unei biblioteci goale fara sa-l vad — o clasa
`custom` fara copii insa exista deja ca tipar verificat (`COMUN\clase\_baza.vc2:114-121`, clasa
`_custom`) si a fost **confirmata printr-un test complet text->binar->text in izolare** (vezi mai
jos), deci e alegerea provata, nu doar plauzibila.

## Procedura, pas cu pas

### 1. Alege binarul-purtator

Trebuie sa fie o pereche `.vcx` + `.vct` **existenta** (ambele — `.vct` e memo-ul cu proprietatile
lungi/codul; fara el binarul nu se deschide). Nu presupune care e cea mai mica — verifica:

```
ls -la Clase/*.vcx Clase/*.vct
```

Alege perechea cu cel mai mic `.vcx`. Nu conteaza ce clase contine acum — le stergi la pasul 3.

### 2. Copiaza si redenumeste

```
cp Clase/<sursa>.vcx Clase/<nume_nou>.vcx
cp Clase/<sursa>.vct Clase/<nume_nou>.vct
```

Ambele comenzi, nu doar `.vcx` — un `.vcx` fara `.vct` pereche e un binar corupt pentru VFP.

### 3. Aplica sablonul si inlocuieste

```
cp docs/sabloane/sablon_vcx_gol.vc2 Clase/<nume_nou>.vc2
```

In fisierul copiat, inlocuieste **toate** aparitiile:

- `SourceFile="__NUME_BIBLIOTECA__.vcx"` -> `SourceFile="<nume_nou>.vcx"` (trebuie sa fie
  exact numele fisierului `.vcx` de la pasul 2, cu tot cu extensie).
- `DEFINE CLASS __NumeClasaExemplu__ AS custom` -> numele si clasa-parinte reala dorita. Poti
  schimba si baseclass-ul (`AS custom` -> ex. `AS _frmbase OF "_frm_base.vcx"` pentru un formular)
  si adauga `ADD OBJECT` / metode dupa nevoie — respecta constrangerile de mai jos.
- `Name = "__NumeClasaExemplu__"` (in blocul `*<PropValue>`) -> **acelasi** nume ca la
  `DEFINE CLASS`, cele doua trebuie sa coincida.

Spre deosebire de fluxul folosit la crearea lui `Clase\ofacturare_util.vcx`
(`docs\nota_s8b_vcx_util.md`), care a luat antetul dintr-o conversie reala ca sa nu-l inventeze,
**antetul acestui sablon e deja verificat printr-un test text->binar->text complet** (mai jos) —
nu mai trebuie reconfirmat printr-o conversie separata inainte de folosire, doar `SourceFile`
trebuie sa corespunda numelui ales la pasul 2.

### 4. Write-back

```
powershell -ExecutionPolicy Bypass -File D:\ROA\UTIL\foxbin2prg\txt2vcx.ps1 `
  -TextFile 'D:\ROA\ROAFACTURARE\Clase\<nume_nou>.vc2' `
  -ProjectRoot D:\ROA\ROAFACTURARE -CacheRoot D:\ROA\ROAFACTURARE
```

Fara `-Force`, fara `-NoVerify` (fidelity check-ul trebuie sa treaca real). Adauga
`-AllowComun` **doar** daca `<nume_nou>.vcx` ajunge sub `COMUN\`.

### 5. Dovada de sincronizare — pe continut, nu pe mtime

`txt2vcx.ps1` rescrie mtime-ul textului la refresh de cache, deci mtime-ul egal nu dovedeste
nimic. Reconverteste binarul proaspat scris intr-un cache **izolat** (diferit de `ProjectRoot`,
altfel `vcx2txt.ps1` isi poate sterge singur binarul sursa — vezi capcana documentata in
`docs\nota_s8b_vcx_util.md`, sectiunea "Conversie text") si compara pe octeti:

```
powershell -ExecutionPolicy Bypass -File D:\ROA\UTIL\foxbin2prg\vcx2txt.ps1 `
  -Source 'D:\ROA\ROAFACTURARE\Clase\<nume_nou>.vcx' `
  -ProjectRoot D:\ROA\ROAFACTURARE -CacheRoot '<cale_temporara_izolata>'

diff Clase/<nume_nou>.vc2 <cale_temporara_izolata>/Clase/<nume_nou>.vc2
```

Zero diferente = dovada reala. Orice diferenta inseamna ca binarul din proiect nu reflecta
textul din arbore.

### 6. Verificari de integritate

```
grep -c 'ADD OBJECT' Clase/<nume_nou>.vc2
grep -c 'OBJECTDATA:' Clase/<nume_nou>.vc2
```

Trebuie sa fie **egale**. Pentru CRLF si diacritice, vezi `COMUN\docs\flux-editare-vfp-text.md`
si memoria de proiect despre editarea `.vc2` in cp1250 (`Edit`/`sed -i` corup octetii non-ASCII —
scrie orice modificare text cu un script Python pe disc, `latin-1`/`cp1250` passthrough, CRLF
explicit, niciodata `sed -i` sau `python -c`).

### 7. `.pjx` ramane manual

`.pjx` nu e editabil din text (cf. `CLAUDE.md` proiect). `Clase\<nume_nou>.vcx` trebuie adaugat
manual in `roafacturare.pjx` (Project Manager > Classes > Add) — dar **doar** cand ai nevoie de
Build/Rebuild pentru EXE. Nu e necesar pentru o proba cu `vfp9.exe` + `DO roafacturare.prg`, unde
`SET CLASSLIB` (pasul 8) rezolva clasa prin `SET PATH`.

### 8. Inregistrare in `roafacturare.prg`

Biblioteca trebuie inregistrata ca sa fie vazuta de aplicatie. Exemplu deja existent in fisier,
langa care se adauga o linie similara pentru biblioteca noua (`Programe\roafacturare.prg:137-139`):

```
SET CLASSLIB TO ocriterii.vcx ADDITIVE
SET CLASSLIB TO ofacturare_util.vcx ADDITIVE
Set Classlib To ctl32_statusbar.vcx Additive
```

`Clase\` e deja pe `SET PATH` (`Programe\roafacturare.prg:89`), deci fara cale completa. Aceasta
editare **nu e facuta automat de acest sablon** — se face separat, cu aprobare, cand biblioteca
noua chiar trebuie incarcata de aplicatie.

## Constrangeri FoxBin2Prg de retinut (au picat fidelity check-ul in trecut)

- `ADD OBJECT` la nivelul unei clase sunt ordonate **ASCII/colationat case-insensitive** pe
  `ObjPath` (ex. `Cw10` intre `Cw1` si `Cw2`), inclusiv obiectele de top-nivel.
- Proprietatile in interiorul unui bloc `ADD OBJECT` / `*<PropValue>` sunt in **ordine
  alfabetica**.
- **Ultima proprietate dintr-un bloc nu are `, ;`** la final (vezi ultima linie din blocul
  `ADD OBJECT` din sablon — n-are virgula).
- Numarul de `ADD OBJECT` == numarul de `*< OBJECTDATA:` (0 = 0 in sablonul de baza).
- Liniile goale din corpul unui `PROCEDURE`/inainte de un `PROCEDURE` la nivel de clasa se
  indenteaza cu un TAB; liniile goale **dintre blocuri `ADD OBJECT` consecutive** raman
  neindentate (verificat direct pe text regenerat, `docs\nota_s8b_vcx_util.md` punctul 3).
- Encoding **cp1250** pentru diacritice, CRLF (`\r\n`) pe fiecare linie, inclusiv ultima
  (`ENDDEFINE\r\n`, fara linie goala dupa la finalul fisierului).

## Ce s-a probat si cum

Test complet text -> binar -> text, **izolat in scratchpad**, fara sa atinga arborele
`D:\ROA\ROAFACTURARE`: copiat un binar-purtator existent intr-un proiect-fals in scratchpad,
aplicat sablonul (cu `SourceFile`/nume de clasa concrete), rulat `txt2vcx.ps1` cu
`-ProjectRoot`/`-CacheRoot` catre acel proiect-fals — **fidelity check trecut din prima
incercare** (spre deosebire de `frm_cursuri_valutare`, care a avut nevoie de 3 corectii). Apoi
reconvertit binarul proaspat cu `vcx2txt.ps1` intr-un cache izolat separat si comparat cu
`diff` — **zero diferente**. Detalii complete si comenzile exacte: `docs\nota_s8b_sablon_vc2.md`.

**Neprobat**: adaugarea in `.pjx` si deschiderea reala in designer/rulare (pasii 7-8 raman
descrisi, nu executati — n-ar fi trebuit sa atinga arborele real fara aprobare).