rar-autopass/docs/prd/prd-5.7-raspuns-onest-mapare-inline.md

PRD 5.7 — Raspuns API onest la blocaje + mapare inline din detaliu

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

Doua goluri raportate din clientul Visual FoxPro (2026-06-23):

1. Raspunsul POST /v1/prezentari minte prin omisiune. Cand o prezentare e blocata (needs_data — date respinse de RAR; needs_mapping — cod fara mapare), API-ul intoarce {submission_id, status} fara detalii: campul erori ramane gol (se populeaza azi DOAR pe ramura on_unmapped_error=True). Un integrator care verifica "am submission_id si erori e gol → e ok" trateaza un rand blocat ca succes. Screenshot live: rand needs_data (data in viitor) pe care clientul l-a primit "fara erori". Reparam: raspunsul devine onest — pentru orice status != queued expune erori (validare continut), nemapate (coduri fara mapare) si un motiv uman pe o linie. Strict aditiv (campuri noi + populare a unui camp existent) — clientii vechi nu se rup.

2. Maparea unui cod nemapat cere drum prin tab-ul Mapari. Din panoul de detaliu al unei trimiteri needs_mapping, userul vede "Lipseste codul prestatiei" dar trebuie sa navigheze in alt tab ca sa o mapeze. Adaugam mapare inline: chiar in panoul de detaliu, fiecare operatie nemapata primeste un selector de cod RAR (cu sugestii fuzzy preselectate) si un buton care salveaza maparea + re-rezolva submission-ul pe loc.

Etapa 5 (ergonomie & integrare). Niciun apel live la RAR.

2. Non-Goals (anti scope-creep)

• NU schimba masina de stari, worker-ul, idempotency-ul, schema. Zero coloane noi. classify_prezentare ramane sursa unica de clasificare (invariantul dry-run din 5.2 se pastreaza).
• NU schimba comportamentul on_unmapped_error (ramura error/respins): erori cu COD_NEMAPAT ramane exact ca azi (lock-uit de test_on_unmapped_error_respinge_fara_enqueue). Doar adaugam nemapate + motiv si pe acea ramura.
• NU imbogateste raspunsul deduped cu erori/motiv: un dedup intoarce starea curenta a randului existent fara re-clasificare (clientul poate cere GET /v1/prezentari/{id} pentru detaliu). Pastram semantica actuala a caii de dedup.
• NU atinge /valideaza (dry-run-ul are deja erori+nemapate; ramane referinta de forma).
• NU schimba editorul din tab-ul Mapari — maparea inline il completeaza, nu il inlocuieste; reutilizeaza save_mapping + reresolve_account (aceeasi logica, fara ramura noua).
• NU mapare inline pe needs_data — acolo exista deja corectia de campuri (US-010, 3.5). Inline-ul de mapare apare DOAR pe needs_mapping cu operatii nemapate reale.

3. Stories atomice

US-001: Raspuns POST /v1/prezentari onest pentru randuri blocate

Ca integrator (ROAAUTO / soft propriu / punte VFP) vreau ca raspunsul la enqueue sa-mi spuna de ce un rand e blocat (nu doar status), pentru ca sa nu tratez un needs_data/needs_mapping drept succes si sa pot reactiona programatic.

• Depinde de: —
• Fisiere: app/models.py (SubmissionResult += nemapate, motiv), app/api/v1/router.py (create_prezentari populeaza din cl), tests/test_api.py + tests/test_mapping.py (~4 fisiere)
• Test intai (RED): tests/test_api.py —
  • test_needs_data_intoarce_erori (data in viitor → status="needs_data", erori negol cu cod="DATA_VIITOR" pe field="data_prestatie", motiv negol)
  • test_vin_invalid_intoarce_erori_pe_camp (VIN cu O/I/Q → erori cu field="vin")
  • test_needs_mapping_intoarce_nemapate (cod necunoscut → status="needs_mapping", nemapate negol cu cod_op_service, erori=[], motiv negol)
  • test_queued_fara_erori_nemapate (valid → erori=[], nemapate=[], motiv null)
  • tests/test_mapping.py::test_on_unmapped_error_pastreaza_erori (regresie: on_unmapped_error=True inca da erori[0].cod=="COD_NEMAPAT"; + acum nemapate negol)
• Acceptance criteria:
  • SubmissionResult are campurile noi nemapate: list[dict] = [] si motiv: str | None = None (aditiv; erori ramane).
  • Pe enqueue cu status="needs_data": erori = exact validate_prezentare (3 niveluri), nemapate=[], motiv = rezumat uman pe o linie.
  • Pe enqueue cu status="needs_mapping" din coduri nemapate: nemapate = [{cod_op_service, denumire, cod, problema, cauza, fix, message}], erori=[], motiv negol.
  • Pe enqueue cu status="needs_mapping" din auto_send=0: motiv explica "confirmare manuala" (chiar daca erori/nemapate sunt goale).
  • Pe status="queued": erori=[], nemapate=[], motiv=None.
  • Ramura on_unmapped_error=True (status="error", submission_id=None): erori neschimbat (COD_NEMAPAT), nemapate negol, motiv negol.
  • Raspunsul nu contine niciodata echo de creds (password) — validat pe corpul serializat.
• Verificare E2E: POST /v1/prezentari din client (sau curl) cu data in viitor → JSON cu erori vizibile; cu cod intern → nemapate.

