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

```bash
# 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

```bash
# 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:

```env
# 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`)
```javascript
// Authentication state and actions
const authStore = useAuthStore()
authStore.login(credentials)
authStore.logout()
authStore.isAuthenticated
```

#### Companies Store (`useCompanyStore`)
```javascript
// Company selection and management
const companyStore = useCompanyStore()
companyStore.loadCompanies()
companyStore.setSelectedCompany(company)
companyStore.selectedCompany
```

#### Invoices Store (`useInvoicesStore`)
```javascript
// Invoice data and filtering
const invoicesStore = useInvoicesStore()
invoicesStore.loadInvoices(companyCode, filters)
invoicesStore.setFilters(newFilters)
invoicesStore.invoiceList
```

#### Payments Store (`usePaymentsStore`)
```javascript
// Payment data and statistics
const paymentsStore = usePaymentsStore()
paymentsStore.loadPayments(companyCode, filters)
paymentsStore.totalAmount
paymentsStore.paymentList
```

## 🧩 Composables

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

### useResponsiveTable
```javascript
const { shouldStackTable, defaultRows, getMobileColumns } = useResponsiveTable()
```

### useResponsiveForm
```javascript
const { shouldStackButtons, getFormClass } = useResponsiveForm()
```

### useMobileNav
```javascript
const { isMenuOpen, toggleMenu, closeMenu } = useMobileNav()
```

## 🚀 Production Build

### Build Process

```bash
# 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

```bash
# 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):**
```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):**
```bash
# Start backend and frontend
cd /mnt/e/proiecte/roa2web/roa2web
./start-dev.sh

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

**Cleanup (WSL):**
```bash
# 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)

```bash
# 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
```vue
<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