roa2web-service-auto/reports-app/frontend/README.md

ROA Reports Frontend

Vue.js 3 frontend application for the ROA2WEB reports system.

🚀 Features

• Vue.js 3 with Composition API
• PrimeVue UI components with Aura theme
• Pinia for state management
• Vue Router with navigation guards
• Axios for API communication
• Responsive design for mobile and desktop
• JWT Authentication with token refresh
• TypeScript-ready architecture

📁 Project Structure

src/
├── main.js              # Application entry point
├── App.vue              # Root component
├── assets/
│   ├── css/
│   │   ├── global.css   # Global styles and utilities
│   │   └── mobile.css   # Mobile-specific styles
│   └── images/          # Static images
├── components/          # Reusable components
│   ├── layout/          # Layout components
│   ├── reports/         # Report-specific components
│   └── ui/              # Generic UI components
├── composables/         # Vue composables
│   ├── index.js         # Composables exports
│   └── useResponsive.js # Responsive design utilities
├── router/
│   └── index.js         # Vue Router configuration
├── services/
│   ├── api.js           # API service with interceptors
│   └── index.js         # Services exports
├── stores/              # Pinia stores
│   ├── auth.js          # Authentication store
│   ├── companies.js     # Companies management
│   ├── invoices.js      # Invoices store
│   ├── payments.js      # Payments store
│   └── index.js         # Stores exports
├── utils/               # Utility functions
│   └── index.js         # Utils exports
└── views/               # Page components
    ├── LoginView.vue    # Authentication page
    ├── DashboardView.vue # Main dashboard
    ├── InvoicesView.vue # Invoices management
    └── PaymentsView.vue # Payments management

🛠️ Development Setup

Prerequisites

• Node.js 16+ and npm 8+
• ROA2WEB Backend running on http://localhost:8000

Installation

# Navigate to frontend directory
cd roa2web/reports-app/frontend/

# Install dependencies
npm install

# Start development server
npm run dev

# Application will be available at http://localhost:3000

Development Commands

# Development server with hot reload
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# Format code
npm run format

🔧 Configuration

Environment Variables

Create a .env file in the frontend directory:

# API Configuration
VITE_API_BASE_URL=http://localhost:8000/api
VITE_APP_TITLE=ROA Reports
VITE_APP_VERSION=1.0.0

# Development
VITE_DEV_MODE=true
VITE_LOG_LEVEL=debug

API Integration

The frontend communicates with the FastAPI backend through:

