rar-autopass/docs/prd/prd-5.6-observabilitate-jurnal.md

PRD 5.6 — Observabilitate, jurnal aplicatie & lifecycle trimiteri blocate

Stare: aprobat + review /autoplan complet (4 decizii de gust rezolvate 2026-06-23; vezi Anexa /autoplan)

Proces complet: docs/ROADMAP.md §5. Contract RAR (sursa de adevar): docs/api-rar-contract.md. Catalog erori (sursa de adevar coduri): app/errors.py (PRD 5.4). Redactare creds: app/security.py.

0. Context — de ce acum

Un client ROAAUTO (Visual FoxPro, MSXML2.ServerXMLHTTP) a primit "Internal Server Error" la POST /v1/prezentari si nu a existat niciun mod de a vedea ce s-a intamplat fara a citi traceback-ul brut din access-log-ul uvicorn (.run/api.log).

Cauza concreta a fost o cheie Fernet invalida in .env (AUTOPASS_CREDS_KEY), care arunca ValueError abia la primul encrypt_creds — un 500 brut, fara mesaj util pentru client si fara inregistrare la nivel de aplicatie. Cauza a fost reparata ca hotfix (cheie valida in .env + validare fail-fast la startup — crypto.validate_creds_key, apelata in main.lifespan; confirmat live HTTP 200).

Acest incident a expus trei goluri structurale, care sunt obiectul acestui PRD:

1. Excepțiile interne devin 500 brut, fara traducere in contractul de erori pe 3 niveluri (PRD 5.4) si fara log cu context (request_id, ruta, cont).
2. Nu exista jurnal de aplicatie la nivel de eveniment — doar access-log uvicorn (linii HTTP) + print(...) ad-hoc in worker. Nu se poate raspunde la "ce s-a intamplat cu cererea X / contul Y" fara grep prin traceback-uri.
3. Nu exista monitorizare a fluxului de afaceri dincolo de /healthz + /metrics: incercari de login RAR, ciclul de viata al trimiterilor, erori din catalog.

0bis. Context — lacune de lifecycle (descoperite la testarea live)

La testul live pe RAR test au iesit la iveala doua probleme de lifecycle, confirmate in cod:

• Trimiterile blocate sunt permanente. purge_after se seteaza DOAR la status='sent' (mark()), iar purge_expired sterge DOAR randuri sent expirate. Randurile error/ needs_data/needs_mapping nu primesc niciodata purge_after → nu se purjeaza niciodata. Login 401 (creds RAR gresite) → error direct, fara retry (by design, ca sa nu blocheze contul) → randul ramane la nesfarsit in dashboard, fara cale de stergere prin UI/API/CLI (corectia inline US-010 e doar pentru needs_*, nu error).
• Un rand error blocheaza retrimiterea aceluiasi payload. Cheia de idempotenta e hash de CONTINUT (vin+nr+data+odometru+prestatii+cont) — parola NU intra in cheie. Daca un client trimite cu parola gresita (→ error), apoi corecteaza parola si retrimite acelasi payload, primeste deduped: true cu status: error si prezentarea nu se mai trimite niciodata. Randul eronat "fura" cheia.

Reproductibil acum: submission 15 (din clientul VFP cu parola placeholder) e blocat pe error RAR_CREDS_INVALIDE; testul reusit (submission 16 → idPrezentare 68818) a necesitat un odometru diferit tocmai ca sa ocoleasca aceasta capcana.

1. Obiectiv

Un sistem de observabilitate coerent: orice eveniment relevant (cerere API, login RAR, tranzitie de trimitere, eroare) este inregistrat structurat intr-un tabel app_events (vizibil intr-un tab "Jurnal" din dashboard, filtrabil pe cont/tip/data) si intr-un log text pentru depanare low-level. Orice excepție neasteptata produce un raspuns pe 3 niveluri (PRD 5.4) in loc de 500 brut. PII si credentialele sunt redactate peste tot.

In plus, inchidem doua lacune de lifecycle descoperite la testarea live (vezi §0bis): trimiterile blocate (mai ales error din creds RAR gresite) sunt azi permanente, nu se pot sterge/re-pune in coada din interfata, blocheaza retrimiterea aceluiasi payload prin dedup si nu se purjeaza niciodata. Le facem gestionabile (sterge / re-pune in coada), deblocam dedup-ul si le aducem sub retentie.

2. Non-Goals (anti scope-creep)

• Fara dependinte/infrastructura noi de observabilitate (Sentry, ELK, Loki, OpenTelemetry, Prometheus push). Ramanem pe SQLite + fisier + dashboard HTMX existent.
• Fara alerting (email/SMS/webhook la eroare). notify_signup ramane singura notificare; alertarea = follow-up daca apare nevoia din uz real.
• Nu schimbam contractul de erori (PRD 5.4). Pe partea de observabilitate doar observam si traducem 500-urile ramase. Partea de lifecycle (US-009+) adauga DOAR doua tranzitii noi controlate — error → queued (re-pune in coada) si stergere de randuri ne-sent — fara a atinge logica de trimitere a worker-ului.
• Nu stergem/atingem randuri sent prin noile actiuni de lifecycle: sunt dovada de trimitere la RAR (audit). Stergerea/re-punerea opereaza DOAR pe error/needs_data/ needs_mapping; sending (in zbor) e protejat de lease-ul worker-ului.
• Nu anulam nimic la RAR — FINALIZATA ramane terminal acolo (fara API de anulare). Stergem doar randul LOCAL din coada gateway-ului, nu inregistrarea de la RAR.
• Nu modificam /healthz si /metrics (raman; jurnalul e complementar, nu inlocuitor).
• Fara UI de configurare a logarii (nivel/retentie se seteaza din env, nu din web).
• Nu logam corpuri de payload integral (PII vehicul/proprietar) — doar metadate + identificatori (submission_id, cont, cod eroare). VIN/nr se logheaza doar redactat/partial.

