roa2web-service-auto/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 🚀 Project Overview

**ROA2WEB** - Modern ERP Reports Application with FastAPI backend and Vue.js frontend using microservices architecture.

**Active Branch**: `v2-roa2web-fastapi`
**Main Branch**: `main` (use for PRs)
**Working Directory**: Repository root - All development happens here

## 🏗️ Architecture

### Microservices Structure
```
.
├── shared/                    # Shared components across microservices
│   ├── database/             # Oracle connection pool (singleton pattern)
│   ├── auth/                 # JWT authentication & middleware
│   └── utils/                # Common utilities
├── reports-app/              # Main reports application
│   ├── backend/              # FastAPI API (port 8001)
│   ├── frontend/             # Vue.js 3 UI (Vite dev server, port 3000-3005)
│   └── telegram-bot/         # Telegram bot frontend (port 8002 internal API)
├── nginx/                    # Reverse proxy & load balancer
└── ssh-tunnel/              # SSH tunnel for Oracle DB access
```

### Key Architectural Decisions
- **Shared Database Connection Pool**: Singleton `OraclePool` class in `shared/database/oracle_pool.py` is shared across all microservices. Uses `python-oracledb` with connection pooling.
- **Centralized Authentication**: JWT-based auth in `shared/auth/` with middleware that auto-injects user data into `request.state`.
- **SSH Tunnel Requirement**: All Oracle DB connections go through an SSH tunnel to the remote server (see Database Setup below).
- **FastAPI Structure**: Routers in `backend/app/routers/`, schemas in `backend/app/schemas/`, no traditional models (Oracle stored procedures used instead).
- **Telegram Bot Frontend**: Alternative command-based interface for Telegram. Uses standalone SQLite database for Telegram-specific data (auth codes, sessions) and communicates with backend via HTTP API.

## 🗄️ Database Setup

**Schema**: `CONTAFIN_ORACLE` - Used for authentication and user management
**Connection Method**: SSH tunnel required (Oracle DB is on remote network)

### SSH Tunnel Management
```bash
./ssh_tunnel.sh start     # Start tunnel (localhost:1526 -> remote:1521)
./ssh_tunnel.sh stop      # Stop tunnel
./ssh_tunnel.sh status    # Check tunnel status
./ssh_tunnel.sh restart   # Restart tunnel
```

**SSH Configuration**:
- Remote Server: `83.103.197.79:22122`
- User: `roa2web`
- SSH Key: `ssh-tunnel/secrets/roa_oracle_server`
- Local Port: `1526`
- Remote Oracle: `10.0.20.36:1521`

**IMPORTANT**: Always ensure SSH tunnel is running before starting backend services.

### Environment Variables
Located in `reports-app/backend/.env`:
```bash
# Oracle Database (through SSH tunnel)
ORACLE_USER=CONTAFIN_ORACLE
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 Integration
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
```

**IMPORTANT for Windows Deployment:** Ensure `TELEGRAM_BOT_INTERNAL_API` is set in backend `.env` file. This allows the backend to communicate with the Telegram bot's internal API for auth code management. See `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md` for diagnostics.

## 🛠️ Development Commands

### Quick Start (All Services)
```bash
./start-dev.sh        # Starts SSH tunnel, backend, and frontend
./start-dev.sh stop   # Stops all ROA2WEB services
./start-dev.sh help   # Show help
```

This script manages:
- SSH tunnel (Oracle DB connection)
- Backend (FastAPI on port 8001)
- Frontend (Vue.js/Vite on port 3000-3005)

### Backend (FastAPI)
```bash
cd reports-app/backend/

# Create virtual environment (first time only)
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

# API Documentation (when running)
# http://localhost:8001/docs          # Swagger UI
# http://localhost:8001/redoc         # ReDoc
# http://localhost:8001/health        # Health check endpoint
```

### Frontend (Vue.js + Vite)
```bash
cd reports-app/frontend/

# Install dependencies
npm install

# Run development server (Vite will auto-assign port 3000-3005)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint and format
npm run lint
npm run format
```

