romfast/roa2web-service-auto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): README orientat pe scop — învățare + hedge VFP, nu produs

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Claude Agent
2026-06-13 11:45:39 +00:00
parent 22f66c4633
commit 3a10cc69c0
1 changed files with 66 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

462
README.md
View File

@@ -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 Visual FoxPro (VFP) e o limbă moartă. ERP-ul care alimentează 4 clienți de lungă durată e
- **Frontend**: Vue.js 3 + PrimeVue - Single-page application with lazy-loaded modules scris în VFP + Oracle, iar **nu se mai pot angaja programatori dispuși să învețe VFP** →
- **Telegram Bot**: Alternative command-based interface (integrated module) risc de talent care se acumulează an de an.
- **Database**: Oracle Database + SQLite (hybrid approach)
- **Architecture**: Ultrathin monolith with clear module boundaries
--- 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+ ## Ce probează concret (învățarea reală)
- Node.js 16+
- Oracle Database access
- SSH access to Oracle server (for development)
### 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 | # | Ipoteză | Status / referință |
# Clone repository |---|---------|--------------------|
git clone <repository-url> | 1 | `python-oracledb` async apelează curat PL/SQL cu params IN+OUT | `poc/`, `week1-notes.md` |
cd roa2web | 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 **Livrabilul real NU e ecranul de comandă** — e un **template reutilizabil pentru module
./start.sh prod # Production Oracle** (`docs/service-auto/template-modul-oracle.md`) + un **decision log**
./start.sh test # Test environment (`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 ## Relația cu roa2web
- **Backend API Docs**: http://localhost:8001/docs (Swagger UI)
- **Backend ReDoc**: http://localhost:8001/redoc
- **Health Check**: http://localhost:8001/health
--- 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
``` | Zonă | Cale |
. |------|------|
├── backend/ # Unified FastAPI backend (port 8001) | Backend | `backend/modules/service_auto/` (router / service / schemas / tests) |
│ ├── modules/ # Business logic modules | Frontend | `src/modules/service-auto/` + `src/shared/components/AsyncAutoComplete.vue` |
│ │ ├── reports/ # Reports module (Oracle read-only) | Oracle (pack-uri, DDL, migrări) | `docs/service-auto/` (`pack_auto.pck`, `pack_sesiune.pck`, `migrations/`) |
│ │ ├── data_entry/ # Data entry module (SQLite + workflow) | POC-uri | `poc/` |
│ │ └── telegram/ # Telegram bot module | Design, decizii, learnings | `docs/service-auto/` |
│ ├── 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
```
### Key Features ## ⚠️ Stare curentă
- **Shared Database Pool**: Singleton Oracle connection pool shared across all modules **WIP.** Ultimul commit de dezvoltare moștenit era „modificari in curs nu stiu care este
- **Two-Tier Cache System**: Hybrid L1 (Memory) + L2 (SQLite) for optimal performance faza" (2026-06-05) — proiectul **nu era la un checkpoint curat** când a fost desprins din
- **JWT Authentication**: Secure token-based auth with middleware roa2web (2026-06-13). Înainte de orice reluare: citește `docs/service-auto/decision-log.md`
- **Modular Architecture**: Independent modules with clear separation of concerns și notele săptămânale (`week*-notes.md`) ca să reconstruiești faza.
- **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)
--- 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)** Bază de cod identică cu roa2web — vezi instrucțiunile de pornire din scripturile
**Frontend**: Vue.js 3 (Composition API), PrimeVue, Pinia, Vite, Axios, Chart.js, Playwright `start.sh` / `start-backend.sh` / `start-frontend.sh` și `docs/`. Necesită acces la
**Telegram Bot**: python-telegram-bot, SQLite + aiosqlite, httpx, FastAPI (internal) serverul Oracle de test (`MARIUSM_AUTO`) prin user-ul tehnic `ROA_WEB`.
**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