Actualizare documentatie si plan pentru VFP Orchestrator

- CLAUDE.md: Actualizare completa cu architecture multi-tier si status project - PRD.md: Adaugat plan detaliat pentru sync-comenzi-web.prg cu: * Flux complet de procesare (input/output/logging) * Helper functions necesare (CleanGoMagText, BuildArticlesJSON, etc.) * Cod complet pentru procesarea articolelor GoMag → Oracle * Gestionare cazuri speciale (shipping/billing/discounts) * Mapare detaliata Phase 2 cu P2-001 prin P2-004 - LLM_PROJECT_MANAGER_PROMPT.md: Update comenzi disponibile Phase 1 Database Foundation: 75% complete, ready for P1-004 testing Phase 2 VFP Integration: Fully planned, ready for implementation 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-09 20:33:31 +03:00
parent 3a234b5240
commit 461b26e8a7
5 changed files with 1656 additions and 109 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,127 +4,257 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co

 ## Project Overview

-This is a Visual FoxPro 9 project that interfaces with the GoMag e-commerce API. The application retrieves both product and order data from GoMag's REST API endpoints with full pagination support and comprehensive error handling.
+**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

- **Main Application**: `gomag-vending.prg` - Primary Visual FoxPro script with pagination support
- **Utility Module**: `utils.prg` - INI file handling, logging, and helper functions
- **JSON Library**: `nfjson/` - Third-party JSON parsing library for VFP
- **Technology**: Visual FoxPro 9 with WinHttp.WinHttpRequest.5.1 for HTTP requests
- **API Integration**: GoMag REST API v1 for products and orders management
+```
+[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

-### gomag-vending.prg
-Main application script with:
- Complete pagination support for products and orders
- Configurable API settings via INI file
- Comprehensive error handling and logging
- Rate limiting compliance (1-second delays between requests)
- JSON array output generation for both products and orders
+### Oracle PL/SQL Packages

-### utils.prg
-Utility functions module containing:
- INI file operations (`ReadPini`, `WritePini`, `LoadSettings`)
- Logging system (`InitLog`, `LogMessage`, `CloseLog`)
- Connectivity testing (`TestConnectivity`)
- URL encoding utilities (`UrlEncode`)
- Default configuration creation (`CreateDefaultIni`)
+#### 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"

-### settings.ini
-Configuration file with sections:
- `[API]` - API endpoints, credentials, and headers
- `[PAGINATION]` - Page size limits
- `[OPTIONS]` - Feature toggles for products/orders retrieval
- `[FILTERS]` - Date range filters for orders
+**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

-### Running the Application
+### 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 gomag-vending.prg
+DO vfp/gomag-vending.prg
 ```

-### Running from Windows Command Line
-Use the provided batch file:
-```cmd
-run-gomag.bat
+### Flask Admin Interface
+```bash
+cd api
+python admin.py
 ```

-Direct execution with Visual FoxPro:
-```cmd
-"C:\Program Files (x86)\Microsoft Visual FoxPro 9\vfp9.exe" -T "gomag-vending.prg"
-```
-
-## Configuration Management
-
-The application uses `settings.ini` for all configuration. Key settings:
-
-### Required Configuration
- `ApiKey` - Your GoMag API key
- `ApiShop` - Your shop URL (e.g., "https://yourstore.gomag.ro")
-
-### Feature Control
- `GetProducts` - Set to "1" to retrieve products, "0" to skip
- `GetOrders` - Set to "1" to retrieve orders, "0" to skip
- `OrderDaysBack` - Number of days back to retrieve orders (default: 7)
-
-### Pagination
- `Limit` - Records per page (default: 100, max recommended for GoMag API)
-
-## API Integration Details
-
-### Authentication
- Header-based authentication using `Apikey` and `ApiShop` headers
- User-Agent must differ from "PostmanRuntime"
-
-### Endpoints
- Products: `https://api.gomag.ro/api/v1/product/read/json?enabled=1`
- Orders: `https://api.gomag.ro/api/v1/order/read/json`
-
-### Rate Limiting
- 1-second pause between paginated requests
- No specific READ request limitations
- POST requests limited to ~1 request per second (Leaky Bucket)
-
-## Directory Structure
+## Project Structure

 ```
 /
-├── gomag-vending.prg         # Main application
-├── utils.prg                 # Utility functions
-├── settings.ini              # Configuration file
-├── run-gomag.bat            # Windows launcher
-├── nfjson/                  # JSON parsing library
-│   ├── nfjsoncreate.prg
-│   └── nfjsonread.prg
-├── log/                     # Generated log files
-├── output/                  # Generated JSON files
-└── products-example.json    # Sample API response
+├── 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
 ```

-## Output Files
+## Configuration

-### Generated Files
- `log/gomag_sync_YYYYMMDD_HHMMSS.log` - Detailed execution logs
- `output/gomag_all_products_YYYYMMDD_HHMMSS.json` - Complete product array
- `output/gomag_orders_last7days_YYYYMMDD_HHMMSS.json` - Orders array
+### Environment Variables (.env)
+```env
+ORACLE_USER=CONTAFIN_ORACLE
+ORACLE_PASSWORD=********
+ORACLE_DSN=ROA_ROMFAST
+TNS_ADMIN=/app
+INSTANTCLIENTPATH=/opt/oracle/instantclient
+```

-### Error Files
- `gomag_error_pageN_*.json` - Raw API responses for failed parsing
- `gomag_error_pageN_*.log` - HTTP error details with status codes
+### 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

-### Main Application (gomag-vending.prg)
- `SaveProductsArray` - Converts paginated product data to JSON array
- `SaveOrdersArray` - Converts paginated order data to JSON array
- `MergeProducts` - Combines products from multiple pages
- `MergeOrdersArray` - Combines orders from multiple pages
+### 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

-### Utilities (utils.prg)
- `LoadSettings` - Loads complete INI configuration into object
- `InitLog`/`LogMessage`/`CloseLog` - Comprehensive logging system
- `TestConnectivity` - Internet connection verification
- `CreateDefaultIni` - Generates template configuration file
+### 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