3. Stories atomice

US-000 (hotfix 500) e DEJA LIVRAT in afara procesului normal (vezi §0): cheie Fernet valida in .env + crypto.validate_creds_key() apelata in main.lifespan, confirmata live (POST VFP → 200, queued). Listata aici doar pentru trasabilitate; nu se re-executa.

US-001: Handler global de excepții → eroare 3 niveluri + log

Ca integrator ROAAUTO vreau ca orice eroare interna sa-mi intoarca un raspuns structurat (nu "Internal Server Error" gol) pentru ca sa stiu daca e problema mea (date) sau a gateway-ului, si sa pot raporta cu un identificator.

• Depinde de: — (US-003 imbogateste logul; handlerul poate loga si simplu intai)
• Fisiere: app/main.py (@app.exception_handler(Exception)), app/errors.py (cod nou EROARE_INTERNA), tests/test_error_handler.py
• Test intai (RED): tests/test_error_handler.py — test_exceptie_neasteptata_da_500_structurat, test_raspuns_contine_request_id_fara_traceback, test_creds_nu_apar_in_raspuns
• Acceptance criteria:
  • O excepție neprinsa pe orice ruta → HTTP 500 cu body {cod: "EROARE_INTERNA", problema, fix, request_id} (3 niveluri, PRD 5.4).
  • Body-ul NU contine traceback, mesaj de excepție brut, sau credentiale (scrub).
  • Traceback-ul complet + request_id + ruta + account_id se scriu in log (fisier) prin scrub (app/security.py), niciodata in raspuns.
  • Handlerele existente (LoginRequired/AdminRequired/CSRF/RequestValidationError) raman neatinse; doar Exception generic e nou.
• Verificare E2E: forteaza o excepție (ex. cheie Fernet invalida pe o ruta de test) → raspuns JSON 3 niveluri cu request_id; traceback doar in log.

US-002: request_id per cerere (corelare)

Ca operator vreau un identificator unic pe fiecare cerere pentru ca sa pot lega raspunsul clientului de randul din jurnal si de traceback.

• Depinde de: —
• Fisiere: app/web/middleware.py (sau middleware in main.py), tests/test_request_id.py
• Test intai (RED): tests/test_request_id.py — test_raspuns_are_header_x_request_id, test_request_id_propagat_in_log
• Acceptance criteria:
  • Fiecare raspuns are header X-Request-ID (generat daca clientul nu trimite unul).
  • request_id e disponibil in handlerul de erori (US-001) si in logger (US-003) pe durata cererii (contextvar, fara a polua semnaturi).
  • Format opac, fara PII (ex. secrets.token_hex(8)).
• Verificare E2E: doua cereri → doua X-Request-ID distincte, regasite in jurnal.

US-003: Logger structurat central (app/observ.py)

Ca dezvoltator vreau un singur punct prin care se emit evenimente pentru ca formatul, redactarea si dublul canal (DB + fisier) sa fie consistente si imposibil de ocolit.

• Depinde de: US-002 (request_id), schema app_events (US-004)
• Fisiere: app/observ.py (modul nou: log_event(...)), app/schema.sql (tabela app_events), app/db.py (helper insert + read paginat), tests/test_observ.py
• Test intai (RED): tests/test_observ.py — test_log_event_scrie_in_db_si_fisier, test_log_event_redacteaza_pii_si_creds, test_nivel_filtrat_din_env
• Acceptance criteria:
  • log_event(tip, *, nivel, account_id=None, cod=None, mesaj=None, context=None) scrie un rand in app_events SI o linie in log text (acelasi continut redactat).
  • Toate valorile trec prin scrub (app/security.py) inainte de persistare — parole/token-uri/rar_credentials → ***REDACTED***; VIN logat doar partial.
  • Nivelul minim e configurabil din env (AUTOPASS_LOG_LEVEL, default INFO).
  • Eroarea la scrierea jurnalului NU propaga (best-effort, ca notify_signup): o cadere a logului nu doboara cererea/worker-ul.
  • app_events: id, ts, request_id, account_id, sursa(api|worker), tip, nivel, cod, mesaj, context_json, purge_after.
• Verificare E2E: apel log_event din shell → rand in DB + linie in fisier, ambele redactate.

US-004: Audit cerere API per cont

