rar-autopass/docs/prd/prd-5.2-dryrun-valideaza.md

PRD 5.2 — Endpoint dry-run POST /v1/prezentari/valideaza

Stare: inchis

Proces complet: docs/ROADMAP.md §5. Contract RAR (sursa de adevar): docs/api-rar-contract.md. Starea trece: draft → aprobat → in-executie → verify-pass → inchis (actualizata de lead).

1. Obiectiv

Un endpoint care valideaza un payload de prezentari exact ca POST /v1/prezentari, dar fara enqueue si fara efecte secundare: intoarce verdictul (queued / needs_data / needs_mapping), erorile reale [{field, message}] si codurile nemapate, ca integratorul (ROAAUTO / soft propriu / punte VFP) sa-si verifice integrarea inainte sa trimita ceva real. "Magical moment" de onboarding (Etapa 5 — ergonomie & integrare).

Invariant de corectitudine (motivul cheie de design): dry-run-ul trebuie sa produca acelasi verdict pe care l-ar produce POST /v1/prezentari pe acelasi payload. Daca cele doua cai diverg, dry-run-ul minte — mai rau decat sa nu existe. De aceea logica de clasificare se extrage intr-un helper pur partajat folosit de AMBELE endpoint-uri (nu se duplica).

2. Non-Goals (anti scope-creep)

• NU atinge coada submissions — zero INSERT/UPDATE/DELETE; endpoint read-only (citeste doar operations_mapping pentru rezolvarea codurilor, scoped pe cont).
• NU detectie duplicat / idempotency — nu raporteaza idempotency_key si nu cauta submission-uri identice existente (decizie utilizator 2026-06-22: doar validare + mapare). idempotency.py neatins.
• NU stocheaza si NU foloseste creds RAR — rar_credentials devine optional si, daca e prezent, e ignorat (nu se cripteaza, nu se logheaza, nu se trimite nicaieri).
• NU UI / hub — documentarea in /integrare (5.1) + snippet-uri ramane follow-up (decizie utilizator 2026-06-22). Acest PRD = strict endpoint + teste.
• NU atinge worker, masina de stari, schema, validation.py (regulile), nomenclator.
• NU apel live la RAR — validarea e 100% locala (replica regulilor RAR din validation.py).

3. Stories atomice

US-001: Endpoint dry-run POST /v1/prezentari/valideaza

Ca integrator (ROAAUTO / soft propriu / VFP) vreau sa trimit un payload de prezentari si sa primesc inapoi exact erorile + verdictul pe care le-ar produce trimiterea reala, fara sa enqueue ceva sau sa am nevoie de creds RAR, pentru ca sa-mi validez integrarea sigur, repetabil, inainte de prima trimitere reala.

• Depinde de: —
• Fisiere: app/mapping.py (helper pur nou classify_prezentare), app/api/v1/router.py (ruta + refactor create_prezentari sa foloseasca helper-ul), app/models.py (modele request/response), tests/test_validare_dryrun.py (~4 fisiere)
• Test intai (RED): tests/test_validare_dryrun.py —
  • test_payload_valid_returneaza_queued (valid → status_estimat="queued", valid=True, erori=[])
  • test_vin_invalid_returneaza_needs_data (VIN cu O/I/Q → needs_data + eroare pe field="vin")
  • test_data_viitoare_needs_data (data in viitor → needs_data)
  • test_cod_op_nemapat_returneaza_needs_mapping (cod_op_service necunoscut → needs_mapping + nemapate=[{cod_op_service, denumire}])
  • test_mapare_existenta_rezolva_codul (cu mapare salvata pe cont → cod_op_service rezolvat in prestatii_rezolvate, status_estimat="queued")
  • test_fara_creds_merge (body FARA rar_credentials → 200)
  • test_nu_scrie_in_coada (COUNT(*) submissions inainte == dupa; zero efecte secundare)
  • test_multi_prezentari_rezultate_per_index (lista [valid, invalid] → 2 rezultate, index 0/1, statusuri diferite)
  • test_shape_invalid_422 (prestatie fara cod_prestatie SI fara cod_op_service → 422 de shape, ca endpoint-ul real; raspunsul NU contine echo de input/parola)
