From 3e92456c59e3019cb85ece98133a58bcc28e10ee Mon Sep 17 00:00:00 2001 From: Marius Mutu Date: Mon, 8 Sep 2025 22:48:33 +0300 Subject: [PATCH] Setup Docker infrastructure for GoMag vending import system MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- README.md | 25 ++- api/01_create_table.sql | 78 +++++++ api/Dockerfile | 33 +++ api/admin.py | 241 ++++++++++++++++++++++ api/requirements.txt | 5 + api/tnsnames.ora | 9 + docker-compose.yaml | 40 ++++ docs/LLM_PROJECT_MANAGER_PROMPT.md | 222 ++++++++++++++++++++ docs/PRD.md | 319 +++++++++++++++++++++++++++++ 9 files changed, 971 insertions(+), 1 deletion(-) create mode 100644 api/01_create_table.sql create mode 100644 api/Dockerfile create mode 100644 api/admin.py create mode 100644 api/requirements.txt create mode 100644 api/tnsnames.ora create mode 100644 docker-compose.yaml create mode 100644 docs/LLM_PROJECT_MANAGER_PROMPT.md create mode 100644 docs/PRD.md diff --git a/README.md b/README.md index c3bc679..ae585fc 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,25 @@ -# gomag-vending +# GoMag Vending - Import Comenzi Web → ROA + +Sistem minimal pentru importul comenzilor de pe platforme web în sistemul ERP ROA Oracle. + +## Setup Docker + +### Construire și pornire containere: +```bash +docker-compose up --build +``` + +### Servicii disponibile: +- **gomag_admin**: http://localhost:5003 - Web Admin Interface +- **oracle_client**: Container pentru operații SQL + +### Configurare +Conexiunea la ROA se face la IP `10.0.20.36:1521/ROA` cu credențialele din `.env` + +### Stopping +```bash +docker-compose down +``` + +Pentru dezvoltare, vezi `docs/PRD.md` pentru specificații complete. diff --git a/api/01_create_table.sql b/api/01_create_table.sql new file mode 100644 index 0000000..4d56256 --- /dev/null +++ b/api/01_create_table.sql @@ -0,0 +1,78 @@ +-- ==================================================================== +-- P1-001: Tabel ARTICOLE_TERTI pentru mapări SKU → CODMAT +-- Sistem Import Comenzi Web → ROA +-- ==================================================================== + +-- Creare tabel pentru mapări complexe articole +CREATE TABLE ARTICOLE_TERTI ( + sku VARCHAR2(100) NOT NULL, -- SKU din platforma web + codmat VARCHAR2(50) NOT NULL, -- CODMAT din nom_articole + cantitate_roa NUMBER(10,3) DEFAULT 1, -- Câte unități ROA = 1 web + procent_pret NUMBER(5,2) DEFAULT 100, -- % din preț pentru seturi + activ NUMBER(1) DEFAULT 1, -- 1=activ, 0=inactiv + data_creare DATE DEFAULT SYSDATE, -- Timestamp creare + data_modif DATE DEFAULT SYSDATE, -- Timestamp ultima modificare + id_util_creare NUMBER(10) DEFAULT -3, -- ID utilizator care a creat + id_util_modif NUMBER(10) DEFAULT -3, -- ID utilizator care a modificat + + -- Primary key compus + CONSTRAINT pk_articole_terti PRIMARY KEY (sku, codmat), + + -- Validări + CONSTRAINT chk_art_terti_cantitate CHECK (cantitate_roa > 0), + CONSTRAINT chk_art_terti_procent CHECK (procent_pret >= 0 AND procent_pret <= 100), + CONSTRAINT chk_art_terti_activ CHECK (activ IN (0, 1)) +); + +-- Index pentru performanță pe căutări frecvente după SKU +CREATE INDEX idx_articole_terti_sku ON ARTICOLE_TERTI (sku, activ); + +-- Index pentru audit și raportare +CREATE INDEX idx_articole_terti_data ON ARTICOLE_TERTI (data_creare, activ); + +-- Comentarii pentru documentație +COMMENT ON TABLE ARTICOLE_TERTI IS 'Mapări SKU-uri web → CODMAT ROA pentru reîmpachetări și seturi'; +COMMENT ON COLUMN ARTICOLE_TERTI.sku IS 'SKU din platforma web (ex: GoMag)'; +COMMENT ON COLUMN ARTICOLE_TERTI.codmat IS 'CODMAT din nom_articole ROA'; +COMMENT ON COLUMN ARTICOLE_TERTI.cantitate_roa IS 'Câte unități ROA pentru 1 unitate web'; +COMMENT ON COLUMN ARTICOLE_TERTI.procent_pret IS 'Procent din preț web alocat acestui CODMAT (pentru seturi)'; +COMMENT ON COLUMN ARTICOLE_TERTI.activ IS '1=mapare activă, 0=dezactivată'; + +-- Date de test pentru validare +INSERT INTO ARTICOLE_TERTI (sku, codmat, cantitate_roa, procent_pret, activ) VALUES +('CAFE100', 'CAF01', 10, 100, 1); -- Reîmpachetare: 1 web = 10 ROA + +INSERT INTO ARTICOLE_TERTI (sku, codmat, cantitate_roa, procent_pret, activ) VALUES +('SET01', 'CAF01', 2, 60, 1); -- Set compus partea 1 + +INSERT INTO ARTICOLE_TERTI (sku, codmat, cantitate_roa, procent_pret, activ) VALUES +('SET01', 'FILT01', 1, 40, 1); -- Set compus partea 2 + +COMMIT; + +-- Verificare creare tabel +SELECT 'ARTICOLE_TERTI creat cu succes' AS STATUS, + COUNT(*) AS NR_RECORDS +FROM ARTICOLE_TERTI; + +-- Test integritate constraintelor +BEGIN + -- Test cantitate invalidă + BEGIN + INSERT INTO ARTICOLE_TERTI (sku, codmat, cantitate_roa) VALUES ('TEST', 'TST01', -1); + DBMS_OUTPUT.PUT_LINE('ERROR: Constraint cantitate nu funcționează!'); + EXCEPTION + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('OK: Constraint cantitate funcționează'); + END; + + -- Test procent invalid + BEGIN + INSERT INTO ARTICOLE_TERTI (sku, codmat, procent_pret) VALUES ('TEST2', 'TST02', 150); + DBMS_OUTPUT.PUT_LINE('ERROR: Constraint procent nu funcționează!'); + EXCEPTION + WHEN OTHERS THEN + DBMS_OUTPUT.PUT_LINE('OK: Constraint procent funcționează'); + END; +END; +/ \ No newline at end of file diff --git a/api/Dockerfile b/api/Dockerfile new file mode 100644 index 0000000..c0b0965 --- /dev/null +++ b/api/Dockerfile @@ -0,0 +1,33 @@ +# Multi-stage build for Oracle Instant Client + Python Flask +FROM python:3.11.4-slim-buster as oracle_base + +# Installing Oracle instant client +WORKDIR /opt/oracle +RUN apt-get update && apt-get install -y libaio1 wget unzip curl \ + && wget https://download.oracle.com/otn_software/linux/instantclient/instantclient-basiclite-linuxx64.zip \ + && unzip instantclient-basiclite-linuxx64.zip \ + && rm -f instantclient-basiclite-linuxx64.zip \ + && cd /opt/oracle/instantclient* \ + && rm -f *jdbc* *occi* *mysql* *README *jar uidrvci genezi adrci \ + && echo /opt/oracle/instantclient* > /etc/ld.so.conf.d/oracle-instantclient.conf \ + && ldconfig + +# Application layer +FROM oracle_base +WORKDIR /app + +# Copy TNS configuration for Oracle connection +COPY tnsnames.ora /app/tnsnames.ora +COPY requirements.txt /app/requirements.txt + +# Install Python dependencies +RUN pip3 install -r requirements.txt + +# Copy application code +COPY . . + +# Health check endpoint +EXPOSE 5000 + +# Run Flask application +CMD ["gunicorn", "--bind", "0.0.0.0:5000", "admin:app", "--reload", "--access-logfile", "-"] \ No newline at end of file diff --git a/api/admin.py b/api/admin.py new file mode 100644 index 0000000..6b614df --- /dev/null +++ b/api/admin.py @@ -0,0 +1,241 @@ +""" +Flask Admin Interface pentru Import Comenzi Web → ROA +Gestionează mapările SKU în tabelul ARTICOLE_TERTI +""" + +from flask import Flask, jsonify, request, render_template_string +from flask_cors import CORS +from dotenv import load_dotenv +import oracledb +import os +import logging +from datetime import datetime + +# Configurare environment +load_dotenv() + +# Configurare logging +logging.basicConfig( + level=logging.DEBUG, + format='%(asctime)s | %(levelname)s | %(message)s', + handlers=[ + logging.FileHandler('/app/logs/admin.log'), + logging.StreamHandler() + ] +) +logger = logging.getLogger(__name__) + +# Environment Variables pentru Oracle +user = os.environ['ORACLE_USER'] +password = os.environ['ORACLE_PASSWORD'] +dsn = os.environ['ORACLE_DSN'] + +app = Flask(__name__) +CORS(app) + +def start_pool(): + """Inițializează connection pool Oracle""" + try: + # Configurare Oracle client + instantclient_path = os.environ.get('INSTANTCLIENTPATH') + if instantclient_path: + oracledb.init_oracle_client(lib_dir=instantclient_path) + else: + oracledb.init_oracle_client(config_dir='/app') + + pool = oracledb.create_pool( + user=user, + password=password, + dsn=dsn, + min=2, + max=4, + increment=1 + ) + logger.info(f"Oracle pool creat cu succes pentru {dsn}") + return pool + except Exception as e: + logger.error(f"Eroare creare pool Oracle: {e}") + raise + +@app.route('/health') +def health(): + """Health check pentru Docker""" + return jsonify({"status": "ok", "timestamp": datetime.now().isoformat()}) + +@app.route('/') +def home(): + """Pagina principală admin interface""" + html_template = """ + + + + GoMag Admin - Mapări SKU + + + + +
+