US-002: Backend mapare inline din panoul de detaliu (ruta + context)

Ca operator in dashboard vreau sa mapez codul unei operatii direct din detaliul trimiterii pentru ca sa deblochez randul fara sa schimb tab-ul.

• Depinde de: —
• Fisiere: app/web/routes.py (helper _nemapate_pentru_submission, context in _detaliu_ctx, ruta POST /trimitere/{id}/mapeaza), tests/test_web_mapare_inline.py (~2 fisiere)
• Test intai (RED): tests/test_web_mapare_inline.py —
  • test_detaliu_needs_mapping_arata_operatii_nemapate (GET detaliu pe needs_mapping → HTML contine selectorul de cod RAR + denumirea operatiei + cel putin o sugestie)
  • test_mapeaza_inline_deblocheaza_randul (POST /trimitere/{id}/mapeaza cu cod valid → submission trece queued, maparea apare in operations_mapping)
  • test_mapeaza_inline_cod_necunoscut_respins (cod inexistent in nomenclator → mesaj eroare, submission ramane needs_mapping, nicio mapare salvata)
  • test_mapeaza_inline_scoped_pe_sesiune (POST pe submission al altui cont → 404, fara mapare)
  • test_mapeaza_inline_csrf_obligatoriu (fara token → 403)
  • test_mapeaza_inline_respecta_batch (submission din import cu batch_id → re-rezolvarea il atinge)
• Acceptance criteria:
  • _detaliu_ctx pe status="needs_mapping" expune nemapate_inline = [{cod_op_service, denumire, suggestions:[{cod_prestatie, nume_prestatie, score}]}] + nomenclator.
  • POST /trimitere/{id}/mapeaza (Form: cod_op_service, cod_prestatie, auto_send, csrf_token): verifica CSRF, scope pe sesiune (404 cross-account/inexistent ca restul rutelor), respinge cod absent din nomenclator (re-randeaza detaliul cu mesaj), altfel save_mapping + reresolve_account cu batch_id al randului, re-randeaza detaliul cu starea noua + mesaj.
  • Re-rezolvarea foloseste EXACT save_mapping/reresolve_account existente (fara logica noua de clasificare); randurile-frate cu aceeasi operatie din acelasi batch se deblocheaza si ele.
  • Raspunsul trimite HX-Trigger: trimiteriChanged (lista Trimiteri se reimprospateaza).
• Verificare E2E: dashboard pe needs_mapping → alegi cod RAR inline → randul devine queued.

US-003: UI mapare inline in _trimitere_detaliu.html

Ca operator vreau un formular clar in detaliu (operatie + sugestii + selector cod + salveaza) pentru ca maparea sa fie evidenta si rapida.

• Depinde de: US-002
• Fisiere: app/web/templates/_trimitere_detaliu.html, (eventual reuse din _macros.html), tests/test_web_mapare_inline.py (asserts pe HTML)
• Test intai (RED): acoperit de US-002 (test_detaliu_needs_mapping_arata_operatii_nemapate)
• Acceptance criteria:
  • Sectiune "Mapeaza codul operatiei" vizibila DOAR cand status="needs_mapping" si exista nemapate_inline; un <form hx-post="/trimitere/{id}/mapeaza"> per operatie, hx-target="#trimitere-detaliu".
  • Selector cod RAR populat din nomenclator, cu sugestia top (score >= 60) preselectata; sugestiile afisate cu procent (ca in tab-ul Mapari).
  • Include csrf_token + comutatorul auto-send (reuse ui.autosend_toggle, default pornit).
  • Mesaj de rezultat (succes/eroare) randat la re-render, fara a pierde restul panoului.
• Verificare E2E: idem US-002 (browser HTMX).

4. Riscuri

• Divergenta clasificarii: maparea inline NU trebuie sa reimplementeze rezolvarea. Mitigare: reutilizeaza save_mapping + reresolve_account (singura cale, ca tab-ul Mapari) — orice corectie de comportament ramane intr-un singur loc.
• Scope batch: reresolve_account(batch_id=None) atinge doar canalul API (batch_id IS NULL). Un submission de import (batch_id setat) nu s-ar debloca. Mitigare: ruta paseaza batch_id-ul randului (test dedicat test_mapeaza_inline_respecta_batch).
• Compat raspuns: noile campuri trebuie sa fie pur aditive. Mitigare: defaulturi goale + test de regresie pe on_unmapped_error si pe forma deduped.

5. Intrebari deschise — REZOLVATE (poarta de aprobare, 2026-06-23)

• Q1 [DA]: pastram AMBELE — campuri structurate (erori/nemapate) pentru masini + motiv (string uman pe o linie) pentru log/UI rapida. Implementat ca atare.
• Q2 [DA]: maparea inline apare DOAR pe operatii nemapate reale. Pe needs_mapping din auto_send=0 (cod deja mapat, doar trimitere oprita) NU se afiseaza — _nemapate_pentru_submission intoarce lista goala in acel caz; confirmarea ramane in tab-ul Mapari.

6. Valuri de executie (graful de dependente)

Val 1: [US-001]  [US-002]     ← fisiere disjuncte (router/models vs web routes) → paralel
Val 2: [US-003]               ← deblocat de US-002 (template peste contextul nou)

---

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 RAR test). Lipseste pana la VERIFY.