roa2web-service-auto/tasks/prd-unified-mobile-material-design.md

# PRD: Unified Mobile Material Design Interface

## 1. Introducere

Aplicația ROA2WEB are deja implementată o interfață Material Design nativă Android pentru modulul de bonuri (ReceiptsListView). Acest PRD definește extinderea aceleiași interfețe unitare la toate paginile aplicației în modul mobil: Dashboard, Facturi, Balanță de Verificare, Trezorerie, Statistici, Loguri etc.

Scopul este o experiență consistentă cross-module pe dispozitive mobile, cu header/footer unitar și pattern-uri de interacțiune identice.

## 2. Obiective

### Obiectiv Principal
- **Consistență UI/UX**: Toate paginile mobile să aibă aceeași structură vizuală și pattern-uri de interacțiune ca lista de bonuri

### Obiective Secundare
- Eliminare cod duplicat (buton delete în header când există în footer)
- Adăugare navigare back (← Înapoi) în editare bonuri
- Dashboard cu carousel swipeable pentru KPI cards
- MD3 color tokens pentru theming consistent

### Metrici de Succes
- 100% consistență vizuală între pagini pe mobil
- Reducere CSS duplicat cu minim 30%
- Zero regresii vizuale în modul desktop
- Funcționare pe Android Chrome, iOS Safari, Samsung Internet

## 3. User Stories

### US-101: Creare sistem de componente Material Design reutilizabile
**Ca** developer
**Vreau** componente Vue reutilizabile pentru elementele MD comune
**Pentru că** să evit duplicarea codului și să asigur consistența

**Acceptance Criteria:**
- [ ] Componentă `MobileTopBar.vue` extrasă din ReceiptsListView
- [ ] Componentă `MobileBottomNav.vue` extrasă din ReceiptsListView
- [ ] Componentă `MobileSelectionFooter.vue` pentru batch actions
- [ ] Componentă `MobileFilterChips.vue` pentru filtre orizontale scrollable
- [ ] Componentă `BottomSheet.vue` pentru filtre avansate
- [ ] Props pentru customizare (title, actions, items)
- [ ] npm run build passes

### US-102: Definire MD3 color tokens în CSS
**Ca** developer
**Vreau** variabile CSS pentru Material Design 3 color system
**Pentru că** să am culori consistente și dark mode automatic

**Acceptance Criteria:**
- [ ] Fișier `src/assets/css/core/md3-tokens.css` creat
- [ ] Tokens pentru: primary, secondary, surface, on-surface, outline
- [ ] Dark mode variants cu `[data-theme="dark"]`
- [ ] Mapping la tokens existenți unde posibil
- [ ] Import în main.css
- [ ] npm run build passes

### US-103: Refactor ReceiptsListView să folosească componente comune
**Ca** developer
**Vreau** ReceiptsListView să folosească noile componente
**Pentru că** să validez API-ul componentelor și să reduc duplicarea

**Acceptance Criteria:**
- [ ] Import MobileTopBar, MobileBottomNav, MobileSelectionFooter
- [ ] Ștergere CSS duplicat din ReceiptsListView
- [ ] Funcționalitate identică cu implementarea actuală
- [ ] Verify in browser că lista bonuri funcționează identic pe mobil
- [ ] npm run build passes

### US-104: Eliminare buton delete duplicat din header tabel bonuri
**Ca** utilizator
**Vreau** să văd butonul de ștergere doar în footer când am selecție activă
**Pentru că** afișarea în ambele locuri e confuză și ocupă spațiu inutil

**Acceptance Criteria:**
- [ ] Desktop: bulk-actions-bar NU mai afișează buton Șterge când e pe mobil
- [ ] Desktop: bulk-actions-bar afișează doar când `!isMobile`
- [ ] Mobile: delete apare DOAR în `mobile-selection-bottom-bar`
- [ ] Verify in browser: pe mobil, delete e doar în footer
- [ ] Verify in browser: pe desktop, delete e în header table
- [ ] npm run build passes

### US-105: Adăugare buton Înapoi în editare bon (mobile)
**Ca** utilizator
**Vreau** să pot reveni la lista de bonuri din pagina de editare
**Pentru că** navigarea back prin browser nu e intuitivă pe mobil

