documentatie

CLAUDE.md

@@ -97,6 +97,11 @@ screenshots/
 [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
@@ -106,6 +111,65 @@ screenshots/
 - **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
@@ -124,6 +188,8 @@ screenshots/
 - 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