### Testing

#### Backend Tests (Shared Components)
```bash
cd shared/
python -m pytest -v                    # All tests
python -m pytest tests/test_auth.py -v # Specific test file
```

#### Frontend E2E Tests (Playwright)
```bash
cd reports-app/frontend/

# Run all 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
```

**Frontend Test Structure**:
- Uses Page Object Model pattern
- Tests in `tests/e2e/{auth,dashboard,invoices,payments,responsive}/`
- Page objects in `tests/page-objects/`
- Mocks all backend API calls for speed and reliability
- See `reports-app/frontend/tests/README.md` for details

#### Telegram Bot Tests
```bash
cd reports-app/telegram-bot/

# Run all tests
pytest tests/ -v

# Run specific test suites
pytest tests/test_auth.py -v       # Authentication flow tests
pytest tests/test_session_company.py -v # Session management tests

# Run with coverage
pytest tests/ --cov=app --cov-report=html
```

**Telegram Bot Test Coverage:**
- Authentication flow tests (link/unlink, JWT management)
- Session management tests (active company persistence)
- Manual testing checklist: `tests/MANUAL_TESTING_CHECKLIST.md`

## 🔑 Authentication Flow

1. **Login**: `POST /api/auth/login` calls Oracle stored procedure `pack_drepturi.verificautilizator(username, password)`
2. **Token Generation**: JWT token includes `username`, `user_id`, `companies[]`, `permissions[]`, `exp`, `iat`, `type`
3. **Middleware**: `AuthenticationMiddleware` in `shared/auth/middleware.py` auto-validates tokens and injects user into `request.state.user`
4. **Protected Routes**: All routes except `excluded_paths` require valid JWT token

**Key Files**:
- `shared/auth/middleware.py` - FastAPI middleware with rate limiting
- `shared/auth/jwt_handler.py` - Token creation/validation
- `reports-app/backend/app/main.py` - Auth router inline definition

## 🔌 API Endpoints

All endpoints prefixed with `/api`:

### Authentication
- `POST /api/auth/login` - Login with username/password

### 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 stats

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

### Telegram Bot
- `POST /api/telegram/auth/generate-code` - Generate 8-char linking code (requires JWT)
- `POST /api/telegram/auth/verify-user` - Verify Oracle user_id (public)
- `POST /api/telegram/auth/refresh-token` - Refresh JWT token (public)
- `POST /api/telegram/export` - Export reports for Telegram (requires JWT)
- `GET /api/telegram/health` - Health check (public)

**Backend Routers**: `reports-app/backend/app/routers/{companies,dashboard,invoices,treasury,telegram}.py`

## 🎨 Frontend Stack

- **Framework**: Vue.js 3 (Composition API)
- **UI Library**: PrimeVue (rich component library)
- **State Management**: Pinia stores in `src/stores/`
- **Routing**: Vue Router in `src/router/`
- **Build Tool**: Vite
- **Charts**: Chart.js via vue-chartjs
- **HTTP**: Axios
- **Testing**: Playwright (E2E)

**Key Frontend Components**:
- `src/views/LoginView.vue` - Login page
- `src/views/DashboardView.vue` - Main dashboard
- `src/views/InvoicesView.vue` - Invoice management
- `src/components/dashboard/cards/` - Dashboard metric cards
- `src/components/layout/` - Layout components

## 🤖 Telegram Bot Frontend

The Telegram Bot provides an alternative command-based interface to ROA2WEB for Telegram users.

### Architecture

- **Bot Framework**: python-telegram-bot (v20.7+)
- **Database**: Standalone SQLite (auth codes, sessions, active company)
- **Backend Communication**: HTTP API client (httpx)
- **Internal API**: FastAPI (port 8002) for backend callbacks

### Development Commands

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

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with TELEGRAM_BOT_TOKEN

# Run bot
python -m app.main

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

### Authentication Flow (Telegram)

