romfast/gomag-vending
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add sync flow documentation with all 3 sync types explained

Browse Source 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Agent
2026-03-23 10:17:23 +00:00
parent b625609645
commit 65dcafba03
1 changed files with 51 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
README.md
View File

@@ -213,7 +213,53 @@ gomag-vending/
## Facturi & Cache
Facturile sunt verificate live din Oracle si cacate in SQLite (`factura_*` pe tabelul `orders`).
### Sincronizari
Sistemul are 3 procese de sincronizare si o setare de refresh UI:
#### 1. Sync Comenzi (Dashboard → scheduler sau buton Sync)
Procesul principal. Importa comenzi din GoMag in Oracle si verifica statusul celor existente.
**Pasi:**
1. Descarca comenzile din GoMag API (ultimele N zile, configurat in Setari)
2. Valideaza SKU-urile fiecarei comenzi:
- Cauta in ARTICOLE_TERTI (mapari manuale) → apoi in NOM_ARTICOLE (potrivire directa)
- Daca un SKU nu e gasit nicaieri → comanda e marcata SKIPPED si SKU-ul apare in "SKU-uri lipsa"
3. Verifica daca comanda exista deja in Oracle → da: ALREADY_IMPORTED, nu: se importa
4. Comenzi cu status ERROR din run-uri anterioare sunt reverificate in Oracle (crash recovery)
5. Import in Oracle: cauta/creeaza partener → adrese → comanda
6. **Verificare facturi** (la fiecare sync):
- Comenzi nefacturate → au primit factura in ROA? → salveaza serie/numar/total
- Comenzi facturate → a fost stearsa factura? → sterge cache
- Comenzi importate → au fost sterse din ROA? → marcheaza DELETED_IN_ROA
**Cand ruleaza:**
- **Automat:** scheduler configurat din Dashboard (interval: 5 / 10 / 30 min)
- **Manual:** buton "Sync" din Dashboard sau `POST /api/sync/start`
- **Doar facturi:** `POST /api/dashboard/refresh-invoices` (sare pasii 1-5)
> Facturarea in ROA **nu** declanseaza sync — statusul se actualizeaza la urmatorul sync sau refresh manual.
#### 2. Sync Preturi din Comenzi (Setari → on/off)
La fiecare sync comenzi, daca este activat (`price_sync_enabled=1`), compara preturile din comanda GoMag cu cele din politica de pret Oracle si le actualizeaza daca difera.
Configurat din: **Setari → Sincronizare preturi din comenzi**
#### 3. Sync Catalog Preturi (Setari → manual sau zilnic)
Sync independent de comenzi. Descarca **toate produsele** din catalogul GoMag, le potriveste cu articolele Oracle (prin CODMAT/SKU) si actualizeaza preturile in politica de pret.
Configurat din: **Setari → Sincronizare Preturi** (activare + program)
- **Doar manual:** buton "Sincronizeaza acum" din Setari sau `POST /api/price-sync/start`
- **Zilnic la 03:00 / 06:00:** optiune in UI (**neimplementat** — setarea se salveaza dar scheduler-ul zilnic nu exista inca)
#### Interval polling dashboard (Setari → Dashboard)
Cat de des verifica **interfata web** (browser-ul) statusul sync-ului. Valoare in secunde (implicit 5s). **Nu afecteaza frecventa sync-ului** — e doar refresh-ul UI-ului.
Facturile sunt verificate din Oracle si cached in SQLite (`factura_*` pe tabelul `orders`).
### Sursa Oracle
```sql
@@ -225,8 +271,8 @@ WHERE id_comanda IN (...) AND sters = 0
```
### Populare Cache
1. **Dashboard** (`GET /api/dashboard/orders`) — comenzile fara cache sunt verificate live si cacate automat la fiecare request
2. **Detaliu comanda** (`GET /api/sync/order/{order_number}`) — verifica Oracle live daca nu e caat
1. **Dashboard** (`GET /api/dashboard/orders`) — comenzile fara cache sunt verificate live si cached automat la fiecare request
2. **Detaliu comanda** (`GET /api/sync/order/{order_number}`) — verifica Oracle live daca nu e cached
3. **Refresh manual** (`POST /api/dashboard/refresh-invoices`) — refresh complet pentru toate comenzile
### Refresh Complet — `/api/dashboard/refresh-invoices`
@@ -235,8 +281,8 @@ Face trei verificari in Oracle si actualizeaza SQLite:
| Verificare | Actiune |
|------------|---------|
| Comenzi necacturate → au primit factura? | Cacheaza datele facturii |
| Comenzi cacturate → factura a fost stearsa? | Sterge cache factura |
| Comenzi nefacturate → au primit factura? | Cached datele facturii |
| Comenzi facturate → factura a fost stearsa? | Sterge cache factura |
| Toate comenzile importate → comanda stearsa din ROA? | Seteaza status `DELETED_IN_ROA` |
Returneaza: `{ checked, invoices_added, invoices_cleared, orders_deleted }`