documentatie

2026-03-16 18:18:45 +00:00
parent 5dfd795908
commit b930b2bc85
2 changed files with 196 additions and 7 deletions
--- a/README.md
+++ b/README.md
@@ -173,6 +173,18 @@ gomag-vending/
 6. Rezultate salvate in SQLite (orders, sync_run_orders, order_items)
 ```

+### Statuses Comenzi
+
+| Status | Descriere |
+|--------|-----------|
+| `IMPORTED` | Importata nou in ROA in acest run |
+| `ALREADY_IMPORTED` | Existenta deja in Oracle, contorizata |
+| `SKIPPED` | SKU-uri lipsa → neimportata |
+| `ERROR` | Eroare la import |
+| `DELETED_IN_ROA` | A fost importata dar comanda a fost stearsa din ROA |
+
+**Regula upsert:** daca statusul existent este `IMPORTED`, nu se suprascrie cu `ALREADY_IMPORTED`.
+
 ### Reguli Business
 - **Persoana**: shipping name = persoana pe eticheta = beneficiarul facturii
 - **Adresa**: cand billing ≠ shipping → adresa shipping pentru ambele (facturare + livrare)
@@ -182,6 +194,87 @@ gomag-vending/

 ---

+## Facturi & Cache
+
+Facturile sunt verificate live din Oracle si cacate in SQLite (`factura_*` pe tabelul `orders`).
+
+### Sursa Oracle
+```sql
+SELECT id_comanda, numar_act, serie_act,
+       total_fara_tva, total_tva, total_cu_tva,
+       TO_CHAR(data_act, 'YYYY-MM-DD')
+FROM vanzari
+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
+3. **Refresh manual** (`POST /api/dashboard/refresh-invoices`) — refresh complet pentru toate comenzile
+
+### Refresh Complet — `/api/dashboard/refresh-invoices`
+
+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 |
+| Toate comenzile importate → comanda stearsa din ROA? | Seteaza status `DELETED_IN_ROA` |
+
+Returneaza: `{ checked, invoices_added, invoices_cleared, orders_deleted }`
+
+---
+
+## API Reference — 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 + progres + last_run |
+| GET | `/api/sync/history` | Istoric run-uri (paginat) |
+| GET | `/api/sync/run/{id}` | Detalii run specific |
+| GET | `/api/sync/run/{id}/log` | Log per comanda (JSON) |
+| GET | `/api/sync/run/{id}/text-log` | Log text (live din memorie sau reconstruit din SQLite) |
+| GET | `/api/sync/run/{id}/orders` | Comenzi run filtrate/paginate |
+| GET | `/api/sync/order/{number}` | Detaliu comanda + items + ARTICOLE_TERTI + factura |
+
+### Dashboard Comenzi
+| Method | Path | Descriere |
+|--------|------|-----------|
+| GET | `/api/dashboard/orders` | Comenzi cu enrichment factura |
+| POST | `/api/dashboard/refresh-invoices` | Force-refresh stare facturi + deleted orders |
+
+**Parametri `/api/dashboard/orders`:**
+- `period_days`: 3/7/30/90 sau 0 (toate sau interval custom)
+- `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`
+
+Filtrele `UNINVOICED` si `INVOICED` fac fetch din toate comenzile IMPORTED si filtreaza server-side dupa prezenta/absenta cache-ului de factura.
+
+### Scheduler
+| Method | Path | Descriere |
+|--------|------|-----------|
+| PUT | `/api/sync/schedule` | Configureaza (enabled, interval_minutes: 5/10/30) |
+| GET | `/api/sync/schedule` | Status curent |
+
+Configuratia este persistata in SQLite (`scheduler_config`).
+
+### Settings
+| Method | Path | Descriere |
+|--------|------|-----------|
+| GET | `/api/settings` | Citeste setari aplicatie |
+| PUT | `/api/settings` | Salveaza setari |
+| GET | `/api/settings/sectii` | Lista sectii Oracle |
+| GET | `/api/settings/politici` | Lista politici preturi Oracle |
+
+**Setari disponibile:** `transport_codmat`, `transport_vat`, `discount_codmat`, `discount_vat`, `transport_id_pol`, `discount_id_pol`, `id_pol`, `id_sectie`, `gomag_api_key`, `gomag_api_shop`, `gomag_order_days_back`, `gomag_limit`
+
+---
+
 ## Status Implementare

 | Faza | Status | Descriere |
@@ -204,13 +297,20 @@ gomag-vending/

 Scriptul `deploy.ps1` face automat: git clone, venv, dependinte, detectare Oracle, `start.bat`, serviciu NSSM, configurare IIS reverse proxy.

