# CLAUDE.md

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

## Project Overview

Data Intelligence Report Generator for ERP ROA (Oracle Database). Generates Excel and PDF business intelligence reports with sales analytics, margin analysis, stock tracking, and alerts.

## Commands

### Option 1: Virtual Environment (WSL or Windows)
```bash
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/WSL
# or: .venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Run report
python main.py
```

### Option 2: Docker (Windows Docker Desktop / Linux)
```bash
# Copy and configure environment
cp .env.example .env
# Edit .env with your Oracle credentials

# Run with docker-compose
docker-compose run --rm report-generator

# Or with custom months
docker-compose run --rm report-generator python main.py --months 6
```

### Common Options
```bash
# Run with custom period
python main.py --months 6

# Custom output directory
python main.py --output-dir /path/to/output
```

## Oracle Connection from Different Environments

| Environment | ORACLE_HOST value |
|-------------|-------------------|
| Windows native | `127.0.0.1` |
| WSL | Windows IP (run: `cat /etc/resolv.conf \| grep nameserver`) |
| Docker | `host.docker.internal` (automatic in docker-compose) |

## Architecture

**Entry point**: `main.py` - CLI interface, orchestrates query execution and report generation

**Data flow**:
1. `config.py` loads Oracle connection settings from `.env` file
2. `queries.py` contains all SQL queries in a `QUERIES` dictionary with metadata (title, description, params)
3. `main.py` executes queries via `OracleConnection` context manager, stores results in `results` dict
4. `report_generator.py` receives dataframes and generates:
   - `ExcelReportGenerator`: Multi-sheet workbook with conditional formatting
   - `PDFReportGenerator`: Executive summary with charts via ReportLab

**Key patterns**:
- Queries use parameterized `:months` for configurable analysis period
- Sheet order in `main.py:sheet_order` controls Excel tab sequence
- Charts are generated via matplotlib, converted to images for PDF

## Oracle Database Schema

Required views: `fact_vfacturi2`, `fact_vfacturi_detalii`, `vnom_articole`, `vnom_parteneri`, `vstoc`, `vrul`

Filter conventions:
- `sters = 0` excludes deleted records
- `tip NOT IN (7, 8, 9, 24)` excludes returns/credit notes
- Account codes: `341`, `345` = own production; `301` = raw materials

## Adding New Reports

1. Add SQL query constant in `queries.py`
2. Add entry to `QUERIES` dict with `sql`, `params`, `title`, `description`
3. Add query name to `sheet_order` list in `main.py` (line ~143)
4. For PDF inclusion, add rendering logic in `main.py:generate_reports()`

## Alert Thresholds (in config.py)

- Low margin: < 15%
- Price variation: > 20%
- Slow stock: > 90 days without movement
- Minimum sales for analysis: 1000 RON