rar-autopass/docs/plans/plan-eng-review.md

Plan implementare: Gateway RAR AUTOPASS (migrare ROAAUTO din VFP în web)

Sursă: review CEO (SELECTIVE EXPANSION) peste design-ul vreau-sa-migrez-acest-precious-mochi.md. Grounded pe codul VFP existent + spec-ul oficial RAR (Documentatie Serviciu AutoPass_Final.txt, Document informativ RAR- Autopass.txt).

Context

ROAAUTO (Visual FoxPro + Oracle, la fiecare service client) declară azi prestațiile la RAR AUTOPASS direct din clasa RarAutoPass (rar_autopass.prg), prin MSXML2.ServerXMLHTTP. Obligație legală (L.142/2023, OM 210/2024). Integrarea e testată doar pe endpoint-ul de test RAR, nepusă la clienți.

Problema reală e de ISV: nu vrei să redistribui un .exe VFP la fiecare corecție. Muți logica (mapare + login RAR + jurnal + retry) pe un gateway central depanabil o dată pentru toți, iar ROAAUTO rămâne client subțire. Un client real a cerut automatizarea — primul plătitor, nu ipoteză.

Rezultat țintă (treapta 1): o prezentare reală trimisă din ROAAUTO prin gateway apare la RAR, vizibilă în dashboard, cu retry pe erori tranzitorii și fără a stoca parole.

Decizii blocate în review

#	Decizie	Alegere
Mod	Postura review	SELECTIVE EXPANSION — bulletproof treapta 1 + 4 cherry-picks acceptate
Idempotency	Anti-dublură	Hash de conținut pe server, UNIQUE; "nu se acceptă 2 prezentări identice". nr_comanda NU e cerut (RAR n-are câmpul; SaaS n-are comenzi)
Defensibilitate	Dovadă vs privacy	Reținere temporară 90 zile a payload-ului criptat, apoi purjare
Poză odometru	b64Image obligatoriu?	Se validează întâi la „The Assignment" pe endpoint test; nu construim orbește
Odometru repair	Validare	Strict + stare needs_data (nu trimite incomplet)
Cherry-picks	Adăugate în v1	Alertă submission-uri blocate; /healthz+/metrics; sugestie fuzzy mapare; export audit CSV
Import DBF	Migrare date	import_dbf.py cu dry-run + raport înainte de scriere

Constatări din spec-ul oficial (corecturi față de design)

