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

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

• ✅ 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)

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