Setup Docker infrastructure for GoMag vending import system

- Add Flask admin interface with Oracle connection pool - Create ARTICOLE_TERTI table for SKU mappings - Configure Docker container with Oracle Instant Client - Setup project documentation and requirements 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-09-08 22:48:33 +03:00
parent 6a841e3cc0
commit 3e92456c59
9 changed files with 971 additions and 1 deletions
--- a/docs/PRD.md
+++ b/docs/PRD.md
@@ -0,0 +1,319 @@
+# Product Requirements Document (PRD)
+## Import Comenzi Web → Sistem ROA
+
+**Versiune:** 1.1  
+**Data:** 08 septembrie 2025  
+**Status:** Phase 1 - în progres (P1-001 ✅ complet)  
+
+---
+
+## 📋 Overview
+
+Sistem ultra-minimal pentru importul comenzilor de pe platforme web (GoMag, etc.) în sistemul ERP ROA Oracle. Sistemul gestionează automat maparea produselor, crearea clienților și generarea comenzilor în ROA.
+
+### Obiective Principale
+- ✅ Import automat comenzi web → ROA
+- ✅ Mapare flexibilă SKU → CODMAT (reîmpachetări + seturi)
+- ✅ Crearea automată a partenerilor noi
+- ✅ Interfață web pentru administrare mapări
+- ✅ Logging complet pentru troubleshooting
+
+---
+
+## 🎯 Scope & Limitations
+
+### În Scope
+- Import comenzi din orice platformă web (nu doar GoMag)
+- Mapare SKU complexe (1:1, 1:N, reîmpachetări, seturi)
+- Crearea automată parteneri + adrese
+- Interfață web admin pentru mapări
+- Logging în fișiere text
+
+### Out of Scope
+- Modificarea comenzilor existente în ROA
+- Sincronizare bidirectională
+- Gestionarea stocurilor
+- Interfață pentru utilizatori finali
+
+---
+
+## 🏗️ Architecture Overview
+
+```
+[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
+- **Data:** Oracle 11g/12c
+
+---
+
+## 📊 Data Model
+
+### Tabel Nou: ARTICOLE_TERTI
+```sql
+CREATE TABLE ARTICOLE_TERTI (
+    sku           VARCHAR2(100),      -- SKU din platforma web
+    codmat        VARCHAR2(50),       -- CODMAT din nom_articole
+    cantitate_roa NUMBER(10,3),       -- Câte unități ROA = 1 web
+    procent_pret  NUMBER(5,2),        -- % din preț pentru seturi
+    activ         NUMBER(1),          -- 1=activ, 0=inactiv
+    PRIMARY KEY (sku, codmat)
+);
+```
+
+### Exemple Mapări
+- **Simplu:** SKU "CAF01" → caută direct în nom_articole (nu se stochează)
+- **Reîmpachetare:** SKU "CAFE100" → CODMAT "CAF01", cantitate_roa=10
+- **Set compus:** 
+  - SKU "SET01" → CODMAT "CAF01", cantitate_roa=2, procent_pret=60
+  - SKU "SET01" → CODMAT "FILT01", cantitate_roa=1, procent_pret=40
+
+---
+
+## 🔧 Components Specification
+
+### 1. Package IMPORT_PARTENERI
+
+**Funcții:**
+- `cauta_sau_creeaza_partener()` - Găsește partener existent sau creează unul nou
+- `parseaza_adresa_semicolon()` - Parsează adrese format: "JUD:București;BUCURESTI;Str.Victoriei;10"
+
+**Logica Căutare Parteneri:**
+1. Caută după cod_fiscal (dacă > 3 caractere)
+2. Caută după denumire exactă
+3. Creează partener nou folosind `pack_def.adauga_partener()`
+4. Adaugă adresa folosind `pack_def.adauga_adresa_partener2()`
+
+### 2. Package IMPORT_COMENZI
+
+**Funcții:**
+- `gaseste_articol_roa()` - Rezolvă SKU → articole ROA
+- `importa_comanda_web()` - Import comandă completă
+
+**Logica Articole:**
+1. Verifică ARTICOLE_TERTI pentru SKU
+2. Dacă nu există → caută direct în nom_articole (SKU = CODMAT)
+3. Calculează cantități și prețuri conform mapărilor
+4. Folosește `PACK_COMENZI.adauga_comanda()` și `PACK_COMENZI.adauga_articol_comanda()`
+
+### 3. VFP Orchestrator (sync-comenzi-web.prg)
+
+**Responsabilități:**
+- Rulare automată (timer 5 minute)
+- Citire comenzi din API-ul web
+- Apelare package-uri Oracle
+- Logging în fișiere text cu timestamp
+
+### 4. Web Admin Interface
+
+**Funcționalități:**
+- Vizualizare mapări SKU existente
+- Adăugare/editare/ștergere mapări
+- Validare date înainte de salvare
+- Interface responsive cu Flask
+
+---
+
+## 📋 Implementation Phases
+
+### Phase 1: Database Foundation (Ziua 1) - 🔄 În Progres
+- [x] ✅ **P1-001:** Creare tabel ARTICOLE_TERTI + Docker setup
+- [ ] 🔄 **P1-002:** Package IMPORT_PARTENERI complet  
+- [ ] ⏳ **P1-003:** Package IMPORT_COMENZI complet
+- [ ] ⏳ **P1-004:** Testare manuală package-uri
+
+### Phase 2: VFP Integration (Ziua 2)
+- [ ] Adaptare gomag-vending-test.prg pentru output JSON
+- [ ] Creare sync-comenzi-web.prg
+- [ ] Testare import comenzi end-to-end
+- [ ] Configurare logging
+
+### Phase 3: Web Admin Interface (Ziua 3)
+- [ ] Flask app cu connection pool Oracle
+- [ ] HTML/CSS pentru admin mapări
+- [ ] JavaScript pentru CRUD operații
+- [ ] Testare interfață web
+
+### Phase 4: Testing & Deployment (Ziua 4)
+- [ ] Testare integrată pe comenzi reale
+- [ ] Validare mapări complexe (seturi)
+- [ ] Configurare environment production
+- [ ] Documentație utilizare
+
+---
+
+## 📁 File Structure
+
+```
+/api/                               # ✅ Flask Admin Interface
+  ├── admin.py                      # ✅ Flask app cu Oracle pool
+  ├── 01_create_table.sql           # ✅ Tabel ARTICOLE_TERTI 
+  ├── 02_import_parteneri.sql       # 🔄 Package parteneri (în progres)
+  ├── 03_import_comenzi.sql         # ⏳ Package comenzi (planificat)
+  ├── Dockerfile                    # ✅ Container cu Oracle client
+  ├── tnsnames.ora                  # ✅ Config Oracle ROA
+  ├── .env                          # ✅ Environment variables
+  └── requirements.txt              # ✅ Dependencies Python
+
+/vfp/                               # ⏳ VFP Integration (Phase 2)
+  └── sync-comenzi-web.prg          # ⏳ Orchestrator principal
+
+/docker-compose.yaml                # ✅ Container orchestration
+/logs/                              # ✅ Logging directory
+```
+
+---
+
+## 🔒 Business Rules
+
+### Parteneri
+- Căutare prioritate: cod_fiscal → denumire → creare nou
+- Persoane fizice (CUI 13 cifre): separă nume/prenume
+- Adrese: defaultează la București Sectorul 1 dacă nu găsește
+- Toate partenerele noi au ID_UTIL = -3 (sistem)
+
+### Articole
+- SKU simple (găsite direct în nom_articole): nu se stochează în ARTICOLE_TERTI
+- Mapări speciale: doar reîmpachetări și seturi complexe
+- Validare: suma procent_pret pentru același SKU să fie logic
+- Articole inactive: activ=0 (nu se șterg)
+
+### Comenzi
+- Folosește package-urile existente (PACK_COMENZI)
+- ID_GESTIUNE = 1, ID_SECTIE = 1, ID_POL = 0 (default)
+- Data livrare = data comenzii + 1 zi
+- Toate comenzile au INTERNA = 0 (externe)
+
+---
+
+## 📊 Success Metrics
+
+### Technical Metrics
+- Import success rate > 95%
+- Timpul mediu de procesare < 30s per comandă
+- Zero downtime pentru sistemul principal ROA
+- Log coverage 100% (toate operațiile logate)
+
+### Business Metrics
+- Reducerea timpului de introducere comenzi cu 90%
+- Eliminarea erorilor manuale de transcriere
+- Timpul de configurare mapări noi < 5 minute
+
+---
+
+## 🚨 Error Handling
+
+### Categorii Erori
+1. **Erori conexiune Oracle:** Retry logic + alertă
+2. **SKU not found:** Log warning + skip articol
+3. **Partener invalid:** Tentativă creare + log detalii
+4. **Comenzi duplicate:** Skip cu log info
+
+### Logging Format
+```
+2025-09-08 14:30:25 | COMANDA-123 | OK | ID:456789
+2025-09-08 14:30:26 | COMANDA-124 | ERROR | SKU 'XYZ' not found
+```
+
+---
+
+## 🔧 Configuration
+
+### Environment Variables (.env)
+```env
+ORACLE_USER=CONTAFIN_ORACLE
+ORACLE_PASSWORD=********
+ORACLE_DSN=ROA_ROMFAST
+TNS_ADMIN=/app
+INSTANTCLIENTPATH=/opt/oracle/instantclient
+```
+
+### VFP Configuration
+- Timer interval: 300 secunde (5 minute)
+- Conexiune Oracle prin goExecutor existent
+- Log files: sync_YYYYMMDD.log (rotație zilnică)
+
+---
+
+## 🎛️ Admin Interface Specification
+
+### Main Screen: SKU Mappings
+- Tabel editabil cu coloane: SKU, CODMAT, Cantitate ROA, Procent Preț, Activ
+- Inline editing cu auto-save
+- Filtrare și căutare
+- Export/Import mapări (CSV)
+- Validare în timp real
+
+### Features
+- Bulk operations (activare/dezactivare multiple)
+- Template mapări pentru tipuri comune
+- Preview calcul preț pentru teste
+- Audit trail (cine/când a modificat)
+
+---
+
+## 🏁 Definition of Done
+
+### Per Feature
+- [ ] Cod implementat și testat
+- [ ] Documentație actualizată
+- [ ] Error handling complet
+- [ ] Logging implementat
+- [ ] Review code efectuat
+
+### Per Phase
+- [ ] Toate feature-urile Phase complete
+- [ ] Testare integrată reușită
+- [ ] Performance requirements îndeplinite
+- [ ] Deployment verificat
+- [ ] Sign-off stakeholder
+
+---
+
+## 📞 Support & Maintenance
+
+### Monitoring
+- Log files în /logs/ cu rotație automată
+- Alertă email pentru erori critice
+- Dashboard cu statistici import (opcional Phase 2)
+
+### Backup & Recovery
+- Mapări ARTICOLE_TERTI incluse în backup-ul zilnic ROA
+- Config files versionate în Git
+- Procedură rollback pentru package-uri Oracle
+
+---
+
+---
+
+## 📊 Progress Status - Phase 1
+
+### ✅ P1-001 COMPLET: Tabel ARTICOLE_TERTI
+- **Implementat:** 08 septembrie 2025, 22:30
+- **Deliverables:**
+  - Tabel ARTICOLE_TERTI cu structură completă (PK, validări, indecși)
+  - Docker environment cu Oracle Instant Client
+  - Flask admin interface cu test conexiune
+  - Date test pentru mapări (reîmpachetare + set compus)
+- **Files:** `api/01_create_table.sql`, `api/admin.py`, `docker-compose.yaml`
+- **Status:** ✅ Ready pentru testare cu ROA (10.0.20.36)
+
+### 🔄 Următorul: P1-002 Package IMPORT_PARTENERI
+- **Funcții de implementat:**
+  - `cauta_sau_creeaza_partener()` 
+  - `parseaza_adresa_semicolon()`
+- **Dependencies:** P1-001 ✅ complet
+- **Estimate:** 6-8 ore
+- **Risk:** MEDIUM (integrare cu pack_def existent)
+
+---
+
+**Document Owner:** Development Team  
+**Last Updated:** 08 septembrie 2025, 22:35  
+**Next Review:** După P1-002 completion