gomag-vending/CLAUDE.md

CLAUDE.md

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

Project Overview

System: Import Comenzi Web → Sistem ROA Oracle

This is a multi-tier system that automatically imports orders from web platforms (GoMag, etc.) into the ROA Oracle ERP system. The project combines Oracle PL/SQL packages, Visual FoxPro orchestration, and a FastAPI web admin/dashboard interface.

Current Status: Phase 4 Complete, Phase 5 In Progress

• ✅ Phase 1: Database Foundation (ARTICOLE_TERTI, IMPORT_PARTENERI, IMPORT_COMENZI)
• ✅ Phase 2: VFP Integration (gomag-vending.prg, sync-comenzi-web.prg)
• ✅ Phase 3-4: FastAPI Admin + Dashboard (mappings CRUD, sync orchestration, pre-validation)
• 🔄 Phase 5: Production (file logging done, auth + notifications pending)

Architecture

[Web Platform API] → [VFP Orchestrator] → [Oracle PL/SQL] → [Web Admin Interface]
       ↓                    ↓                    ↑                  ↑
   JSON Orders        Process & Log        Store/Update      Configuration

Tech Stack

• Backend: Oracle PL/SQL packages
• Integration: Visual FoxPro 9
• Admin/Dashboard: FastAPI + Jinja2 + Oracle pool + SQLite
• Data: Oracle 11g/12c (ROA system), SQLite (local tracking)

Core Components

Oracle PL/SQL Packages

1. IMPORT_PARTENERI Package

Location: api/database-scripts/02_import_parteneri.sql Functions:

• cauta_sau_creeaza_partener() - Search/create partners with priority: cod_fiscal → denumire → create new
• parseaza_adresa_semicolon() - Parse addresses in format "JUD:București;BUCURESTI;Str.Victoriei;10"

Logic:

• Individual vs company detection (CUI 13 digits)
• Automatic address defaults to București Sectorul 1
• All new partners get ID_UTIL = -3 (system)

2. IMPORT_COMENZI Package

Location: api/database-scripts/03_import_comenzi.sql Functions:

• gaseste_articol_roa() - Complex SKU mapping with pipelined functions
• importa_comanda_web() - Complete order import with JSON parsing

Mapping Types:

• Simple: SKU found directly in nom_articole (not stored in ARTICOLE_TERTI)
• Repackaging: SKU → CODMAT with different quantities
• Complex sets: One SKU → multiple CODMATs with percentage pricing

Visual FoxPro Integration

gomag-vending.prg

Location: vfp/gomag-vending.prg Current functionality:

• GoMag API integration with pagination
• JSON data retrieval and processing
• HTML entity cleaning (ă→a, ș→s, ț→t, î→i, â→a)

Future: Will be adapted for JSON output to Oracle packages

sync-comenzi-web.prg (Phase 2)

Planned orchestrator with:

• 5-minute timer automation
• Oracle package integration
• Comprehensive logging system
• Error handling and retry logic

Database Schema

ARTICOLE_TERTI Table

Location: api/database-scripts/01_create_table.sql

CREATE TABLE ARTICOLE_TERTI (
    sku           VARCHAR2(100),      -- SKU from web platform
    codmat        VARCHAR2(50),       -- CODMAT from nom_articole
    cantitate_roa NUMBER(10,3),       -- ROA units per web unit
    procent_pret  NUMBER(5,2),        -- Price percentage for sets
    activ         NUMBER(1),          -- 1=active, 0=inactive
    PRIMARY KEY (sku, codmat)
);

FastAPI Admin/Dashboard

app/main.py

Location: api/app/main.py Features:

• FastAPI with lifespan (Oracle pool + SQLite init)
• File logging to logs/sync_comenzi_YYYYMMDD_HHMMSS.log
• Routers: health, dashboard, mappings, articles, validation, sync
• Services: mapping, article, import, sync, validation, order_reader, sqlite, scheduler
• Templates: Jinja2 (dashboard, mappings, sync_detail, missing_skus)
• Dual database: Oracle (ERP data) + SQLite (tracking)
• APScheduler for periodic sync

Development Commands

Database Setup

# Start Oracle container
docker-compose up -d

# Run database scripts in order
sqlplus CONTAFIN_ORACLE/password@ROA_ROMFAST @01_create_table.sql
sqlplus CONTAFIN_ORACLE/password@ROA_ROMFAST @02_import_parteneri.sql
sqlplus CONTAFIN_ORACLE/password@ROA_ROMFAST @03_import_comenzi.sql

VFP Development

DO vfp/gomag-vending.prg

FastAPI Admin/Dashboard

cd api
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 5003 --reload

Testare

python api/test_app_basic.py       # Test A - fara Oracle
python api/test_integration.py     # Test C - cu Oracle

Project Structure

