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

refactor(docs): consolidate and cleanup documentation

Browse Source 
- 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>
This commit is contained in:
Claude Agent
2026-01-22 09:14:51 +00:00
parent 1b9ebf1d8f
commit 62f86250cc
55 changed files with 604 additions and 6334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

566
deployment/windows/README.md
View File

@@ -1,492 +1,200 @@
# ROA2WEB - Windows Deployment Package
# ROA2WEB - Windows Deployment
Complete deployment solution for ROA2WEB on Windows Server with IIS and Oracle Database.
**Includes:**
- **Reports App** - Read-only Oracle reports (Port 8000)
- **Telegram Bot** - Telegram integration (Port 8002)
- **Data Entry App** - Receipt data entry with approval workflow (Port 8003)
**Arhitectură:** Ultrathin Monolith | **Serviciu:** `ROA2WEB-Backend` (port 8000)
---
## 📂 Package Contents
## Quick Start
```
deployment/windows/
├── config/ # Configuration files
│ ├── web.config # IIS config for Reports App
│ ├── web.config.data-entry # IIS config for Data Entry App
│ └── .env.production.windows # Environment variables template
│
├── scripts/ # PowerShell automation scripts
│ ├── Build-ROA2WEB.ps1 # Build all components (interactive menu)
│ ├── ROA2WEB-Console.ps1 # Unified deployment & management console
│ ├── Install-ROA2WEB.ps1 # Initial Reports App installation
│ ├── Install-TelegramBot.ps1 # Telegram Bot installation
│ └── deploy-config.json # Deployment configuration
│
├── docs/ # Documentation
│ └── WINDOWS_DEPLOYMENT.md # Complete deployment guide
│
└── README.md # This file
```
---
## 🎯 Quick Start
### Prerequisites
- **Windows Server** 2016+ (or Windows 10/11 Pro)
- **IIS** installed
- **Oracle Database** (local or network-accessible)
- **PowerShell 5.1+**
- **Administrator privileges**
### Installation Steps
#### 1. Build Frontend (on development machine)
```bash
# On WSL/Linux/Mac
cd roa2web/deployment/windows/scripts
./Build-Frontend.ps1
# This creates: ./deploy-package/
```
#### 2. Transfer to Server
Copy the entire project to Windows Server:
```
C:\roa2web\deployment\windows\
```
#### 3. Run Installation
### 1. Instalare Server Nou
```powershell
# On Windows Server (PowerShell as Administrator)
cd C:\roa2web\deployment\windows\scripts
# Install everything
# Pe Windows Server (PowerShell Administrator)
cd C:\path\to\deployment\windows\scripts
.\Install-ROA2WEB.ps1
```
This will:
- ✅ Install Python 3.11+
- ✅ Install NSSM (service manager)
- ✅ Install IIS URL Rewrite and ARR
- ✅ Create directory structure
- ✅ Install Python dependencies
- ✅ Create Windows Service
- ✅ Configure IIS website
#### 4. Configure Application
### 2. Configurare
```powershell
# Copy and edit environment file
Copy-Item C:\inetpub\wwwroot\roa2web\backend\config\.env.production.windows `
C:\inetpub\wwwroot\roa2web\backend\.env
# Edit with your values
notepad C:\inetpub\wwwroot\roa2web\backend\.env
# Module control:
MODULE_REPORTS_ENABLED=true
MODULE_DATA_ENTRY_ENABLED=true
MODULE_TELEGRAM_ENABLED=true
```
**Required settings:**
Configure these variables in `.env`:
- Database credentials (user, password, host, port, SID)
- JWT secret key for authentication
- Other application-specific settings
Example structure:
```env
ORACLE_USER=CONTAFIN_ORACLE
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SID=ROA
# Add password and JWT secret here
```
#### 5. Deploy Application Files
### 3. Start
```powershell
# Deploy frontend and backend
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\path\to\deploy-package"
Start-Service ROA2WEB-Backend
```
#### 6. Verify Installation
---
## Deployment (Actualizări)
### Opțiunea A: Din Windows (Publish-And-Deploy.ps1)
```powershell
# Check service
# Pe mașina de dezvoltare Windows
cd deployment\windows\scripts
.\Publish-And-Deploy.ps1
# Non-interactiv:
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component All
```
### Opțiunea B: Din Linux/LXC (deploy.sh)
```bash
# Pe mașina de dezvoltare Linux
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
```
**Ambele metode:**
1. Build frontend (npm) + copiere backend
2. Transfer la server (`C:\Temp\deploy-YYYYMMDD-HHmmss\`)
3. Server-ul auto-deploy în 5 minute (sau manual)
---
## Management
### Consolă Interactivă (Recomandat)
```powershell
.\ROA2WEB-Console.ps1
```
### Comenzi Rapide
```powershell
# Service
Start-Service ROA2WEB-Backend
Stop-Service ROA2WEB-Backend
Restart-Service ROA2WEB-Backend
Get-Service ROA2WEB-Backend
# Test backend
# Status & Health
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
Invoke-WebRequest http://localhost:8000/health
# Open application
Start-Process "http://localhost"
# Logs
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stdout.log -Tail 50
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 20
# Deploy manual
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll -PackagePath "C:\Temp\deploy-XXXXXXXX"
```
---
## 🔄 Update Workflow
For deploying updates to existing installation:
**1. Build on development machine:**
```bash
cd roa2web/deployment/windows/scripts
./Build-Frontend.ps1 -OutputPath "./deploy-$(date +%Y%m%d)"
```
**2. Transfer to server:**
```powershell
Copy-Item .\deploy-20250118 -Destination C:\Temp\roa2web-deploy -Recurse
```
**3. Deploy on server:**
```powershell
cd C:\inetpub\wwwroot\roa2web\deployment\windows\scripts
.\Deploy-ROA2WEB.ps1 -SourcePath "C:\Temp\roa2web-deploy"
```
---
## 🔧 Management Commands
### Interactive Console (Recommended)
```powershell
# Open unified management console
cd C:\inetpub\wwwroot\roa2web\deployment\windows\scripts
.\ROA2WEB-Console.ps1
# Menu options:
# [1] Deploy Components
# [2] Manage Services
# [3] Check Status
```
### Non-Interactive Commands
```powershell
# Deploy all components
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
# Deploy specific component
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployBackend
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployTelegramBot
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployDataEntry
# Service management
.\ROA2WEB-Console.ps1 -NonInteractive -Action StartAll
.\ROA2WEB-Console.ps1 -NonInteractive -Action StopAll
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartAll
# Data Entry service management
.\ROA2WEB-Console.ps1 -NonInteractive -Action StartDataEntry
.\ROA2WEB-Console.ps1 -NonInteractive -Action StopDataEntry
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartDataEntry
# Check status
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
```
### Direct Service Commands
```powershell
# Check all ROA2WEB services
Get-Service ROA2WEB-*
# View logs
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stdout.log -Tail 50 -Wait
Get-Content C:\inetpub\wwwroot\roa2web\data-entry-backend\logs\stdout.log -Tail 50 -Wait
# Check IIS
Get-Website | Where-Object { $_.Name -like "*roa2web*" -or $_.Name -like "*data-entry*" }
```
---
## 📊 Architecture
### Components
| Component | Type | Port | Purpose |
|-----------|------|------|---------|
| **Reports Frontend** | IIS Static Files | 80/443 | Vue.js SPA (Reports) |
| **Reports Backend** | Windows Service | 8000 | FastAPI API (Reports) |
| **Telegram Bot** | Windows Service | 8002 | Telegram integration |
| **Data Entry Frontend** | IIS Static Files | 80/443 | Vue.js SPA (Data Entry) |
| **Data Entry Backend** | Windows Service | 8003 | FastAPI API (Data Entry) |
| **Database** | Oracle | 1521 | Reports data (read-only) |
| **SQLite** | File | - | Data Entry local storage |
### Network Flow
```
Client → IIS (port 80/443)
│
├─ /roa2web/api/* → Reports Backend (localhost:8000) → Oracle DB
│
├─ /roa2web/* → Reports Frontend (Vue.js)
│
├─ /data-entry/api/* → Data Entry Backend (localhost:8003) → SQLite
│
└─ /data-entry/* → Data Entry Frontend (Vue.js)
```
### Windows Services
| Service Name | Description | Port |
|-------------|-------------|------|
| ROA2WEB-Backend | Reports API | 8000 |
| ROA2WEB-TelegramBot | Telegram Bot | 8002 |
| ROA2WEB-DataEntry | Data Entry API | 8003 |
---
## 📋 Directory Structure After Installation
## Structura Server
```
C:\inetpub\wwwroot\roa2web\
│
├── backend\ # Reports Backend (FastAPI)
│ ├── app\
│ ├── requirements.txt
│ ├── venv\
│ └── .env
│
├── frontend\ # Reports Frontend (Vue.js)
│ ├── index.html
│ ├── assets\
│ └── web.config
│
├── telegram-bot\ # Telegram Bot
│ ├── app\
│ ├── data\telegram_bot.db
│ ├── requirements.txt
│ ├── venv\
│ └── .env
│
├── data-entry-backend\ # Data Entry Backend (FastAPI)
│ ├── app\
│ ├── migrations\
│ ├── data\receipts.db # SQLite database
│ ├── data\uploads\ # Uploaded receipts
│ ├── requirements.txt
│ ├── venv\
│ └── .env
│
├── data-entry-frontend\ # Data Entry Frontend (Vue.js)
│ ├── index.html
│ ├── assets\
│ └── web.config
│
├── shared\ # Shared Python modules
│ ├── auth\
│ ├── database\
│ └── utils\
│
├── logs\ # Service logs
│ ├── backend-stdout.log
│ └── backend-stderr.log
│
└── backups\ # Automatic backups
└── backup-YYYYMMDD-HHMMSS\
├── backend\ # FastAPI (Reports, Data Entry, Telegram modules)
│ └── .env # Configurare (MODULE_*_ENABLED flags)
├── frontend\ # Vue.js SPA + web.config
├── shared\ # Module Python partajate (auth, db)
├── logs\ # backend-stdout.log, backend-stderr.log
└── backups\ # Backup-uri automate
```
---
## 🆘 Troubleshooting
## Arhitectură
### Service won't start
```powershell
# Check logs
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50
# Test manually
cd C:\inetpub\wwwroot\roa2web\backend
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000
```
Client → IIS (80/443)
│
├─ /roa2web/api/* → ROA2WEB-Backend (localhost:8000)
│ ├── Reports Module → Oracle DB
│ ├── Data Entry Module → SQLite
│ └── Telegram Module
│
└─ /roa2web/* → Frontend (Vue.js SPA)
```
### Frontend not loading
**Single Service:** `ROA2WEB-Backend` pe port 8000
**Module Control:** Via `.env` flags (fără restart cod)
```powershell
# Restart IIS
iisreset
---
## Workflow Deployment
# Check website status
Get-Website ROA2WEB
Start-Website ROA2WEB
```
DEV MACHINE WINDOWS SERVER
─────────── ──────────────
### API calls failing (502/504)
```powershell
# Check backend service
Get-Service ROA2WEB-Backend
.\Restart-ROA2WEB.ps1
# Test backend directly
Invoke-WebRequest http://localhost:8000/health
```
### Database connection issues
```powershell
# Test Oracle connection
sqlplus CONTAFIN_ORACLE/password@localhost:1521/ROA
# Check Oracle service
Get-Service Oracle*
# Check .env configuration
Get-Content C:\inetpub\wwwroot\roa2web\backend\.env | Select-String ORACLE
Publish-And-Deploy.ps1
sau ───► C:\Temp\deploy-*\
deploy.sh (Linux) │
▼
Check-And-Deploy.ps1
(scheduled task, 5 min)
│
▼
ROA2WEB-Console.ps1
├── Stop Service
├── Backup
├── Deploy Files
├── Start Service
└── Health Check
│
▼
✅ PRODUCTION RUNNING
```
---
## 📖 Full Documentation
## Troubleshooting
For complete documentation, see:
- **[WINDOWS_DEPLOYMENT.md](docs/WINDOWS_DEPLOYMENT.md)** - Comprehensive deployment guide
- **[.env.production.windows](config/.env.production.windows)** - Configuration reference
| Problemă | Verificare | Soluție |
|----------|------------|---------|
| Service nu pornește | `Get-Content ...\backend-stderr.log -Tail 30` | Verifică .env, port 8000 |
| API 502/504 | `Invoke-WebRequest http://localhost:8000/health` | Restart service |
| Frontend nu se încarcă | `iisreset` | Verifică IIS, web.config |
| Auto-deploy nu merge | `Get-ScheduledTask ROA2WEB-AutoDeploy` | `.\Setup-AutoDeploy.ps1` |
---
## 🔑 Key Features
## Fișiere web.config
✅ **Simple Installation** - One PowerShell script installs everything
✅ **Minimal Dependencies** - Only Python + IIS (already on Windows Server)
✅ **Easy Replication** - Same scripts work on all servers
✅ **Automatic Backups** - Every deployment creates a backup
✅ **Windows Service** - Backend runs as service with auto-start/restart
✅ **Production Ready** - Optimized for performance and reliability
| 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).
---
## 📊 System Requirements
## Documentație Detaliată
| Resource | Minimum | Recommended |
|----------|---------|-------------|
| **OS** | Windows Server 2016 | Windows Server 2019+ |
| **RAM** | 4 GB | 8 GB (16 GB if using OCR) |
| **CPU** | 2 cores | 4 cores |
| **Disk** | 10 GB free | 20 GB free |
| **Network** | 100 Mbps | 1 Gbps |
- **HTTPS Setup:** `docs/HTTPS_SETUP.md`
- **2-Tier IIS:** `docs/TWO-TIER-IIS-DEPLOYMENT.md`
- **Telegram Bot:** `docs/TELEGRAM-BOT-DEPLOYMENT.md`
---
## 🔍 OCR Dependencies (Data Entry App)
## Cerințe Sistem
Data Entry App foloseste OCR pentru extragerea automata a datelor din bonuri fiscale. Pe Windows trebuie instalate manual:
### 1. Poppler (conversie PDF → imagini)
```powershell
# Descarca de la: https://github.com/osborn/poppler-windows/releases
# Extrage in: C:\Program Files\poppler\
# Adauga la System PATH: C:\Program Files\poppler\Library\bin
# Verificare instalare:
pdfinfo --version
```
### 2. Tesseract OCR (engine OCR backup)
```powershell
# Descarca installer: https://github.com/UB-Mannheim/tesseract/wiki
# Selecteaza limbile: English + Romanian
# Default path: C:\Program Files\Tesseract-OCR\
# Adauga la System PATH
# Verificare instalare:
tesseract --version
```
### 3. Python OCR Packages
```powershell
cd C:\inetpub\wwwroot\roa2web\data-entry-backend
.\venv\Scripts\activate
pip install paddlepaddle>=2.5.0
pip install paddleocr>=2.7.0
pip install opencv-python>=4.8.0
pip install pytesseract>=0.3.10
pip install pdf2image>=1.16.0
# Restart serviciu
nssm restart ROA2WEB-DataEntry
```
### Note importante
- **PaddleOCR** descarca modele (~200MB) la prima rulare
- **RAM**: PaddleOCR necesita ~2GB RAM disponibil
- **PATH**: Dupa modificari PATH, restart serviciul backend
- **Test OCR**: `curl http://localhost:8003/api/ocr/status`
| Resursă | Minim | Recomandat |
|---------|-------|------------|
| OS | Windows Server 2016 | 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 |
---
## 🔐 Security Recommendations
1. **Generate Strong JWT Secret:**
```powershell
-join ((65..90) + (97..122) + (48..57) | Get-Random -Count 32 | % {[char]$_})
```
2. **Secure .env File:**
```powershell
icacls C:\inetpub\wwwroot\roa2web\backend\.env /inheritance:r /grant:r Administrators:F
```
3. **Enable HTTPS:** ⭐ **RECOMMENDED**
```powershell
# Quick setup with automated script
cd C:\roa2web\deployment\windows\scripts
.\Enable-HTTPS.ps1
# For detailed instructions, see:
# docs/HTTPS_SETUP.md
```
**What it does:**
- Creates/installs SSL certificate
- Configures HTTPS binding (port 443)
- Enables HTTP to HTTPS redirect
- Activates HSTS (Strict Transport Security)
**Access your application securely:**
- `https://10.0.20.36/roa2web` (or your domain)
4. **Regular Updates:**
- Keep Windows Server updated
- Update Python packages monthly
- Monitor security advisories
- Renew SSL certificates before expiry
---
## 📞 Support
For issues or questions:
1. Check logs: `C:\inetpub\wwwroot\roa2web\logs\`
2. Review [WINDOWS_DEPLOYMENT.md](docs/WINDOWS_DEPLOYMENT.md)
3. Contact: development-team@your-company.com
---
## 📝 Version History
| Version | Date | Changes |
|---------|------|---------|
| 2.1.0 | 2025-12-18 | Added Data Entry App deployment support |
| 2.0.0 | 2025-01-18 | Initial Windows deployment package |
---
*ROA2WEB - Modern ERP Application (Reports + Data Entry)*
*Windows Server Deployment Package v2.1.0*
*ROA2WEB - Ultrathin Monolith Architecture*
*Last Updated: 2025-01-22*