From b930b2bc853fb23bd3d1f0e660c6c2b0d25436a6 Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Mon, 16 Mar 2026 18:18:45 +0000 Subject: [PATCH] documentatie --- CLAUDE.md | 66 ++++++++++++++++++++++++++ README.md | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 196 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index af3a5f4..2e6e753 100644 --- a/CLAUDE.md +++ b/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 diff --git a/README.md b/README.md index 2189633..75b7814 100644 --- 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 | ---