1. User logs into ROA2WEB web app
2. User requests Telegram linking → Backend generates 8-char code
3. Backend saves code to telegram-bot via `POST /internal/save-code` (port 8002)
4. User sends code to Telegram bot: `/start ABC123XY`
5. Bot verifies code, creates user in SQLite, receives JWT token
6. User can now use commands to query data

### Bot Commands

- `/start [code]` - Welcome message or link account with code
- `/help` - Usage guide and available commands
- `/companies` - View accessible companies
- `/selectcompany [name]` - Select or search for active company
- `/dashboard` - View financial dashboard for active company
- `/sold` - View balance (alias for `/dashboard`)
- `/facturi [filter]` - View invoices (optional filters: neplatite, platite)
- `/trezorerie` - View treasury/payment data
- `/clear` - Clear active company selection
- `/unlink` - Unlink Telegram from Oracle account

### Database (SQLite)

Standalone database in `data/telegram_bot.db`:
- **telegram_users**: Telegram-Oracle account linking
- **telegram_auth_codes**: 8-char codes (15 min expiry)
- **telegram_sessions**: Active company selection

Automatic cleanup runs hourly to remove expired data.

### Testing

```bash
# Unit and integration tests
pytest tests/ -v

# Coverage report
pytest tests/ --cov=app --cov-report=html
```

### Key Files

- `app/main.py` - Bot entry point and Telegram application setup
- `app/bot/handlers.py` - Telegram command handlers
- `app/bot/helpers.py` - Helper functions for commands
- `app/bot/formatters.py` - Response formatting utilities
- `app/agent/session.py` - Session management (active company)
- `app/auth/linking.py` - Account linking logic
- `app/db/operations.py` - SQLite CRUD operations
- `app/api/client.py` - Backend API client
- `app/internal_api.py` - Internal FastAPI for backend callbacks

See `reports-app/telegram-bot/README.md` for complete documentation.

## 🐳 Docker & Production

### Docker Compose (Legacy Flask App)
The root `docker-compose.yaml` is for the old Flask application - NOT for the current FastAPI/Vue.js app.

### Production Deployment Options

ROA2WEB supports two production deployment architectures:

#### 🐧 Linux Production (Docker)

```bash
# Setup production environment
./setup_production.sh

# Deployment scripts
./scripts/deploy.sh           # Deploy application
./scripts/backup.sh           # Backup data
./scripts/rollback.sh         # Rollback deployment
./scripts/health-check.sh     # Health monitoring
```

See `DEPLOYMENT_GUIDE.md` for full Linux/Docker deployment instructions.

#### 🪟 Windows Server Production (IIS)

Windows Server deployment uses IIS and Windows Services without Docker:

**Build deployment package (on WSL/Linux development machine):**
```bash
cd deployment/windows/scripts
./Build-Frontend.ps1

# Output: ./deploy-package/
# Transfer this to Windows Server
```

**Deploy on Windows Server (PowerShell as Administrator):**
```powershell
# Initial installation
cd C:\path\to\deploy-package\scripts
.\Install-ROA2WEB.ps1

# Configure application
notepad C:\inetpub\wwwroot\roa2web\backend\.env

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

# Management
.\Start-ROA2WEB.ps1
.\Stop-ROA2WEB.ps1
.\Restart-ROA2WEB.ps1

# Check status
Get-Service ROA2WEB-Backend
Get-Website ROA2WEB
```

**Windows Deployment Architecture:**
- **IIS Web Server**: Serves frontend static files (port 80/443)
- **Windows Service**: FastAPI backend via NSSM (port 8000)
- **Windows Service**: Telegram Bot via NSSM (internal API port 8002)
- **Direct Oracle Connection**: No SSH tunnel required
- **URL Rewrite Module**: Reverse proxy for `/api/*` routes

**Telegram Bot Integration:**
- Backend must have `TELEGRAM_BOT_INTERNAL_API=http://localhost:8002` in `.env`
- Telegram Bot service must be running before generating linking codes
- Troubleshooting: See `deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md`

See `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` for complete Windows deployment guide.

## 📝 Common Development Tasks