**Acceptance Criteria:**
- [ ] MobileTopBar în ReceiptCreateView/ReceiptCreateUnifiedView
- [ ] Iconiță ← în stânga header-ului
- [ ] Click pe ← navighează la `/data-entry`
- [ ] Title: "Editare Bon" sau "Bon nou" în funcție de context
- [ ] Verify in browser: butonul funcționează corect
- [ ] npm run build passes

### US-106: Dashboard Mobile cu Swipeable KPI Cards
**Ca** utilizator
**Vreau** să văd KPI-urile ca un carousel swipeable pe mobil
**Pentru că** cardurile stacked ocupă prea mult spațiu vertical

**Acceptance Criteria:**
- [ ] Componentă `SwipeableCards.vue` creată
- [ ] Dots indicator pentru poziție
- [ ] Touch swipe left/right funcțional
- [ ] DashboardView.vue folosește componenta pe mobil
- [ ] Fallback la layout normal pe desktop
- [ ] Verify in browser: swipe funcționează pe touch devices
- [ ] npm run build passes

### US-107: InvoicesView Mobile Material Design Header
**Ca** utilizator
**Vreau** pagina de facturi să aibă același header Material ca lista bonuri
**Pentru că** interfața trebuie să fie unitară

**Acceptance Criteria:**
- [ ] MobileTopBar cu title "Facturi"
- [ ] App Bar Actions: refresh, export în header (iconițe dreapta)
- [ ] MobileBottomNav identic cu cel din bonuri
- [ ] Filtre în Bottom Sheet (nu inline pe mobil)
- [ ] Verify in browser: header arată ca la bonuri
- [ ] npm run build passes

### US-108: TrialBalanceView Mobile Material Design Header
**Ca** utilizator
**Vreau** pagina de balanță să aibă același header Material
**Pentru că** interfața trebuie să fie unitară

**Acceptance Criteria:**
- [ ] MobileTopBar cu title "Balanță de Verificare"
- [ ] App Bar Actions: export în header
- [ ] MobileBottomNav identic
- [ ] Bottom Sheet pentru filtre complexe (perioadă, conturi)
- [ ] Verify in browser că arată consistent
- [ ] npm run build passes

### US-109: BankCashRegisterView (Trezorerie) Mobile Material Design
**Ca** utilizator
**Vreau** pagina de trezorerie să aibă același header Material
**Pentru că** interfața trebuie să fie unitară

**Acceptance Criteria:**
- [ ] MobileTopBar cu title "Trezorerie"
- [ ] App Bar Actions: refresh, export
- [ ] MobileBottomNav identic
- [ ] Bottom Sheet pentru filtre
- [ ] Verify in browser
- [ ] npm run build passes

### US-110: ServerLogsView Mobile Material Design
**Ca** admin
**Vreau** pagina de loguri să aibă interfață Material
**Pentru că** și paginile admin trebuie să fie unitare

**Acceptance Criteria:**
- [ ] MobileTopBar cu title "Loguri Server"
- [ ] App Bar Actions: refresh, export
- [ ] MobileBottomNav (fără link-ul de setări OCR pentru non-admin)
- [ ] Verify in browser
- [ ] npm run build passes

### US-111: CacheStatsView Mobile Material Design
**Ca** admin
**Vreau** pagina de statistici cache să aibă interfață Material
**Pentru că** și paginile admin trebuie să fie unitare

**Acceptance Criteria:**
- [ ] MobileTopBar cu title "Statistici Cache"
- [ ] App Bar Actions: refresh
- [ ] MobileBottomNav
- [ ] Verify in browser
- [ ] npm run build passes

### US-112: Bottom Sheet Component pentru Filtre
**Ca** utilizator
**Vreau** să pot accesa filtrele într-un bottom sheet pe mobil
**Pentru că** ocupă mai puțin spațiu și e pattern MD familiar

**Acceptance Criteria:**
- [ ] Componentă `BottomSheet.vue` cu animație slide-up
- [ ] Drag handle în partea de sus
- [ ] Close pe tap outside sau swipe down
- [ ] Slot pentru conținut
- [ ] Suport pentru visible v-model
- [ ] Verify in browser: animația e smooth
- [ ] npm run build passes

