From 9a6bec33ffec1321f5a68afbb165bbd55094653a Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Sun, 15 Mar 2026 21:20:36 +0000 Subject: [PATCH] docs: rewrite CLAUDE.md and README.md, remove VFP references - Remove all Visual FoxPro references (VFP fully replaced by Python) - Add TeamCreate workflow for parallel UI development - Document before/preview/after visual verification with Playwright - Add mandatory rule: use TeamCreate, not superpowers subagents - Update architecture, tech stack, project structure to current state - Update import flow to reference Python services Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 326 +++++++++++++++--------------------------------------- README.md | 52 ++++----- 2 files changed, 115 insertions(+), 263 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8f3cd6a..3d60c20 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,270 +1,128 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## 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 → Sistem ROA Oracle +**System:** Import Comenzi Web GoMag → Sistem ROA Oracle -This is a multi-tier system that automatically imports orders from web platforms (GoMag, etc.) into the ROA Oracle ERP system. The project combines Oracle PL/SQL packages, Visual FoxPro orchestration, and a FastAPI web admin/dashboard interface. - -**Current Status:** Phase 4 Complete, Phase 5 In Progress -- ✅ Phase 1: Database Foundation (ARTICOLE_TERTI, IMPORT_PARTENERI, IMPORT_COMENZI) -- ✅ Phase 2: VFP Integration (gomag-vending.prg, sync-comenzi-web.prg) -- ✅ Phase 3-4: FastAPI Admin + Dashboard (mappings CRUD, sync orchestration, pre-validation) -- 🔄 Phase 5: Production (file logging done, auth + notifications pending) - -## Architecture - -``` -[Web Platform API] → [VFP Orchestrator] → [Oracle PL/SQL] → [Web Admin Interface] - ↓ ↓ ↑ ↑ - JSON Orders Process & Log Store/Update Configuration -``` +Importa automat comenzi din GoMag in sistemul ERP ROA Oracle. Stack complet Python/FastAPI. ### Tech Stack -- **Backend:** Oracle PL/SQL packages -- **Integration:** Visual FoxPro 9 -- **Admin/Dashboard:** FastAPI + Jinja2 + Oracle pool + SQLite -- **Data:** Oracle 11g/12c (ROA system), SQLite (local tracking) - -## Core Components - -### Oracle PL/SQL Packages - -#### 1. IMPORT_PARTENERI Package -**Location:** `api/database-scripts/02_import_parteneri.sql` -**Functions:** -- `cauta_sau_creeaza_partener()` - Search/create partners with priority: cod_fiscal → denumire → create new -- `parseaza_adresa_semicolon()` - Parse addresses in format "JUD:București;BUCURESTI;Str.Victoriei;10" - -**Logic:** -- Individual vs company detection (CUI 13 digits) -- Automatic address defaults to București Sectorul 1 -- All new partners get ID_UTIL = -3 (system) - -#### 2. IMPORT_COMENZI Package -**Location:** `api/database-scripts/03_import_comenzi.sql` -**Functions:** -- `gaseste_articol_roa()` - Complex SKU mapping with pipelined functions -- `importa_comanda_web()` - Complete order import with JSON parsing - -**Mapping Types:** -- Simple: SKU 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 - -### Visual FoxPro Integration - -#### gomag-vending.prg -**Location:** `vfp/gomag-vending.prg` -Current functionality: -- GoMag API integration with pagination -- JSON data retrieval and processing -- HTML entity cleaning (ă→a, ș→s, ț→t, î→i, â→a) - -**Future:** Will be adapted for JSON output to Oracle packages - -#### sync-comenzi-web.prg (Phase 2) -**Planned orchestrator with:** -- 5-minute timer automation -- Oracle package integration -- Comprehensive logging system -- Error handling and retry logic - -### Database Schema - -#### ARTICOLE_TERTI Table -**Location:** `api/database-scripts/01_create_table.sql` -```sql -CREATE TABLE ARTICOLE_TERTI ( - sku VARCHAR2(100), -- SKU from web platform - codmat VARCHAR2(50), -- CODMAT from nom_articole - cantitate_roa NUMBER(10,3), -- ROA units per web unit - procent_pret NUMBER(5,2), -- Price percentage for sets - activ NUMBER(1), -- 1=active, 0=inactive - PRIMARY KEY (sku, codmat) -); -``` - -### FastAPI Admin/Dashboard - -#### app/main.py -**Location:** `api/app/main.py` -**Features:** -- FastAPI with lifespan (Oracle pool + SQLite init) -- File logging to `logs/sync_comenzi_YYYYMMDD_HHMMSS.log` -- Routers: health, dashboard, mappings, articles, validation, sync -- Services: mapping, article, import, sync, validation, order_reader, sqlite, scheduler -- Templates: Jinja2 (dashboard, mappings, sync_detail, missing_skus) -- Dual database: Oracle (ERP data) + SQLite (tracking) -- APScheduler for periodic sync +- **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 -### Database Setup ```bash -# Start Oracle container -docker-compose up -d +# Run FastAPI server +cd api && uvicorn app.main:app --host 0.0.0.0 --port 5003 --reload -# Run database scripts in order -sqlplus CONTAFIN_ORACLE/password@ROA_ROMFAST @01_create_table.sql -sqlplus CONTAFIN_ORACLE/password@ROA_ROMFAST @02_import_parteneri.sql -sqlplus CONTAFIN_ORACLE/password@ROA_ROMFAST @03_import_comenzi.sql -``` - -### VFP Development -```foxpro -DO vfp/gomag-vending.prg -``` - -### FastAPI Admin/Dashboard -```bash -cd api -pip install -r requirements.txt -uvicorn app.main:app --host 0.0.0.0 --port 5003 --reload -``` - -### Testare -```bash +# Tests python api/test_app_basic.py # Test A - fara Oracle python api/test_integration.py # Test C - cu Oracle ``` -## Project Structure +## UI Development Workflow: Before → Preview → After + +For UI/frontend changes, follow this visual verification workflow: + +### 1. Before Screenshots +Capture current state with Playwright MCP at target viewports: +- **Mobile:** 375x812 +- **Desktop:** 1440x900 +Save to `screenshots/before/` + +### 2. Plan & Preview +- Write implementation plan with design decisions +- Generate preview mockups if needed → save to `screenshots/preview/` +- Get user approval on previews before implementation + +### 3. 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 care isi iau task-uri din lista +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. Screenshot-uri → `screenshots/after/` +3. Compara `after/` vs `preview/` vizual +4. Raporteaza discrepante la team lead +5. Verifica ca desktop-ul ramane neschimbat ``` -/ -├── api/ # ✅ Flask Admin & Database -│ ├── admin.py # ✅ Flask app with Oracle pool -│ ├── database-scripts/ # ✅ Oracle SQL scripts -│ │ ├── 01_create_table.sql # ✅ ARTICOLE_TERTI table -│ │ ├── 02_import_parteneri.sql # ✅ Partners package -│ │ └── 03_import_comenzi.sql # ✅ Orders package -│ ├── Dockerfile # ✅ Oracle client container -│ ├── tnsnames.ora # ✅ Oracle connection config -│ ├── .env # ✅ Environment variables -│ └── requirements.txt # ✅ Python dependencies -├── docs/ # 📋 Project Documentation -│ ├── PRD.md # ✅ Product Requirements -│ ├── LLM_PROJECT_MANAGER_PROMPT.md # ✅ Project Management -│ └── stories/ # 📋 User Stories -│ ├── P1-001-ARTICOLE_TERTI.md # ✅ Story P1-001 (COMPLETE) -│ ├── P1-002-Package-IMPORT_PARTENERI.md # ✅ Story P1-002 (COMPLETE) -│ ├── P1-003-Package-IMPORT_COMENZI.md # ✅ Story P1-003 (COMPLETE) -│ └── P1-004-Testing-Manual-Packages.md # 📋 Story P1-004 (READY) -├── vfp/ # ⏳ VFP Integration -│ ├── gomag-vending.prg # ✅ Current GoMag client -│ ├── utils.prg # ✅ Utility functions -│ ├── nfjson/ # ✅ JSON parsing library -│ └── sync-comenzi-web.prg # ⏳ Future orchestrator -├── docker-compose.yaml # ✅ Container setup -└── logs/ # ✅ Application logs +screenshots/ +├── before/ # Starea inainte de modificari +├── preview/ # Mockup-uri aprobate de user +└── after/ # Verificare post-implementare ``` -## Configuration +### 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 -### Environment Variables (.env) -```env -ORACLE_USER=CONTAFIN_ORACLE -ORACLE_PASSWORD=******** -ORACLE_DSN=ROA_ROMFAST -TNS_ADMIN=/app -INSTANTCLIENTPATH=/opt/oracle/instantclient +## Architecture + +``` +[GoMag API] → [Python Sync Service] → [Oracle PL/SQL] → [FastAPI Admin] + ↓ ↓ ↑ ↑ + JSON Orders Download/Parse/Import Store/Update Dashboard + Config ``` -### Business Rules +### 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) -#### Partners +## Business Rules + +### Partners - Search priority: cod_fiscal → denumire → create new - Individuals (CUI 13 digits): separate nume/prenume -- Default address: București Sectorul 1 +- Default address: Bucuresti Sectorul 1 - All new partners: ID_UTIL = -3 -#### Articles -- Simple SKUs: found directly in nom_articole (not stored) -- Special mappings: only repackaging and complex sets -- Inactive articles: activ=0 (not deleted) +### 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 -- Uses existing PACK_COMENZI packages +### Orders - Default: ID_GESTIUNE=1, ID_SECTIE=1, ID_POL=0 - Delivery date = order date + 1 day - All orders: INTERNA=0 (external) -## Phase Implementation Status +## Configuration -### ✅ Phase 1: Database Foundation (75% Complete) -- **P1-001:** ✅ ARTICOLE_TERTI table + Docker setup -- **P1-002:** ✅ IMPORT_PARTENERI package complete -- **P1-003:** ✅ IMPORT_COMENZI package complete -- **P1-004:** 🔄 Manual testing (READY TO START) - -### ⏳ Phase 2: VFP Integration (Planned) -- Adapt gomag-vending.prg for JSON output -- Create sync-comenzi-web.prg orchestrator -- Oracle packages integration -- Logging system with rotation - -### ⏳ Phase 3: Web Admin Interface (Planned) -- Flask app with Oracle connection pool -- HTML/CSS admin interface -- JavaScript CRUD operations -- Client/server-side validation - -### ⏳ Phase 4: Testing & Deployment (Planned) -- End-to-end testing with real orders -- Complex mappings validation -- Production environment setup -- User documentation - -## Key Functions - -### Oracle Packages -- `IMPORT_PARTENERI.cauta_sau_creeaza_partener()` - Partner management -- `IMPORT_PARTENERI.parseaza_adresa_semicolon()` - Address parsing -- `IMPORT_COMENZI.gaseste_articol_roa()` - SKU resolution -- `IMPORT_COMENZI.importa_comanda_web()` - Order import - -### VFP Utilities (utils.prg) -- `LoadSettings` - INI configuration management -- `InitLog`/`LogMessage`/`CloseLog` - Logging system -- `TestConnectivity` - Connection verification -- `CreateDefaultIni` - Default configuration - -## Success Metrics - -### Technical KPIs -- Import success rate > 95% -- Average processing time < 30s per order -- Zero downtime for main ROA system -- 100% log coverage - -### Business KPIs -- 90% reduction in manual order entry time -- Elimination of manual transcription errors -- New mapping configuration < 5 minutes - -## Error Handling - -### Categories -1. **Oracle connection errors:** Retry logic + alerts -2. **SKU not found:** Log warning + skip item -3. **Invalid partner:** Create attempt + detailed log -4. **Duplicate orders:** Skip with info log - -### Logging Format +```bash +# .env +ORACLE_USER=CONTAFIN_ORACLE +ORACLE_PASSWORD=******** +ORACLE_DSN=ROA_ROMFAST +TNS_ADMIN=/app ``` -2025-09-09 14:30:25 | ORDER-123 | OK | ID:456789 -2025-09-09 14:30:26 | ORDER-124 | ERROR | SKU 'XYZ' not found -``` - -## Project Manager Commands - -Available commands for project tracking: -- `status` - Overall progress and current story -- `stories` - List all stories with status -- `phase` - Current phase details -- `risks` - Identify and prioritize risks -- `demo [story-id]` - Demonstrate implemented functionality -- `plan` - Re-planning for changes \ No newline at end of file diff --git a/README.md b/README.md index f0570c5..c5ba731 100644 --- a/README.md +++ b/README.md @@ -5,16 +5,16 @@ System automat de import comenzi din platforma GoMag in sistemul ERP ROA Oracle. ## Arhitectura ``` -[GoMag API] → [VFP Orchestrator] → [Oracle PL/SQL] → [FastAPI Admin] - ↓ ↓ ↑ ↑ - JSON Orders Process & Log Store/Update Dashboard + Config +[GoMag API] → [Python Sync Service] → [Oracle PL/SQL] → [FastAPI Admin] + ↓ ↓ ↑ ↑ + JSON Orders Download/Parse/Import Store/Update Dashboard + Config ``` ### Stack Tehnologic -- **Database:** Oracle PL/SQL packages (PACK_IMPORT_PARTENERI, PACK_IMPORT_COMENZI) -- **Integrare:** Visual FoxPro 9 (gomag-vending.prg, sync-comenzi-web.prg) -- **Admin/Dashboard:** FastAPI + Jinja2 + Oracle pool + SQLite -- **Date:** Oracle 11g/12c (schema ROA), SQLite (tracking local) +- **API + Admin:** FastAPI + Jinja2 + Bootstrap 5.3 +- **GoMag Integration:** Python (`gomag_client.py` — download comenzi cu paginare) +- **Sync Orchestrator:** Python (`sync_service.py` — download → parse → validate → import) +- **Database:** Oracle PL/SQL packages (IMPORT_PARTENERI, IMPORT_COMENZI) + SQLite (tracking) --- @@ -27,7 +27,6 @@ System automat de import comenzi din platforma GoMag in sistemul ERP ROA Oracle. ### Instalare ```bash -# Din project root (gomag/) pip install -r api/requirements.txt cp api/.env.example api/.env # Editeaza api/.env cu datele de conectare Oracle @@ -38,7 +37,6 @@ cp api/.env.example api/.env **Important:** serverul trebuie pornit **din project root**, nu din `api/`: ```bash -# Din gomag/ python -m uvicorn api.app.main:app --host 0.0.0.0 --port 5003 ``` @@ -55,13 +53,11 @@ Deschide `http://localhost:5003` in browser. ```bash python api/test_app_basic.py ``` -Verifica importuri de module + rute GET. Asteptat: 32/33 PASS (1 fail pre-existent `/sync` HTML). **Test C - Integrare Oracle:** ```bash python api/test_integration.py ``` -Necesita Oracle activ. Verifica health, mappings CRUD, article search, validation, sync. --- @@ -82,7 +78,7 @@ cp api/.env.example api/.env | `INSTANTCLIENTPATH` | Cale Instant Client (thick mode) | `/opt/oracle/instantclient_21_15` | | `FORCE_THIN_MODE` | Thin mode fara Instant Client | `true` | | `SQLITE_DB_PATH` | Path SQLite (relativ la project root) | `api/data/import.db` | -| `JSON_OUTPUT_DIR` | Folder JSON-uri VFP (relativ la project root) | `vfp/output` | +| `JSON_OUTPUT_DIR` | Folder JSON-uri descarcate | `api/data/orders` | | `APP_PORT` | Port HTTP | `5003` | | `ID_POL` | ID Politica ROA | `39` | | `ID_GESTIUNE` | ID Gestiune ROA | `0` | @@ -97,7 +93,7 @@ cp api/.env.example api/.env ## Structura Proiect ``` -gomag/ +gomag-vending/ ├── api/ # FastAPI Admin + Dashboard │ ├── app/ │ │ ├── main.py # Entry point, lifespan, logging @@ -111,30 +107,28 @@ gomag/ │ │ │ ├── validation.py # /api/validate/* │ │ │ └── sync.py # /api/sync/* + /api/dashboard/orders │ │ ├── services/ -│ │ │ ├── sync_service.py # Orchestrare: JSON→validate→import +│ │ │ ├── gomag_client.py # Download comenzi GoMag API +│ │ │ ├── sync_service.py # Orchestrare: download→validate→import │ │ │ ├── import_service.py # Import comanda in Oracle ROA │ │ │ ├── mapping_service.py # CRUD ARTICOLE_TERTI + pct_total │ │ │ ├── sqlite_service.py # Tracking runs/orders/missing SKUs │ │ │ ├── order_reader.py # Citire gomag_orders_page*.json │ │ │ ├── validation_service.py │ │ │ ├── article_service.py +│ │ │ ├── invoice_service.py # Verificare facturi ROA │ │ │ └── scheduler_service.py # APScheduler timer │ │ ├── templates/ # Jinja2 HTML │ │ └── static/ # CSS + JS │ ├── database-scripts/ # Oracle SQL (ARTICOLE_TERTI, packages) -│ ├── data/ # SQLite DB (import.db) +│ ├── data/ # SQLite DB (import.db) + JSON orders │ ├── .env # Configurare locala (nu in git) │ ├── .env.example # Template configurare │ ├── test_app_basic.py # Test A - fara Oracle │ ├── test_integration.py # Test C - cu Oracle │ └── requirements.txt -├── vfp/ # VFP Integration -│ ├── gomag-vending.prg # Client GoMag API (descarca JSON-uri) -│ ├── sync-comenzi-web.prg # Orchestrator VFP -│ ├── utils.prg # Utilitare (log, settings, connectivity) -│ └── output/ # JSON-uri descarcate (gomag_orders_page*.json) ├── logs/ # Log-uri aplicatie (sync_comenzi_*.log) ├── docs/ # Documentatie (PRD, stories) +├── screenshots/ # Before/preview/after pentru UI changes ├── start.sh # Script pornire (Linux/WSL) └── CLAUDE.md # Instructiuni pentru AI assistants ``` @@ -171,10 +165,10 @@ gomag/ ## Fluxul de Import ``` -1. VFP descarca comenzi GoMag API → vfp/output/gomag_orders_page*.json -2. FastAPI citeste JSON-urile (order_reader) -3. Valideaza SKU-uri contra ARTICOLE_TERTI + NOM_ARTICOLE (validation_service) -4. Import_service creeaza/cauta partener in Oracle (shipping person = facturare) +1. gomag_client.py descarca comenzi GoMag API → JSON files +2. order_reader.py parseaza JSON-urile +3. validation_service.py valideaza SKU-uri contra ARTICOLE_TERTI + NOM_ARTICOLE +4. import_service.py creeaza/cauta partener in Oracle (shipping person = facturare) 5. PACK_IMPORT_COMENZI.importa_comanda_web() insereaza comanda in ROA 6. Rezultate salvate in SQLite (orders, sync_run_orders, order_items) ``` @@ -192,15 +186,15 @@ gomag/ | Faza | Status | Descriere | |------|--------|-----------| -| Phase 1: Database Foundation | ✅ Complet | ARTICOLE_TERTI, PACK_IMPORT_PARTENERI, PACK_IMPORT_COMENZI | -| Phase 2: VFP Integration | ✅ Complet | gomag-vending.prg, sync-comenzi-web.prg | -| Phase 3-4: FastAPI Dashboard | ✅ Complet | Redesign UI, smart polling, filter bar, paginare, tooltip | -| Phase 5: Production | 🔄 In Progress | Logging ✅, Auth ⏳, SMTP ⏳, NSSM service ⏳ | +| Phase 1: Database Foundation | Complet | ARTICOLE_TERTI, PACK_IMPORT_PARTENERI, PACK_IMPORT_COMENZI | +| Phase 2: Python Integration | Complet | gomag_client.py, sync_service.py | +| Phase 3-4: FastAPI Dashboard | Complet | UI responsive, smart polling, filter bar, paginare | +| Phase 5: Production | In Progress | Logging done, Auth + SMTP pending | --- ## WSL2 Note - `uvicorn --reload` **nu functioneaza** pe `/mnt/e/` (WSL2 limitation) — restarta manual -- Serverul trebuie pornit din **project root** (`gomag/`), nu din `api/` +- Serverul trebuie pornit din **project root**, nu din `api/` - `JSON_OUTPUT_DIR` si `SQLITE_DB_PATH` sunt relative la project root