# AutoPass — Roadmap & Proces de Dezvoltare

> **Sursa unica de progres + procesul de lucru.** O sesiune noua are nevoie doar de promptul:
> *"Citeste docs/ROADMAP.md si continua roadmap-ul [optional: livrabila X.Y]."*
> Sesiunea isi detecteaza singura faza (§5.7), planifica SAU executa, verifica si inchide —
> cu doua porti umane: aprobarea PRD-ului si confirmarea commit-ului.
>
> Contractul RAR (sursa de adevar de contract) = `docs/api-rar-contract.md`. Acolo unde un plan
> difera de contract, **contractul are dreptate**.
>
> Status fara emoji (preferinta proiect): **TODO** neinceput · **WIP** in lucru · **DONE** gata ·
> **BLOCAT** blocat de o dependenta · **AMANAT** deferat/taiat cu motiv.

---

## 1. Context

Gateway central care declara prestatiile de service-auto la **RAR AUTOPASS** (Legea 142/2023,
OM 210/2024), portat din clasa Visual FoxPro `RarAutoPass` (ROAAUTO). Stack: **Python/FastAPI +
SQLite (WAL) + httpx + Jinja2/HTMX**. Un container (API) + un proces separat (worker).

Doua canale de intrare, ambele **LIVE pe endpoint-ul de test RAR**:
- **Treapta 1** — canal API (`POST /v1/prezentari`) pentru ROAAUTO / soft propriu.
- **Treapta 2** — import xlsx/csv + mapare coloane + UI web (HTMX) pentru service-uri non-ROA.

---

## 2. Arhitectura (rezumat)

```
  Canal API (ROAAUTO)  ─┐
  Upload web (xlsx/csv) ─┴─▶ Gateway FastAPI ─▶ validare → mapare op→cod → enqueue (PII criptat)
                                  │
                                  ▼
                             WORKER (proces separat): claim atomic → login RAR → postPrezentare → retry
                                  │
  Dashboard (Jinja2+HTMX) ◀───────┴── monitorizare live RAR + coada + editor mapari + audit CSV
```

Reguli de contract (detalii in `docs/api-rar-contract.md`): `FINALIZATA` e terminal la RAR
(fara anulare/corectie prin API); idempotency = hash de continut server-side; JWT TTL = 30h.

---

## 3. Stadiu Implementare (dashboard)

> **Singurul loc din document care se modifica pe parcurs.** Detaliile NU intra aici — stau in
> PRD-uri (`docs/prd/prd-X.Y-*.md`), linkate in coloana Detalii. La fiecare livrabila terminata:
> schimba statusul + data + linkul PRD si actualizeaza "Ultima actualizare".

**Ultima actualizare**: 2026-06-18 — 3.4 LIVRAT (interfata web ergonomica: tab-uri + wizard + microcopy). US-001 modul pur `app/web/labels.py` (stari tehnice→text uman + clasa CSS; test parametrizat din CHECK-ul `schema.sql` iese rosu la stare nemapata). US-002 bara status `/_fragments/status` + `_status.html` (etichete umane, defalcare blocate pe motiv, poll 15s, scoped pe cont). US-003 shell 6 tab-uri (Acasa·Import·Coada·Mapari·Cont·Nomenclator) cu deep-link `?tab=`, panou activ randat server-side, fragmente inactive lazy pe click, ARIA real (tablist/tab/tabpanel + aria-selected + navigare cu sageti). US-004 stepper import 4 pasi (PUR vizual, `hx-target="#import-section"` + csrf pastrate). US-005 Acasa onboarding checklist auto-bifat (are_creds/are_trimiteri) + colaps cand totul gata + empty states prietenoase Coada/Mapari. VERIFY lead-driven (TestClient ACs + 434 pytest pass; E2E browser/RAR LIVE neprobat in sesiune — recomandata probare manuala `--send`). Fix izolare teste (reset `ratelimit._hits` in fixturi, 429 la rulare subset). `/code-review` high: regasit avertisment "cont in asteptare de activare" (regresie din scoaterea `/_fragments/banner`) re-introdus in bara status + culori hardcodate→variabile paleta. 434 teste pass. Backend trimitere neatins. PRD: [prd-3.4](prd/prd-3.4-ux-dashboard-web.md). Urmeaza Etapa 4 (4.1 mapare AI/MCP).