### US-113: Batch Actions per Module (contextuale)
**Ca** utilizator
**Vreau** acțiuni batch diferite în funcție de modulul curent
**Pentru că** bonurile au ștergere, facturile au export+print, balanța doar export

**Acceptance Criteria:**
- [ ] MobileSelectionFooter acceptă prop `actions` array
- [ ] Bonuri: Delete button (existent) + Export
- [ ] Facturi: Export + Print
- [ ] Balanță: Export only
- [ ] Verify in browser pentru fiecare modul
- [ ] npm run build passes

### US-114: Integrare și testare completă
**Ca** QA
**Vreau** toate paginile testate pe multiple device-uri
**Pentru că** trebuie să fim siguri că nu sunt regresii

**Acceptance Criteria:**
- [ ] Test pe Chrome Android (real device sau emulator)
- [ ] Test pe Safari iOS (simulator sau real)
- [ ] Test desktop Chrome/Firefox/Safari
- [ ] Verify dark mode funcționează peste tot
- [ ] Verify landscape orientation
- [ ] npm run build passes
- [ ] Zero erori în console

---

## User Stories: Documentație și Reguli (Faza 7)

### US-115: Actualizare CSS_PATTERNS.md cu Mobile Material Design
**Ca** developer viitor
**Vreau** documentație completă pentru pattern-urile Mobile Material Design
**Pentru că** să pot implementa pagini noi consistent fără a citi codul existent

**Acceptance Criteria:**
- [ ] Secțiune nouă "Mobile Material Design Components" în CSS_PATTERNS.md
- [ ] Documentat MobileTopBar: structură HTML, clase CSS, props
- [ ] Documentat MobileBottomNav: linkuri, iconițe, structură
- [ ] Documentat MobileSelectionFooter: când se afișează, acțiuni
- [ ] Documentat BottomSheet: usage, v-model, slots
- [ ] Documentat SwipeableCards: props, dots indicator
- [ ] Exemple de cod copy-paste ready pentru fiecare componentă
- [ ] Screenshots/ASCII diagrams pentru layout-uri

### US-116: Actualizare DESIGN_TOKENS.md cu MD3 Tokens
**Ca** developer viitor
**Vreau** documentație pentru noile MD3 color tokens
**Pentru că** să știu ce variabile CSS să folosesc pentru Material Design

**Acceptance Criteria:**
- [ ] Secțiune nouă "Material Design 3 Tokens" în DESIGN_TOKENS.md
- [ ] Tabel cu toate variabilele MD3: `--md-sys-color-*`
- [ ] Mapping la tokens existenți (ex: `--md-sys-color-primary` → `--primary-color`)
- [ ] Exemple dark mode: cum se schimbă valorile
- [ ] Reguli când să folosești MD3 tokens vs tokens existenți
- [ ] Color swatches vizuale (ASCII sau referință la Figma)

### US-117: Actualizare CLAUDE.md cu Reguli Mobile Development
**Ca** Claude Code (AI)
**Vreau** reguli clare în CLAUDE.md pentru dezvoltare mobilă
**Pentru că** să respect pattern-urile stabilite la generarea automată de cod

**Acceptance Criteria:**
- [ ] Secțiune nouă "### Mobile Development Rules" în CLAUDE.md
- [ ] Regulă: "Toate paginile mobile TREBUIE să folosească MobileTopBar"
- [ ] Regulă: "Filtrele pe mobil se pun în BottomSheet, NU inline"
- [ ] Regulă: "Selecția multiplă afișează acțiuni în footer, NU în header"
- [ ] Regulă: "Touch targets minim 44x44px"
- [ ] Regulă: "Folosește isMobile composable pentru condiționare"
- [ ] Checklist rapid pentru code review mobile

### US-118: Creare MOBILE_PATTERNS.md dedicat
**Ca** developer
**Vreau** un fișier dedicat pentru documentația mobilă
**Pentru că** e prea mult pentru CSS_PATTERNS.md și merită propriul fișier