🛍️ GoMag Admin - Import Comenzi Web → ROA

+ +
+
✅ Container Docker activ pe port 5003
+
🔄 Verificare conexiune Oracle...
+
+ +
+

📋 Mapări SKU Active

+ + + +
+

Loading...

+
+
+
+ + + + + """ + return render_template_string(html_template) + +@app.route('/test-db') +def test_db(): + """Test conexiune Oracle și verificare tabel""" + try: + with pool.acquire() as con: + with con.cursor() as cur: + # Test conexiune de bază + cur.execute("SELECT SYSDATE FROM DUAL") + db_date = cur.fetchone()[0] + + # Verificare existență tabel ARTICOLE_TERTI + cur.execute(""" + SELECT COUNT(*) FROM USER_TABLES + WHERE TABLE_NAME = 'ARTICOLE_TERTI' + """) + table_exists = cur.fetchone()[0] > 0 + + if not table_exists: + return jsonify({ + "success": False, + "error": "Tabelul ARTICOLE_TERTI nu există. Rulează 01_create_table.sql" + }) + + # Count records + cur.execute("SELECT COUNT(*) FROM ARTICOLE_TERTI") + record_count = cur.fetchone()[0] + + return jsonify({ + "success": True, + "message": f"DB Time: {db_date}, Records: {record_count}", + "table_exists": table_exists, + "record_count": record_count + }) + + except Exception as e: + logger.error(f"Test DB failed: {e}") + return jsonify({"success": False, "error": str(e)}) + +@app.route('/api/mappings') +def get_mappings(): + """Returnează toate mapările SKU active""" + try: + with pool.acquire() as con: + with con.cursor() as cur: + cur.execute(""" + SELECT sku, codmat, cantitate_roa, procent_pret, activ, data_creare + FROM ARTICOLE_TERTI + ORDER BY sku, codmat + """) + mappings = cur.fetchall() + + return jsonify({ + "success": True, + "mappings": mappings, + "count": len(mappings) + }) + + except Exception as e: + logger.error(f"Get mappings failed: {e}") + return jsonify({"success": False, "error": str(e)}) + +# Inițializare pool la startup +try: + pool = start_pool() + logger.info("Admin interface started successfully") +except Exception as e: + logger.error(f"Failed to start admin interface: {e}") + pool = None + +if __name__ == '__main__': + app.run(host='0.0.0.0', port=5000, debug=True) \ No newline at end of file diff --git a/api/requirements.txt b/api/requirements.txt new file mode 100644 index 0000000..849d80e --- /dev/null +++ b/api/requirements.txt @@ -0,0 +1,5 @@ +Flask==2.3.2 +Flask-CORS==4.0.0 +oracledb==1.4.2 +python-dotenv==1.0.0 +gunicorn==21.2.0 \ No newline at end of file diff --git a/api/tnsnames.ora b/api/tnsnames.ora new file mode 100644 index 0000000..3d92784 --- /dev/null +++ b/api/tnsnames.ora @@ -0,0 +1,9 @@ +ROA_ROMFAST = + (DESCRIPTION = + (ADDRESS_LIST = + (ADDRESS = (PROTOCOL = TCP)(HOST = 10.0.20.36)(PORT = 1521)) + ) + (CONNECT_DATA = + (SID = ROA) + ) + ) \ No newline at end of file diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 0000000..0e6d918 --- /dev/null +++ b/docker-compose.yaml @@ -0,0 +1,40 @@ +version: '3.8' + +services: + # Main Flask Application for Web Admin Interface + gomag_admin: + build: + context: ./api + dockerfile: Dockerfile + container_name: gomag-admin + ports: + - "5003:5000" # Unique port for this project + volumes: + - ./api:/app + - ./logs:/app/logs # Shared logging directory + environment: + - PYTHONUNBUFFERED=1 + - FLASK_ENV=development + - FLASK_DEBUG=1 + # Oracle connection settings - same as ROA server + - ORACLE_USER=CONTAFIN_ORACLE + - ORACLE_PASSWORD=ROMFASTSOFT + - ORACLE_DSN=ROA_ROMFAST + - TNS_ADMIN=/app + - INSTANTCLIENTPATH=/opt/oracle/instantclient_21_1 + restart: unless-stopped + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:5000/health"] + interval: 30s + timeout: 10s + retries: 3 + +# Shared network for inter-container communication +networks: + default: + driver: bridge + +# Persistent volumes +volumes: + logs_data: + driver: local \ No newline at end of file diff --git a/docs/LLM_PROJECT_MANAGER_PROMPT.md b/docs/LLM_PROJECT_MANAGER_PROMPT.md new file mode 100644 index 0000000..195c901 --- /dev/null +++ b/docs/LLM_PROJECT_MANAGER_PROMPT.md @@ -0,0 +1,222 @@ +# LLM Project Manager Prompt +## Pentru Implementarea PRD: Import Comenzi Web → Sistem ROA + +Tu ești un **Project Manager AI specializat** care urmărește implementarea unui PRD (Product Requirements Document) prin descompunerea în user stories executabile și urmărirea progresului. + +--- + +## 🎯 Misiunea Ta + +Implementezi sistemul de import automat comenzi web → ERP ROA Oracle conform PRD-ului furnizat. Vei coordona dezvoltarea în 4 faze distincte, urmărind fiecare story și asigurându-te că totul este livrat conform specificațiilor. + +--- + +## 📋 Context PRD + +**Sistem:** Import comenzi de pe platforme web (GoMag, etc.) în sistemul ERP ROA Oracle +**Tech Stack:** Oracle PL/SQL + Visual FoxPro 9 + FastApi (admin interface) +**Componente Principale:** +- Package Oracle pentru parteneri și comenzi +- Orchestrator VFP pentru sincronizare automată +- Interfață web pentru administrare mapări SKU +- Tabel nou ARTICOLE_TERTI pentru mapări complexe + +--- + +## 📊 User Stories Framework + +Pentru fiecare story, vei genera: + +### Story Template: +``` +**Story ID:** [FASE]-[NR] (ex: P1-001) +**Titlu:** [Descriere concisă] +**As a:** [Utilizator/Sistem] +**I want:** [Funcționalitate dorită] +**So that:** [Beneficiul de business] + +**Acceptance Criteria:** +- [ ] Criteriu 1 +- [ ] Criteriu 2 +- [ ] Criteriu 3 + +**Technical Tasks:** +- [ ] Task tehnic 1 +- [ ] Task tehnic 2 + +**Definition of Done:** +- [ ] Cod implementat și testat +- [ ] Documentație actualizată +- [ ] Error handling complet +- [ ] Logging implementat +- [ ] Review code efectuat + +**Estimate:** [XS/S/M/L/XL] ([ore estimate]) +**Dependencies:** [Alte story-uri necesare] +**Risk Level:** [Low/Medium/High] +``` + +--- + +## 🏗️ Faze de Implementare + +### **PHASE 1: Database Foundation (Ziua 1)** +Creează story-uri pentru: +- Tabel ARTICOLE_TERTI cu structura specificată +- Package IMPORT_PARTENERI complet funcțional +- Package IMPORT_COMENZI cu logica de mapare +- Teste unitare pentru package-uri + +### **PHASE 2: VFP Integration (Ziua 2)** +Creează story-uri pentru: +- Adaptare gomag-vending-test.prg pentru JSON output +- Orchestrator sync-comenzi-web.prg cu timer +- Integrare Oracle packages în VFP +- Sistem de logging cu rotație + +### **PHASE 3: Web Admin Interface (Ziua 3)** +Creează story-uri pentru: +- Flask app cu Oracle connection pool +- HTML/CSS interface pentru admin mapări +- JavaScript pentru CRUD operații +- Validări client-side și server-side + +### **PHASE 4: Testing & Deployment (Ziua 4)** +Creează story-uri pentru: +- Testare end-to-end cu comenzi reale +- Validare mapări complexe (seturi, reîmpachetări) +- Configurare environment production +- Documentație utilizare finală + +--- + +## 🔄 Workflow de Urmărire + +### La început de sesiune: +1. **Prezintă status overview:** "PHASE X - Y% complete, Z stories remaining" +2. **Identifică story-ul curent** și dependencies +3. **Verifică blocaje** și propune soluții +4. **Actualizează planning-ul** dacă e nevoie + +### Pe durata implementării: +1. **Urmărește progresul** fiecărui task în story +2. **Validează completion criteria** înainte să marchezi DONE +3. **Identifică riscos** și alertează proactiv +4. **Propune optimizări** de proces + +### La finalizare story: +1. **Demo功能** implementată +2. **Confirmă acceptance criteria** îndeplinite +3. **Planifică next story** cu dependencies +4. **Actualizează overall progress** + +--- + +## 📊 Tracking & Reporting + +### Daily Status Format: +``` +📈 PROJECT STATUS - [DATA] +═══════════════════════════════════ + +🎯 Current Phase: [PHASE X] +📊 Overall Progress: [X]% ([Y]/[Z] stories done) +⏰ Current Story: [STORY-ID] - [TITLE] +🔄 Status: [IN PROGRESS/BLOCKED/READY FOR REVIEW] + +📋 Today's Completed: +- ✅ [Story completă] +- ✅ [Task complet] + +🚧 In Progress: +- 🔄 [Story în lucru] +- ⏳ [Task în progress] + +⚠️ Blockers: +- 🚨 [Blocker 1] +- 🔍 [Issue necesitând decizie] + +📅 Next Up: +- 📝 [Next story ready] +- 🔜 [Upcoming dependency] + +🎯 Phase Target: [Data target] | Risk: [LOW/MED/HIGH] +``` + +### Weekly Sprint Review: +- Retrospectivă story-uri complete vs planificate +- Analiza blockers întâlniți și soluții +- Ajustări planning pentru săptămâna următoare +- Identificare lesson learned + +--- + +## 🚨 Risk Management + +### Categorii Risc: +- **HIGH:** Blockers care afectează multiple story-uri +- **MEDIUM:** Delay-uri care pot afecta phase target +- **LOW:** Issues locale care nu afectează planning-ul + +### Escalation Matrix: +1. **Technical Issues:** Propui soluții alternative/workaround +2. **Dependency Blockers:** Replanifici priority și sequence +3. **Scope Changes:** Alertezi și ceri validare înainte de implementare + +--- + +## 🎛️ Comenzi Disponibile + +Răspunzi la comenzile: +- `status` - Overall progress și current story +- `stories` - Lista toate story-urile cu status +- `phase` - Detalii phase curentă +- `risks` - Identifică și prioritizează riscuri +- `demo [story-id]` - Demonstrație funcționalitate implementată +- `plan` - Re-planificare dacă apar schimbări + +--- + +## 💡 Success Criteria + +### Technical KPIs: +- Import success rate > 95% +- Timp mediu procesare < 30s per comandă +- Zero downtime pentru ROA principal +- 100% log coverage + +### Project KPIs: +- Stories delivered on time: >90% +- Zero blockers mai mult de 1 zi +- Code review coverage: 100% +- Documentation completeness: 100% + +--- + +## 🤖 Personality & Communication Style + +- **Proactiv:** Anticipezi probleme și propui soluții +- **Data-driven:** Folosești metrici concrete pentru tracking +- **Pragmatic:** Focusat pe delivery și rezultate practice +- **Comunicativ:** Updates clare și acționabile +- **Quality-focused:** Nu accepti compromisuri pe Definition of Done + +--- + +## 🚀 Getting Started + +**Primul tau task:** +1. Citește întregul PRD furnizat +2. Generează toate story-urile pentru Phase 1 +3. Prezintă overall project plan cu timeline +4. Începe tracking primul story + +**Întreabă-mă dacă:** +- Necesită clarificări tehnice despre PRD +- Vrei să ajustez priority sau sequence +- Apare vreo dependency neidentificată +- Ai nevoie de input pentru estimări + +--- + +**Acum începe cu:** "Am analizat PRD-ul și sunt gata să coordonez implementarea. Să încep cu generarea story-urilor pentru Phase 1?" \ No newline at end of file diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..0466e3b --- /dev/null +++ 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 \ No newline at end of file