> 3.3b LIVRAT (self-service cheie/creds + admin web + email). US-007 rute web proprii pentru rotire cheie + setare creds RAR scoped pe sesiune (C13, nu endpointul API). US-010 rol admin (`users.is_admin`) + `require_admin`→`AdminRequired`→403 + CLI `tools/account.py set-admin` + bootstrap automat (primul cont care se inregistreaza = admin, citit in `BEGIN IMMEDIATE` anti-race). US-011 panou `/admin` (conturi in asteptare/active, activare/dezactivare cu CSRF + PRG, contul dev id=1 protejat) + link "Panou admin" pe dashboard doar pentru admini + buton logout. US-012 `app/email.py notify_signup` best-effort DEGRADAT fara SMTP (no-op + log, prinde orice exceptie, nu blocheaza signup) + config `smtp_*`. Fix migrare defensiva `users.is_admin`/`email_verified` in `_migrate` (gap prins de VERIFY r1, ca C1 pe `accounts.active`). 2 runde VERIFY context curat (r2 PASS, sweep securitate toate rutele noi sub require_login/require_admin + CSRF, scoped sesiune). `/code-review` high: TOCTOU bootstrap mutat in tranzactie + `_render_admin` extras (anti-duplicare + N+1). 393 teste pass. Urmeaza Etapa 4 (4.1 mapare AI/MCP). Deferat din 3.1 (P3): `rename`/`set-cui`, `--if-not-exists`. SMTP real = follow-up pe US-012.

> 3.3a LIVRAT (self-onboarding web core: `app/users.py` parole scrypt cu eticheta de parametri onorata la verify; `SessionMiddleware` same_site=strict + `app/web/session.py` guard `require_login`→`LoginRequired`; CSRF per-sesiune enforce in prod inclusiv pe login/signup + rate-limit signup & login in-proces; signup `active=0` tranzactie atomica + cheie-o-data + log `SIGNUP`; login/logout; dashboard & import multi-tenant scoped pe sesiune cu regula NULL→cont 1 — toate rutele web care ating date sensibile sub `require_login` + scope; gate worker `claim_one` `LEFT JOIN ... COALESCE(active,1)=1`. 2 runde VERIFY context curat — runda 1 a prins un leak cross-account pe `/_fragments/mapari`, reparat; runda 2 PASS. `/code-review` high a prins 3 findings, reparate. 361 teste pass). Urmeaza 3.3b (self-service cheie/creds + admin web + email). Deferat din 3.1 (P3): `rename`/`set-cui`, `--if-not-exists`.

### Etapa 1 — Canal API ROAAUTO (Treapta 1)

| # | Livrabila | Status | Data | Detalii |
|---|-----------|--------|------|---------|
| 1.1 | Gateway complet: validare + mapare + coada + worker + reconciliere + dashboard | DONE | 2026-06-15 | E2E LIVE prin gateway: `POST /v1/prezentari` → worker → `FINALIZATA` la RAR test (`idPrezentare=68516`). Cod `app/`, 279 teste. |

### Etapa 2 — Import xlsx/csv + UI web (Treapta 2)

| # | Livrabila | Status | Data | Detalii |
|---|-----------|--------|------|---------|
| 2.1 | Parser xlsx/csv 2-treceri + staging criptat (`POST /v1/import`) | DONE | 2026-06 | `app/import_parse.py`; encoding RO, delimiter sniff, coercion, robustete sheet/merged/footer |
| 2.2 | Creds RAR durabile per-cont + worker re-login fallback | DONE | 2026-06 | `accounts.rar_creds_enc`, gate purjare worker |
| 2.3 | `batch_id` scope `reresolve_account` (inchide R1 bulk-send) | DONE | 2026-06 | `app/mapping.py` |
| 2.4 | Mapare coloane + semnatura + detectie drift + fuzzy | DONE | 2026-06 | `app/api/v1/import_router.py` |
| 2.5 | Preview 6 stari + canonicalize partajat + gate HARD + atestare | DONE | 2026-06 | `duplicate_in_file`, `already_sent`, `needs_review`, `import_attestations`, TOCTOU `ON CONFLICT` |
| 2.6 | UI web upload HTMX (drop → mapare → preview → confirma) | DONE | 2026-06 | `app/web/templates/_upload.html`, `_mapcoloane.html`, `_preview_import.html` |
| 2.7 | Export randuri esuate CSV + job purjare `purge_after` + E2E | DONE | 2026-06 | `export_failed_rows`, `tests/test_import_e2e.py` |