• Base URL: /api (proxied to http://localhost:8000 in development)
• Authentication: JWT tokens with automatic refresh
• Error Handling: Global interceptors for error management
• Loading States: Integrated with Pinia stores

Responsive Design

The application uses a mobile-first approach with breakpoints:

• xs: < 640px (Small phones)
• sm: 640px+ (Large phones)
• md: 768px+ (Tablets)
• lg: 1024px+ (Desktop)
• xl: 1280px+ (Large desktop)
• 2xl: 1536px+ (Extra large)

🎨 UI Components

PrimeVue Components Used

• Navigation: Menubar, Menu
• Forms: InputText, Password, Dropdown, Calendar
• Data: DataTable, Column, Paginator
• Feedback: Toast, ConfirmDialog, ProgressSpinner
• Layout: Card, Badge, Tag, Button
• Overlay: Dialog

Custom Styling

• Global utilities in global.css
• Mobile optimizations in mobile.css
• Responsive composables for dynamic behavior
• CSS custom properties for consistent theming

📱 Mobile Features

• Touch-friendly interface with 44px minimum touch targets
• Swipe gestures support (prepared for future implementation)
• Responsive tables that stack on mobile
• Mobile navigation with hamburger menu
• Optimized forms with proper input types
• Accessible design following WCAG guidelines

🔐 Authentication

Login Flow

1. User submits credentials to /auth/login
2. Backend returns access and refresh tokens
3. Tokens stored in localStorage
4. API requests include JWT token in Authorization header
5. Automatic token refresh on expiration

Route Protection

• Public routes: /login
• Protected routes: All others require authentication
• Navigation guards handle redirects
• Auto-logout on token expiry

📊 State Management

Pinia Stores

Auth Store (useAuthStore)

// Authentication state and actions
const authStore = useAuthStore()
authStore.login(credentials)
authStore.logout()
authStore.isAuthenticated

Companies Store (useCompanyStore)

// Company selection and management
const companyStore = useCompanyStore()
companyStore.loadCompanies()
companyStore.setSelectedCompany(company)
companyStore.selectedCompany

Invoices Store (useInvoicesStore)

// Invoice data and filtering
const invoicesStore = useInvoicesStore()
invoicesStore.loadInvoices(companyCode, filters)
invoicesStore.setFilters(newFilters)
invoicesStore.invoiceList

Payments Store (usePaymentsStore)

// Payment data and statistics
const paymentsStore = usePaymentsStore()
paymentsStore.loadPayments(companyCode, filters)
paymentsStore.totalAmount
paymentsStore.paymentList

🧩 Composables

useResponsive

const { isMobile, isTablet, isDesktop, screenSize } = useResponsive()

useResponsiveTable

const { shouldStackTable, defaultRows, getMobileColumns } = useResponsiveTable()

useResponsiveForm

const { shouldStackButtons, getFormClass } = useResponsiveForm()

useMobileNav

const { isMenuOpen, toggleMenu, closeMenu } = useMobileNav()

🚀 Production Build

Build Process

# Create production build
npm run build

# Build outputs to dist/ directory
# Static files ready for web server deployment

Build Optimization

• Code splitting for vendor libraries
• Tree shaking for unused code elimination
• Asset optimization with Vite
• Modern JS with automatic fallbacks
• Gzip compression ready

Deployment

The production build creates static files that can be served by:

• Nginx (recommended for production)
• Apache with URL rewriting
• Node.js static server
• CDN with SPA support

🔍 Debugging

Development Tools

• Vue DevTools browser extension
• Pinia DevTools for state inspection
• Network tab for API debugging
• Console logging with environment-based levels

Common Issues

1. CORS errors: Ensure backend allows frontend origin
2. 401 errors: Check token expiration and refresh logic
3. Loading states: Verify store loading flags
4. Responsive issues: Test with browser dev tools

📋 Testing

E2E Tests with Playwright

# Run all E2E tests (headless)
npm run test:e2e

# Run with browser UI visible
npm run test:e2e:headed

# Debug mode with step-through
npm run test:e2e:debug

# Interactive UI mode
npm run test:e2e:ui

# View test report
npm run test:e2e:report

Test Structure:

• Uses Page Object Model pattern
• Tests organized by feature: tests/e2e/{auth,dashboard,invoices,payments,responsive}/
• Page objects in tests/page-objects/
• Mocks all backend API calls for speed and reliability

See tests/README.md for detailed testing guide.

Testing on Real Android Devices

For accurate mobile testing, you can test the application on a real Android phone using ADB WiFi and Chrome DevTools MCP.

Quick Setup (Windows PowerShell):

# 1. Connect phone via WiFi (first time pairing)
adb pair 10.0.20.114:PAIRING_PORT    # Use pairing code from phone
adb connect 10.0.20.114:MAIN_PORT    # Connect to wireless debugging port

# 2. Run automated setup script
cd E:\proiecte\roa2web\roa2web\reports-app\frontend\scripts
.\android-test-setup.ps1

Start Application (WSL):

# Start backend and frontend
cd /mnt/e/proiecte/roa2web/roa2web
./start-dev.sh

# On phone Chrome: http://localhost:3000

Cleanup (WSL):

# Remove port forwarding when done
./scripts/android-disconnect.sh

Advantages over emulation:

• [OK] Real device performance and rendering
• [OK] Actual touch interactions
• [OK] True mobile experience on real hardware
• [OK] Claude Code can control your phone directly through MCP
• [OK] Screenshot capture from real device

Architecture:

• ADB WiFi connection (Android 10+) - no USB cable needed
• Windows PowerShell for all ADB operations (WSL cannot access Android devices)
• Multi-layer port forwarding: ADB forward + Windows port proxy + Firewall rules
• Chrome DevTools MCP configured with physical Windows IP (not localhost!)

Complete Guides:

• Quick Start (5 minutes): ANDROID_QUICK_START.md
• Full Setup Guide: tests/ANDROID_TESTING_GUIDE.md
• Scripts Documentation: scripts/README_ANDROID.md

Requirements:

• Android phone (Android 10+) with Wireless Debugging
• Windows 10/11 with PowerShell
• ADB Platform Tools (install via winget install Google.PlatformTools)
• Phone and PC on same WiFi network
• Chrome DevTools MCP server configured in Claude Code

Unit Tests (Future Implementation)

# Unit tests with Vitest
npm run test

# Component tests
npm run test:component

🔄 API Endpoints

Authentication

• POST /auth/login - User login
• POST /auth/refresh - Token refresh
• POST /auth/logout - User logout

Companies

• GET /companies - List user companies

Invoices

• GET /invoices/{company_code} - Get company invoices
• GET /invoices/{company_code}/{invoice_id} - Get invoice details

Payments

• GET /payments/{company_code} - Get company payments
• GET /payments/{company_code}/{payment_id} - Get payment details

🎯 Browser Support

• Chrome 88+
• Firefox 84+
• Safari 14+
• Edge 88+
• Mobile browsers (iOS Safari 14+, Chrome Mobile 88+)

📝 Development Guidelines

Code Style

• Use Composition API for new components
• Follow Vue 3 best practices
• Use TypeScript-style prop definitions
• Implement responsive design patterns

Component Structure

<template>
  <!-- Template with semantic HTML -->
</template>

<script setup>
// Composition API with proper imports
// Props, emits, lifecycle hooks
// Computed properties and methods
</script>

<style scoped>
/* Scoped styles with CSS custom properties */
/* Responsive breakpoints */
</style>

Performance

• Use v-memo for expensive renders
• Implement virtual scrolling for large lists
• Lazy load images and components
• Code split routes and features

---

ROA2WEB Frontend - Vue.js 3 application for modern ERP reporting