# ROA2WEB - Modern ERP Reports Application

**FastAPI Backend + Vue.js 3 Frontend + Telegram Bot**

Modern microservices-based ERP reporting application for managing invoices, payments, and financial data with Oracle database integration.

---

## Project Overview

ROA2WEB is a comprehensive financial reporting platform built with modern technologies:

- **Backend**: FastAPI (Python) - High-performance async API
- **Frontend**: Vue.js 3 + PrimeVue - Rich, responsive web interface
- **Telegram Bot**: Alternative command-based interface
- **Database**: Oracle Database with connection pooling
- **Architecture**: Microservices with shared components

---

## Quick Start

### Prerequisites

- Python 3.11+
- Node.js 16+
- Oracle Database access
- SSH access to Oracle server (for development)

### Development Setup

```bash
# Clone repository
git clone <repository-url>
cd roa2web

# Start all services (SSH tunnel + Backend + Frontend)
cd roa2web
./start-dev.sh

# Or start services individually:

# 1. Start SSH tunnel for Oracle DB
./ssh_tunnel.sh start

# 2. Start FastAPI backend (port 8001)
cd reports-app/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# 3. Start Vue.js frontend (port 3000-3005)
cd reports-app/frontend
npm install
npm run dev

# 4. Start Telegram Bot (optional, port 8002)
cd reports-app/telegram-bot
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m app.main
```

### Access the Application

- **Frontend**: http://localhost:3000 (or 3001-3005 if 3000 is busy)
- **Backend API Docs**: http://localhost:8001/docs (Swagger UI)
- **Backend ReDoc**: http://localhost:8001/redoc
- **Health Check**: http://localhost:8001/health

---

## Architecture

### Directory Structure

```

├── shared/                    # Shared components
│   ├── database/             # Oracle connection pool (singleton)
│   ├── auth/                 # JWT authentication & middleware
│   └── utils/                # Common utilities
│
├── reports-app/              # Main reports application
│   ├── backend/              # FastAPI backend (port 8001)
│   ├── frontend/             # Vue.js 3 frontend (port 3000-3005)
│   └── telegram-bot/         # Telegram bot (port 8002)
│
├── nginx/                    # Nginx reverse proxy config
├── ssh-tunnel/              # SSH tunnel for Oracle DB
├── deployment/              # Deployment scripts (Linux & Windows)
└── scripts/                 # Utility scripts
```

### Key Features

- **Shared Database Pool**: Singleton Oracle connection pool shared across microservices
- **JWT Authentication**: Secure token-based auth with middleware
- **Microservices**: Independent services with clear separation of concerns
- **Oracle Integration**: Direct Oracle stored procedure calls
- **Responsive Design**: Mobile-friendly Vue.js interface
- **Telegram Integration**: Alternative bot-based interface

---

## Core Technologies

### Backend
- **FastAPI**: Modern, high-performance Python web framework
- **python-oracledb**: Oracle database driver with connection pooling
- **JWT (PyJWT)**: Token-based authentication
- **Pydantic**: Data validation and settings management
- **pytest**: Comprehensive testing

### Frontend
- **Vue.js 3**: Progressive JavaScript framework (Composition API)
- **PrimeVue**: Rich UI component library
- **Pinia**: State management
- **Vue Router**: Client-side routing
- **Vite**: Fast build tool
- **Axios**: HTTP client
- **Chart.js**: Data visualization
- **Playwright**: E2E testing

### Telegram Bot
- **python-telegram-bot**: Telegram Bot API wrapper
- **SQLite + aiosqlite**: Standalone database for bot data
- **httpx**: Async HTTP client for backend communication
- **FastAPI**: Internal API for backend callbacks

### Infrastructure
- **Oracle Database**: Enterprise data storage
- **SSH Tunnel**: Secure database access (development)
- **Nginx**: Reverse proxy and load balancer (production)
- **Docker**: Containerization (production)

---

## Development Commands

### Backend (FastAPI)

```bash
cd reports-app/backend

# Development server with auto-reload
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# Run tests
pytest -v

# API documentation
# Swagger UI: http://localhost:8001/docs
# ReDoc: http://localhost:8001/redoc
```

### Frontend (Vue.js)

```bash
cd reports-app/frontend

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint

# E2E tests (Playwright)
npm run test:e2e
npm run test:e2e:ui    # Interactive UI mode
npm run test:e2e:debug # Debug mode
```

### Telegram Bot

```bash
cd reports-app/telegram-bot

# Run bot
python -m app.main

# Run tests
pytest tests/ -v

# Health check
curl http://localhost:8002/internal/health
```