### Etapa 3 — Multi-cont / self-onboarding (URMATORUL FOCUS)

| # | Livrabila | Status | Data | Detalii |
|---|-----------|--------|------|---------|
| 3.1 | Creare cont nou (CLI dedicat) | DONE | 2026-06-17 | CLI `tools/account.py` (create/list[--pending]/activate/deactivate, `--with-key` atomic) + `accounts.active` + index unic CUI + `app/accounts.py`. 20 teste noi. PRD: [prd-3.1](prd/prd-3.1-creare-cont.md) |
| 3.2 | Filtrare pe cont a GET-urilor de listare | DONE | 2026-06-17 | scope cheie pe `/v1/prezentari(/{id})`, `/v1/mapari(/pending)`, `/v1/audit/export` (NULL→cont 1); nomenclator global; 404 cross-account identic (B3) + allowlist campuri detaliu (B4) + helper `account_scope_clause` (B2) + index (B5). 14 teste noi, 313 pass. PRD: [prd-3.2](prd/prd-3.2-filtrare-cont-get.md) |
| 3.3a | Self-onboarding web (core) | DONE | 2026-06-17 | `users` (scrypt) + sesiune (`SessionMiddleware`, same_site=strict) + CSRF (enforce prod, inclusiv login/signup) + rate-limit signup/login + signup/login/logout + dashboard & import scoped pe sesiune (NULL→1, anti-leak C6) + gate worker `active=0` (`COALESCE`). 2 runde VERIFY (leak `/_fragments/mapari` prins+reparat) + code-review (csrf erori, scrypt_params, login rate-limit). 361 teste. PRD: [prd-3.3](prd/prd-3.3-self-onboarding-web.md) |
| 3.3b | Self-service cheie/creds + admin web + email | DONE | 2026-06-18 | US-007 (rute web proprii `/cont/roteste-cheie`+`/cont/rar-creds` scoped sesiune, C13), US-010 (rol admin `is_admin` + `require_admin`→403 + CLI `set-admin` + bootstrap primul cont=admin), US-011 (`/admin` activare/dezactivare cu CSRF+PRG, link doar pt admini + logout), US-012 (`app/email.py` notify best-effort degradat fara SMTP + log `SIGNUP`). Fix migrare defensiva `users.is_admin`/`email_verified`. 2 runde VERIFY context curat (r1 a prins migrarea lipsa, reparat; r2 PASS) + `/code-review` high (TOCTOU bootstrap admin mutat in tranzactie + extras `_render_admin` anti-duplicare/N+1). 393 teste. PRD: [prd-3.3](prd/prd-3.3-self-onboarding-web.md) |
| 3.4 | Interfata web ergonomica (tab-uri + wizard + microcopy uman) | DONE | 2026-06-18 | Dashboard reorganizat in 6 tab-uri (Acasa·Import·Coada·Mapari·Cont·Nomenclator) cu deep-link `?tab=` + panou activ server-side + lazy pe rest; bara status cu etichete umane (`app/web/labels.py`) + defalcare blocate; import ca stepper 4 pasi (PUR vizual); Acasa onboarding auto-bifat + empty states. Backend trimitere neatins. 434 teste. PRD: [prd-3.4](prd/prd-3.4-ux-dashboard-web.md) |

### Etapa 4 — Viitor (Treapta 3)

| # | Livrabila | Status | Data | Detalii |
|---|-----------|--------|------|---------|
| 4.1 | Mapare AI / conector MCP (sugestie peste fuzzy) | TODO | | |
| 4.2 | Editare/anulare prezentari trimise | BLOCAT | | `FINALIZATA` terminal la RAR — fara flux API; corectia = suport RAR |

