GoMag Vending - Import Comenzi Web → ROA Oracle

System automat de import comenzi din platforma GoMag in sistemul ERP ROA Oracle.

Arhitectura

[GoMag API] → [Python Sync Service] → [Oracle PL/SQL] → [FastAPI Admin]
     ↓                ↓                      ↑                  ↑
 JSON Orders    Download/Parse/Import    Store/Update    Dashboard + Config

Stack Tehnologic

• API + Admin: FastAPI + Jinja2 + Bootstrap 5.3
• GoMag Integration: Python (gomag_client.py — download comenzi cu paginare)
• Sync Orchestrator: Python (sync_service.py — download → parse → validate → import)
• Database: Oracle PL/SQL packages (IMPORT_PARTENERI, IMPORT_COMENZI) + SQLite (tracking)

---

Quick Start

Prerequisite

• Python 3.10+
• Oracle Instant Client 21.x (optional — suporta si thin mode pentru Oracle 12.1+)

Instalare

pip install -r api/requirements.txt
cp api/.env.example api/.env
# Editeaza api/.env cu datele de conectare Oracle

Pornire server

Important: serverul trebuie pornit din project root, nu din api/:

python -m uvicorn api.app.main:app --host 0.0.0.0 --port 5003

Sau folosind scriptul inclus:

./start.sh

Deschide http://localhost:5003 in browser.

Testare

Test A - Basic (fara Oracle):

python api/test_app_basic.py

Test C - Integrare Oracle:

python api/test_integration.py

---

Configurare (.env)

Copiaza .env.example si completeaza:

cp api/.env.example api/.env

Variabila	Descriere	Exemplu
ORACLE_USER	User Oracle	MARIUSM_AUTO
ORACLE_PASSWORD	Parola Oracle	secret
ORACLE_DSN	TNS alias	ROA_CENTRAL
TNS_ADMIN	Cale absoluta la tnsnames.ora	/mnt/e/.../gomag/api
INSTANTCLIENTPATH	Cale Instant Client (thick mode)	/opt/oracle/instantclient_21_15
FORCE_THIN_MODE	Thin mode fara Instant Client	true
SQLITE_DB_PATH	Path SQLite (relativ la project root)	api/data/import.db
JSON_OUTPUT_DIR	Folder JSON-uri descarcate	api/data/orders
APP_PORT	Port HTTP	5003
ID_POL	ID Politica ROA	39
ID_GESTIUNE	ID Gestiune ROA	0
ID_SECTIE	ID Sectie ROA	6

Nota Oracle mode:

• Thick mode (Oracle 10g/11g): seteaza INSTANTCLIENTPATH
• Thin mode (Oracle 12.1+): seteaza FORCE_THIN_MODE=true, sterge INSTANTCLIENTPATH

---

Structura Proiect

gomag-vending/
├── api/                          # FastAPI Admin + Dashboard
│   ├── app/
│   │   ├── main.py              # Entry point, lifespan, logging
│   │   ├── config.py            # Settings (pydantic-settings + .env)
│   │   ├── database.py          # Oracle pool + SQLite schema + migrari
│   │   ├── routers/             # Endpoint-uri HTTP
│   │   │   ├── health.py        # GET /health
│   │   │   ├── dashboard.py     # GET / (HTML)
│   │   │   ├── mappings.py      # /mappings, /api/mappings
│   │   │   ├── articles.py      # /api/articles/search
│   │   │   ├── validation.py    # /api/validate/*
│   │   │   └── sync.py          # /api/sync/* + /api/dashboard/orders
│   │   ├── services/
│   │   │   ├── gomag_client.py      # Download comenzi GoMag API
│   │   │   ├── sync_service.py      # Orchestrare: download→validate→import
│   │   │   ├── import_service.py    # Import comanda in Oracle ROA
│   │   │   ├── mapping_service.py   # CRUD ARTICOLE_TERTI + pct_total
│   │   │   ├── sqlite_service.py    # Tracking runs/orders/missing SKUs
│   │   │   ├── order_reader.py      # Citire gomag_orders_page*.json
│   │   │   ├── validation_service.py
│   │   │   ├── article_service.py
│   │   │   ├── invoice_service.py   # Verificare facturi ROA
│   │   │   └── scheduler_service.py # APScheduler timer
│   │   ├── templates/           # Jinja2 HTML
│   │   └── static/              # CSS + JS
│   ├── database-scripts/        # Oracle SQL (ARTICOLE_TERTI, packages)
│   ├── data/                    # SQLite DB (import.db) + JSON orders
│   ├── .env                     # Configurare locala (nu in git)
│   ├── .env.example             # Template configurare
│   ├── test_app_basic.py        # Test A - fara Oracle
│   ├── test_integration.py      # Test C - cu Oracle
│   └── requirements.txt
├── logs/                        # Log-uri aplicatie (sync_comenzi_*.log)
├── docs/                        # Documentatie (PRD, stories)
├── screenshots/                 # Before/preview/after pentru UI changes
├── start.sh                     # Script pornire (Linux/WSL)
└── CLAUDE.md                    # Instructiuni pentru AI assistants

