# 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=, 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 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.