207 lines
9.1 KiB
Markdown
207 lines
9.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# .env
|
|
ORACLE_USER=CONTAFIN_ORACLE
|
|
ORACLE_PASSWORD=********
|
|
ORACLE_DSN=ROA_ROMFAST
|
|
TNS_ADMIN=/app
|
|
```
|
|
|
|
## Deploy & Depanare Windows
|
|
|
|
Vezi [README.md](README.md#deploy-windows) pentru instructiuni complete de deploy si depanare pe Windows Server.
|