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.

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.