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
cd api && uvicorn app.main:app --host 0.0.0.0 --port 5003 --reload

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

UI Development Workflow: Before → Preview → After

For UI/frontend changes, follow this visual verification workflow:

1. Before Screenshots

Capture current state with Playwright MCP at target viewports:

• Mobile: 375x812
• Desktop: 1440x900 Save to screenshots/before/

2. Plan & Preview

• Write implementation plan with design decisions
• Generate preview mockups if needed → save to screenshots/preview/
• Get user approval on previews before implementation

3. 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 care isi iau task-uri din lista
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. Screenshot-uri → screenshots/after/
3. Compara after/ vs preview/ vizual
4. Raporteaza discrepante la team lead
5. Verifica ca desktop-ul ramane neschimbat

screenshots/
├── before/     # Starea inainte de modificari
├── preview/    # Mockup-uri aprobate de user
└── after/      # Verificare post-implementare

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