• Acceptance criteria:
  • POST /v1/prezentari/valideaza exista, accepta {prezentari:[...], rar_credentials?}, intoarce {results:[{index, valid, status_estimat, erori, nemapate, prestatii_rezolvate}]}.
  • status_estimat ∈ {queued, needs_data, needs_mapping} si coincide cu statusul pe care POST /v1/prezentari l-ar atribui pe acelasi payload + aceeasi mapare de cont (verificat prin helper partajat classify_prezentare, folosit de ambele rute).
  • valid == (status_estimat == "queued").
  • erori = exact lista validate_prezentare (forma [{field, message}]), goala cand e curat.
  • nemapate = [{cod_op_service, denumire}] cand exista coduri interne nerezolvate; altfel [].
  • prestatii_rezolvate arata codurile RAR rezolvate (cod_op_service mapat → cod_prestatie umplut).
  • rar_credentials optional; daca lipseste → 200; daca e prezent → ignorat (necriptat, nelogat).
  • Zero scriere in DB: COUNT(*) FROM submissions neschimbat dupa apel (read-only pe mapping).
  • Scope pe cont prin resolve_account_id (ca endpoint-ul real): maparea folosita la rezolvare e a contului cheii API (dev fara cheie → cont 1; prod → cheie obligatorie).
  • create_prezentari (endpoint-ul real) ramane cu comportament identic — toate testele existente tests/test_api.py raman verzi dupa refactor-ul catre helper-ul partajat.
  • python3 -m pytest -q verde.
• Verificare E2E: canal API — POST /v1/prezentari/valideaza pe instanta locala cu (a) payload valid → queued, (b) VIN invalid → needs_data + mesaj real, (c) cod_op nemapat → needs_mapping; apoi COUNT(*) submissions neschimbat. Regresia de aur: POST /v1/prezentari real → worker → FINALIZATA la RAR test (neatins de endpoint-ul nou).

4. Riscuri

• Divergenta dry-run vs. real (risc principal) → mitigat prin helper pur partajat classify_prezentare folosit de ambele rute + AC explicit + testele test_api.py care lock-uiesc calea reala dupa refactor.
• Refactor al caii reale (create_prezentari adopta helper-ul) ar putea schimba subtil comportamentul → mitigat: testele existente test_api.py sunt contractul; raman verzi = comportament identic. Helper-ul intoarce exact aceleasi status + rar_error ca azi (queued / needs_data + erori JSON / needs_mapping + unmapped JSON / needs_mapping + auto_send note).
• Scurgere de creds prin noul model → mitigat: rar_credentials optional, ignorat, repr=False pastrat; handler-ul global 422 din main.py deja dropeaza input/ctx (no-echo parola) — acoperit de test_shape_invalid_422.
• Asteptare gresita: "valideaza" = duplicat-check → documentat ca Non-Goal in raspuns/docstring; fara idempotency_key in raspuns ca sa nu sugereze dedup.

5. Intrebari deschise

Rezolvate cu utilizatorul la poarta de aprobare PRD (2026-06-22).

• Continut raspuns — REZOLVAT: doar validare + mapare (fara idempotency/duplicat). [user 2026-06-22]
• Hub /integrare — REZOLVAT: amanat; 5.2 = endpoint + teste. [user 2026-06-22]
• auto_send=0 pe un cod mapat: pe calea reala devine needs_mapping cu nota "review manual". Dry-run-ul raporteaza acelasi status_estimat="needs_mapping" (consistenta cu real). Confirmat ca acceptabil — fara camp separat pentru cazul auto_send (ar fi scope creep). [decizie de plan, acceptata implicit]

6. Valuri de executie (graful de dependente)