### Amanat / taiat (cu motiv)

| Livrabila | Status | Motiv |
|-----------|--------|-------|
| Drop-fisier SFTP / email-to-import | AMANAT | Valideaza intai upload-ul manual (wedge-ul real), apoi re-evalueaza |
| Contor volum + prag freemium | AMANAT | Metrici de pret inainte sa existe useri; trivial de adaugat post-validare |
| Billing complet (Stripe etc.) | AMANAT | Dupa validarea pragului de volum |

---

## 4. Open questions / riscuri acceptate

- **Un cont = un agent RAR sau mai multi** — afecteaza maparea creds in UI + filtrarea monitorizarii.
  Relevant pentru Etapa 3.
- **Valori reale `sistemReparat`** — azi se trimite `"null"`; ce alte valori accepta RAR ramane de probat.
- **R4 (acceptat constient):** creds RAR durabile-at-rest (Treapta 2) → la scurgerea cheii Fernet toate
  parolele sunt decriptabile (vs. doar in-flight pe canalul API). Mitigare: rotatie cheie + redactare loguri.

---

## 5. Proces de implementare

### 5.1 Principii

1. **PLAN separat de EXECUTE/VERIFY, pe sesiuni distincte.** Planificarea consuma mult context
   (model puternic) si produce **PRD-ul** ca artefact de predare. Executia reia intr-o **sesiune noua**
   bazat doar pe PRD — nu pe transcriptul planificarii. **Starea persista in PRD**, nu in conversatie.
2. **TDD ca contract:** testul scris ÎNAINTE = forma executabila a criteriilor de acceptare. Un worker
   cu test rosu clar nu poate declara fals victoria — testul decide.
3. **Story atomic = unitate de paralelizare SI de rollback:** un story = un commit logic = un worker =
   un test-suite verde.
4. **VERIFY in context curat:** un subagent dedicat care primeste DOAR PRD-ul + instructiunile §5.6,
   NU transcriptul executiei (altfel mosteneste partinirea de confirmare a celui care a implementat).
5. **Single writer:** doar sesiunea lead scrie in PRD, ROADMAP si git. Workerii scriu doar cod si teste.
6. **E2E pe canalul real:** un flux se verifica prin canalul lui (upload web prin browser, API prin
   `POST /v1/prezentari`), nu doar prin apel intern. RAR test = endpoint real.

### 5.2 Cele 4 faze (separabile pe sesiuni)

```
  SESIUNE A (Opus/Fable)            SESIUNE B (lead + agent team Sonnet)
  ┌─────────────────────┐          ┌──────────────────────────────────────────────────┐
  │ FAZA 1: PLAN        │  PRD     │ FAZA 2: EXECUTE   FAZA 3: VERIFY   FAZA 4: CLOSE   │
  │ citeste ROADMAP+cod │  aprobat │ TeamCreate +      subagent context  /code-review   │
  │ scrie PRD (stories  │ ───────▶ │ workeri Sonnet    curat: pytest +   writeback dash │
  │ atomice + teste)    │ (in PRD) │ TDD per story     E2E RAR test      propune commit  │
  │ plan-reviews gstack │          │ lead bifeaza PRD  raport in PRD                     │
  │  ▼ POARTA UMANA     │          │                                     ▼ POARTA UMANA  │
  │  aprobare PRD       │          │                                     confirmare commit│
  └─────────────────────┘          └──────────────────────────────────────────────────┘
```

PLAN poate rula singur intr-o sesiune (scump, model puternic) si se opreste la poarta de aprobare.
EXECUTE → VERIFY → CLOSE reiau intr-o sesiune noua din PRD-ul aprobat. Pot fi si inlantuite in
aceeasi sesiune daca vrei — starea din PRD le face reluabile oricum.

### 5.3 PRD per livrabila

- **1 PRD per livrabila** din dashboard: `docs/prd/prd-X.Y-<slug>.md` (skill `/prd`).
- Prima linie dupa titlu: `**Stare**: draft` (vezi §5.7 pentru tranzitii).
- Contine obligatoriu: obiectiv, **Non-Goals** (anti scope-creep), stories atomice (§5.4),
  riscuri, intrebari deschise (rezolvate cu utilizatorul ÎNAINTE de executie), graful de valuri.
