gomag-vending/docs/PRD.md

# 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