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.