### SSH Tunnel Management

```bash
cd roa2web

# Start tunnel (localhost:1526 -> remote Oracle:1521)
./ssh_tunnel.sh start

# Check status
./ssh_tunnel.sh status

# Stop tunnel
./ssh_tunnel.sh stop

# Restart tunnel
./ssh_tunnel.sh restart
```

---

## Testing

### Backend Tests
```bash
cd shared
python -m pytest -v
```

### Frontend E2E Tests
```bash
cd reports-app/frontend
npm run test:e2e        # Headless mode
npm run test:e2e:headed # With browser UI
npm run test:e2e:ui     # Interactive mode
```

### Telegram Bot Tests
```bash
cd reports-app/telegram-bot
pytest tests/ -v
pytest tests/ --cov=app --cov-report=html
```

---

## Production Deployment

### Linux/Docker Deployment

```bash
cd roa2web

# Setup production environment
./setup_production.sh

# Deploy application
./scripts/deploy.sh

# Health check
./scripts/health-check.sh
```

See `DEPLOYMENT_GUIDE.md` for complete deployment instructions.

### Windows Server Deployment

ROA2WEB supports deployment on Windows Server with IIS:

```powershell
# On Windows Server (PowerShell as Administrator)
cd C:\path\to\roa2web\deployment\windows\scripts

# Install
.\Install-ROA2WEB.ps1

# Deploy
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"

# Manage services
.\Start-ROA2WEB.ps1
.\Stop-ROA2WEB.ps1
.\Restart-ROA2WEB.ps1
```

See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for details.

---

## API Endpoints

All endpoints prefixed with `/api`:

### Authentication
- `POST /api/auth/login` - Login with Oracle credentials

### Companies
- `GET /api/companies` - Get user's accessible companies

### Dashboard
- `GET /api/dashboard/{company_id}` - Dashboard statistics

### Invoices
- `GET /api/invoices/{company_id}` - List invoices with filters
- `GET /api/invoices/{company_id}/summary` - Invoice summary

### Treasury
- `GET /api/treasury/{company_id}` - Payment data

### Telegram Bot
- `POST /api/telegram/auth/generate-code` - Generate linking code
- `POST /api/telegram/auth/verify-user` - Verify Oracle user
- `POST /api/telegram/auth/refresh-token` - Refresh JWT token
- `POST /api/telegram/export` - Export reports

---

## Environment Configuration

Copy `.env.example` to `.env` in each microservice and configure:

### Backend (`reports-app/backend/.env`)
```bash
# Oracle Database (through SSH tunnel)
ORACLE_USER=your_username
ORACLE_PASSWORD=your_password
ORACLE_HOST=localhost
ORACLE_PORT=1526
ORACLE_SID=ROA

# JWT Authentication
JWT_SECRET_KEY=your_secret_key
JWT_ALGORITHM=HS256
JWT_EXPIRE_MINUTES=30
```

### Telegram Bot (`reports-app/telegram-bot/.env`)
```bash
# Telegram Bot Token
TELEGRAM_BOT_TOKEN=your_bot_token

# Backend API
BACKEND_API_URL=http://localhost:8001
```

---

## Documentation

### General
- `CLAUDE.md` - Development guide for Claude Code
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
- `TEAM_IMPLEMENTATION_GUIDE.md` - Team implementation guide
- `ARCHITECTURE_SCHEMA.md` - Architecture diagrams
- `MICROSERVICES_GUIDE.md` - Microservices details

### Component-Specific
- `README.md` - Main application README
- `reports-app/backend/README.md` - Backend specifics
- `reports-app/frontend/README.md` - Frontend guide
- `reports-app/frontend/tests/README.md` - Frontend testing
- `reports-app/telegram-bot/README.md` - Telegram bot guide
- `reports-app/telegram-bot/TELEGRAM_COMMANDS.md` - Bot commands

### Deployment
- `DEPLOYMENT_GUIDE.md` - Production deployment (Linux & Windows)
- `deployment/windows/README.md` - Windows quick start
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows guide

---

## Contributing

1. Create feature branch from `main`
2. Make changes following project structure
3. Write tests for new features
4. Run all tests before committing
5. Create pull request with clear description

---

## License

[Your License Here]

---

## Support

For issues and questions:
- Check documentation in `` subdirectories
- Review CLAUDE.md for development guidelines
- See component-specific READMEs for detailed information

---

**Branch**: v2-roa2web-fastapi
**Working Directory**: `` - All development happens here