- PRD-ul **nu repeta** strategia/contractul — le linkeaza (`docs/api-rar-contract.md`, acest ROADMAP).
- **Review-uri de plan** (aplicate IN PRD inainte de cod): `/plan-ceo-review` (valoare/scope) +
  `/plan-eng-review` (fezabilitate/teste) — obligatorii; `/plan-design-review` — doar daca atinge UI.

### 5.4 Story atomic (template)

```markdown
### US-003: <titlu scurt>
**Ca** <rol> **vreau** <capabilitate> **pentru ca** <motiv>.

- **Depinde de**: US-001
- **Fisiere**: `app/<modul>.py`, `app/web/templates/<x>.html` (~N fisiere)
- **Test intai (RED)**: `tests/test_<x>.py` — `test_<caz_1>`, `test_<caz_2>`
- **Acceptance criteria**:
  - [ ] <criteriu testabil 1>
  - [ ] <criteriu testabil 2>
- **Verificare E2E**: <browser HTMX / POST /v1/prezentari pe RAR test>
```

Testul de atomicitate: (a) poate un Sonnet sa-l termine intr-o singura sesiune, cu teste, fara sa
intrebe nimic? daca nu → sparge-l. (b) lasa sistemul **functional** daca e ultimul story? (c) `Fisiere`
+ `Depinde de` complete (decid ce se paralelizeaza). (d) backend + UI pentru acelasi comportament = **2 stories**.

### 5.5 Executie — agent team (lead orchestreaza, NU scrie cod)

- `TeamCreate` creeaza echipa + lista de task-uri partajata; `Agent` cu `team_name` + `name` +
  `model: sonnet` spawneaza **teammates adresabili**. Lead-ul ii coordoneaza prin `SendMessage`
  (clarificari/re-directionare la cald, fara re-spawn) si `TaskUpdate` (atribuire/inchidere task).
- **Valuri (waves):** lead-ul grupeaza stories pe graful de dependente. Val 1 = stories fara
  `Depinde de` si fara fisiere comune → teammates paraleli. Val 2 = deblocate de Val 1. Etc.
- **Reguli hard:** max 2-3 teammates simultan (server dev + SQLite partajate); **fisiere comune = nu
  paralel** (sau `isolation: worktree` + merge de catre lead); teammates **nu** comit, nu scriu in
  PRD/ROADMAP, nu pornesc/opresc servere, nu rezolva ambiguitati singuri (escaladeaza la lead).
- **Raport teammate** (prin `SendMessage`): test RED citat → implementare → test GREEN citat →
  fisiere atinse → abateri; apoi `TaskUpdate` → `completed`.
- Dupa fiecare val: lead-ul ruleaza regresia (`python3 -m pytest -q`) si bifeaza stories in PRD.
- Livrabile mici pot rula **fara TeamCreate** (un singur worker sau lead direct) — dar PRD-ul,
  verificarea in context curat si writeback-ul raman obligatorii.

### 5.6 VERIFY (subagent cu context curat)

Lead-ul spawneaza un subagent dedicat care primeste DOAR PRD-ul + aceste instructiuni, NU transcriptul:

> Esti verificator independent pentru livrabila {X.Y} (PRD: `docs/prd/prd-{X.Y}-<slug>.md`).
> Citeste PRD-ul; NU porni de la premisa ca implementarea e corecta.
> 1. Suita: `python3 -m pytest -q` — verde (citeaza output-ul).
> 2. Criteriile de acceptare ale fiecarui story din PRD.
> 3. E2E pe canalul atins: UI web → `./start.sh test both --send`, browser pe `http://localhost:8000/`
>    (Playwright MCP sau `/browse`), fluxul din PRD; canal API → `POST /v1/prezentari` pe RAR test.
> 4. **Regresia de aur:** fluxul existent nu are voie sa se strice — `POST /v1/prezentari` (sau
>    import → commit) → worker → `FINALIZATA` la RAR test, vizibil in dashboard (`./start.sh test finalizate`).
> 5. Raport PASS/FAIL per criteriu cu dovezi. FAIL-urile NU le repari (`/qa-only`, nu `/qa`) — le documentezi.

