From 3a10cc69c0f4b51e2facacc9116544833bc1839b Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Sat, 13 Jun 2026 11:45:39 +0000 Subject: [PATCH] =?UTF-8?q?docs(readme):=20README=20orientat=20pe=20scop?= =?UTF-8?q?=20=E2=80=94=20=C3=AEnv=C4=83=C8=9Bare=20+=20hedge=20VFP,=20nu?= =?UTF-8?q?=20produs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pagina repo-ului arăta README-ul generic roa2web și nu explica ce e diferit / ce se urmărea. README-ul nou pune scopul pe prima pagină: prototip de probă „web (Python/Vue) conduce business logic Oracle prin PL/SQL", driver-ul de risc-talent VFP, cele 6 ipoteze, scope wall, relația cu roa2web, stare WIP. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 462 ++++++++---------------------------------------------- 1 file changed, 66 insertions(+), 396 deletions(-) diff --git a/README.md b/README.md index 5c260c4..3a9916a 100644 --- a/README.md +++ b/README.md @@ -1,422 +1,92 @@ -# ROA2WEB - Modern ERP Application +# roa2web-service-auto -**FastAPI Backend + Vue.js 3 Frontend + Telegram Bot** +> **Prototip de învățare + hedge de risc de talent.** NU un produs, NU un MVP, NU un +> angajament de livrare către clienți. -Modern ultrathin monolith ERP application for managing reports, data entry, and financial data with Oracle database integration. +Acest repo explorează o singură întrebare strategică: ---- +**Poate stack-ul web (Python / FastAPI async / Vue 3 / PrimeVue) să conducă logica de +business Oracle end-to-end prin proceduri PL/SQL — păstrând PL/SQL ca strat durabil?** -## Project Overview +Domeniul ales pentru probă: **gestiune comenzi service auto** (atelier reparații auto) — +cel mai sigur teren de testare, pe o schemă Oracle dedicată de test (`MARIUSM_AUTO`), fără +nicio atingere a producției. -ROA2WEB is a comprehensive financial platform built with modern technologies: +## De ce există (driver-ul strategic) -- **Backend**: FastAPI (Python) - Unified async API with modular architecture -- **Frontend**: Vue.js 3 + PrimeVue - Single-page application with lazy-loaded modules -- **Telegram Bot**: Alternative command-based interface (integrated module) -- **Database**: Oracle Database + SQLite (hybrid approach) -- **Architecture**: Ultrathin monolith with clear module boundaries +Visual FoxPro (VFP) e o limbă moartă. ERP-ul care alimentează 4 clienți de lungă durată e +scris în VFP + Oracle, iar **nu se mai pot angaja programatori dispuși să învețe VFP** → +risc de talent care se acumulează an de an. ---- +Migrarea la Postgres nu e 1:1 (25 de ani de PL/SQL, sinonime cross-schema, arhitectură +tenant-per-schemă). Deci calea realistă de hedge este: -## Quick Start +> **Rămâi pe Oracle, mută stratul de UI + business logic pe Python/Vue, păstrează PL/SQL +> ca strat durabil.** -### Prerequisites +Service auto e locul cu cel mai mic risc unde se poate proba dacă această cale funcționează. +Hedge-ul rezolvă jumătatea de stack unde **există** forță de muncă (Python+Vue+integrare), +NU problema angajării de specialiști PL/SQL. -- Python 3.11+ -- Node.js 16+ -- Oracle Database access -- SSH access to Oracle server (for development) +## Ce probează concret (învățarea reală) -### Development Setup +Prototipul confirmă sau infirmă 6 ipoteze. Dacă oricare eșuează cu un răspuns **clar**, +prototipul s-a încheiat cu succes — learning obținut, decizie clară, zero cod irosit. -```bash -# Clone repository -git clone -cd roa2web +| # | Ipoteză | Status / referință | +|---|---------|--------------------| +| 1 | `python-oracledb` async apelează curat PL/SQL cu params IN+OUT | `poc/`, `week1-notes.md` | +| 2 | `session_callback` pentru `CURRENT_SCHEMA` nu leak-uiește între requests concurente | `week5-session-callback.md` | +| 3 | Grants „EXECUTE pe SP, zero acces direct la tabele" țin în practică | `grants-audit.md`, `week3-auth-audit.md` | +| 4 | `RAISE_APPLICATION_ERROR` cu diacritice ajunge în Vue ca eroare user-friendly (encoding corect) | mapare ORA→HTTP în `backend/modules/service_auto/` | +| 5 | DX (FastAPI hot-reload + Vite + SSH tunnel Oracle) e acceptabil pt side-work 2-4h/săpt | `week1-notes.md` | +| 6 | Auth-ul multi-server existent suportă un server nou **fără modificări la shared code** | `week3-auth-audit.md` | -# Start all services with one command -./start.sh prod # Production -./start.sh test # Test environment -``` +**Livrabilul real NU e ecranul de comandă** — e un **template reutilizabil pentru module +Oracle** (`docs/service-auto/template-modul-oracle.md`) + un **decision log** +(`docs/service-auto/decision-log.md`). Dacă dovezile sunt pozitive, același pattern se +aplică modulului următor. -This starts SSH tunnel (if needed), unified backend (port 8000), and frontend (port 3000). +## Ce e în scope vs NU -**For individual service setup or troubleshooting**: See "Development & Testing" section below. +**În scope** (prototip): 1 ecran (`ComandaNoua.vue`) → 1 SP de scriere → insert într-un +tabel dedicat de comenzi pe `MARIUSM_AUTO` → return ID + număr → Toast. -### Access the Application +**NU în scope** (zid de scop explicit): cei 4 clienți existenți (rămân pe VFP, zero +atingere), migrare scheme, eFactura/ANAF, insert în ACT (registrul jurnal — doar la +facturare), facturare, mobile/responsive, e2e Playwright, multi-tenant complet. Detalii în +`docs/service-auto/claude-main-design-20260411-rethink.md` (secțiunea „Scope wall"). -- **Frontend**: http://localhost:3000 -- **Backend API Docs**: http://localhost:8001/docs (Swagger UI) -- **Backend ReDoc**: http://localhost:8001/redoc -- **Health Check**: http://localhost:8001/health +## Relația cu roa2web ---- +Acest repo e un **fork complet** din [`romfast/roa2web`](https://gitea.romfast.ro/romfast/roa2web) +(strămoș comun: commit `b0f4800`). Conține tot codul comun roa2web (auth/JWT, pool Oracle +multi-tenant, shell-ul Vue SPA, design tokens, `AsyncAutoComplete`) PLUS modulul service-auto, +deci **rulează standalone**. Fix-urile se pot face `cherry-pick` în ambele sensuri. -## Architecture +Detalii de proveniență: [`PROVENANCE.md`](PROVENANCE.md). -### Ultrathin Monolith Structure +## Cod specific service-auto -``` -. -├── backend/ # Unified FastAPI backend (port 8001) -│ ├── modules/ # Business logic modules -│ │ ├── reports/ # Reports module (Oracle read-only) -│ │ ├── data_entry/ # Data entry module (SQLite + workflow) -│ │ └── telegram/ # Telegram bot module -│ ├── config.py # Centralized configuration -│ └── main.py # FastAPI app entry point -│ -├── src/ # Unified Vue.js 3 frontend -│ ├── modules/ # Feature modules -│ │ ├── reports/ # Reports frontend -│ │ └── data-entry/ # Data entry frontend -│ ├── shared/ # Shared frontend components -│ ├── assets/ # Global CSS, images -│ └── router/ # Vue Router -│ -├── shared/ # Shared backend components -│ ├── database/ # Oracle connection pool -│ ├── auth/ # JWT authentication -│ └── frontend/ # Shared frontend assets -│ -├── docs/ # Documentation -├── deployment/ # Deployment scripts -└── ssh-tunnel/ # SSH tunnel for Oracle DB -``` +| Zonă | Cale | +|------|------| +| Backend | `backend/modules/service_auto/` (router / service / schemas / tests) | +| Frontend | `src/modules/service-auto/` + `src/shared/components/AsyncAutoComplete.vue` | +| Oracle (pack-uri, DDL, migrări) | `docs/service-auto/` (`pack_auto.pck`, `pack_sesiune.pck`, `migrations/`) | +| POC-uri | `poc/` | +| Design, decizii, learnings | `docs/service-auto/` | -### Key Features +## ⚠️ Stare curentă -- **Shared Database Pool**: Singleton Oracle connection pool shared across all modules -- **Two-Tier Cache System**: Hybrid L1 (Memory) + L2 (SQLite) for optimal performance -- **JWT Authentication**: Secure token-based auth with middleware -- **Modular Architecture**: Independent modules with clear separation of concerns -- **Oracle Integration**: Direct Oracle stored procedure calls with caching -- **Responsive Design**: Mobile-friendly Vue.js interface -- **Telegram Integration**: Bot-based interface cu procesare bonuri fiscale prin OCR (PDF/foto → preview → salvare Oracle) +**WIP.** Ultimul commit de dezvoltare moștenit era „modificari in curs nu stiu care este +faza" (2026-06-05) — proiectul **nu era la un checkpoint curat** când a fost desprins din +roa2web (2026-06-13). Înainte de orice reluare: citește `docs/service-auto/decision-log.md` +și notele săptămânale (`week*-notes.md`) ca să reconstruiești faza. ---- +Teste auto-raportate la desprindere: 62 passed / 3 skipped (dependente de Oracle live). -## Tech Stack +## Setup -**Backend**: FastAPI, python-oracledb, JWT (PyJWT), Pydantic, pytest, **Two-tier cache (Memory + SQLite)** -**Frontend**: Vue.js 3 (Composition API), PrimeVue, Pinia, Vite, Axios, Chart.js, Playwright -**Telegram Bot**: python-telegram-bot, SQLite + aiosqlite, httpx, FastAPI (internal) -**Infrastructure**: Oracle Database, SSH Tunnel, Nginx, Docker (Linux), IIS + NSSM (Windows) - -*See `CLAUDE.md` for detailed tech stack information, cache system, and architecture decisions.* - ---- - -## Development & Testing - -**Quick Start**: Use `./start.sh prod` to start all services (SSH tunnel + Backend + Frontend). - -**For detailed development commands, testing procedures, and troubleshooting**: See `CLAUDE.md` and component-specific READMEs: -- Backend: `backend/ modules and CLAUDE.md` -- Frontend: `src/ and docs/MONOLITH_ARCHITECTURE.md` & `E2E testing guide in docs/` -- Telegram Bot: `backend/modules/telegram/README.md` - -**Key Commands**: -```bash -# Start All Services -./start.sh prod # Start PROD (SSH tunnel + Backend + Frontend) -./start.sh test # Start TEST (direct Oracle connection) -./start.sh prod stop # Stop PROD services -./start.sh test stop # Stop TEST services - -# Individual Service Control (for quick restarts) -./start-frontend.sh start|stop|restart|status # Frontend only (~7s restart!) -./start-backend.sh start|stop|restart|status # Backend only - -# System Monitoring -./status.sh # Show all services status + health checks - -# Infrastructure Only -./ssh-tunnel.sh start|stop|status # Oracle DB tunnel (for servers with SSH) -``` - -**💡 Pro Tips**: -- **Frontend changes?** Use `./start-frontend.sh restart` instead of restarting everything (87% faster!) -- **Check what's running:** `./status.sh` shows everything at a glance -- **Single unified script:** `start.sh` handles both environments with parameters - -### 📖 Usage Flow - -**Individual scripts (`start-frontend.sh`, `start-backend.sh`) are environment-neutral:** -- They DON'T change `.env` files -- They use whatever `.env` is already present -- Use them for **quick restarts** when working on a specific service - -**Master scripts (`start.sh prod`, `start.sh test`) set the environment:** -- `start.sh prod` → uses existing `.env` files (DEV mode) -- `start.sh test` → copies `.env.test` → `.env` (TEST mode) - -**Recommended workflow:** - -```bash -# Morning: Start full stack with environment selection -./start.sh prod # DEV mode - sets up .env files - -# During development: Quick service restarts -./start-frontend.sh restart # Frontend only (~7s) -./backend-reports.sh restart # Reports backend only (~30s) -# ⚠️ Individual scripts inherit the environment set by start.sh prod - -# End of day: Stop everything -./start.sh prod stop -``` - -**Common scenarios:** - -```bash -# Scenario 1: Working on frontend only -./start.sh prod # Start everything once -./start-frontend.sh restart # Restart frontend multiple times (fast!) - -# Scenario 2: Debugging a single backend -./start.sh prod stop # Stop all -./ssh-tunnel.sh start # SSH tunnel (if needed) -./start-backend.sh start # Just the backend -./start-frontend.sh start # Just the frontend - -# Scenario 3: Testing mode -./start.sh test # Starts everything in TEST mode -# All subsequent individual script calls use TEST .env files - -# Scenario 4: Check what's running -./status.sh # See all services + health checks -``` - -**Note**: For automated testing and validation (`/validate` command), use `start.sh test` which starts all services connected to Oracle TEST server (LXC 10.0.20.121) with test credentials. - -**API Documentation** (when backend running): -- Swagger UI: http://localhost:8001/docs -- ReDoc: http://localhost:8001/redoc -- Health Check: http://localhost:8001/health - ---- - -## Production Deployment - -ROA2WEB supports two deployment architectures: - -### 🐧 Linux/Docker Deployment -```bash -./setup_production.sh # Initial setup -./scripts/deploy.sh # Deploy application -./scripts/health-check.sh # Health monitoring -``` - -### 🪟 Windows/IIS Deployment - -**Modern Unified Workflow** (recommended): -```powershell -# On Development Machine (WSL/Linux) -cd deployment/windows/scripts -.\Publish-And-Deploy.ps1 # Build + Transfer to server (interactive menu) - -# On Windows Server (PowerShell as Admin) -cd deployment/windows/scripts -.\ROA2WEB-Console.ps1 # Deploy + Manage services (interactive console) -``` - -**Alternative - Manual Installation**: -```powershell -# First-time installation -.\Install-ROA2WEB.ps1 -.\Install-TelegramBot.ps1 - -# Automated deployment -.\Check-And-Deploy.ps1 -``` - -**Complete Documentation**: -- **`DEPLOYMENT_GUIDE.md`** - Comprehensive guide for both platforms -- **`deployment/windows/README.md`** - Windows quick start -- **`deployment/windows/docs/WINDOWS_DEPLOYMENT.md`** - Complete Windows guide - ---- - -## API Endpoints - -All endpoints prefixed with `/api`: - -### Authentication -- `POST /api/auth/login` - Login with Oracle credentials - -### Companies -- `GET /api/companies` - Get user's accessible companies - -### Dashboard -- `GET /api/dashboard/{company_id}` - Dashboard statistics - -### Invoices -- `GET /api/invoices/{company_id}` - List invoices with filters -- `GET /api/invoices/{company_id}/summary` - Invoice summary - -### Treasury -- `GET /api/treasury/{company_id}` - Payment data - -### Telegram Bot -- `POST /api/telegram/auth/generate-code` - Generate linking code -- `POST /api/telegram/auth/verify-user` - Verify Oracle user -- `POST /api/telegram/auth/refresh-token` - Refresh JWT token -- `POST /api/telegram/export` - Export reports - ---- - -## SSH Tunnel Configuration - -ROA2WEB uses SSH tunnels to connect to Oracle servers. Configuration is in `backend/ssh-tunnels.json`. - -### Setup (one-time) - -**Linux:** -```bash -# Copy SSH key to secrets folder -cp ~/.ssh/your_key backend/secrets/vending.ssh_key -chmod 600 backend/secrets/vending.ssh_key - -# Or use password (requires sshpass) -echo "your_password" > backend/secrets/vending.ssh_pass -sudo apt install sshpass -``` - -**Windows:** -```powershell -# Option 1: SSH Key (recommended) -ssh-keygen -t rsa -b 4096 -f C:\inetpub\wwwroot\roa2web\backend\secrets\vending.ssh_key -N "" -# Then add public key to remote server's ~/.ssh/authorized_keys - -# Option 2: Password (requires PuTTY) -choco install putty -y -echo "your_password" > C:\inetpub\wwwroot\roa2web\backend\secrets\vending.ssh_pass -``` - -### Configuration File - -`backend/ssh-tunnels.json`: -```json -[ - { - "id": "vending", - "name": "Vending Master", - "local_port": 1522, - "ssh_host": "79.119.86.134", - "ssh_port": 22122, - "ssh_user": "romfast", - "ssh_hostkey": "SHA256:xxxxx", - "oracle_host": "127.0.0.1", - "oracle_port": 1521 - } -] -``` - -**Important:** -- `local_port` must match the port in `ORACLE_SERVERS` (.env) for this server -- `ssh_hostkey` is **required on Windows** (plink batch mode). Get it with: - ```powershell - plink.exe -ssh user@host -P port "exit" - # Accept the key, then copy SHA256 fingerprint from output - ``` - -### Commands - -| Platform | Start | Stop | Status | -|----------|-------|------|--------| -| Linux | `./ssh-tunnel.sh start` | `./ssh-tunnel.sh stop` | `./ssh-tunnel.sh status` | -| Windows | `.\scripts\ssh-tunnel.ps1 start` | `.\scripts\ssh-tunnel.ps1 stop` | `.\scripts\ssh-tunnel.ps1 status` | - -### Auto-Start (Production) - -- **Linux**: `start.sh` automatically starts tunnels before backend -- **Windows Service**: `start-backend-service.ps1` wrapper starts tunnels before uvicorn -- **Auto-Reconnect**: Backend monitors tunnels and restarts them if they drop (every 30s check) - ---- - -## Environment Configuration - -Copy `.env.example` to `.env` in each microservice and configure: - -### Backend (`backend/.env`) -```bash -# Oracle Database (through SSH tunnel) -ORACLE_USER=your_username -ORACLE_PASSWORD=your_password -ORACLE_HOST=localhost -ORACLE_PORT=1526 -ORACLE_SID=ROA - -# JWT Authentication -JWT_SECRET_KEY=your_secret_key -JWT_ALGORITHM=HS256 -JWT_EXPIRE_MINUTES=30 -``` - -### Telegram Bot (`backend/modules/telegram/.env`) -```bash -# Telegram Bot Token -TELEGRAM_BOT_TOKEN=your_bot_token - -# Backend API -BACKEND_API_URL=http://localhost:8001 -``` - ---- - -## Documentation - -### Quick Reference -- **`CLAUDE.md`** - Development guide for AI/Claude Code (architecture, cache system, common tasks, troubleshooting) -- **`docs/ARCHITECTURE-DECISIONS.md`** - Architecture Decision Records (ADRs) -- **`docs/MONOLITH_ARCHITECTURE.md`** - Ultrathin monolith architecture details - -### Module Documentation -- `docs/data-entry/DATA-ENTRY-MODULE.md` - Data Entry module (SQLModel, workflow, OCR) -- `docs/telegram/README.md` - Telegram bot integration -- `docs/telegram/DEPLOYMENT.md` - Telegram single-worker requirement - -### Frontend Styling & CSS -- `docs/ONBOARDING_CSS.md` - CSS system onboarding guide (start here!) -- `docs/CSS_PATTERNS.md` - Comprehensive CSS patterns library -- `docs/DESIGN_TOKENS.md` - Design tokens reference (colors, spacing, typography) -- `docs/MOBILE_PATTERNS.md` - Mobile UI patterns and components - -### Deployment -- **`docs/DEPLOYMENT.md`** - Principal deployment guide (start here!) -- `deployment/linux/README.md` - Deploy from Linux/LXC -- `deployment/windows/README.md` - Deploy from Windows - -### Testing -- `tests/ocr-validation/README.md` - OCR validation tests - ---- - -## Contributing - -1. Create feature branch from `main` -2. Make changes following project structure -3. Write tests for new features -4. Run all tests before committing -5. Create pull request with clear description - ---- - -## License - -[Your License Here] - ---- - -## Support - -For issues and questions: -- Check documentation in `` subdirectories -- Review CLAUDE.md for development guidelines -- See component-specific READMEs for detailed information - ---- - -**Branch**: v2-roa2web-fastapi -**Working Directory**: `` - All development happens here +Bază de cod identică cu roa2web — vezi instrucțiunile de pornire din scripturile +`start.sh` / `start-backend.sh` / `start-frontend.sh` și `docs/`. Necesită acces la +serverul Oracle de test (`MARIUSM_AUTO`) prin user-ul tehnic `ROA_WEB`.