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

⚠️ SURSA DE ADEVĂR pentru contractul RAR = docs/api-rar-contract.md (verificat live). Acolo unde planurile (docs/plans/*) diferă, contractul are dreptate. Vezi „Corecții față de planuri".

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 (vechi, are typo-uri)	înlocuit de docs/api-rar-contract.md
docs/api-rar-documentatie-oficiala.md	răspuns oficial programatori RAR	sintetizat în docs/api-rar-contract.md
docs/api-rar-contract.md	contract verificat live — sursa de adevăr	referință pentru app/

Planul (în docs/plans/)

plan.md — planul unic executabil (sursă unică). Consolidează designul de produs + implementarea, aliniat la contractul verificat live. Conține: arhitectură, reguli contract, validare, mașina de stări, componente, securitate, failure modes, Roadmap de execuție (T1-T7 + pașii rămași), verificare E2E, NOT in scope, decizii blocate, și anexa de produs/SaaS.

Continuă cu docs/plans/plan.md → secțiunea „Roadmap de execuție". Pasul blocant următor = T1 (un postPrezentare real pe test). Fostele plan-eng-review.md + plan-design-review.md au fost consolidate în plan.md (review-urile eng + design au intervenit pe el).

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

„The Assignment" (spike) — REZOLVAT în mare parte (2026-06-15)

Detalii complete în docs/api-rar-contract.md. Rezumat:

1. JWT TTL = 108000s = 30 ORE (nu „scurt"). → worker-ul singur poate relua peste pene lungi; re-push ROAAUTO devine secundar. Reconsideră arhitectura de robustețe din planuri.
2. b64Image (poza) = OPȚIONALĂ (confirmat oficial). Open question „sursa pozei" închisă.
3. tipPrestatie = generat de server (GENERIC), nu se trimite. sistemReparat se trimite (poate fi "null"); valorile reale rămân de probat.
4. needs_data determinist: odometruInitial obligatoriu doar dacă prestatii conține R-ODO sau I-ODO.

Rămas: un singur postPrezentare real pe test (mesaje de eroare exacte + data.id). Vezi contract.

De făcut după spike (din plan.md, Roadmap de execuție + 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 (actualizat 2026-06-15)

1. Sursa pozei odometrului — închis (poză opțională, vezi contract).
2. tipPrestatie valori — închis pentru request (generat de server). Rămâne: ce valori reale acceptă sistemReparat (în afară de "null").
3. Un singur user RAR per agent economic sau mai mulți (afectează idUser/idAgent / filtrare monitorizare).
4. Monetizare/direcție SaaS — de reluat după ce prima prezentare reală merge la primul client.
5. Anulare/corecție: nu există flux API (records FINALIZATA); corecția = email suport RAR. De reflectat în UX dashboard (nu promite anulare).