docs: PRD 5.6 observabilitate + jurnal + lifecycle trimiteri blocate (APROBAT)

Nascut din incidentul 500 (client VFP). 14 stories: observabilitate
(handler global 500->3 niveluri, request_id, jurnal app_events DB+fisier,
audit API + login RAR, redactare PII, retentie), lifecycle trimiteri
blocate (sterge/re-pune in coada UI+API, dedup nemaiblocat de un rand
error, purjare blocate) si banner "Necesita atentia ta" actionabil.
Decizii §5 rezolvate cu user. ROADMAP: rand 5.6 APROBAT + hotfix in
"Ultima actualizare".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Agent
2026-06-23 13:55:12 +00:00
parent 0b288b90d7
commit f48346de5c
2 changed files with 421 additions and 1 deletions

File diff suppressed because one or more lines are too long

View File

@@ -0,0 +1,419 @@
# PRD 5.6 — Observabilitate, jurnal aplicatie & lifecycle trimiteri blocate
**Stare**: aprobat (decizii §5 rezolvate 2026-06-23)
> 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/204 pe randuri ne-sent ale contului cheii;
403 pe `sent`/`sending`; 404 cross-account/inexistent (acelasi mesaj, ca B3).
- [ ] `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`), si raspunsul
NU mai e `deduped: true` ci starea noua (ex. `queued`).
- [ ] 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".
---
## 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.