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