gomag-vending/CLAUDE.md

CLAUDE.md

REGULI OBLIGATORII

Pentru task-uri paralele foloseste INTOTDEAUNA TeamCreate + TaskCreate, NU Agent tool cu subagenti paraleli. Skill-ul superpowers:dispatching-parallel-agents NU se aplica in acest proiect. In loc de dispatch cu Agent tool, creeaza o echipa cu TeamCreate, defineste task-uri cu TaskCreate, si spawneaza teammates cu Agent tool + team_name.

Project Overview

System: Import Comenzi Web GoMag → Sistem ROA Oracle

Importa automat comenzi din GoMag in sistemul ERP ROA Oracle. Stack complet Python/FastAPI.

Tech Stack

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

Development Commands

# Run FastAPI server — INTOTDEAUNA via start.sh (seteaza Oracle env vars)
./start.sh
# NU folosi uvicorn direct — lipsesc LD_LIBRARY_PATH si TNS_ADMIN pentru Oracle

# Tests
python api/test_app_basic.py       # Test A - fara Oracle
python api/test_integration.py     # Test C - cu Oracle

UI Development Workflow: Preview → Implement → Verify

OBLIGATORIU: Respecta ordinea exacta. NU treci la pasul urmator fara aprobare explicita.

1. Plan & Preview — ASTEAPTA APROBARE

1. Citeste TOATE fisierele implicate
2. Scrie planul de implementare cu decizii de design
3. Genereaza mockup-uri Markdown care descriu rezultatul asteptat (tabele, liste, cod pseudo-CSS) — NU HTML static
4. Prezinta mockup-urile userului si ASTEAPTA aprobare explicita
5. Rafineaza planul daca userul cere modificari
6. NU trece la implementare pana userul nu spune explicit "ok", "aprob", "executa" sau similar

2. Implementation cu TeamCreate (Agent Teams)

Folosim TeamCreate (team agents), NU superpowers subagents. Diferenta:

• TeamCreate: agenti independenti cu task list partajat, comunicare directa intre ei, context propriu
• Subagents (Agent tool): agenti care raporteaza doar la main — NU se folosesc

Workflow TeamCreate:

1. Main agent (team lead) citeste TOATE fisierele implicate, creeaza planul
2. TeamCreate creeaza echipa (ex: ui-polish)
3. TaskCreate creeaza task-uri independente, pe fisiere non-overlapping:
   • Task 1: Templates + CSS (HTML templates, style.css, cache-bust)
   • Task 2: JavaScript (shared.js, dashboard.js, logs.js, mappings.js)
   • Task 3: Verificare Playwright (depinde de Task 1 + Task 2)
4. Agent tool cu team_name spawneaza teammates folosind agentii predefiniti din .claude/agents/:
   • subagent_type: ui-templates → pentru Task 1 (templates + CSS)
   • subagent_type: ui-js → pentru Task 2 (JavaScript)
   • subagent_type: ui-verify → pentru Task 3 (Playwright verification)
   • subagent_type: backend-api → pentru modificari backend/API (routers, services, Oracle/SQLite)
   • subagent_type: qa-tester → pentru teste de integrare
5. Teammates lucreaza in paralel, comunica intre ei, marcheaza task-uri completate
6. Cand Task 1 + Task 2 sunt complete, teammate-ul de verificare preia Task 3

Teammate-ul de verificare (Task 3):

1. Navigheaza la fiecare pagina cu Playwright MCP la 375x812 (mobile) si 1440x900 (desktop)
2. Foloseste browser_snapshot (NU screenshot-uri) pentru a inspecta structura DOM
3. Verifica ca implementarea respecta fiecare punct din preview-ul aprobat (structura coloane, bold, dots, filtre etc.)
4. Raporteaza discrepante concrete la team lead (ce e diferit fata de preview)
5. NU salveaza screenshot-uri after/

Bucla de corectie (responsabilitatea team lead-ului):

1. Dupa ce verify-agent raporteaza, team lead-ul analizeaza discrepantele
2. Pentru fiecare discrepanta, creeaza un nou task de fix si spawneaza un agent sa-l rezolve
3. Dupa fix, spawneaza din nou verify-agent pentru re-verificare
4. Repeta bucla pana cand toate verificarile trec (implementare ≈ preview)
5. Abia atunci declara task-ul complet

screenshots/
└── preview/    # Mockup-uri Markdown aprobate de user (referinta pentru verificare)

Principii

• Team lead citeste TOATE fisierele inainte sa creeze task-uri
• Task-uri pe fisiere non-overlapping (evita conflicte)
• Fiecare task contine prompt detaliat, self-contained
• Desktop-ul nu trebuie sa se schimbe cand se adauga imbunatatiri mobile
• Cache-bust static assets (increment ?v=N) la fiecare schimbare UI
• Teammates comunica intre ei cu SendMessage, nu doar cu team lead-ul

Architecture

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

FastAPI App Structure

• Routers: health, dashboard, mappings, articles, validation, sync
• Services: gomag_client, sync, order_reader, import, mapping, article, validation, invoice, sqlite, scheduler
• Templates: Jinja2 (dashboard, mappings, missing_skus, logs)
• Static: CSS (style.css), JS (shared.js, dashboard.js, logs.js, mappings.js)
• Databases: Oracle (ERP data) + SQLite (order tracking, sync runs)

Business Rules

Partners

• Search priority: cod_fiscal → denumire → create new
• Individuals (CUI 13 digits): separate nume/prenume
• Default address: Bucuresti Sectorul 1
• All new partners: ID_UTIL = -3

Articles & Mappings

• Simple SKUs: found directly in nom_articole (not stored in ARTICOLE_TERTI)
• Repackaging: SKU → CODMAT with different quantities
• Complex sets: One SKU → multiple CODMATs with percentage pricing (must sum to 100%)
• Inactive articles: activ=0 (soft delete)

Orders

• Default: ID_GESTIUNE=1, ID_SECTIE=1, ID_POL=0
• Delivery date = order date + 1 day
• All orders: INTERNA=0 (external)

Configuration

# .env
ORACLE_USER=CONTAFIN_ORACLE
ORACLE_PASSWORD=********
ORACLE_DSN=ROA_ROMFAST
TNS_ADMIN=/app