Val 1: [US-001]   ← singur story, fara dependente. Un worker (sau lead direct, livrabila mica — ROADMAP §5.5).

Livrabila mica: poate rula fara TeamCreate (un singur worker Sonnet TDD), dar VERIFY in context curat

• writeback raman obligatorii (ROADMAP §5.5).

7. Review-uri de plan (aplicate inainte de cod — ROADMAP §5.3)

CEO (valoare/scope) — PASS. Problema corecta, calea cea mai directa (reuse pur validation.py+mapping.py, zero logica de domeniu noua). Inversiune ("ce-l face sa esueze?"): divergenta dry-run vs. real — neutralizata prin helper-ul partajat classify_prezentare + lock-ul test_api.py. Scope minim corect; singura "expansiune" (extragerea clasificatorului) e ceruta de corectitudine, nu scope creep. Risc flagat (deferare constienta): descoperibilitate — un endpoint pe care integratorii nu-l gasesc nu-si livreaza valoarea pana cand un follow-up il expune in /integrare. Acceptat de utilizator (amanat); valoarea 5.2 se realizeaza la follow-up.

Eng (fezabilitate/teste) — PASS. Fezabilitate triviala, fara atingere schema/worker/idempotenta. Lista de teste e completa (happy path + fiecare ramura de eroare + fara-creds + multi-prezentare cu index + shape-422 fara echo + aserctia critica zero-efecte COUNT(*) inainte==dupa). Singurul risc pe calea de aur = refactor-ul create_prezentari pe helper-ul partajat; contractul de blocare = suita test_api.py existenta (ramane verde = comportament identic). Read-only → fara logging nou (consistent cu GET-urile existente); in prod cere cheie prin resolve_account_id (fara suprafata noua de abuz).

---

Raport VERIFY

Completat de subagentul verificator (context curat) in faza VERIFY — vezi ROADMAP §5.6. PASS/FAIL per criteriu, cu dovezi (output pytest citat, E2E pe canal API). Lipseste pana la VERIFY.

Verificator independent (context curat, rol qa-only), 2026-06-22. VERDICT GLOBAL: PASS.

1. Suita — PASS. python3 -m pytest -q → 577 passed (226 warnings preexistente Starlette/templating). pytest tests/test_validare_dryrun.py tests/test_api.py -q → 14 passed (9 dry-run TDD + 5 regresia caii reale).

2. Acceptance criteria US-001 — toate PASS. Endpoint exista cu raspunsul {results:[{index,valid, status_estimat,erori,nemapate,prestatii_rezolvate}]}. status_estimat coincide cu POST /v1/prezentari prin helper-ul partajat classify_prezentare apelat de AMBELE rute (router.py create + valideaza, acelasi load_mapping_meta). valid == (status=="queued"). erori=lista validate_prezentare. nemapate= [{cod_op_service,denumire}]. rar_credentials optional + ignorat (encrypt_creds absent din ruta; parola din body NU apare in raspuns). Zero scriere DB (COUNT(*) submissions=0 dupa 3 apeluri). Scope prin resolve_account_id. create_prezentari identic (test_api.py verde).

3. E2E canal API (TestClient + DB temp, verificare directa SQLite) — PASS. (a) valid+creds → queued, valid=true, erori=[], fara leak creds; (b) VIN cu O/I/Q → needs_data + eroare reala pe vin; (c) cod_op nemapat → needs_mapping + nemapate populat. Dupa toate: GET /v1/prezentari=0, DB COUNT(*)=0.

4. Regresia de aur — PASS (live neprobat, conform asteptarii). POST /v1/prezentari enqueue-aza corect (200, queued, COUNT(*)=1) + test_api.py verde. Flux live RAR (worker→FINALIZATA pe RAR test) NEPROBAT — lipsesc secretele in mediu (AUTOPASS_CREDS_KEY nesetat, fara creds RAR test/--send). NU e FAIL al 5.2: endpoint-ul nou e read-only, nu atinge worker/coada/schema. Documentat, nu inventat.