---

Dashboard Features

Sync Panel

• Start sync manual sau scheduler automat (5/10/30 min)
• Progress live: "Import 45/80: #CMD-1234 Ion Popescu"
• Smart polling: 30s idle → 3s cand ruleaza → auto-refresh tabela
• Last sync clickabil → jurnal detaliat

Comenzi

• Filtru perioada: 3z / 7z / 30z / 3 luni / toate / custom
• Status pills cu conturi totale pe perioada (nu per-pagina)
• Cautare integrata in bara de filtre
• Coloana Client cu tooltip ▲ cand persoana livrare ≠ facturare
• Paginare sus + jos, selector rezultate per pagina (25/50/100/250)

Mapari SKU

• Badge ✓ 100% / ⚠ 80% per grup SKU
• Filtru Complete / Incomplete
• Verificare duplicat SKU-CODMAT (409 cu optiune de restaurare)

SKU-uri Lipsa

• Cautare dupa SKU sau nume produs
• Filtru Nerezolvate / Rezolvate / Toate cu conturi
• Re-scan cu progress inline si banner rezultat

---

Fluxul de Import

1. gomag_client.py descarca comenzi GoMag API → JSON files
2. order_reader.py parseaza JSON-urile
3. validation_service.py valideaza SKU-uri contra ARTICOLE_TERTI + NOM_ARTICOLE
4. import_service.py creeaza/cauta partener in Oracle (shipping person = facturare)
5. PACK_IMPORT_COMENZI.importa_comanda_web() insereaza comanda in ROA
6. Rezultate salvate in SQLite (orders, sync_run_orders, order_items)

Reguli Business

• Persoana: shipping name = persoana pe eticheta = beneficiarul facturii
• Adresa: cand billing ≠ shipping → adresa shipping pentru ambele (facturare + livrare)
• SKU simplu: gasit direct in NOM_ARTICOLE → nu se stocheaza in ARTICOLE_TERTI
• SKU cu repackaging: un SKU → CODMAT cu cantitate diferita
• SKU set complex: un SKU → multiple CODMAT-uri cu procente de pret

---

Status Implementare

Faza	Status	Descriere
Phase 1: Database Foundation	Complet	ARTICOLE_TERTI, PACK_IMPORT_PARTENERI, PACK_IMPORT_COMENZI
Phase 2: Python Integration	Complet	gomag_client.py, sync_service.py
Phase 3-4: FastAPI Dashboard	Complet	UI responsive, smart polling, filter bar, paginare
Phase 5: Production	In Progress	Logging done, Auth + SMTP pending

---

WSL2 Note

• uvicorn --reload nu functioneaza pe /mnt/e/ (WSL2 limitation) — restarta manual
• Serverul trebuie pornit din project root, nu din api/
• JSON_OUTPUT_DIR si SQLITE_DB_PATH sunt relative la project root