Initial commit: ROA2WEB - FastAPI + Vue.js + Telegram Bot
Modern ERP Reports Application with microservices architecture Tech Stack: - Backend: FastAPI + python-oracledb (Oracle DB integration) - Frontend: Vue.js 3 + PrimeVue + Vite - Telegram Bot: python-telegram-bot + SQLite - Infrastructure: Shared database pool, JWT authentication, SSH tunnel Features: - FastAPI backend with async Oracle connection pool - Vue.js 3 responsive frontend with PrimeVue components - Telegram bot alternative interface - Microservices architecture with shared components - Complete deployment support (Linux Docker + Windows IIS) - Comprehensive testing (Playwright E2E + pytest) Repository Structure: - reports-app/ - Main application (backend, frontend, telegram-bot) - shared/ - Shared components (database pool, auth, utils) - deployment/ - Deployment scripts (Linux & Windows) - docs/ - Project documentation - security/ - Security scanning and git hooks
This commit is contained in:
437
reports-app/frontend/README.md
Normal file
437
reports-app/frontend/README.md
Normal file
@@ -0,0 +1,437 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user