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 Flask web admin interface for SKU mapping management.

**Current Status:** Phase 1 (Database Foundation) - 75% Complete
- ✅ P1-001: ARTICOLE_TERTI table created
- ✅ P1-002: IMPORT_PARTENERI package complete
- ✅ P1-003: IMPORT_COMENZI package complete
- 🔄 P1-004: Manual testing packages (NEXT UP)

## 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 Interface:** Flask + Oracle connection pool
- **Data:** Oracle 11g/12c (ROA system)

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

### Flask Admin Interface

#### admin.py
**Location:** `api/admin.py`
**Features:**
- Oracle connection pool management
- SKU mappings CRUD operations
- Web interface for configuration
- Real-time validation

## Development Commands

### Database Setup
```bash
# 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
```foxpro
DO vfp/gomag-vending.prg
```

### Flask Admin Interface
```bash
cd api
python admin.py
```

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