Ca operator vreau sa vad fiecare cerere /v1/* (cine, ce, rezultat) pentru ca sa pot diagnostica integrari (ex. clientul VFP) fara acces la server.

• Depinde de: US-003
• Fisiere: middleware/dependinta in app/api/v1/ (hook pe rutele v1), app/api/v1/router.py (evenimente la enqueue), tests/test_audit_api.py
• Test intai (RED): tests/test_audit_api.py — test_post_prezentari_logheaza_eveniment_cont, test_eveniment_contine_status_si_count_fara_pii, test_401_logat_ca_auth_esuat
• Acceptance criteria:
  • POST /v1/prezentari emite eveniment api_prezentari cu: account_id, nr. prezentari, distributie status rezultat (queued/needs_data/needs_mapping/deduped).
  • Esecurile de auth (401 cheie invalida/lipsa in prod) emit api_auth_esuat cu IP + prefix cheie (nu cheia intreaga).
  • Niciun camp de payload PII integral (doar count + statusuri + coduri).
• Verificare E2E: POST ca VFP (cheie valida + invalida) → ambele apar in jurnal cu cont/rezultat.

US-005: Audit login RAR + ciclu de viata trimiteri (worker)

Ca operator vreau sa vad incercarile de login RAR si tranzitiile trimiterilor pentru ca "nu exista incercari de login vizibile" a fost o plangere directa.

• Depinde de: US-003
• Fisiere: app/worker/__main__.py (inlocuieste print(...) cu log_event), app/rar_client.py (eveniment login ok/esuat), tests/test_worker_observ.py
• Test intai (RED): tests/test_worker_observ.py — test_login_reusit_logat, test_login_401_logat_fara_parola, test_tranzitie_sent_si_error_logate
• Acceptance criteria:
  • Login RAR (reusit/esuat) → eveniment rar_login cu account_id, rezultat, cod HTTP; fara email/parola in clar (scrub).
  • Tranzitiile sending→sent / →needs_data / →error / reconciliere → evenimente cu submission_id, account_id, cod eroare din catalog.
  • print(...) existente din worker migrate la log_event (sursa=worker), fara a pierde mesajele in stdout (logul text ramane).
• Verificare E2E: o trimitere live pe RAR test (--send) → rar_login ok + sent cu idPrezentare in jurnal.

US-006: Tab "Jurnal" in dashboard (admin, filtrabil)

Ca admin vreau sa vad jurnalul in dashboard pentru ca sa diagnostichez fara SSH.

• Depinde de: US-003 (date), US-004/US-005 (continut util)
• Fisiere: app/web/routes.py (ruta /_fragments/jurnal + tab), app/web/admin_routes.py (gating admin daca e global), app/web/templates/_jurnal.html, tests/test_web_jurnal.py
• Test intai (RED): tests/test_web_jurnal.py — test_jurnal_doar_admin, test_filtru_pe_tip_si_data, test_non_admin_vede_doar_evenimentele_contului_sau
• Acceptance criteria:
  • Tab "Jurnal" cu lista paginata: ts, sursa, tip, nivel, cont, cod, mesaj (redactat).
  • Filtre: tip eveniment, nivel, interval data, (admin) cont. Scoped: un cont non-admin vede DOAR evenimentele proprii (regula NULL→cont 1, ca restul UI-ului).
  • Stil consistent cu tabelele PRD 5.5 (grila .tablewrap), AA light+dark.
  • Fara expunere de creds/PII (rendare din campuri deja redactate la scriere).
• Verificare E2E: browser HTMX pe / → tab Jurnal, filtrare pe rar_login/api_prezentari, scoping verificat cu 2 conturi.

US-007: Redactare PII/parole in jurnal (gard de siguranta)

Ca responsabil GDPR vreau garantia ca jurnalul nu scurge date sensibile pentru ca PII vehicul/proprietar + creds RAR nu au voie in loguri (L.142/GDPR).

• Depinde de: US-003
• Fisiere: app/security.py (extinde scrub/SENSITIVE_KEYS daca e nevoie), tests/test_jurnal_redactare.py
• Test intai (RED): tests/test_jurnal_redactare.py — test_parola_niciodata_in_app_events, test_vin_logat_partial, test_payload_integral_nu_se_logheaza
• Acceptance criteria:
  • Niciun rand app_events (sau linie fisier) nu contine password/token/ email creds in clar — verificat prin scanare la nivel de test.
  • VIN/nr inmatriculare se logheaza doar partial (ex. ultimele 4) sau hash scurt.
  • Test "fuzz": evenimente cu chei sensibile in context → toate mascate.
• Verificare E2E: provoaca eroare cu creds reale → cauta parola in app_events + fisier → 0 hits.

US-008: Retentie / purjare jurnal (GDPR)

Ca responsabil GDPR vreau ca jurnalul sa se auto-stearga dupa o perioada pentru ca retentia PII e limitata (acelasi mecanism ca submissions/import_batches).

• Depinde de: US-003
• Fisiere: app/worker/__main__.py (purge_expired extins pe app_events), app/schema.sql (purge_after), tests/test_jurnal_retentie.py
• Test intai (RED): tests/test_jurnal_retentie.py — test_app_events_primesc_purge_after, test_purjare_sterge_evenimente_expirate
• Acceptance criteria:
  • Fiecare rand app_events primeste purge_after = now + 90 zile (AUTOPASS_LOG_RETENTION_DAYS, default 90 — decizie §5).
  • Purjarea orara existenta (T16) sterge si app_events expirate.
  • Logul text foloseste RotatingFileHandler in aplicatie (rotatie pe dimensiune, N fisiere de backup) — decizie §5; nu depindem de deploy pentru rotatie.
• Verificare E2E: insereaza eveniment cu purge_after in trecut → rulează purjarea → dispare.

US-009: Backend — sterge + re-pune in coada randuri ne-sent (helper)

Ca operator vreau sa pot sterge sau re-pune in coada o trimitere blocata pentru ca un rand error (creds gresite) ramane altfel permanent si nereparabil.

• Depinde de: —
• Fisiere: app/submissions_admin.py (modul nou: delete_submission, requeue_submission), tests/test_submissions_admin.py
• Test intai (RED): tests/test_submissions_admin.py — test_sterge_rand_error_scoped, test_nu_sterge_sent_sau_sending, test_repune_error_devine_queued_reset_retry, test_repune_re_ruleaza_classify , test_scope_cross_account_404
• Acceptance criteria:
  • delete_submission(conn, account_id, sid) sterge randul DOAR daca e error/needs_data/needs_mapping SI apartine contului; altfel ridica/Intoarce refuz (sent/sending → interzis, cross-account → inexistent).
  • requeue_submission(conn, account_id, sid) muta error → queued, reseteaza retry_count=0, next_attempt_at=NULL, sending_since=NULL, re-ruleaza classify pe payload (poate ajunge needs_data/needs_mapping daca continutul cere).
  • Niciuna nu atinge sent (audit) sau sending (lease worker).
  • Ambele emit eveniment in jurnal (US-003): submission_sters / submission_repus.
• Verificare E2E: helper apelat din shell pe submission 15 → queued; pe un sent → refuz.

US-010: API v1 — sterge + re-pune in coada

Ca integrator ROAAUTO vreau endpointuri pentru a curata/relua trimiteri blocate pentru ca softul propriu sa gestioneze coada fara interventie manuala in DB.

• Depinde de: US-009
• Fisiere: app/api/v1/router.py (DELETE /v1/prezentari/{id}, POST /v1/prezentari/{id}/repune), tests/test_api_lifecycle.py
• Test intai (RED): tests/test_api_lifecycle.py — test_delete_scoped_pe_cheie, test_delete_sent_403, test_repune_error_queued, test_repune_inexistent_404
• Acceptance criteria:
  • DELETE /v1/prezentari/{id} → 200 + body JSON {ok, submission_id, status_anterior} (NU 204; clienti VFP string-parse) pe randuri ne-sent ale contului cheii.
  • Scope evaluat INAINTEA starii (decizie /autoplan #20): cross-account / inexistent → 404 (acelasi mesaj, B3 — nu confirmam existenta); own-account sent/sending → 409 (conflict de stare). Test test_delete_cross_account_sent_404.
  • POST /v1/prezentari/{id}/repune → randul devine queued (peste helper US-009).
  • Scoped strict pe contul cheii API (nu se poate atinge alt cont).
• Verificare E2E: cu cheia contului 2, POST .../15/repune → 200; worker il re-trimite (creds corecte).

US-011: Web dashboard — butoane Sterge / Re-pune in coada

Ca operator in dashboard vreau butoane pe randurile blocate pentru ca sa le gestionez vizual, fara API/SQL.

• Depinde de: US-009
• Fisiere: app/web/routes.py (rute POST /trimitere/{id}/sterge, POST /trimitere/{id}/repune, POST /trimiteri/sterge-bulk cu CSRF + PRG), app/web/templates/_trimitere_detaliu.html + lista Trimiteri (selectie), tests/test_web_lifecycle.py
• Test intai (RED): tests/test_web_lifecycle.py — test_buton_sterge_doar_pe_blocate, test_repune_din_ui_scoped_sesiune, test_csrf_enforce, test_bulk_sterge_doar_blocate_scoped
• Acceptance criteria:
  • Pe detaliul unui rand error: buton "Re-pune in coada" + "Sterge" cu dialog de confirmare simpla (decizie §5).
  • Pe lista Trimiteri: selectie multipla + "Sterge selectate" (bulk), pe modelul panoului admin (PRD 5.5); actioneaza DOAR pe randuri blocate ale contului.
  • Randuri sent/sending: fara butoane si neselectabile pentru stergere (read-only).
  • Scoped pe sesiune (regula NULL→cont 1); CSRF enforce; PRG dupa actiune.
  • Stil consistent cu corectia inline existenta + panoul admin bulk (PRD 5.5), AA light+dark.
• Verificare E2E: browser HTMX → pe submission 15 "Re-pune in coada" → dispare din "error", reapare ca trimis dupa worker; "Sterge" → dispare din lista.

US-012: Dedup nu mai e blocat de un rand error

Ca integrator vreau ca o retrimitere a aceluiasi payload (dupa ce am corectat parola) sa fie acceptata pentru ca azi un rand error cu aceeasi cheie o blocheaza tacit.

• Depinde de: — (atinge app/api/v1/router.py enqueue + import_router)
• Fisiere: app/api/v1/router.py (create_prezentari), app/api/v1/import_router.py (commit, daca aplica), tests/test_dedup_error.py
• Test intai (RED): tests/test_dedup_error.py — test_resubmit_peste_error_reactiveaza, test_resubmit_actualizeaza_creds_pe_reactivare, test_resubmit_peste_sent_ramane_deduped, test_resubmit_peste_queued_ramane_deduped
• Acceptance criteria:
  • La enqueue, daca randul existent cu aceeasi idempotency_key e error: se RE-ACTIVEAZA acelasi rand (re-ruleaza classify, actualizeaza rar_creds_enc cu creds-urile noi din cerere, reset retry_count/next_attempt_at, purge_after=NULL), si raspunsul poarta camp aditiv reactivated: true + starea noua (ex. queued); deduped ramane cu semantica actuala (decizie /autoplan #19, NU se repurpose-aza).
  • Reactivarea e un UPDATE compare-and-swap (WHERE id=? AND status='error'); daca rowcount==0 (alt POST/requeue a schimbat starea intre timp) -> raspuns dedup pe starea curenta. Worker-ul invalideaza sesiunea RAR cache-uita a contului cand randul claim-uit poarta rar_creds_enc != NULL (altfel JWT vechi 30h trimite cu parola gresita — vezi T1 anexa).
  • Creds noi se propaga si in accounts.rar_creds_enc (canal web durabil, decizie #17).
  • Pentru sent/queued/sending: comportament neschimbat → deduped: true (nu cream dubluri, nu deranjam in-flight/trimise).
  • needs_data/needs_mapping: raman deduped la resubmit (decizie §5) — corectia se face exclusiv prin UI (corectia inline existenta), nu prin re-trimiterea payload-ului.
  • Invariantul UNIQUE(idempotency_key) ramane (re-folosim randul, nu inseram al doilea).
• Verificare E2E: POST cu parola gresita → error; re-POST acelasi payload cu parola corecta → queued (nu deduped); worker trimite → sent.

US-013: Retentie / purjare randuri ne-sent blocate

Ca responsabil GDPR vreau ca si trimiterile blocate sa se auto-stearga dupa o perioada pentru ca altfel PII-ul lor ramane permanent (azi doar sent se purjeaza).

• Depinde de: —
• Fisiere: app/worker/__main__.py (mark seteaza purge_after si pe stari blocate; purge_expired extins pe error/needs_*), tests/test_purge_blocate.py
• Test intai (RED): tests/test_purge_blocate.py — test_error_primeste_purge_after, test_purjare_sterge_error_expirat, test_sent_si_blocate_retentii_separate_daca_difera
• Acceptance criteria:
  • Randurile care intra in error/needs_data/needs_mapping primesc purge_after (AUTOPASS_BLOCKED_RETENTION_DAYS, default 30 zile — decizie §5, mai scurt decat 90z sent).
  • Purjarea orara (T16) sterge si randurile blocate expirate, nu doar sent.
  • O re-activare (US-012) / re-pune in coada (US-009) reseteaza/curata purge_after (randul redevine activ, nu mai e candidat la purjare imediat).
• Verificare E2E: rand error cu purge_after in trecut → rulează purjarea → dispare.

US-014: "Necesita atentia ta" devine actionabil (link + identificare rand)

Ca operator vreau ca avertismentul de trimiteri blocate sa-mi spuna CARE prezentare a esuat si sa ma duca la ea pentru ca azi arata doar un contor ("Eroare la trimitere (1)"), fara VIN/id/link — nu pot actiona, iar banner-ul nu se stinge niciodata cat timp exista error.

• Depinde de: — (UI peste filtrul existent /_fragments/submissions?status=); se imbina natural cu US-011 (butoane sterge/re-pune in coada) si US-013 (purjare → banner se stinge)
• Fisiere: app/web/templates/_status.html, app/web/routes.py (_render_status/ fragment status — expune si identificatorii randurilor blocate, nu doar contoare), tests/test_web_status_fragment.py
• Test intai (RED): tests/test_web_status_fragment.py — test_categorie_blocata_linkeaza_la_trimiteri_filtrate, test_status_arata_identificator_rand_blocat, test_scoped_pe_cont
• Acceptance criteria:
  • Fiecare categorie din "Necesita atentia ta" e link catre lista "Trimiteri" filtrata pe acea stare (deep-link ?tab=...&status=error etc.), scoped pe cont.
  • Sub fiecare categorie se afiseaza identificatorul randurilor blocate (VIN partial
    • nr inmatriculare + #id), cel putin pentru primele N, cu "...si inca M" daca sunt mai multe.
  • Banner-ul dispare cand nu mai exista randuri blocate (consecinta US-009/011/013: stergere / re-pune in coada / purjare → contor 0 → sectiunea nu se mai randeaza).
  • Nimic nou expus fara scope (regula NULL→cont 1); PII doar partial (ca jurnalul, US-007).
• Verificare E2E: browser HTMX → "Eroare la trimitere (1)" arata #15 WVW…0001 / B123ABC si linkeaza in Trimiteri filtrat pe error; dupa re-pune in coada + sent, banner-ul dispare.

4. Riscuri

• Scriere DB pe calea fiecarei cereri (US-004) poate adauga latenta/contentie pe SQLite (WAL). Mitigare: insert minimal, best-effort, nivel filtrat; eveniment per cerere agregat (1 rand), nu per camp. De masurat la VERIFY.
• Scurgere PII e riscul central. Mitigare: redactare la SCRIERE (nu la afisare), testata adversarial (US-007); nimic din payload integral nu intra in jurnal.
• Volum jurnal poate umfla DB-ul. Mitigare: retentie + nivel (US-008), INFO default.
• Dublu canal divergent (DB vs fisier). Mitigare: un singur log_event ca sursa unica (US-003), ca dry-run/erori la PRD 5.2/5.4 — imposibil de divergat.
• Migrare schema app_events. Mitigare: migrare defensiva idempotenta in _migrate (ca accounts.active/override_json).
• US-012 schimba semantica deduped la enqueue. Risc: re-activare nedorita a unui rand trimis. Mitigare: re-activarea e strict pe error (nu sent/queued/sending); teste explicite pe fiecare stare; UNIQUE(idempotency_key) garanteaza un singur rand per continut.
• Re-pune in coada cu creds gresite (US-009/010/011): daca creds-urile contului sunt inca gresite, randul re-intra in error. Acceptat — actiunea nu garanteaza succesul, doar reda dreptul la o noua incercare; jurnalul (US-005) arata de ce a reesuat.

5. Decizii (rezolvate cu utilizatorul — poarta de aprobare PRD)

Rezolvate 2026-06-23. Sunt obligatorii pentru executie.

• Retentie jurnal: 90 zile (aliniat cu submissions/import_batches). [US-008]
• Tipuri de evenimente: lista extensibila, nu fixata acum — tip e text liber documentat, adaugam tipuri pe parcurs fara migrare. [US-003]
• Log text: RotatingFileHandler in aplicatie (rotatie pe dimensiune; nu depindem de deploy). [US-008]
• Vizibilitate jurnal: non-admin vede DOAR evenimentele contului sau; adminul vede tot, cu filtru pe cont. [US-006]
• Resubmit peste blocate (US-012): doar error se re-activeaza (re-ruleaza classify
  • actualizeaza creds). needs_data/needs_mapping raman deduped — corectia exclusiv prin UI (corectia inline existenta). sent/queued/sending raman deduped (neschimbat).
• Retentie randuri blocate (US-013): 30 zile (mai scurt decat cele 90 ale sent; un blocat n-are valoare de audit ca o trimitere reusita). Configurabil prin AUTOPASS_BLOCKED_RETENTION_DAYS, default 30.
• Stergere din UI (US-011): confirmare simpla (dialog) + actiune in bloc pe lista (selectie multipla + "Sterge selectate"), pe modelul panoului admin (PRD 5.5).

6. Valuri de executie (graful de dependente)

Val 1: [US-002 request_id] [US-003 logger+schema]   ← fundatii, fisiere disjuncte → paralel
Val 2: [US-001 handler 500] [US-004 audit API] [US-005 audit worker] [US-007 redactare]
                                                     ← deblocate de US-003 (+US-002)
Val 3: [US-006 tab Jurnal] [US-008 retentie]         ← consuma datele/coloanele din Val 1-2

--- Lifecycle trimiteri blocate (independent de observabilitate; poate rula in paralel) ---
Val A: [US-009 helper sterge/repune] [US-012 dedup peste error] [US-013 retentie blocate]
                                                     ← fisiere disjuncte, fara dependente
Val B: [US-010 API lifecycle] [US-011 UI lifecycle] [US-014 banner actionabil]
                                                     ← deblocate de US-009 (US-014 indep., dar grupat cu UI)

Nota scope: 5 stories de lifecycle (US-009..US-013) in loc de 3 din schita initiala — regula proiectului separa backend + UI in stories distincte (helper / API / UI). Daca vrei livrare mai mica, US-010 (API) e optional pentru un MVP "doar dashboard".

---

Anexa /autoplan — Raport de review (2026-06-23)

Generat de /autoplan (CEO -> Design -> Eng -> DX), commit f48346d, branch main. Voci: Claude subagent per faza + Codex. Codex INDISPONIBIL (usage limit la runtime) -> toate fazele ruleaza [subagent-only]. Premisa "app_events table + tab Jurnal" confirmata de utilizator la poarta de premise (vs alternativa stdout-first). Restore point: vezi comentariul HTML din capul fisierului.

Consensus tables (Codex = N/A, subagent-only)

CEO:    1 premise flagged (substrate, CONFIRMAT keep) · 3 right-problem/scope · 4 alt-uri necomparate
DESIGN: 3 high (poll vs select, deep-link inexistent, banner->panel) · stari lipsa
ENG:    2 CRITICAL (US-012 race+JWT stale, purge_after) · 0 concurrency tests · WAL contention
DX:     5 high (500 envelope 6 chei, 403/404 oracle, deduped breaking, docs, rar_error allowlist)

Diagrame

US-012 reactivare error — masina de stari + cursa (fix necesar T1):

  POST /v1/prezentari (acelasi payload, parola corectata)
        |
        v
  SELECT status WHERE idempotency_key=?  ---- error ----> UPDATE ... SET status='queued',
        |                                                  rar_creds_enc=<nou>, retry=0,
        | sent/queued/sending/needs_*                       next_attempt_at=NULL,
        v                                                   purge_after=NULL
   deduped:true (neschimbat)                                      |
                                                                  v
   CURSA (fara CAS):  worker.claim_one (BEGIN IMMEDIATE) queued->sending
   CURSA (JWT):       AccountSessions[account_id] are token vechi (30h) din creds GRESITE
                      -> trimite cu parola veche, ignora corectia  <-- BUG CENTRAL
   FIX: UPDATE ... WHERE id=? AND status='error' (CAS; rowcount 0 -> deduped) +
        la claim, daca randul poarta rar_creds_enc != NULL -> sessions.invalidate(account_id)

Retentie / purjare (fix T2):

  mark(sent)     -> purge_after = now + 90z   (existent)
  mark(blocate)  -> purge_after = now + 30z   (US-013 nou; error/needs_data/needs_mapping)
  reactivare/    -> purge_after = NULL        (US-009/012; ALTFEL purjat inainte de claim)
   re-pune coada
  purge_expired WHERE purge_after<now AND status IN ('sent','error','needs_data','needs_mapping')
                EXCLUDE explicit 'queued'/'sending'

Failure Modes Registry (noi, din review)

  CODEPATH                         | FAILURE MODE                  | RESCUED? | TEST? | USER SEES        | LOGGED?
  ---------------------------------|-------------------------------|----------|-------|------------------|--------
  create_prezentari reactivare     | cursa cu claim_one / 2x POST  | FIX T1   | FIX T3| queued det.      | US-004
  worker JWT cache dupa creds noi  | trimite cu parola veche       | FIX T1   | FIX T3| ramane error     | US-005  <- CRITICAL
  reactivare fara purge_after=NULL | purjat inainte de claim       | FIX T2   | FIX T3| dispare tacit    | US-005  <- CRITICAL
  log_event own-conn pe hot path   | WAL write-lock pana la 15s    | FIX T4   | da    | latenta POST     | -
  RotatingFileHandler 2 procese    | rotatie rename race           | FIX T5   | n/a   | log corupt       | -
  500 envelope 4 chei              | parser client crapa pe 5xx    | FIX T7   | da    | KeyError client  | US-001
  403 sent vs 404 cross-acct       | oracol de existenta           | FIX TD2  | da    | leak             | US-004
  bulk select vs poll 15s          | selectie stearsa mid-actiune  | FIX T12  | da    | frustrare        | -
  deep-link status inexistent      | banner duce la lista nefiltr. | FIX T13  | da    | dead-end         | -

Decision Audit Trail (auto-decis cu cele 6 principii)

#	Faza	Decizie	Clasificare	Principiu	Rationament
1	CEO	Premisa app_events table + tab	GATE (user)	-	Confirmat de utilizator: web-visibility e scop de produs (operator fara SSH)
2	Eng	US-012 = CAS guarded + invalidare sesiune worker la creds noi (T1)	Mechanical	P1 completeness	Bug central; fara el US-012 nu-si atinge scopul
3	Eng	reactivare/requeue purge_after=NULL; purge exclude queued/sending (T2)	Mechanical	P1	Altfel randul reactivat e purjat tacit
4	Eng	teste concurenta + purge-before-claim (T3)	Mechanical	P1 well-tested	Lista de teste US-012 era single-thread
5	Eng	log_event(conn opt) reuse hot-path (T4)	Mechanical	P3 pragmatic	Evita contentie WAL
6	Eng	log-uri per-proces api.log/worker.log (T5)	Mechanical	P5 explicit	RotatingFileHandler nu e multiproces-safe
7	Eng	vin_partial() + context curat (T6)	Mechanical	P1	scrub() nu acopera VIN (US-007)
8	DX	EROARE_INTERNA in CATALOG; 500 = 6 chei + request_id (T7)	Mechanical	P1	Contract 6 chei (PRD 5.4)
9	DX	X-Request-ID pe TOATE raspunsurile (T8)	Mechanical	P1	Corelare si pe 422/401/404
10	DX	rar_error in _PREZENTARE_FIELDS (T9)	Mechanical	P6 action	Recovery API observabil fara dashboard
11	DX	update api-rar-contract.md + reconcile de-scope (T10)	Mechanical	P1	Sursa de adevar trebuie sa includa endpointurile noi
12	DX	DELETE -> 200+JSON, nu 204 (T11)	Mechanical	P5	Consistent cu restul v1; clienti VFP string-parse
13	Design	poll vs bulk-select rezolvat (T12)	Mechanical	P1	Selectie stearsa la 15s = defect
14	Design	plumbing deep-link status (T13)	Mechanical	P1	Destinatia US-014 nu exista azi
15	Design	banner -> panou detaliu (T14)	Mechanical	P3	Duce direct la butonul de actiune
16	Design	stari empty/loading/partial + collision checkbox (T15)	Mechanical	P1	Acoperire stari = scope, nu afterthought
17	CEO	REZOLVAT: DA — resubmit/requeue cu creds noi reimprospateaza si accounts.rar_creds_enc (T16)	Taste	P1	Utilizator: ambele canale converg pe parola corectata
18	CEO	REZOLVAT: pastram bundled, lifecycle (Val A) PRIMUL	Taste	P6	Utilizator: §6 izoleaza deja valurile; overhead minim pe PRD aprobat
19	DX	REZOLVAT: camp aditiv reactivated:true (NU repurpose deduped)	Taste	P5	Utilizator: backward-compat pentru clienti care testeaza deduped
20	DX	REZOLVAT: cross-account 404 INAINTE de verificare status; own-account sent/sending -> 409	Taste(sec)	P1	Utilizator: inchide oracolul de existenta (B3)

Decizii /autoplan rezolvate la poarta finala (2026-06-23, obligatorii pentru executie)

• Bundling [#18]: PRD 5.6 ramane unitar; ordinea de executie pune Val A (lifecycle: US-009/012/013/011/014) inaintea observabilitatii. Un singur VERIFY.
• US-012 raspuns [#19]: la reactivarea unui rand error se intoarce camp aditiv reactivated: true pe SubmissionResult (NU se repurpose-aza deduped). deduped ramane cu semantica actuala; clientii vechi nu se sparg. Update app/models.py + contract.
• US-010 coduri [#20]: scope-ul (cross-account) se evalueaza inaintea starii. Cross-account / inexistent -> 404 (acelasi mesaj, B3). Own-account sent/sending -> 409 (conflict de stare, nu 403). Test nou test_delete_cross_account_sent_404.
• US-009/012 creds [#17]: cand resubmit/requeue aduce creds noi, se reimprospateaza si accounts.rar_creds_enc (canalul web durabil), nu doar submissions.rar_creds_enc. Combinat cu invalidarea sesiunii worker (T1).

Implementation Tasks (auto-generate, vezi JSONL ~/.gstack/projects/romfast-rar-autopass/)

P1 (blocheaza ship): T1 (US-012 CAS+sesiune), T2 (purge_after), T3 (teste concurenta), T4 (log_event conn), T5 (log per-proces), T7 (500 6-chei), T8 (X-Request-ID global), T9 (rar_error allowlist), T10 (docs contract), T12 (poll vs select), T13 (deep-link). P2 (acelasi branch): T6 (vin_partial), T11 (DELETE 200+body), T14 (banner->panou), T15 (stari UI), T16 (creds web).

Completion Summaries

  CEO     | premise 1 (confirmat keep) · right-problem OK (lifecycle=10x) · 1 challenge bundling · F6 creds web
  DESIGN  | 3 high (poll/select, deep-link, banner) · stari lipsa · checkbox collision · AA de verificat
  ENG     | 2 CRITICAL (race+JWT, purge) · 0 concurrency tests · WAL contention · IDOR ordine 404
  DX      | 5 high (500 envelope, oracle, deduped, docs, rar_error) · recovery matrix per-stare de documentat
  Lake    | toate auto-deciziile au ales optiunea completa (16/16 mechanical = ADD/fix complet)

Raport VERIFY

Executie completa 2026-06-23 (TDD, RED->GREEN per story). Toate cele 14 stories livrate.

Rezultat teste

python3 -m pytest -q -> 741 passed, 0 failed (~64s). Baseline inainte de 5.6: 561 teste (restul de 114 "esecuri" de la pornire erau artefact de mediu — .env-ul de testare live are AUTOPASS_REQUIRE_API_KEY=true; rulat cu override-urile standard de test, baseline-ul e verde). Teste noi adaugate (toate verzi):

• US-001 tests/test_error_handler.py (5) — 500 structurat 6-chei + request_id, fara traceback/creds.
• US-002 tests/test_request_id.py (4) — X-Request-ID pe toate raspunsurile, contextvar.
• US-003 tests/test_observ.py (4) — dublu canal DB+fisier, redactare, nivel din env, best-effort.
• US-004 tests/test_audit_api.py (3) — api_prezentari (count+distributie), api_auth_esuat (IP+prefix).
• US-005 tests/test_worker_observ.py (3) — rar_login ok/esuat fara parola, tranzitii sent/error.
• US-007 tests/test_jurnal_redactare.py (4) — parola/token/VIN niciodata integral; fuzz chei sensibile.
• US-006 tests/test_web_jurnal.py (5) — scope non-admin/admin, filtru tip/nivel/cont, deep-link tab.
• US-008 tests/test_jurnal_retentie.py (5) — purge_after pe app_events, purjare, RotatingFileHandler.
• US-009 tests/test_submissions_admin.py (6) — sterge/repune scoped, 404 cross-account, classify la repune.
• US-010 tests/test_api_lifecycle.py (7) — DELETE/repune 200+JSON, scope-before-state (404 vs 409).
• US-011 tests/test_web_lifecycle.py (7) — butoane doar pe blocate, CSRF, bulk scoped.
• US-012 tests/test_dedup_error.py (5) — reactivare peste error + reactivated:true, creds noi; sent/queued/needs_* raman deduped.
• US-013 tests/test_purge_blocate.py (5) — purge_after pe blocate (30z), purjare exclude queued/sending.
• US-014 tests/test_web_status_fragment.py (+3) — categorie linkeaza la lista filtrata, identificator partial, scope.

Fix-uri tehnice cheie (din /autoplan)

• T1 (CRITICAL): reactivarea e UPDATE compare-and-swap (WHERE id=? AND status='error'); worker-ul invalideaza sesiunea RAR cache-uita cand randul claim-uit poarta rar_creds_enc != NULL (JWT vechi 30h din parola gresita nu mai trimite). Creds noi se propaga si in accounts.rar_creds_enc.
• T2: reactivare/requeue seteaza purge_after=NULL; purge_expired exclude explicit queued/sending.
• T7: 500 = envelope 6-chei (catalog) + request_id. T8: X-Request-ID pe TOATE raspunsurile (middleware).
• T9: rar_error in allowlist-ul GET /v1/prezentari/{id} (recovery observabil; test vechi actualizat).

Note

• Teste modificate intentionat (comportament schimbat de PRD): test_t16_purjare (error primeste acum purge_after — US-013), test_get_scope_prezentari (rar_error expus acum — T9).
• E2E live pe RAR test: NEPROBAT in aceasta sesiune (necesita creds RAR test + --send). Backend-ul de trimitere e neatins ca logica; modificarile worker sunt aditive (evenimente + invalidare sesiune la creds noi). Recomandat la deploy: o trimitere --send pentru a confirma rar_login ok + submission_sent in jurnal.