vending_data_intelligence_report/CLAUDE.md

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)

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

# 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

# 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