**Acceptance Criteria:**
- [ ] Fișier `docs/MOBILE_PATTERNS.md` creat
- [ ] Table of Contents cu linkuri rapide
- [ ] Secțiuni pentru fiecare componentă
- [ ] Secțiune "Quick Start" pentru devs noi
- [ ] Secțiune "Do's and Don'ts" cu exemple concrete
- [ ] Diagrame ASCII pentru layout mobile
- [ ] Linkuri către fișierele sursă componente
- [ ] Referință adăugată în CSS_PATTERNS.md și CLAUDE.md

### US-119: Actualizare claude-learn-frontend.md cu Pattern-uri Noi
**Ca** Claude Code (AI)
**Vreau** pattern-urile noi salvate în memoria Claude
**Pentru că** să le pot aplica automat în sesiuni viitoare

**Acceptance Criteria:**
- [ ] Pattern nou: "Mobile Material Design Component Architecture"
- [ ] Pattern nou: "Bottom Sheet Filter Pattern"
- [ ] Pattern nou: "Mobile Selection Mode Flow"
- [ ] Gotcha: "Nu duplica delete button în header și footer"
- [ ] Gotcha: "Filtrele mobile trebuie în BottomSheet"
- [ ] Format corect cu @date și tags

### US-120: Validare Documentație cu Fresh Developer Test
**Ca** lead developer
**Vreau** să validez că documentația e suficientă
**Pentru că** să mă asigur că un dev nou poate implementa o pagină mobilă fără ajutor

**Acceptance Criteria:**
- [ ] Un developer (sau AI) poate crea o pagină mobilă nouă doar din docs
- [ ] Toate componentele sunt documentate cu exemple
- [ ] Nu sunt referințe circulare sau documente lipsă
- [ ] Documentația e consistentă între fișiere
- [ ] npm run build passes după ce dev-ul urmează docs

## 4. Cerințe Funcționale

1. [REQ-001] Toate paginile mobile trebuie să aibă MobileTopBar cu structură identică
2. [REQ-002] MobileBottomNav trebuie să fie consistent între pagini (aceleași linkuri)
3. [REQ-003] Selecția multiplă trebuie să folosească footer fix, nu header tabel
4. [REQ-004] Filtrele pe mobil trebuie să fie în Bottom Sheet, nu inline
5. [REQ-005] App Bar Actions (iconițe) trebuie să respecte ordinea: refresh, export, print, more
6. [REQ-006] Dashboard KPI cards trebuie să fie swipeable cu dots indicator
7. [REQ-007] Navigarea înapoi trebuie să fie vizibilă în app bar pentru pagini secundare
8. [REQ-008] MD3 tokens trebuie să suporte toate cele 3 theme modes (auto/light/dark)
9. [REQ-009] Documentația trebuie actualizată ÎNAINTE de merge în main
10. [REQ-010] CLAUDE.md trebuie să conțină reguli explicite pentru mobile development
11. [REQ-011] Orice developer nou trebuie să poată implementa o pagină mobilă doar din documentație

## 5. Non-Goals (Ce NU facem)

- ❌ Nu modificăm layout-ul desktop (doar mobile)
- ❌ Nu schimbăm structura tabelelor existente (sunt deja optimizate)
- ❌ Nu implementăm gesture navigation nativă (back swipe) - folosim buton explicit
- ❌ Nu adăugăm animații complexe (transform, spring physics)
- ❌ Nu diferențiem comportamentul iOS vs Android (identic cross-platform)
- ❌ Nu modificăm logica backend sau API calls
- ❌ Nu implementăm pull-to-refresh (complexitate excesivă)

## 6. Considerații Tehnice

### Stack/Tehnologii
- Vue 3 Composition API
- PrimeVue components (Button, Dialog, Menu, Sidebar)
- CSS custom cu design tokens
- Touch events native (touchstart, touchmove, touchend)

### Patterns de Urmat
- Pattern existent din `ReceiptsListView.vue` (US-038, US-039, US-040)
- CSS tokens din `src/assets/css/core/tokens.css`
- Mobile breakpoint: `max-width: 768px`
- Touch target minimum: 44px

### Dependențe
- `useMediaQuery` composable pentru `isMobile`
- Router pentru navigare
- Design tokens existenți

### Riscuri Tehnice
- **Risc mediu**: Bottom Sheet poate avea probleme cu keyboard pe iOS
  - Mitigare: Testare extensivă, fallback la modal simplu
