Files

Claude Agent 62f86250cc refactor(docs): consolidate and cleanup documentation

- Delete 9 deprecated/obsolete docs (~6,300 lines removed)
- Move test PDFs to tests/fixtures/ocr-samples/
- Create docs/DEPLOYMENT.md as principal guide
- Create tests/ocr-validation/README.md
- Update all refs for ultrathin monolith architecture
- Update OCR tests to use relative paths

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-22 09:14:51 +00:00

5.9 KiB

Raw Blame History

ROA2WEB Deployment Guide

Arhitectură: Ultrathin Monolith | Serviciu: ROA2WEB-Backend (port 8000)

Overview

ROA2WEB folosește o arhitectură ultrathin monolith - un singur serviciu backend care gestionează toate modulele:

Modul	Descriere	Control
Reports	Rapoarte read-only din Oracle	`MODULE_REPORTS_ENABLED`
Data Entry	Input date cu workflow aprobare	`MODULE_DATA_ENTRY_ENABLED`
Telegram	Bot Telegram integrat	`MODULE_TELEGRAM_ENABLED`

Avantaje:

Single Windows/Linux service de gestionat
Shared database connection pool
Deployment simplificat
Consum redus de memorie

Quick Deploy

Din Linux/LXC (Recomandat)

cd deployment/linux
./deploy.sh              # Full deploy (frontend + backend)
./deploy.sh frontend     # Doar frontend
./deploy.sh backend      # Doar backend
./deploy.sh test         # Test conexiune SSH

Detalii: deployment/linux/README.md

Din Windows

cd deployment\windows\scripts
.\Publish-And-Deploy.ps1

# Non-interactiv:
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component All

Detalii: deployment/windows/README.md

Deployment Flow

DEV MACHINE                          WINDOWS SERVER
───────────                          ──────────────

deploy.sh (Linux)
      sau                     ───►   C:\Temp\deploy-*\
Publish-And-Deploy.ps1                      │
                                            ▼
                                     Check-And-Deploy.ps1
                                     (scheduled task, 5 min)
                                            │
                                            ▼
                                     ROA2WEB-Console.ps1
                                     ├── Stop Service
                                     ├── Backup
                                     ├── Deploy Files
                                     ├── Start Service
                                     └── Health Check
                                            │
                                            ▼
                                     ✅ PRODUCTION RUNNING

Server Configuration

Structura pe Server

C:\inetpub\wwwroot\roa2web\
├── backend\          # FastAPI (toate modulele)
│   └── .env          # MODULE_*_ENABLED flags
├── frontend\         # Vue.js SPA + web.config
├── shared\           # Module Python partajate
├── logs\             # backend-stdout.log, backend-stderr.log
└── backups\          # Backup-uri automate

Configurare Modul (.env)

# Module enable/disable
MODULE_REPORTS_ENABLED=true
MODULE_DATA_ENTRY_ENABLED=true
MODULE_TELEGRAM_ENABLED=true

# Database
ORACLE_DSN=localhost:1521/ORCL
ORACLE_USER=contafin
ORACLE_PASSWORD=***

# Auth
JWT_SECRET_KEY=your-secret-key

Architecture

Client → IIS (80/443)
           │
           ├─ /roa2web/api/* → ROA2WEB-Backend (localhost:8000)
           │                   ├── Reports Module → Oracle DB
           │                   ├── Data Entry Module → SQLite
           │                   └── Telegram Module (background task)
           │
           └─ /roa2web/* → Frontend (Vue.js SPA)

Single Worker Requirement

IMPORTANT: Backend-ul TREBUIE rulat cu --workers 1 pentru:

Telegram bot (un singur bot instance permis)
SQLite cache (evită conflicte de locking)

Detalii: docs/telegram/DEPLOYMENT.md

Platform-Specific Guides

Platform	Guide	Scop
Linux/LXC	deployment/linux/README.md	Deploy din container Linux
Windows	deployment/windows/README.md	IIS setup, Windows service
HTTPS	deployment/windows/docs/HTTPS_SETUP.md	SSL certificate setup
2-Tier IIS	deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md	Public → Internal architecture
Auto-Deploy	deployment/windows/docs/DEPLOYMENT_AUTOMATION.md	Scheduled task automation

web.config Files

Fișier	Scop	Când se folosește
`public/web.config`	Sub-aplicație IIS (/roa2web)	La fiecare deploy (via Vite)
`deployment/windows/config/web.config`	Server IIS complet	La instalare nouă

Notă: Ambele au configurat no-cache pentru API (backend gestionează cache-ul).

Troubleshooting

Problemă	Verificare	Soluție
Service nu pornește	Logs: `backend-stderr.log`	Verifică `.env`, port 8000
API 502/504	`curl http://localhost:8000/health`	Restart service
Frontend nu se încarcă	`iisreset`	Verifică IIS, web.config
Auto-deploy nu merge	`Get-ScheduledTask ROA2WEB-AutoDeploy`	Re-run setup script
Telegram conflicts	Logs: "terminated by other getUpdates"	Ensure `--workers 1`

System Requirements

Resursă	Minim	Recomandat
OS	Windows Server 2016 / Ubuntu 20.04	Windows Server 2019+
RAM	4 GB	8 GB (16 GB cu OCR)
CPU	2 cores	4 cores
Python	3.11+	3.11+
IIS	URL Rewrite + ARR	URL Rewrite + ARR

ARCHITECTURE-DECISIONS.md - ADR-uri importante
MONOLITH_ARCHITECTURE.md - Arhitectura detaliată
telegram/DEPLOYMENT.md - Single worker requirement

ROA2WEB - Ultrathin Monolith Architecture Last Updated: 2026-01-22

5.9 KiB Raw Blame History