/
├── api/                                    # ✅ Flask Admin & Database
│   ├── admin.py                           # ✅ Flask app with Oracle pool
│   ├── database-scripts/                  # ✅ Oracle SQL scripts
│   │   ├── 01_create_table.sql           # ✅ ARTICOLE_TERTI table
│   │   ├── 02_import_parteneri.sql       # ✅ Partners package
│   │   └── 03_import_comenzi.sql         # ✅ Orders package
│   ├── Dockerfile                        # ✅ Oracle client container
│   ├── tnsnames.ora                      # ✅ Oracle connection config
│   ├── .env                              # ✅ Environment variables
│   └── requirements.txt                  # ✅ Python dependencies
├── docs/                                 # 📋 Project Documentation
│   ├── PRD.md                           # ✅ Product Requirements
│   ├── LLM_PROJECT_MANAGER_PROMPT.md    # ✅ Project Management
│   └── stories/                         # 📋 User Stories
│       ├── P1-001-ARTICOLE_TERTI.md     # ✅ Story P1-001 (COMPLETE)
│       ├── P1-002-Package-IMPORT_PARTENERI.md  # ✅ Story P1-002 (COMPLETE)
│       ├── P1-003-Package-IMPORT_COMENZI.md    # ✅ Story P1-003 (COMPLETE)
│       └── P1-004-Testing-Manual-Packages.md   # 📋 Story P1-004 (READY)
├── vfp/                                  # ⏳ VFP Integration
│   ├── gomag-vending.prg                # ✅ Current GoMag client
│   ├── utils.prg                        # ✅ Utility functions
│   ├── nfjson/                          # ✅ JSON parsing library
│   └── sync-comenzi-web.prg             # ⏳ Future orchestrator
├── docker-compose.yaml                  # ✅ Container setup
└── logs/                                # ✅ Application logs

Configuration

Environment Variables (.env)

ORACLE_USER=CONTAFIN_ORACLE
ORACLE_PASSWORD=********
ORACLE_DSN=ROA_ROMFAST
TNS_ADMIN=/app
INSTANTCLIENTPATH=/opt/oracle/instantclient

Business Rules

Partners

• Search priority: cod_fiscal → denumire → create new
• Individuals (CUI 13 digits): separate nume/prenume
• Default address: București Sectorul 1
• All new partners: ID_UTIL = -3

Articles

• Simple SKUs: found directly in nom_articole (not stored)
• Special mappings: only repackaging and complex sets
• Inactive articles: activ=0 (not deleted)

Orders

• Uses existing PACK_COMENZI packages
• Default: ID_GESTIUNE=1, ID_SECTIE=1, ID_POL=0
• Delivery date = order date + 1 day
• All orders: INTERNA=0 (external)

Phase Implementation Status

✅ Phase 1: Database Foundation (75% Complete)

• P1-001: ✅ ARTICOLE_TERTI table + Docker setup
• P1-002: ✅ IMPORT_PARTENERI package complete
• P1-003: ✅ IMPORT_COMENZI package complete
• P1-004: 🔄 Manual testing (READY TO START)

⏳ Phase 2: VFP Integration (Planned)

• Adapt gomag-vending.prg for JSON output
• Create sync-comenzi-web.prg orchestrator
• Oracle packages integration
• Logging system with rotation

⏳ Phase 3: Web Admin Interface (Planned)

• Flask app with Oracle connection pool
• HTML/CSS admin interface
• JavaScript CRUD operations
• Client/server-side validation

⏳ Phase 4: Testing & Deployment (Planned)

• End-to-end testing with real orders
• Complex mappings validation
• Production environment setup
• User documentation

Key Functions

Oracle Packages

• IMPORT_PARTENERI.cauta_sau_creeaza_partener() - Partner management
• IMPORT_PARTENERI.parseaza_adresa_semicolon() - Address parsing
• IMPORT_COMENZI.gaseste_articol_roa() - SKU resolution
• IMPORT_COMENZI.importa_comanda_web() - Order import

VFP Utilities (utils.prg)

• LoadSettings - INI configuration management
• InitLog/LogMessage/CloseLog - Logging system
• TestConnectivity - Connection verification
• CreateDefaultIni - Default configuration

Success Metrics

Technical KPIs

• Import success rate > 95%
• Average processing time < 30s per order
• Zero downtime for main ROA system
• 100% log coverage

Business KPIs

• 90% reduction in manual order entry time
• Elimination of manual transcription errors
• New mapping configuration < 5 minutes

Error Handling

Categories

1. Oracle connection errors: Retry logic + alerts
2. SKU not found: Log warning + skip item
3. Invalid partner: Create attempt + detailed log
4. Duplicate orders: Skip with info log

Logging Format

2025-09-09 14:30:25 | ORDER-123 | OK | ID:456789
2025-09-09 14:30:26 | ORDER-124 | ERROR | SKU 'XYZ' not found

Project Manager Commands

Available commands for project tracking:

• status - Overall progress and current story
• stories - List all stories with status
• phase - Current phase details
• risks - Identify and prioritize risks
• demo [story-id] - Demonstrate implemented functionality
• plan - Re-planning for changes