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)

GStack Workflow (pentru features noi)

1. /plan-ceo-review — planning interactiv (alegi modul: expansion / hold scope / reducere)
2. Implementare cu TeamCreate (ca de obicei)
3. /review — code review pe diff înainte de ship
4. /ship — push + unit tests + crează PR automat
5. /qa — testează aplicația live în browser real (după ce rulează)

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
                       ↓
              [SQLite — tracking DB]
              orders, sync_runs, missing_skus,
              order_items, web_products,
              invoice cache, app_settings

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)

API Endpoints — Sync & Comenzi

Sync

Method	Path	Descriere
POST	/api/sync/start	Porneste sync in background
POST	/api/sync/stop	Trimite semnal de stop
GET	/api/sync/status	Status curent + last_run
GET	/api/sync/history	Istoric run-uri (paginat)
GET	/api/sync/run/{run_id}	Detalii run
GET	/api/sync/run/{run_id}/log	Log per comanda (JSON)
GET	/api/sync/run/{run_id}/text-log	Log text (live sau din SQLite)
GET	/api/sync/run/{run_id}/orders	Comenzi run filtrate/paginate
GET	/api/sync/order/{order_number}	Detaliu comanda + items + factura

Dashboard Comenzi

Method	Path	Descriere
GET	/api/dashboard/orders	Comenzi cu date factura (cache SQLite → Oracle fallback)
POST	/api/dashboard/refresh-invoices	Force-refresh stare facturi + comenzi sterse din ROA

Parametri /api/dashboard/orders:

• period_days: 3/7/30/90 sau 0 (all / custom range)
• period_start, period_end: interval custom (cand period_days=0)
• status: all / IMPORTED / SKIPPED / ERROR / UNINVOICED / INVOICED
• search, sort_by, sort_dir, page, per_page

POST /api/dashboard/refresh-invoices face:

1. Necacturate → verifica Oracle daca au primit factura
2. Cacturate → verifica Oracle daca factura a fost stearsa
3. Toate importate → verifica Oracle daca comanda a fost stearsa (→ DELETED_IN_ROA)

Scheduler

Method	Path	Descriere
PUT	/api/sync/schedule	Configureaza scheduler (enabled, interval_minutes)
GET	/api/sync/schedule	Status curent scheduler

Settings

Method	Path	Descriere
GET	/api/settings	Citeste setari aplicatie
PUT	/api/settings	Salveaza setari
GET	/api/settings/sectii	Lista sectii Oracle (dropdown)
GET	/api/settings/politici	Lista politici preturi Oracle (dropdown)

Invoice Cache (SQLite)

Facturile sunt cacate in coloana factura_* pe tabelul orders:

• factura_serie, factura_numar, factura_data
• factura_total_fara_tva, factura_total_tva, factura_total_cu_tva

Sursa Oracle: SELECT ... FROM vanzari WHERE id_comanda IN (...) AND sters=0

Populare cache:

• La fiecare cerere /api/dashboard/orders — comenzile fara cache sunt verificate live si cacate
• La deschidere detaliu comanda /api/sync/order/{order_number} — verifica live daca nu e caat
• La POST /api/dashboard/refresh-invoices — refresh complet pentru toate comenzile

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)
• Statuses: IMPORTED / ALREADY_IMPORTED / SKIPPED / ERROR / DELETED_IN_ROA
• Upsert rule: daca status=IMPORTED exista, nu se suprascrie cu ALREADY_IMPORTED

Configuration

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

Deploy & Depanare Windows

Vezi README.md pentru instructiuni complete de deploy si depanare pe Windows Server.