rar-autopass/docs/CONTEXT.md

Context proiect — Gateway RAR AutoPass (migrare ROAAUTO din VFP în Web API)

Fișier de continuitate între sesiuni. Citește-l înainte de a relua lucrul. Ultima actualizare: 2026-06-14.

Reluare pe alt calculator (portabil)

Tot ce ai nevoie pentru a continua e în acest repo (acest fișier + docs/plans/).

git clone git@gitea.romfast.ro:romfast/rar-autopass.git

Remote-ul Gitea (org romfast) merge prin SSH: git@gitea.romfast.ro:romfast/<repo>.git. Push-to-create e activ (un git push -u origin main creează repo-ul automat). După clonare: copiază settings.xml.example → settings.xml și completează credențialele (NU se comite). Apoi citește mai jos.

Ce este acest repo

Arhiva bazei Visual FoxPro existente (clasa RarAutoPass, ROAAUTO) care declară prestațiile de service la RAR AUTOPASS (Legea 142/2023, OM 210/2024), plus planurile pentru rescrierea ca Web API central (Python / FastAPI).

Codul VFP de aici este punctul de plecare / sursa de adevăr de contract pentru versiunea web. Nu se mai dezvoltă; se portează.

Stare actuală (iunie 2026)

• Integrarea VFP funcționează și e testată pe endpoint-ul de test RAR, dar nu e pusă la clienți încă.
• Comunică direct cu RAR prin MSXML2.ServerXMLHTTP din rar_autopass.prg / rar-forms.prg.
• Maparea operație→codPrestatie în mapare_prestatii.DBF; nomenclator în prestatii_rar.DBF; jurnal în rar_log.DBF; credențiale (în clar) în settings.xml.
• ⚠️ settings.xml conținea o parolă de test reală (marius.mutu@romfast.ro). E exclus din git (.gitignore) și înlocuit cu settings.xml.example. De rotit parola — a fost expusă în istoricul SVN vechi.

Fișiere-cheie (VFP) și ce reutilizăm

Fișier	Rol	Se portează în
rar_autopass.prg	clasa RarAutoPass: login+JWT, nomenclator, postPrezentare, cancel	app/rar_client.py
rar-forms.prg	UI + timer auto-process (OnAutoProcessTimer)	logica → worker; timer → re-push ROAAUTO
export_comenzi.prg	citește comenzi/operații, construiește payload	client subțire: POST /v1/prezentari
rar_advanced.prg	export Excel (oglindă pentru treapta 2)	referință import xlsx/csv
mapare_prestatii.DBF	cod_op_service → codPrestatie	operations_mapping (via tools/import_dbf.py)
prestatii_rar.DBF	nomenclator {codPrestatie, numePrestatie}	nomenclator_rar (via tools/import_dbf.py)
Documentatie Serviciu AutoPass_Final.txt, Document informativ RAR- Autopass.txt	spec oficial RAR	contract API

Planurile (în docs/plans/)

1. plan-design-review.md — designul produsului/arhitecturii (output /office-hours). Problemă ISV, topologie gateway central pass-through credențiale, zero stocare parole, privacy-first, teză SaaS pe trepte.
2. plan-eng-review.md — planul de implementare (review CEO, SELECTIVE EXPANSION peste design). Decizii blocate, constatări din spec, mașina de stări submission, securitate, verificare E2E.

Continuă cu plan-eng-review și plan-design-review — acestea sunt cele două documente de reluat în următoarea sesiune.

Arhitectura țintă (rezumat)

ROAAUTO (VFP, client subțire) ──HTTPS──▶ Gateway FastAPI (central, 1 container)
   trimite comanda + creds RAR             API: validare → mapare op→cod → enqueue (PII criptat)
   ◀── {submissionId, status} ─────────────┘
                         WORKER (proces separat): claim atomic → login RAR → postPrezentare → retry
   Dashboard (Jinja2+HTMX): monitorizare live din RAR + stare coadă + editor mapări
   ROAAUTO (timer) ──▶ GET /v1/prezentari?status=error → re-push (durabilitate pene lungi)

Stack: Python/FastAPI + SQLite (WAL) + httpx. Deploy: LXC Proxmox + Cloudflare Tunnel (start) → VPS (~5€/lună). Open-source pe github.com/romfast, AGPL-3.0 (⚠️ decide CLA din ziua 1 dacă vrei dual-license).

⚠️ Următorul pas BLOCANT — „The Assignment" (spike, ~1h, ÎNAINTE de cod)

Pe endpoint-ul de test RAR, măsoară:

1. Durata de viață a JWT-ului (/public/login → postPrezentare la intervale crescătoare până la 401) → dimensionează fereastra de retry autonom din worker.
2. Dacă postPrezentare trece fără b64Image (poză odometru) și fără odometruInitial → decide dacă poza e obligatorie în prod și dacă ROAAUTO trebuie s-o atașeze.
3. Valorile acceptate pentru tipPrestatie / sistemReparat (enum nedocumentat).

Rezultatul decide robustețea cozii și scopul real al ROAAUTO. Nu porni worker-ul înainte.

De făcut după spike (din plan-eng-review, secțiunea Verificare)

1. tools/import_dbf.py --dry-run pe mapare_prestatii.DBF + prestatii_rar.DBF (raport întâi, apoi import).
2. Schelet repo: app/api/v1, app/rar_client.py, app/worker, app/web, SQLite (WAL), docker compose up, /healthz verde.
3. POST /v1/prezentari cu o comandă reală (test) → worker trimite → FINALIZATA la RAR + în dashboard.
4. Test idempotency (re-trimitere identică → același submissionId, fără dublu la RAR).
5. needs_mapping / needs_data (nu se trimite incomplet); error + re-push.
6. Verifică: SQLite fără câmp parolă; după sent PII criptat + purge_after; loguri fără parole.
7. Teste: unit (mapare, hash idempotency, validare odometru), integration (claim atomic, retry), E2E test RAR.

Decizii deja blocate (nu le re-deschide fără motiv)

• Idempotency = hash de conținut pe server, UNIQUE (RAR n-are câmp nr. comandă, acceptă duplicate).
• Reținere temporară 90 zile a payload-ului criptat, apoi purjare (defensibilitate vs privacy).
• Odometru repair: strict + stare needs_data (nu trimite incomplet).
• Cherry-picks în v1: alertă submission-uri blocate, /healthz+/metrics, sugestie fuzzy mapare, export audit CSV.
• URL-urile RAR: sursa de adevăr = VFP testat, NU spec-ul (are typo-uri de copy/paste).

Open questions rămase

1. Sursa pozei odometrului în fluxul ROAAUTO (dacă spike confirmă b64Image obligatoriu).
2. tipPrestatie — valori acceptate (de probat la spike).
3. Un singur user RAR per agent economic sau mai mulți (afectează idUser / filtrare monitorizare).
4. Monetizare/direcție SaaS — de reluat după ce prima prezentare reală merge la primul client.