### Adding a New API Endpoint
1. Create router in `reports-app/backend/app/routers/your_router.py`
2. Define Pydantic schemas in `app/schemas/`
3. Use `oracle_pool.get_connection()` context manager for DB queries
4. Register router in `app/main.py` with `app.include_router(your_router, prefix="/api/your_prefix")`

### Adding Shared Functionality
1. Place in `shared/{database|auth|utils}/`
2. Import using `sys.path.append()` pattern (see `backend/app/main.py:21`)
3. Test in `shared/tests/`

### Working with Oracle Stored Procedures
```python
async with oracle_pool.get_connection() as connection:
    with connection.cursor() as cursor:
        cursor.execute("""
            SELECT pack_name.procedure_name(:param1, :param2)
            FROM DUAL
        """, {
            'param1': value1,
            'param2': value2
        })
        result = cursor.fetchone()
```

### Frontend API Integration
```javascript
// Store pattern (src/stores/authStore.js)
import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8001/api',
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const response = await api.get('/companies');
```

## 🔒 Security

- **Git Hooks**: Security scanning hooks in `security/install_hooks.sh`
- **Environment Files**: Never commit `.env` files (use `.env.example` as template)
- **SSH Keys**: Stored in `ssh-tunnel/secrets/` (gitignored)
- **JWT Secrets**: Generate strong secrets for production
- **Rate Limiting**: Built into authentication middleware (5 requests per 5 minutes)

## 🐛 Troubleshooting

### SSH Tunnel Issues
```bash
# Check tunnel status
./ssh_tunnel.sh status

# View tunnel logs
ps aux | grep ssh | grep 1526

# Test Oracle connectivity through tunnel
timeout 5 bash -c "cat < /dev/null > /dev/tcp/127.0.0.1/1526"
```

### Backend Not Starting
- Ensure SSH tunnel is running
- Check `.env` file exists with correct credentials
- Verify virtual environment is activated
- Check port 8001 is not already in use: `lsof -ti:8001`

### Frontend Build Issues
- Clear node_modules: `rm -rf node_modules && npm install`
- Check Node.js version: `node -v` (requires 16+)
- Vite may auto-assign ports 3000-3005 if 3000 is busy

### Database Connection Errors
- Verify SSH tunnel: `./ssh_tunnel.sh status`
- Check Oracle listener is running on remote server
- Verify credentials in `.env` file
- Test connection: `http://localhost:8001/health`

## 📚 Additional Documentation

### General Documentation
- `README.md` - Project overview
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
- `ARCHITECTURE_SCHEMA.md` - Architecture diagrams and schemas
- `MICROSERVICES_GUIDE.md` - Microservices architecture details

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

### Component Documentation
- `reports-app/backend/README.md` - Backend specifics
- `reports-app/frontend/README.md` - Frontend guide
- `reports-app/frontend/tests/README.md` - Testing guide
- `reports-app/telegram-bot/README.md` - Telegram bot complete guide
- `reports-app/telegram-bot/TELEGRAM_COMMANDS.md` - Command reference

## 🔧 Tech Stack Summary

**Backend**:
- FastAPI (async Python web framework)
- python-oracledb (Oracle database driver)
- JWT (PyJWT for authentication)
- Pydantic (data validation)
- pytest (testing)

**Frontend**:
- Vue.js 3 (Composition API)
- PrimeVue (UI components)
- Pinia (state management)
- Vite (build tool)
- Playwright (E2E testing)
- Axios (HTTP client)
- Chart.js (data visualization)

**Telegram Bot Frontend**:
- python-telegram-bot (Telegram API wrapper)
- SQLite + aiosqlite (standalone database)
- httpx (async HTTP client for backend)
- FastAPI + uvicorn (internal API)
- pytest + pytest-asyncio (testing)

**Infrastructure**:
- Oracle Database (enterprise data)
- SQLite (Telegram bot standalone data)
- SSH Tunnel (secure database access - Linux/development)
- Nginx (reverse proxy - Linux production)
- Docker Compose (orchestration - Linux production)
- Windows Server + IIS (Windows production deployment)
- NSSM (Windows service manager for backend)