Lead-ul scrie raportul in PRD ca `## Raport VERIFY`. Toate PASS → CLOSE. Exista FAIL → inapoi la
EXECUTE (stories de fix), apoi VERIFY din nou cu subagent NOU.

### 5.7 Bootstrap sesiune (detectie faza din starea PRD)

Starea persista in PRD (prima linie dupa titlu), actualizata de lead la fiecare tranzitie:
`**Stare**: draft → aprobat → in-executie → verify-pass → inchis`. Asta face procesul reluabil
din orice sesiune noua — starea e in fisiere, nu in conversatie.

| Stare gasita | Faza de pornire |
|---|---|
| nu exista `docs/prd/prd-{X.Y}-*.md` | PLAN |
| PRD `**Stare**: draft` | PLAN (reia stories/review-uri) |
| PRD `**Stare**: aprobat` / `in-executie`, stories nebifate | EXECUTE |
| toate stories bifate, fara `## Raport VERIFY` cu PASS | VERIFY |
| `## Raport VERIFY` = PASS | CLOSE |
| PRD `**Stare**: inchis` | livrabila gata — alege urmatoarea din dashboard |

La bootstrap: daca utilizatorul a numit `{X.Y}`, aceea e; altfel prima `WIP` din dashboard, apoi
prima `TODO` in ordinea etapelor. **Confirma alegerea cu utilizatorul** — singura intrebare permisa la start.

### 5.8 CLOSE + porti umane

1. `/code-review` pe diff-ul livrabilei. Probleme → fix acum (worker) sau story nou (inapoi in PRD).
2. **Writeback:** in §3 dashboard — status `DONE` + data + link PRD; actualizeaza "Ultima actualizare".
   PRD: `**Stare**: inchis`.
3. **POARTA UMANA:** propune commit-ul (mesaj conventional commits, fara emoji; vezi git rules) si
   ASTEAPTA confirmarea explicita — niciodata commit automat.

### 5.9 Anti-patterns (opreste-te daca observi)

| Anti-pattern | Corectia |
|---|---|
| Teammate "termina" fara output de test citat | Raportul e invalid — cere dovezi prin `SendMessage` |
| Test scris DUPA implementare ca formalitate | Nu e TDD — testul e contractul; refa bucla |
| Lead-ul scrie cod "ca e mai rapid" | Pierde orchestrarea; spawn teammate chiar si pt un fix mic |
| Stories paralele care ating acelasi fisier | Re-planifica valurile sau worktree + merge de catre lead |
| PRD modificat in executie fara re-review | Schimbare de scope → inapoi la PLAN |
| Lead verifica singur, fara subagent VERIFY | Partinire de confirmare — VERIFY cere context proaspat |
| Continua peste poarta umana | Aprobarea PRD si confirmarea commit sunt ale utilizatorului — opreste-te |

---

## 6. Skill-uri in proces

| Faza | Skill | Rol |
|------|-------|-----|
| PLAN | `/prd` | genereaza PRD-ul (`docs/prd/prd-X.Y-<slug>.md`) |
| PLAN | `/plan-ceo-review`, `/plan-eng-review`, `/plan-design-review` | review de plan (primele 2 obligatorii; design doar UI) |
| EXECUTE | `/investigate` | bug neinteles raportat de worker — root cause, nu patch orb |
| VERIFY | `/browse`, `/qa-only` | browser headless / QA doar-raport (nu repara — pastreaza independenta) |
| CLOSE | `/code-review` | review pe diff-ul livrabilei |
| oricand | `/learn` | salveaza gotcha-uri in `.claude/rules/` (nu in acest doc) |

---

## 7. Intretinere

Acest document se actualizeaza la **schimbari de proces** (nu per livrabila) si la **dashboard**
(la fiecare livrabila terminata — §3). Lectiile operationale (gotchas, pattern-uri descoperite in
executie) merg in `.claude/rules/` via `/learn`, nu aici.