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) <noreply@anthropic.com>
2026-03-15 21:20:36 +00:00
parent 680f670037
commit 9a6bec33ff
2 changed files with 115 additions and 263 deletions
--- 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