1. Prezentari n-are câmp de număr comandă (spec model #11, l.387-391). RAR acceptă duplicate (fără constrângere unică). → cheia de idempotență e doar pentru retry-urile tale, hash pe conținut.
2. Toate câmpurile sunt obligatorii except obs (doc informativ l.47). Asta include b64Image (poză odometru, l.40) — VFP-ul trimite azi gol. Posibil gap de conformitate în producție. De validat.
3. Înlocuire/reparație odometru (l.37, l.39): cer ambele valori odometruInitial + odometruFinal. VFP trimite azi odometruInitial: null. Anti-fraudă (penal până la 5.000 lei).
4. sistemReparat e „codificat în lista de prestații" (l.45) → probabil derivabil din codurile codPrestatie prin mapare, nu input liber separat. Reduce Open Question #2.
5. URL-uri: spec-ul are typo-uri de copy/paste (postPrezentare listat ca /patchPrezentare/{id} l.244; markAnulata ca /getPrezentare/{id} l.227). Sursa de adevăr = URL-urile testate din VFP (/prezentari/postPrezentare, /prezentari/markPrezentareAnulataById/{id}).
6. Monitorizare: spec-ul are getAllPrezentari (prezentări active); VFP folosește getAllPrezentariFinalizate (nedocumentat). De ales deliberat — vezi „Monitorizare" mai jos.

⚠️ Prerequisite blocant — „The Assignment" (spike, ~1h, ÎNAINTE de orice cod)

Pe endpoint-ul de test RAR, măsoară pe /public/login + postPrezentare:

• Durata de viață a JWT-ului (login, apoi postPrezentare la intervale crescătoare până la 401) → dimensionează fereastra de retry autonom din worker.
• Dacă postPrezentare trece FĂRĂ b64Image și fără odometruInitial → decide dacă poza e obligatorie în prod (constatare #2) și dacă ROAAUTO trebuie să atașeze poza.
• Valorile acceptate pentru tipPrestatie / sistemReparat (enum nedocumentat) — probează câteva.

Rezultatul acestui spike decide robustețea cozii și scopul real al ROAAUTO. Nu pornește implementarea worker-ului înainte de el.

Arhitectură

ROAAUTO (VFP, la client)                         GATEWAY FastAPI (central, 1 container)
  citește comanda + creds RAR din Oracle    POST /v1/prezentari {comanda + RAR creds + idempotency implicit}
  ──HTTPS──────────────────────────────────────▶ API
                                                   ├─ valid Pydantic (vin, odometru, prestatii)
                                                   ├─ rezolvă op→codPrestatie (operations_mapping)
                                                   ├─ derivă sistemReparat din coduri
                                                   ├─ calc idempotency_key = hash(conținut canonic)
                                                   ├─ INSERT submission (PII criptat tranzitoriu, queued)
  ◀── {submissionId, status: queued|needs_mapping|needs_data} ──┘  (UNIQUE → dedup, întoarce id existent)

                       WORKER (proces separat, restart:always, poll SQLite WAL)
                         claim atomic: BEGIN IMMEDIATE; UPDATE…SET sending WHERE id=? AND status='queued'
                         login RAR → JWT → postPrezentare → retry/backoff ÎN fereastra JWT
                         succes: scrie idPrezentare; PURJEAZĂ creds; PII criptat rămâne max 90 zile

  Browser ─▶ Dashboard (Jinja2+HTMX): monitorizare + coadă curentă + editor mapări + nomenclator + audit CSV
  ROAAUTO (timer re-push) ─▶ GET /v1/prezentari?status=error → retrimite cu creds proaspete (durabilitate pene lungi)

Data flow + shadow paths (postPrezentare)

INPUT ──▶ VALIDARE ──▶ MAPARE op→cod ──▶ ENQUEUE ──▶ WORKER login+send ──▶ RAR
  │          │              │               │              │
  nil/empty  vin invalid    cod lipsă →     idempotency    JWT expirat → error (re-push ROAAUTO)
  vin?       odometru<0     needs_mapping   key dublu →     RAR 4xx → needs_data/error (logat, NU silent)
  creds?     repair fără    sistemReparat   întoarce id     RAR 5xx/timeout → retry backoff
             init → needs_data nederivabil  existent        b64Image lipsă (dacă obligatoriu) → needs_data

Mașina de stări submission

queued → sending → { sent | needs_mapping | needs_data | error }
  needs_mapping : operație fără codPrestatie mapat → ținut gateway-side, NU trimis incomplet
  needs_data    : repair odometru fără init/final SAU poză lipsă (dacă obligatorie) → ținut, NU trimis
  error         : eligibil re-push din ROAAUTO (GET ?status=error)
  sent          : are idPrezentare RAR; creds purjate; PII criptat max 90 zile; terminal

Componente (un repo, docker compose up)

1. API app/api/v1 (FastAPI):
   • POST /v1/prezentari (una/mai multe) → Pydantic, mapare, enqueue, răspuns submissionId.
   • GET /v1/prezentari?status=&data= și /{id} — monitorizare programatică + re-push ROAAUTO.
   • GET /v1/nomenclator, POST /v1/nomenclator/refresh.
   • GET/PUT /v1/mapari — CRUD mapare per cont, cu sugestie fuzzy pe denumire (cherry-pick).
   • PATCH /v1/prezentari/{id}/anulare, /corectie — proxy markPrezentareAnulataById / patchPrezentare.
   • GET /v1/audit/export?from=&to= — CSV cu ce s-a trimis (cherry-pick, leagă reținerea 90 zile).
   • Auth gateway: API key per cont ROA (separată de creds RAR), cu emitere/rotire/revocare.
   • Redactare credențiale (CORE, nu opțional): middleware care garantează că body-ul pe /v1/prezentari NU se loghează niciodată și password se scrubează din excepții/APM.
   • (Amânat: POST /v1/import xlsx/csv — treapta 2.)
2. Client RAR app/rar_client.py — portare din rar_autopass.prg + rar-forms.prg: login+JWT, getNomenclatorPrestatii, postPrezentare, getAllPrezentari, getPrezentare, markPrezentareAnulataById, patchPrezentare. httpx + retry/backoff. URL-uri din VFP testat, nu din spec.
3. Worker app/worker — proces separat sub Docker restart: always (NU asyncio în uvicorn dacă scalezi workeri — un singur scriitor pe coadă ca să nu dublezi un record legal). Buclă claim atomic → login → send → retry → scrie status+idPrezentare. b64Image mare → BLOB/path pe disc, nu RAM.
4. Dashboard app/web — Jinja2 + HTMX (server-rendered, zero build): monitorizare, stare coadă, editor mapări (cu fuzzy), browser nomenclator, banner alertă submission-uri blocate (cherry-pick).
5. SQLite (WAL) — un fișier .db:
   • accounts, api_keys.
   • operations_mapping (cod_op_service → codPrestatie, auto_send) ← mapare_prestatii.DBF.
   • nomenclator_rar (cache {codPrestatie, numePrestatie}) ← prestatii_rar.DBF.
   • submissions: idempotency_key UNIQUE, status, statusCode RAR, eroare, idPrezentare, retry, timestamps. PII (vin, odometru, dataPrestatie, prestatii, b64Image) criptat + purge_after (sent+90z).
   • Niciun câmp pentru parole RAR.

Securitate & raza de explozie (constatare review #5)

Gateway-ul vede parolele RAR ale tuturor clienților în memorie/tranzit. Zero-storage reduce riscul la rest, dar o greșeală de logging scurge parole live, iar AGPL = codul e public. Controale hard:

• Middleware de redactare (mai sus) — body-uri cu parole niciodată în loguri/APM/excepții.
• HTTPS obligatoriu; recomandare TLS pinning din ROAAUTO către gateway.
• Parola folosită doar pentru login în worker, apoi ștearsă din itemul de coadă.

Error & rescue map (extras)

Codepath	Ce poate eșua	Excepție	Rescued?	Acțiune	User vede
rar_client.login	timeout/5xx	httpx.TimeoutException	Y	retry backoff în fereastra JWT	submission error, re-push
rar_client.login	401 creds greșite	AuthError	Y	NU retry; marchează error+motiv	„credențiale RAR invalide"
rar_client.postPrezentare	4xx validare RAR	RarValidationError	Y	needs_data + payload RAR logat	rând flag-uit în dashboard
rar_client.postPrezentare	JSON malformat/empty	JSONDecodeError	Y	error + raw response logat (scrub)	submission error
API enqueue	idempotency dublu	IntegrityError(UNIQUE)	Y	întoarce submissionId existent	„deja înregistrat"
worker claim	două procese	(prevenit) BEGIN IMMEDIATE	Y	un singur scriitor	n/a
mapare	cod lipsă	(control de flux)	Y	needs_mapping, NU trimite	„necesită mapare"

Regulă: fără except Exception generic. Fiecare rescue: retry / degradare cu mesaj / re-raise cu context.

Failure modes registry (gap-uri critice de evitat)

Codepath	Failure	Rescued	Test	User vede	Logged
postPrezentare repair fără odometru init	record fraud-sensibil incomplet	Y (needs_data)	DA	flag dashboard	DA
dublu-send din 2 bucle retry	duplicat la RAR	Y (idempotency UNIQUE)	DA	nimic (transparent)	DA
poză lipsă dacă obligatorie	RAR respinge	Y (needs_data după spike)	DA	flag dashboard	DA
submission blocat tăcut	declarație legală pierdută	Y (alertă cherry-pick)	DA	banner + webhook	DA

Client ROAAUTO (VFP) — refactor minim

• settings.xml păstrează doar URL gateway + API key (rotește parola de test expusă acum în SVN!).
• Creds RAR ale clientului se citesc din Oracle și se trimit în payload la gateway peste HTTPS.
• export_comenzi.prg rămâne, dar construiește JSON și face POST /v1/prezentari (nu XML + apel RAR direct).
• Dispar din VFP: Login, UpdateNomenclator, GetCodRarPentruOperatie, maparea, rar_log → în web.
• Job periodic „re-push pending" — reutilizează timer-ul existent (OnAutoProcessTimer/nTimerHandle din rar-forms.prg).
• Dacă spike-ul confirmă poza obligatorie: ROAAUTO atașează poza odometrului (de clarificat sursa).

Migrare date

tools/import_dbf.py (cu dbfread) — dry-run + raport întâi: rânduri valide, mapări orfane, coduri necunoscute în nomenclator. Confirmi, apoi scrie în SQLite. Surse: mapare_prestatii.DBF, prestatii_rar.DBF. (rar_log.DBF NU se migrează — jurnalul nou e submissions + live din RAR.)

Observabilitate (cherry-picks)

• /healthz — worker viu + ultimul login RAR reușit + adâncime coadă.
• /metrics — submissions pe status, latență send, retry count, backlog needs_mapping/needs_data.
• Alertă submission-uri blocate — banner dashboard + webhook/email peste prag (plasă de siguranță legală).

Monitorizare — sursa de adevăr

Citit live din RAR + stare coadă locală. Atenție: getAllPrezentariFinalizate (VFP) întoarce doar FINALIZATA; getAllPrezentari (spec) întoarce active. Alege getAllPrezentari dacă vrei și draft/anulate. Cache scurt (ex. 30-60s) + UX „RAR indisponibil, arăt ultima stare a cozii" (nu lega dashboard-ul de uptime RAR).

Deploy

• Start: LXC Proxmox + Cloudflare Tunnel (0 €, teste). Producție: VPS mic always-on (~5 €/lună).
• Un container: uvicorn (API) + worker (proces 2), restart: always, volum SQLite. Mutare = copiezi container + .db.
• Open-source pe github.com/romfast, AGPL-3.0. ⚠️ Vezi „Decizie one-way door" mai jos.
• romfast.ro/hosting.com = doar landing (ASGI + worker daemon nu merg pe shared hosting).

Verificare (end-to-end)

1. Spike „The Assignment" rulat, JWT TTL + cerințe b64Image/odometru documentate.
2. import_dbf.py --dry-run produce raport corect pe DBF-urile reale; apoi import confirmat.
3. docker compose up; /healthz verde.
4. POST /v1/prezentari cu o comandă reală din ROAAUTO (test) → submissionId, worker trimite, apare FINALIZATA la RAR (test) și în dashboard.
5. Re-trimite aceeași comandă identică → întoarce același submissionId (idempotency), NU dublă la RAR.
6. Trimite operație nemapată → needs_mapping; repair odometru fără init → needs_data; nu se trimit incomplet.
7. Oprește RAR (sau forțează 5xx) → submission error, ROAAUTO re-push recuperează; nimic blocat tăcut.
8. Verifică: SQLite n-are câmp parolă; după sent, PII e criptat și are purge_after; logurile n-au parole.
9. Teste automate: unit (mapare, idempotency hash, validare odometru), integration (worker claim atomic, retry/backoff), E2E pe endpoint test RAR.

Decizie one-way door de semnalat (CEO)

Licență AGPL fără CLA poate bloca un viitor strat SaaS comercial: odată ce intră PR-uri externe sub AGPL, relicențierea cere acordul tuturor contributorilor. Dacă vrei să păstrezi opțiunea de dual-license (open core + hosted comercial — exact teza ta de la treapta 2), adoptă CLA / copyright assignment din ziua 1. AGPL în sine e bună pentru moat (forțează competitorii care-l găzduiesc să-și deschidă modificările). Decizia: deliberat, acum.

NOT in scope (amânat, cu motiv)

• POST /v1/import xlsx/csv + UX mapare coloane — treapta 2 (piață non-ROA). Motor identic, fără rescriere.
• Modelul de conturi RAR (addClient/roluri) — nu-l replicăm; rămâne la RAR.
• Outbox în Oracle (Approach C) — pentru clienți non-ROA / viitor, cere acces gateway→Oracle.
• Agregare/produse din datele service-urilor — niciodată default; doar opt-in + anonimizare + lawyered.
• Redis/arq/Postgres — SQLite WAL + un worker acoperă volumul (60-100 prezentări/lună/client).

Open questions rămase

1. Sursa pozei odometrului în fluxul ROAAUTO (dacă spike-ul 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.

What already exists (reuse)

Sub-problemă	Reuse din VFP
Contract RAR (login/JWT, nomenclator, postPrezentare, cancel)	rar_autopass.prg, rar-forms.prg:655,720 → rar_client.py
Mapare op→codPrestatie + auto_send	GetCodRarPentruOperatie → operations_mapping
Timer re-push	OnAutoProcessTimer/nTimerHandle (rar-forms.prg)
Export (oglindă treapta 2)	btnExportExcel.Click (rar_advanced.prg)
Migrare DBF	import_dbf.py citește direct cele 3 .DBF