Refactor environment configuration templates with comprehensive documentation

Updates .env.example files for both backend and telegram-bot with:
- Complete variable coverage matching actual code usage
- Clear section-based organization (Oracle, JWT, SMTP, Cache, etc.)
- Detailed comments explaining purpose and usage location for each variable
- Added missing critical variables (AUTH_SESSION_SECRET, CACHE_*, token expiration settings)
- Removed unused/dead variables (CLAUDE_API_KEY, DEBUG, API_HOST, SQLITE_DB_PATH, etc.)
- Consistent formatting and structure across development and production templates

Critical additions:
- AUTH_SESSION_SECRET for email 2FA flow (must match between backend and telegram-bot)
- Full cache configuration variables (17 vars for hybrid L1/L2 cache system)
- Token expiration settings (ACCESS_TOKEN_EXPIRE_MINUTES, REFRESH_TOKEN_EXPIRE_DAYS)
- SMTP email retry settings for telegram bot

Ensures all .env.example files accurately reflect required and optional environment
variables used in the codebase, making deployment and configuration easier.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

reports-app/backend/.env.example

@@ -1,51 +1,88 @@
-# Oracle Database Configuration (prin SSH tunnel)
-# IMPORTANT: Conectare la schema CONTAFIN_ORACLE pentru authentication
-# Schema CONTAFIN_ORACLE conține utilizatorii și pack_drepturi.verificautilizator
-# Fiecare firmă este o schema separată în Oracle
+# ============================================================================
+# ROA2WEB Backend - Environment Configuration Template
+# ============================================================================
+# Copy this file to .env and fill in your actual values
+# IMPORTANT: Never commit .env file to git!
+
+# ============================================================================
+# ORACLE DATABASE CONFIGURATION (REQUIRED)
+# ============================================================================
+# Connection to CONTAFIN_ORACLE schema for authentication and user management
+# Each company is a separate schema in Oracle Database
+# Development: Through SSH tunnel (localhost:1526)
+# Windows Production: Direct connection to Oracle server
+
 ORACLE_USER=CONTAFIN_ORACLE
 ORACLE_PASSWORD=SET_IN_PRODUCTION_ENV
 ORACLE_HOST=localhost
 ORACLE_PORT=1526
 ORACLE_SID=ROA
 
-# Authentication Flow Information:
-# 1. Conectare la CONTAFIN_ORACLE schema
-# 2. Verificare user/pass prin pack_drepturi.verificautilizator(username, password)
-# 3. Citire drepturi/firme din vdef_util_grup WHERE id_util = user_id
-# 4. User selectează firma/schema pentru acces la date
+# Development Only: Start SSH tunnel before running backend
+# ./ssh_tunnel.sh start
+# ./ssh_tunnel.sh status
 
-# Test User Credentials (pentru dezvoltare):
-# 🔐 SECURITY: Nu pune credențiale reale în acest fișier!
-# Username: "SET_IN_PRODUCTION"
-# Password: "SET_IN_PRODUCTION"
-# Are acces la 66+ firme/scheme Oracle 
+# ============================================================================
+# JWT AUTHENTICATION (REQUIRED)
+# ============================================================================
+# Used for JWT token generation and validation (shared/auth/jwt_handler.py)
+# Generate strong secret: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
 
-# SSH Tunnel Setup Required:
-# Rulează: ./ssh_tunnel.sh start
-# Verifică: ./ssh_tunnel.sh status
-
-# JWT Configuration
-# 🔐 SECURITY: Generate a strong secret key in production!
 JWT_SECRET_KEY=GENERATE_STRONG_SECRET_IN_PRODUCTION
+
+# Token expiration settings (used by shared/auth/jwt_handler.py)
 ACCESS_TOKEN_EXPIRE_MINUTES=30
 REFRESH_TOKEN_EXPIRE_DAYS=7
 
-# Session Security (Email Authentication)
+# ============================================================================
+# SESSION SECURITY - EMAIL 2FA (REQUIRED)
+# ============================================================================
 # Must match telegram-bot AUTH_SESSION_SECRET for email login flow
+# Used by backend/app/routers/telegram.py for session token validation
 # Generate with: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+
 AUTH_SESSION_SECRET=your-secure-random-secret-here-min-32-chars
 
-# Application Configuration
-API_HOST=0.0.0.0
-API_PORT=8000
-DEBUG=True
-
-# CORS Configuration
-FRONTEND_URLS=http://localhost:3000,http://localhost:5173
-
-# Telegram Bot Integration
+# ============================================================================
+# TELEGRAM BOT INTEGRATION (REQUIRED for Telegram features)
+# ============================================================================
 # Internal API URL for telegram bot service (auth code management)
-# Development (with SSH tunnel): http://localhost:8002
-# Windows Production (local): http://localhost:8002
+# Used by backend/app/routers/telegram.py to communicate with bot
+# Development: http://localhost:8002
+# Windows Production: http://localhost:8002
 # Docker Production: http://telegram-bot:8002
-TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
+
+TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
+
+# ============================================================================
+# CACHE CONFIGURATION (OPTIONAL - defaults provided)
+# ============================================================================
+# Two-tier hybrid cache system (L1: in-memory LRU, L2: SQLite persistent)
+# Used by backend/app/cache/config.py
+
+# Core Settings
+CACHE_ENABLED=True
+CACHE_TYPE=hybrid
+CACHE_SQLITE_PATH=./cache_data/roa2web_cache.db
+CACHE_MEMORY_MAX_SIZE=1000
+CACHE_DEFAULT_TTL=900
+
+# TTL per Cache Type (seconds)
+CACHE_TTL_SCHEMA=86400
+CACHE_TTL_COMPANIES=1800
+CACHE_TTL_DASHBOARD_SUMMARY=1800
+CACHE_TTL_DASHBOARD_TRENDS=1800
+CACHE_TTL_INVOICES=600
+CACHE_TTL_INVOICES_SUMMARY=900
+CACHE_TTL_TREASURY=600
+
+# Maintenance
+CACHE_CLEANUP_INTERVAL=3600
+
+# Event-Based Invalidation (experimental)
+CACHE_AUTO_INVALIDATE=False
+CACHE_CHECK_INTERVAL=300
+
+# Performance Tracking
+CACHE_TRACK_PERFORMANCE=True
+CACHE_BENCHMARK_ON_STARTUP=False