-### Update
+### Update cod (pull + restart)

 ```powershell
 # Ca Administrator
 .\update.ps1
 ```

+Sau manual:
+```powershell
+cd C:\gomag-vending
+git pull origin main
+nssm restart GoMagVending
+```
+
 ### Configurare `.env` pe Windows

 ```ini
@@ -220,24 +320,39 @@ ORACLE_PASSWORD=****
 ORACLE_DSN=ROA
 TNS_ADMIN=C:\roa\instantclient_11_2_0_2
 INSTANTCLIENTPATH=C:\app\Server\product\18.0.0\dbhomeXE\bin
+SQLITE_DB_PATH=api/data/import.db
+JSON_OUTPUT_DIR=api/data/orders
+APP_PORT=5003
+ID_POL=39
+ID_GESTIUNE=0
+ID_SECTIE=6
+GOMAG_API_KEY=...
+GOMAG_API_SHOP=...
+GOMAG_ORDER_DAYS_BACK=7
+GOMAG_LIMIT=100
 ```

 **Important:**
 - `TNS_ADMIN` = folderul care contine `tnsnames.ora` (NU fisierul in sine)
 - `ORACLE_DSN` = alias-ul exact din `tnsnames.ora`
- `INSTANTCLIENTPATH` = calea catre Oracle bin (thick mode)
+- `INSTANTCLIENTPATH` = calea catre Oracle bin (thick mode, Oracle 10g/11g)
+- `FORCE_THIN_MODE=true` = elimina necesitatea Instant Client (Oracle 12.1+)
+- Setarile din `.env` pot fi suprascrise din UI → `Setari` → salvate in SQLite

 ### Serviciu Windows (NSSM)

 ```powershell
-nssm restart GoMagVending    # restart
-nssm status GoMagVending     # status
-nssm stop GoMagVending       # stop
+nssm restart GoMagVending    # restart serviciu
+nssm status GoMagVending     # status serviciu
+nssm stop GoMagVending       # stop serviciu
+nssm start GoMagVending      # start serviciu
 ```

 Loguri serviciu: `logs/service_stdout.log`, `logs/service_stderr.log`
 Loguri aplicatie: `logs/sync_comenzi_*.log`

+**Nota:** Userul `gomag` nu are drepturi de admin — `nssm restart` necesita PowerShell Administrator direct pe server.
+
 ### Depanare SSH

 ```bash
@@ -258,9 +373,14 @@ Get-Process *python* | Select-Object Id,ProcessName,Path

 # Verificare loguri recente
 Get-ChildItem C:\gomag-vending\logs\*.log | Sort-Object LastWriteTime -Descending | Select-Object -First 3
-```

-**Nota SSH:** Userul `gomag` nu are drepturi de admin — `nssm restart` si `net stop/start` necesita PowerShell Administrator direct pe server.
+# Test sync manual (verifica ca Oracle pool porneste)
+curl http://localhost:5003/health
+curl -X POST http://localhost:5003/api/sync/start
+
+# Refresh facturi manual
+curl -X POST http://localhost:5003/api/dashboard/refresh-invoices
+```

 ### Probleme frecvente

@@ -269,6 +389,9 @@ Get-ChildItem C:\gomag-vending\logs\*.log | Sort-Object LastWriteTime -Descendin
 | `ORA-12154: TNS:could not resolve` | `TNS_ADMIN` gresit sau `tnsnames.ora` nu contine alias-ul DSN | Verifica `TNS_ADMIN` in `.env` + alias in `tnsnames.ora` |
 | `ORA-04088: LOGON_AUDIT_TRIGGER` + `Nu aveti licenta pentru PYTHON` | Trigger ROA blocheaza executabile nelicențiate | Adauga `python.exe` (calea completa) in ROASUPORT |
 | `503 Service Unavailable` pe `/api/articles/search` | Oracle pool nu s-a initializat | Verifica logul `sync_comenzi_*.log` pentru eroarea exacta |
+| Facturile nu apar in dashboard | Cache SQLite gol — invoice_service nu a putut interoga Oracle | Apasa butonul Refresh Facturi din dashboard sau `POST /api/dashboard/refresh-invoices` |
+| Comanda apare ca `DELETED_IN_ROA` | Comanda a fost stearsa manual din ROA | Normal — marcat automat la refresh |
+| Scheduler nu porneste dupa restart | Config pierduta | Verifica SQLite `scheduler_config` sau reconfigureaza din UI |

 ---