- **Risc scăzut**: Swipe carousel poate conflicta cu scroll lateral pe tabele
  - Mitigare: Disable swipe când e în tabel

## 7. Considerații UI/UX

### Layout Structure (Mobile)
```
┌─────────────────────────────────────┐
│ [☰/←] Title              [🔍][⚙][⋮]│  ← MobileTopBar
├─────────────────────────────────────┤
│ [Filter Chips scrollable...]        │  ← Optional, per page
├─────────────────────────────────────┤
│                                     │
│        Page Content                 │
│        (scrollable)                 │
│                                     │
├─────────────────────────────────────┤
│  [🏠]    [📤]    [📊]    [⚙]     │  ← MobileBottomNav
└─────────────────────────────────────┘

   OR (when selection active):

├─────────────────────────────────────┤
│       [🗑️ Șterge selectate]        │  ← MobileSelectionFooter
└─────────────────────────────────────┘
```

### Stări (States)
- **Normal**: Header cu hamburger, content, bottom nav
- **Selection Mode**: Header cu X și count, content cu checkmarks, footer cu delete
- **Filters Open**: Bottom sheet overlay cu filtre
- **Loading**: Skeleton sau spinner în content area
- **Empty**: Empty state centrat în content area
- **Error**: Toast notification

### Accesibilitate
- Touch targets minim 44x44px
- Focus visible pentru keyboard navigation
- ARIA labels pe butoanele icon-only
- Color contrast minim 4.5:1

## 8. Success Metrics

- **Consistență vizuală**: 100% pagini cu header identic
- **Code reuse**: Min 70% CSS din componente comune
- **Performance**: First Contentful Paint < 1.5s pe 3G
- **Bundle size**: Creștere max 10KB gzipped

## 9. Open Questions

- [ ] TelegramView are nevoie de interfață Material? (e admin-only)
- [ ] Cum gestionăm paginile cu mai mult de 4 acțiuni în app bar?
- [ ] OCRMetricsView necesită bottom nav sau e pagină secundară?

---

## Implementare Sugerată (Ordinea User Stories)

### Faza 1: Fundație (US-101, US-102)
1. Extract componente comune
2. Definire MD3 tokens

### Faza 2: Refactor Bonuri (US-103, US-104, US-105)
3. Validare API componente pe bonuri
4. Fix buton delete duplicat
5. Adaugă navigare înapoi

### Faza 3: Dashboard (US-106)
6. Implement swipeable cards

### Faza 4: Reports Module (US-107, US-108, US-109, US-110, US-111)
7. Apply pattern la fiecare pagină Reports

### Faza 5: Shared Components (US-112, US-113)
8. Bottom Sheet pentru filtre
9. Batch actions contextuale

### Faza 6: Testing (US-114)
10. Cross-device testing

### Faza 7: Documentație (US-115, US-116, US-117, US-118, US-119, US-120)
11. Creare MOBILE_PATTERNS.md dedicat
12. Actualizare CSS_PATTERNS.md cu referințe
13. Actualizare DESIGN_TOKENS.md cu MD3
14. Actualizare CLAUDE.md cu reguli mobile
15. Actualizare claude-learn-frontend.md cu patterns
16. Validare documentație cu fresh developer test

---

## Anexa A: Fișiere de Documentație Afectate

| Fișier | Tip Modificare | User Story |
|--------|---------------|------------|
| `docs/MOBILE_PATTERNS.md` | NOU | US-118 |
| `docs/CSS_PATTERNS.md` | Update | US-115 |
| `docs/DESIGN_TOKENS.md` | Update | US-116 |
| `CLAUDE.md` | Update | US-117 |
| `.claude/rules/claude-learn-frontend.md` | Update | US-119 |

## Anexa B: Structura Documentație Finală

```
docs/
├── MOBILE_PATTERNS.md         # NOU - ghid complet mobile MD
├── CSS_PATTERNS.md            # + link la MOBILE_PATTERNS.md
├── DESIGN_TOKENS.md           # + secțiune MD3 tokens
├── ONBOARDING_CSS.md          # + menționare mobile patterns
└── ...

CLAUDE.md                      # + secțiune Mobile Development Rules

.claude/rules/
└── claude-learn-frontend.md   # + patterns & gotchas noi
```