romfast/roa2web-service-auto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
15327687f44ce111966c31d4e9f42e890dddaae3
roa2web-service-auto/tasks/prd-unified-mobile-material-design.md
Claude Agent dfbaca2477 feat(unified-mobile-material-design): Complete US-101a - Creare MobileTopBar.vue component 
Implemented by Ralph autonomous loop.
Iteration: 1

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-12 09:46:30 +00:00

18 KiB
Raw Blame History

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)

  1. Validare API componente pe bonuri
  2. Fix buton delete duplicat
  3. Adaugă navigare înapoi

Faza 3: Dashboard (US-106)

  1. Implement swipeable cards

Faza 4: Reports Module (US-107, US-108, US-109, US-110, US-111)

  1. Apply pattern la fiecare pagină Reports

Faza 5: Shared Components (US-112, US-113)

  1. Bottom Sheet pentru filtre
  2. Batch actions contextuale

Faza 6: Testing (US-114)

  1. Cross-device testing

Faza 7: Documentație (US-115, US-116, US-117, US-118, US-119, US-120)

  1. Creare MOBILE_PATTERNS.md dedicat
  2. Actualizare CSS_PATTERNS.md cu referințe
  3. Actualizare DESIGN_TOKENS.md cu MD3
  4. Actualizare CLAUDE.md cu reguli mobile
  5. Actualizare claude-learn-frontend.md cu patterns
  6. 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