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>
This commit is contained in:
Claude Agent
31
README.md
31
README.md
@@ -88,7 +88,7 @@ This starts SSH tunnel, unified backend (port 8001), and frontend (port 3000).
|
||||
- **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
|
||||
- **Microservices**: Independent services with clear separation of concerns
|
||||
- **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**: Alternative bot-based interface
|
||||
@@ -299,30 +299,27 @@ BACKEND_API_URL=http://localhost:8001
|
||||
|
||||
### Quick Reference
|
||||
- **`CLAUDE.md`** - Development guide for AI/Claude Code (architecture, cache system, common tasks, troubleshooting)
|
||||
- **`docs/ARCHITECTURE_SCHEMA.md`** - Architecture diagrams, cache system, and schemas
|
||||
- `docs/MICROSERVICES_GUIDE.md` - Microservices architecture details
|
||||
- `DEVELOPMENT_BLUEPRINT.md` - Detailed development plan
|
||||
- **`docs/ARCHITECTURE-DECISIONS.md`** - Architecture Decision Records (ADRs)
|
||||
- **`docs/MONOLITH_ARCHITECTURE.md`** - Ultrathin monolith architecture details
|
||||
|
||||
### Component-Specific
|
||||
- `README.md` - Main application README
|
||||
- `backend/ modules and CLAUDE.md` - Backend specifics
|
||||
- `src/ and docs/MONOLITH_ARCHITECTURE.md` - Frontend guide
|
||||
- `E2E testing guide in docs/` - Frontend testing
|
||||
- `backend/modules/telegram/README.md` - Telegram bot guide
|
||||
- `backend/modules/telegram/TELEGRAM_COMMANDS.md` - Bot commands
|
||||
### 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/STYLING_GUIDELINES.md` - CSS best practices and conventions
|
||||
- `docs/COMPONENT_STYLING.md` - Component-specific styling guide
|
||||
- `docs/FORM_TEMPLATE.md` - Standardized form template and patterns
|
||||
- `docs/MOBILE_PATTERNS.md` - Mobile UI patterns and components
|
||||
|
||||
### Deployment
|
||||
- `DEPLOYMENT_GUIDE.md` - Production deployment (Linux & Windows)
|
||||
- `deployment/windows/README.md` - Windows quick start
|
||||
- `deployment/windows/docs/WINDOWS_DEPLOYMENT.md` - Complete Windows guide
|
||||
- **`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
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -210,6 +210,5 @@ scp test.txt roa2web-prod:C:/Temp/
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Windows Deployment](../windows/docs/WINDOWS_DEPLOYMENT.md)
|
||||
- [Windows Deployment README](../windows/README.md)
|
||||
- [Two-Tier IIS Architecture](../windows/docs/TWO-TIER-IIS-DEPLOYMENT.md)
|
||||
- [ROA2WEB Console](../windows/scripts/ROA2WEB-Console.ps1)
|
||||
|
||||
@@ -1,221 +0,0 @@
|
||||
# 📦 Deployment Package Generation
|
||||
|
||||
This document explains how to generate deployment packages for ROA2WEB Windows deployment.
|
||||
|
||||
## ⚠️ Important Note
|
||||
|
||||
The `deploy-package/` directory is **NOT** committed to git. It contains build artifacts that are generated fresh each time you build.
|
||||
|
||||
## 🔨 Generating Deployment Packages
|
||||
|
||||
Use the unified build script **`Build-ROA2WEB.ps1`** to generate deployment packages:
|
||||
|
||||
### Build Complete Package (Recommended)
|
||||
|
||||
```powershell
|
||||
cd deployment/windows/scripts
|
||||
.\Build-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
This generates a complete deployment package containing:
|
||||
- ✅ Frontend (Vue.js built static files)
|
||||
- ✅ Backend (FastAPI Python application)
|
||||
- ✅ Shared modules (auth, database, utils)
|
||||
- ✅ Telegram Bot application
|
||||
- ✅ Configuration templates
|
||||
- ✅ Deployment scripts
|
||||
|
||||
**Output**: `deployment/windows/deploy-package/`
|
||||
|
||||
### Build Specific Components
|
||||
|
||||
```powershell
|
||||
# Frontend + Backend only
|
||||
.\Build-ROA2WEB.ps1 -Component Frontend
|
||||
|
||||
# Backend only (no frontend build)
|
||||
.\Build-ROA2WEB.ps1 -Component Backend
|
||||
|
||||
# Telegram Bot only
|
||||
.\Build-ROA2WEB.ps1 -Component TelegramBot
|
||||
```
|
||||
|
||||
### Custom Output Path
|
||||
|
||||
```powershell
|
||||
# Build to custom location with date suffix
|
||||
.\Build-ROA2WEB.ps1 -OutputPath "D:\deployments\roa2web-$(Get-Date -Format 'yyyyMMdd')"
|
||||
```
|
||||
|
||||
## 📂 Package Structure
|
||||
|
||||
After building, `deploy-package/` will contain:
|
||||
|
||||
```
|
||||
deploy-package/
|
||||
├── backend/ # FastAPI application files
|
||||
│ ├── app/ # Application code
|
||||
│ ├── requirements.txt # Python dependencies
|
||||
│ └── ...
|
||||
├── frontend/ # Built Vue.js static files
|
||||
│ ├── assets/ # JS, CSS, fonts
|
||||
│ ├── index.html # Main HTML
|
||||
│ └── ...
|
||||
├── telegram-bot/ # Telegram bot application
|
||||
│ ├── app/ # Bot code
|
||||
│ ├── requirements.txt # Bot dependencies
|
||||
│ └── .env.example # Configuration template
|
||||
├── shared/ # Shared Python modules
|
||||
│ ├── auth/ # Authentication
|
||||
│ ├── database/ # Oracle connection pool
|
||||
│ └── utils/ # Utilities
|
||||
├── config/ # Configuration templates
|
||||
│ ├── .env.production.windows
|
||||
│ ├── .env.production.windows.telegram
|
||||
│ └── web.config # IIS configuration
|
||||
├── scripts/ # Deployment scripts
|
||||
│ ├── Install-ROA2WEB.ps1
|
||||
│ ├── Install-TelegramBot.ps1
|
||||
│ ├── Deploy-ROA2WEB.ps1
|
||||
│ ├── Deploy-TelegramBot.ps1
|
||||
│ ├── Manage-ROA2WEB.ps1
|
||||
│ ├── Backup-TelegramDB.ps1
|
||||
│ ├── Setup-DailyBackup.ps1
|
||||
│ ├── Setup-ClaudeAuth.ps1
|
||||
│ └── Enable-HTTPS.ps1
|
||||
└── README.txt # Deployment instructions
|
||||
```
|
||||
|
||||
## 🚀 Deployment Workflow
|
||||
|
||||
### 1. Build Package (Development Machine)
|
||||
|
||||
```powershell
|
||||
# On WSL or development machine
|
||||
cd deployment/windows/scripts
|
||||
.\Build-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
### 2. Transfer to Windows Server
|
||||
|
||||
```powershell
|
||||
# Via network share
|
||||
Copy-Item -Path ./deploy-package -Destination \\SERVER\C$\Temp\roa2web-deploy -Recurse
|
||||
|
||||
# Or via RDP (manual copy)
|
||||
```
|
||||
|
||||
### 3. Install on Server (First Time)
|
||||
|
||||
```powershell
|
||||
# On Windows Server (as Administrator)
|
||||
cd C:\Temp\roa2web-deploy\scripts
|
||||
|
||||
# Install main application
|
||||
.\Install-ROA2WEB.ps1
|
||||
|
||||
# Install Telegram bot
|
||||
.\Install-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### 4. Configure & Start
|
||||
|
||||
```powershell
|
||||
# Configure environment
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Start services
|
||||
.\Manage-ROA2WEB.ps1 -Action Start
|
||||
```
|
||||
|
||||
### 5. Deploy Updates
|
||||
|
||||
```powershell
|
||||
# Stop services
|
||||
.\Manage-ROA2WEB.ps1 -Action Stop
|
||||
|
||||
# Deploy updates
|
||||
.\Deploy-ROA2WEB.ps1
|
||||
.\Deploy-TelegramBot.ps1
|
||||
|
||||
# Start services
|
||||
.\Manage-ROA2WEB.ps1 -Action Start
|
||||
```
|
||||
|
||||
## 🔧 Requirements
|
||||
|
||||
**Development Machine (for building):**
|
||||
- Node.js 16+ (for Frontend builds)
|
||||
- npm
|
||||
- PowerShell 5.1+
|
||||
|
||||
**Windows Server (for deployment):**
|
||||
- Windows Server 2016+ or Windows 10/11
|
||||
- IIS with URL Rewrite Module
|
||||
- Python 3.11+
|
||||
- PowerShell 5.1+ (Administrator)
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
- **Build artifacts are NOT version-controlled**: The `deploy-package/` directory is in `.gitignore`
|
||||
- **Fresh builds recommended**: Always generate a fresh package before deploying
|
||||
- **Virtual environments**: Not included in package (created automatically during installation)
|
||||
- **.env files**: Not included in package (created from templates during installation)
|
||||
- **Database files**: Excluded from package (SQLite for Telegram bot created on server)
|
||||
|
||||
## ⚙️ Advanced Options
|
||||
|
||||
### Transfer to Server Automatically
|
||||
|
||||
```powershell
|
||||
# Using network share (Windows)
|
||||
.\Build-ROA2WEB.ps1 -ServerHost "10.0.20.36" -ServerPath "C:\Temp\roa2web-deploy"
|
||||
```
|
||||
|
||||
### Clean Build
|
||||
|
||||
The build script automatically cleans the output directory. To preserve existing output:
|
||||
|
||||
```powershell
|
||||
.\Build-ROA2WEB.ps1 -Clean $false
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### "Node.js not found"
|
||||
|
||||
Install Node.js 16+ from https://nodejs.org/
|
||||
|
||||
### "deploy-package already exists"
|
||||
|
||||
The script automatically cleans old builds. If you see errors, manually delete `deploy-package/` and retry.
|
||||
|
||||
### Build fails with "locked files"
|
||||
|
||||
Close VS Code, IDEs, and file explorers that might have files open in the source directories.
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **Complete Deployment Guide**: [`docs/WINDOWS_DEPLOYMENT.md`](docs/WINDOWS_DEPLOYMENT.md)
|
||||
- **Script Reference**: [`scripts/README.md`](scripts/README.md)
|
||||
- **Quick Start**: [`README.md`](README.md)
|
||||
- **Project Documentation**: [`../../CLAUDE.md`](../../CLAUDE.md)
|
||||
|
||||
## 🔄 Migration from Old Build Scripts
|
||||
|
||||
If you were using the old build scripts, here's the mapping:
|
||||
|
||||
| Old Script | New Script | Equivalent Command |
|
||||
|------------|------------|-------------------|
|
||||
| `Build-Frontend.ps1` | `Build-ROA2WEB.ps1` | `.\Build-ROA2WEB.ps1 -Component Frontend` |
|
||||
| `Build-TelegramBot.ps1` | `Build-ROA2WEB.ps1` | `.\Build-ROA2WEB.ps1 -Component TelegramBot` |
|
||||
| Both scripts together | `Build-ROA2WEB.ps1` | `.\Build-ROA2WEB.ps1` (default: All) |
|
||||
|
||||
**Note**: Old scripts are marked as DEPRECATED and will be removed in a future version.
|
||||
|
||||
---
|
||||
|
||||
**Generated by**: ROA2WEB Team
|
||||
**Last Updated**: 2025-11-11
|
||||
**Version**: 2.0 (Unified Build System)
|
||||
@@ -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\ # 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Arhitectură
|
||||
|
||||
```
|
||||
Client → IIS (80/443)
|
||||
│
|
||||
├── backend\ # Reports Backend (FastAPI)
|
||||
│ ├── app\
|
||||
│ ├── requirements.txt
|
||||
│ ├── venv\
|
||||
│ └── .env
|
||||
├─ /roa2web/api/* → ROA2WEB-Backend (localhost:8000)
|
||||
│ ├── Reports Module → Oracle DB
|
||||
│ ├── Data Entry Module → SQLite
|
||||
│ └── Telegram Module
|
||||
│
|
||||
├── frontend\ # Reports Frontend (Vue.js)
|
||||
│ ├── index.html
|
||||
│ ├── assets\
|
||||
│ └── web.config
|
||||
└─ /roa2web/* → Frontend (Vue.js SPA)
|
||||
```
|
||||
|
||||
**Single Service:** `ROA2WEB-Backend` pe port 8000
|
||||
**Module Control:** Via `.env` flags (fără restart cod)
|
||||
|
||||
---
|
||||
|
||||
## Workflow Deployment
|
||||
|
||||
```
|
||||
DEV MACHINE WINDOWS SERVER
|
||||
─────────── ──────────────
|
||||
|
||||
Publish-And-Deploy.ps1
|
||||
sau ───► C:\Temp\deploy-*\
|
||||
deploy.sh (Linux) │
|
||||
▼
|
||||
Check-And-Deploy.ps1
|
||||
(scheduled task, 5 min)
|
||||
│
|
||||
├── telegram-bot\ # Telegram Bot
|
||||
│ ├── app\
|
||||
│ ├── data\telegram_bot.db
|
||||
│ ├── requirements.txt
|
||||
│ ├── venv\
|
||||
│ └── .env
|
||||
▼
|
||||
ROA2WEB-Console.ps1
|
||||
├── Stop Service
|
||||
├── Backup
|
||||
├── Deploy Files
|
||||
├── Start Service
|
||||
└── Health Check
|
||||
│
|
||||
├── 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\
|
||||
▼
|
||||
✅ PRODUCTION RUNNING
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
## Troubleshooting
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### Frontend not loading
|
||||
|
||||
```powershell
|
||||
# Restart IIS
|
||||
iisreset
|
||||
|
||||
# Check website status
|
||||
Get-Website ROA2WEB
|
||||
Start-Website ROA2WEB
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
| 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` |
|
||||
|
||||
---
|
||||
|
||||
## 📖 Full Documentation
|
||||
## Fișiere web.config
|
||||
|
||||
For complete documentation, see:
|
||||
- **[WINDOWS_DEPLOYMENT.md](docs/WINDOWS_DEPLOYMENT.md)** - Comprehensive deployment guide
|
||||
- **[.env.production.windows](config/.env.production.windows)** - Configuration reference
|
||||
| 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).
|
||||
|
||||
---
|
||||
|
||||
## 🔑 Key Features
|
||||
## Documentație Detaliată
|
||||
|
||||
✅ **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
|
||||
- **HTTPS Setup:** `docs/HTTPS_SETUP.md`
|
||||
- **2-Tier IIS:** `docs/TWO-TIER-IIS-DEPLOYMENT.md`
|
||||
- **Telegram Bot:** `docs/TELEGRAM-BOT-DEPLOYMENT.md`
|
||||
|
||||
---
|
||||
|
||||
## 📊 System Requirements
|
||||
## Cerințe Sistem
|
||||
|
||||
| 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 |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## 🔍 OCR Dependencies (Data Entry App)
|
||||
|
||||
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`
|
||||
|
||||
---
|
||||
|
||||
## 🔐 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*
|
||||
|
||||
@@ -1,240 +0,0 @@
|
||||
# web.config Files - Which Goes Where?
|
||||
|
||||
## ⚠️ IMPORTANT - Read Before Deployment!
|
||||
|
||||
ROA2WEB uses a **2-tier IIS architecture** with **2 different web.config files** for **2 different servers**.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
Internet
|
||||
↓
|
||||
Public Server (10.0.20.122) - roa2web.romfast.ro
|
||||
↓ HTTPS reverse proxy
|
||||
Internal Server (10.0.20.36) - application host
|
||||
↓ API proxy to localhost
|
||||
Backend Service (localhost:8000 on 10.0.20.36)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Mapping
|
||||
|
||||
### File: `web.config.10.0.20.122-PUBLIC`
|
||||
|
||||
**Server**: 10.0.20.122 (Public IIS - roa2web.romfast.ro)
|
||||
**Role**: Public gateway, reverse proxy to internal server
|
||||
|
||||
**Purpose**:
|
||||
- Proxies ALL requests to `https://10.0.20.36/{REQUEST_PATH}`
|
||||
- Sets forwarding headers (`X-Forwarded-Proto`, `X-Forwarded-Host`, `X-Real-IP`)
|
||||
- Redirects root `/` to `/roa2web/`
|
||||
|
||||
**Key Rule**:
|
||||
```xml
|
||||
<match url="(.*)" />
|
||||
<action type="Rewrite" url="https://10.0.20.36/{R:1}" />
|
||||
```
|
||||
|
||||
**Deployment Location**:
|
||||
```
|
||||
10.0.20.122:
|
||||
C:\inetpub\wwwroot\[ROOT]\web.config
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### File: `web.config.10.0.20.36-INTERNAL`
|
||||
|
||||
**Server**: 10.0.20.36 (Internal IIS - application host)
|
||||
**Role**: Serves frontend, proxies API to localhost backend
|
||||
|
||||
**Purpose**:
|
||||
- Serves Vue.js frontend static files
|
||||
- Proxies `/roa2web/api/*` to `http://localhost:8000/api/*`
|
||||
- Proxies `/roa2web/uploads/*` to `http://localhost:8000/uploads/*`
|
||||
- SPA fallback for client-side routing
|
||||
|
||||
**Key Rules**:
|
||||
```xml
|
||||
<match url="^roa2web/api/(.*)" />
|
||||
<action type="Rewrite" url="http://localhost:8000/api/{R:1}" />
|
||||
|
||||
<match url="^roa2web/uploads/(.*)" />
|
||||
<action type="Rewrite" url="http://localhost:8000/uploads/{R:1}" />
|
||||
|
||||
<match url="^roa2web/.*" />
|
||||
<action type="Rewrite" url="/roa2web/index.html" />
|
||||
```
|
||||
|
||||
**Deployment Location**:
|
||||
```
|
||||
10.0.20.36:
|
||||
C:\inetpub\wwwroot\roa2web\web.config
|
||||
```
|
||||
|
||||
**Note**: This file is also in `public/web.config` (repository root) and is automatically copied to `dist/` during Vite build.
|
||||
|
||||
---
|
||||
|
||||
## Deployment Checklist
|
||||
|
||||
### ✅ Public Server (10.0.20.122)
|
||||
|
||||
```powershell
|
||||
# Copy public server config
|
||||
Copy-Item deployment/windows/config/web.config.10.0.20.122-PUBLIC `
|
||||
C:\inetpub\wwwroot\[ROOT]\web.config
|
||||
|
||||
# Verify
|
||||
Get-Content C:\inetpub\wwwroot\[ROOT]\web.config | Select-String "10.0.20.36"
|
||||
```
|
||||
|
||||
**Expected**: Should see `url="https://10.0.20.36/{R:1}"`
|
||||
|
||||
### ✅ Internal Server (10.0.20.36)
|
||||
|
||||
**Option A: From built dist/ (recommended)**:
|
||||
```powershell
|
||||
# After building frontend with `npm run build`
|
||||
# web.config is automatically in dist/
|
||||
|
||||
# Deploy entire dist/ folder
|
||||
Copy-Item dist\* C:\inetpub\wwwroot\roa2web\ -Recurse -Force
|
||||
```
|
||||
|
||||
**Option B: Manual copy**:
|
||||
```powershell
|
||||
# Copy internal server config
|
||||
Copy-Item deployment/windows/config/web.config.10.0.20.36-INTERNAL `
|
||||
C:\inetpub\wwwroot\roa2web\web.config
|
||||
|
||||
# Verify
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\web.config | Select-String "roa2web/api"
|
||||
```
|
||||
|
||||
**Expected**: Should see `url="^roa2web/api/(.*)"` and `url="http://localhost:8000/api/{R:1}"`
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
### Test Public Server (10.0.20.122)
|
||||
|
||||
```powershell
|
||||
# Should proxy to internal server
|
||||
Invoke-WebRequest https://roa2web.romfast.ro/roa2web/ -UseBasicParsing
|
||||
|
||||
# Check response headers
|
||||
(Invoke-WebRequest https://roa2web.romfast.ro/roa2web/).Headers
|
||||
```
|
||||
|
||||
**Expected**: Request should be proxied to 10.0.20.36
|
||||
|
||||
### Test Internal Server (10.0.20.36)
|
||||
|
||||
```powershell
|
||||
# Test backend directly
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
|
||||
# Test through IIS proxy
|
||||
Invoke-WebRequest https://localhost/roa2web/api/health
|
||||
|
||||
# Test frontend
|
||||
Invoke-WebRequest https://localhost/roa2web/
|
||||
```
|
||||
|
||||
**Expected**: All should return 200 OK
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes ❌
|
||||
|
||||
### ❌ WRONG: Using internal config on public server
|
||||
|
||||
```xml
|
||||
<!-- On 10.0.20.122 - WRONG! -->
|
||||
<match url="^roa2web/api/(.*)" />
|
||||
<action type="Rewrite" url="http://localhost:8000/api/{R:1}" />
|
||||
```
|
||||
|
||||
**Problem**: Public server doesn't have backend on localhost:8000
|
||||
|
||||
### ❌ WRONG: Using public config on internal server
|
||||
|
||||
```xml
|
||||
<!-- On 10.0.20.36 - WRONG! -->
|
||||
<match url="(.*)" />
|
||||
<action type="Rewrite" url="https://10.0.20.36/{R:1}" />
|
||||
```
|
||||
|
||||
**Problem**: Creates infinite redirect loop
|
||||
|
||||
### ❌ WRONG: Missing /roa2web/ prefix on internal server
|
||||
|
||||
```xml
|
||||
<!-- On 10.0.20.36 - WRONG! -->
|
||||
<match url="^api/(.*)" /> <!-- Missing roa2web prefix! -->
|
||||
<action type="Rewrite" url="http://localhost:8000/api/{R:1}" />
|
||||
```
|
||||
|
||||
**Problem**: Requests come as `/roa2web/api/...` from public server, so `^api/` won't match
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: 404 on API calls
|
||||
|
||||
**Symptom**: Frontend loads but API returns 404
|
||||
|
||||
**Check**: web.config on 10.0.20.36
|
||||
|
||||
```powershell
|
||||
# On 10.0.20.36
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\web.config | Select-String "roa2web/api"
|
||||
```
|
||||
|
||||
**Fix**: Update to correct internal server config (see above)
|
||||
|
||||
### Issue: Infinite redirect loop
|
||||
|
||||
**Symptom**: Browser shows "Too many redirects"
|
||||
|
||||
**Check**: Verify you didn't put public config on internal server
|
||||
|
||||
### Issue: Backend not reachable
|
||||
|
||||
**Symptom**: 502 Bad Gateway on API calls
|
||||
|
||||
**Check**: Backend service on 10.0.20.36
|
||||
|
||||
```powershell
|
||||
# On 10.0.20.36
|
||||
Get-Service ROA2WEB-Backend
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Server | IP | Config File | Key Pattern | Proxies To |
|
||||
|--------|----|----|-------------|------------|
|
||||
| **Public** | 10.0.20.122 | `web.config.10.0.20.122-PUBLIC` | `url="(.*)"` | `https://10.0.20.36/{R:1}` |
|
||||
| **Internal** | 10.0.20.36 | `web.config.10.0.20.36-INTERNAL` | `url="^roa2web/api/(.*)"` | `http://localhost:8000/api/{R:1}` |
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
For complete architecture details, see:
|
||||
- `deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md`
|
||||
- `DIAGNOSIS-2025-12-30.md`
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2025-12-30*
|
||||
*ROA2WEB Deployment Configuration Guide*
|
||||
@@ -124,16 +124,27 @@
|
||||
|
||||
</rules>
|
||||
|
||||
<!-- Outbound Rules (optional - for modifying responses) -->
|
||||
<!-- Outbound Rules for response headers -->
|
||||
<outboundRules>
|
||||
<!-- HSTS Header for HTTPS connections -->
|
||||
<rule name="Add HSTS Header" preCondition="IsHTTPS">
|
||||
<match serverVariable="RESPONSE_Strict-Transport-Security" pattern=".*" />
|
||||
<action type="Rewrite" value="max-age=31536000; includeSubDomains" />
|
||||
</rule>
|
||||
|
||||
<!-- API responses: NO browser/proxy caching (backend cache handles this) -->
|
||||
<rule name="No Cache for API" preCondition="IsAPIRequest">
|
||||
<match serverVariable="RESPONSE_Cache-Control" pattern=".*" />
|
||||
<action type="Rewrite" value="no-store, no-cache, must-revalidate, proxy-revalidate" />
|
||||
</rule>
|
||||
|
||||
<preConditions>
|
||||
<preCondition name="IsHTTPS">
|
||||
<add input="{HTTPS}" pattern="on" />
|
||||
</preCondition>
|
||||
<preCondition name="IsAPIRequest">
|
||||
<add input="{URL}" pattern="^/api/" />
|
||||
</preCondition>
|
||||
</preConditions>
|
||||
</outboundRules>
|
||||
</rewrite>
|
||||
|
||||
@@ -422,8 +422,8 @@ Get-Content "C:\ROA2WEB-Scripts\last-deploy.json" | ConvertFrom-Json | Format-Li
|
||||
|
||||
### Check Service Status (Server)
|
||||
```powershell
|
||||
# After deployment, verify services
|
||||
Get-Service -Name "ROA2WEB-Backend", "ROA2WEB-TelegramBot"
|
||||
# After deployment, verify service
|
||||
Get-Service -Name "ROA2WEB-Backend"
|
||||
|
||||
# Or use ROA2WEB-Console.ps1
|
||||
cd C:\inetpub\wwwroot\roa2web\scripts
|
||||
@@ -669,14 +669,13 @@ Get-Content "C:\Temp\ROA2WEB-Scripts\Logs\check-and-deploy.log" -Tail 30
|
||||
```
|
||||
|
||||
```powershell
|
||||
# Verify services are running:
|
||||
Get-Service -Name "ROA2WEB-Backend", "ROA2WEB-TelegramBot"
|
||||
# Verify service is running:
|
||||
Get-Service -Name "ROA2WEB-Backend"
|
||||
|
||||
# Expected output:
|
||||
# Status Name DisplayName
|
||||
# ------ ---- -----------
|
||||
# Running ROA2WEB-Backend ROA2WEB Backend Service
|
||||
# Running ROA2WEB-TelegramBot ROA2WEB Telegram Bot Service
|
||||
```
|
||||
|
||||
#### Step 5: Verify Web Application
|
||||
|
||||
@@ -1,855 +0,0 @@
|
||||
# ROA2WEB Telegram Bot - Windows Server Deployment Guide
|
||||
|
||||
> ⚠️ **DEPRECATED ARCHITECTURE**
|
||||
>
|
||||
> This documentation refers to the OLD microservices architecture where the Telegram bot
|
||||
> ran as a separate service on port 8002. The current architecture is an **ultrathin monolith**
|
||||
> where everything runs on a single port (8000/8001) via `backend/main.py`.
|
||||
>
|
||||
> **Current Architecture**: Telegram bot runs as a background task within the unified backend.
|
||||
> Internal API endpoints are now at `/api/telegram/internal/*` on the main port.
|
||||
>
|
||||
> See `CLAUDE.md` and `QUICK-START.md` for the current architecture.
|
||||
|
||||
**Target Server**: Windows Server (10.0.20.36)
|
||||
**Deployment Method**: Windows Service (NSSM) - No Docker
|
||||
**Service Name**: ROA2WEB-TelegramBot
|
||||
**Internal API Port**: ~~8002~~ (DEPRECATED - now via main backend)
|
||||
**Created**: 2025-10-22
|
||||
**Last Updated**: 2025-10-22
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Prerequisites](#prerequisites)
|
||||
3. [Deployment Architecture](#deployment-architecture)
|
||||
4. [Installation Steps](#installation-steps)
|
||||
5. [Configuration](#configuration)
|
||||
6. [Service Management](#service-management)
|
||||
7. [Database Backup](#database-backup)
|
||||
8. [Monitoring & Troubleshooting](#monitoring--troubleshooting)
|
||||
9. [Security Considerations](#security-considerations)
|
||||
10. [Maintenance Procedures](#maintenance-procedures)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The ROA2WEB Telegram Bot is deployed as a Windows Service on the same server as the backend (10.0.20.36). It provides an alternative conversational interface to ROA2WEB using Claude Agent SDK.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Conversational AI**: Claude Agent SDK with 5 custom tools
|
||||
- **Account Linking**: Secure linking between Telegram and Oracle accounts
|
||||
- **Real-time Queries**: Dashboard, invoices, treasury, exports
|
||||
- **Database**: Standalone SQLite for Telegram-specific data
|
||||
- **Internal API**: FastAPI endpoint for backend callbacks (port 8002)
|
||||
- **Production Ready**: All components use real backend integration (no mocks)
|
||||
|
||||
### Deployment Method
|
||||
|
||||
- **Windows Service**: Runs via NSSM (Non-Sucking Service Manager)
|
||||
- **No Docker**: Direct Windows deployment (same pattern as backend)
|
||||
- **Auto-start**: Service starts automatically on server boot
|
||||
- **Auto-recovery**: Service restarts automatically on failure
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Server Requirements
|
||||
|
||||
- **Operating System**: Windows Server 2016+ or Windows 10/11
|
||||
- **Python**: 3.11 or higher
|
||||
- **RAM**: Minimum 512 MB (dedicated to service)
|
||||
- **Disk Space**: Minimum 500 MB
|
||||
- **Network**: Access to localhost:8000 (backend API)
|
||||
|
||||
### Required Credentials
|
||||
|
||||
1. **Telegram Bot Token**
|
||||
- Get from @BotFather on Telegram
|
||||
- Command: `/newbot` or `/mybots`
|
||||
- Example: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`
|
||||
|
||||
2. **Claude Authentication** (Choose ONE method)
|
||||
|
||||
**Method A: Claude Pro/Max Subscription** ⭐ **RECOMMENDED**
|
||||
- ✅ **NO API key needed**
|
||||
- ✅ **NO additional costs** (included in your subscription)
|
||||
- ✅ Uses browser authentication
|
||||
- See: [Claude Authentication Setup](#claude-authentication-setup) below
|
||||
|
||||
**Method B: Claude API Key** (Alternative)
|
||||
- Get from Anthropic Console: https://console.anthropic.com/settings/keys
|
||||
- Example: `sk-ant-api03-XXXXXXXX...`
|
||||
- ⚠️ Usage-based billing applies
|
||||
- Takes precedence over Method A if both are configured
|
||||
|
||||
3. **Backend Access**
|
||||
- Backend should be running on http://localhost:8000
|
||||
- Verify: `Invoke-WebRequest http://localhost:8000/health`
|
||||
|
||||
### Software Prerequisites
|
||||
|
||||
- **PowerShell 5.1+**: Built into Windows Server
|
||||
- **Python 3.11+**: Will be installed if missing (via Chocolatey)
|
||||
- **NSSM**: Will be installed automatically by installation script
|
||||
|
||||
---
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
C:\inetpub\wwwroot\roa2web\telegram-bot\
|
||||
├── app\ # Application source code
|
||||
│ ├── main.py # Entry point, Claude Agent wrapper
|
||||
│ ├── bot\ # Telegram bot handlers
|
||||
│ ├── agent\ # Claude Agent tools and sessions
|
||||
│ ├── auth\ # Account linking logic
|
||||
│ ├── db\ # SQLite database operations
|
||||
│ ├── api\ # Backend API client
|
||||
│ └── internal_api.py # FastAPI internal API
|
||||
├── venv\ # Python virtual environment
|
||||
├── data\ # SQLite database
|
||||
│ └── telegram_bot.db # Main database file
|
||||
├── logs\ # Application logs
|
||||
│ ├── stdout.log # Service output
|
||||
│ ├── stderr.log # Service errors
|
||||
│ └── backup.log # Backup operations
|
||||
├── backups\ # Database backups
|
||||
├── temp\ # Temporary files
|
||||
├── scripts\ # PowerShell management scripts
|
||||
├── config\ # Configuration templates
|
||||
├── requirements.txt # Python dependencies
|
||||
└── .env # Environment configuration
|
||||
```
|
||||
|
||||
### Service Integration
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Windows Server 10.0.20.36 │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ IIS (Port 80) │ │ ROA2WEB-Backend │ │
|
||||
│ │ Frontend Static │ │ (Port 8000) │ │
|
||||
│ └──────────────────┘ └────────┬─────────┘ │
|
||||
│ │ │
|
||||
│ │ HTTP API Calls │
|
||||
│ │ │
|
||||
│ ┌─────────────────▼──────────────┐ │
|
||||
│ │ ROA2WEB-TelegramBot │ │
|
||||
│ │ (Port 8002 - Internal API) │ │
|
||||
│ │ - Telegram Bot Handlers │ │
|
||||
│ │ - Claude Agent SDK │ │
|
||||
│ │ - SQLite Database │ │
|
||||
│ └────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Telegram Bot API
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Telegram │
|
||||
│ Cloud │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### Step 1: Build Deployment Package (Development Machine)
|
||||
|
||||
On your development machine (WSL/Linux), run:
|
||||
|
||||
```bash
|
||||
cd /mnt/e/proiecte/roa2web/roa2web/deployment/windows/scripts
|
||||
./Build-TelegramBot.ps1
|
||||
```
|
||||
|
||||
This creates the deployment package at:
|
||||
```
|
||||
../deploy-package/telegram-bot/
|
||||
```
|
||||
|
||||
**Package Contents**:
|
||||
- `app/` - Application source code
|
||||
- `requirements.txt` - Python dependencies
|
||||
- `.env.example` - Configuration template
|
||||
- `scripts/` - PowerShell management scripts
|
||||
- `config/` - Production config templates
|
||||
- `README.txt` - Deployment instructions
|
||||
|
||||
### Step 2: Transfer Package to Server
|
||||
|
||||
**Option A: Network Share** (Recommended)
|
||||
```powershell
|
||||
# On development machine
|
||||
Copy-Item -Path ./deploy-package/telegram-bot -Destination \\10.0.20.36\C$\Temp\telegram-bot-deploy -Recurse
|
||||
```
|
||||
|
||||
**Option B: RDP**
|
||||
1. Connect to server via RDP: `mstsc /v:10.0.20.36`
|
||||
2. Manually copy deployment package to `C:\Temp\telegram-bot-deploy`
|
||||
|
||||
### Step 3: Run Installation Script
|
||||
|
||||
On Windows Server (10.0.20.36), open PowerShell as Administrator:
|
||||
|
||||
```powershell
|
||||
cd C:\Temp\telegram-bot-deploy\scripts
|
||||
.\Install-TelegramBot.ps1
|
||||
```
|
||||
|
||||
**Installation Process**:
|
||||
1. ✅ Checks Python 3.11+ installation
|
||||
2. ✅ Installs NSSM (service manager)
|
||||
3. ✅ Creates directory structure
|
||||
4. ✅ Creates Python virtual environment
|
||||
5. ✅ Installs Python dependencies
|
||||
6. ✅ Creates Windows Service (ROA2WEB-TelegramBot)
|
||||
7. ✅ Creates .env configuration template
|
||||
|
||||
**Installation Output**:
|
||||
```
|
||||
====================================================================
|
||||
ROA2WEB TELEGRAM BOT INSTALLATION COMPLETED
|
||||
====================================================================
|
||||
|
||||
Installation Details:
|
||||
Install Path: C:\inetpub\wwwroot\roa2web\telegram-bot
|
||||
Service Name: ROA2WEB-TelegramBot
|
||||
Internal API Port: 8002
|
||||
|
||||
Next Steps:
|
||||
1. Edit configuration: C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
2. Start service: .\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Step 4: Configure Environment
|
||||
|
||||
Edit the `.env` file:
|
||||
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
```
|
||||
|
||||
**Required Configuration**:
|
||||
```env
|
||||
# CRITICAL: Update this value
|
||||
TELEGRAM_BOT_TOKEN=your_production_bot_token_from_@BotFather
|
||||
|
||||
# Claude Authentication: Leave empty to use Claude Pro/Max subscription
|
||||
CLAUDE_API_KEY=
|
||||
|
||||
# Verify these are correct
|
||||
BACKEND_URL=http://localhost:8000
|
||||
SQLITE_DB_PATH=C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
LOG_LEVEL=INFO
|
||||
ENVIRONMENT=production
|
||||
```
|
||||
|
||||
**Get Bot Token**:
|
||||
1. Open Telegram, search for `@BotFather`
|
||||
2. Send `/newbot` or `/mybots`
|
||||
3. Copy token to `TELEGRAM_BOT_TOKEN`
|
||||
|
||||
### Step 4a: Claude Authentication Setup
|
||||
|
||||
**Choose ONE authentication method:**
|
||||
|
||||
#### **Method A: Claude Pro/Max Subscription** ⭐ **RECOMMENDED**
|
||||
|
||||
If you have a Claude Pro or Claude Max subscription, use this method (NO API key needed!):
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Setup-ClaudeAuth.ps1
|
||||
```
|
||||
|
||||
**What happens:**
|
||||
1. Script installs `claude-code` CLI (if not already installed)
|
||||
2. Opens your browser for authentication
|
||||
3. Log in with your Claude Pro/Max account
|
||||
4. Authorize the application
|
||||
5. Credentials are saved to: `%APPDATA%\claude\credentials.json`
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
====================================================================
|
||||
IMPORTANT: Browser Authentication Required
|
||||
====================================================================
|
||||
|
||||
1. A browser window will open
|
||||
2. Log in with your Claude Pro/Max account
|
||||
3. Authorize the application
|
||||
4. Return to this window after authentication
|
||||
|
||||
====================================================================
|
||||
|
||||
[*] Opening browser for authentication...
|
||||
[OK] Authentication successful!
|
||||
[OK] Credentials file found and valid
|
||||
[OK] .env will use Claude Pro subscription (browser login)
|
||||
|
||||
====================================================================
|
||||
CLAUDE AUTHENTICATION SETUP COMPLETE
|
||||
====================================================================
|
||||
```
|
||||
|
||||
**Alternative: Copy credentials from development machine**
|
||||
|
||||
If the server doesn't have browser access, authenticate on your local machine and copy credentials:
|
||||
|
||||
```powershell
|
||||
# On local machine (with browser):
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
claude-code login
|
||||
|
||||
# Copy credentials file to server
|
||||
Copy-Item "$env:APPDATA\claude\credentials.json" -Destination "\\10.0.20.36\C$\Temp\claude-credentials.json"
|
||||
|
||||
# On server:
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Setup-ClaudeAuth.ps1 -Method copy -CredentialsPath "C:\Temp\claude-credentials.json"
|
||||
```
|
||||
|
||||
#### **Method B: Claude API Key** (Alternative)
|
||||
|
||||
If you prefer to use an API key instead:
|
||||
|
||||
1. Visit https://console.anthropic.com/settings/keys
|
||||
2. Create new key
|
||||
3. Edit `.env` and set `CLAUDE_API_KEY=sk-ant-api03-XXXXXXXX...`
|
||||
4. ⚠️ Usage-based billing applies
|
||||
|
||||
**Note:** API key takes precedence over browser login if both are configured.
|
||||
|
||||
### Step 5: Start Service
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
**Expected Output**:
|
||||
```
|
||||
[*] Starting ROA2WEB Telegram Bot Service...
|
||||
[*] Service start command issued
|
||||
[*] Waiting for service to start... (5/30)
|
||||
[OK] Service started successfully
|
||||
[OK] Health check passed: healthy
|
||||
[OK] Database: connected
|
||||
```
|
||||
|
||||
### Step 6: Verify Installation
|
||||
|
||||
**Check Service Status**:
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
```
|
||||
|
||||
Expected: `Status = Running`
|
||||
|
||||
**Check Health Endpoint**:
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health | ConvertFrom-Json
|
||||
```
|
||||
|
||||
Expected Output:
|
||||
```json
|
||||
{
|
||||
"status": "healthy",
|
||||
"timestamp": "2025-10-22T14:30:00",
|
||||
"database": {
|
||||
"status": "connected",
|
||||
"users": 0,
|
||||
"pending_codes": 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Test Bot on Telegram**:
|
||||
1. Open Telegram
|
||||
2. Search for your bot (name from @BotFather)
|
||||
3. Send `/start`
|
||||
4. Expected: Welcome message with linking instructions
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables Reference
|
||||
|
||||
See `.env.production.windows.telegram` in `config/` directory for complete reference.
|
||||
|
||||
**Key Settings**:
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `TELEGRAM_BOT_TOKEN` | *required* | Bot token from @BotFather |
|
||||
| `CLAUDE_API_KEY` | *required* | API key from Anthropic |
|
||||
| `BACKEND_URL` | `http://localhost:8000` | Backend API URL |
|
||||
| `SQLITE_DB_PATH` | `C:\...\telegram_bot.db` | Database file location |
|
||||
| `INTERNAL_API_PORT` | `8002` | Internal API port |
|
||||
| `LOG_LEVEL` | `INFO` | Logging level (DEBUG/INFO/WARN/ERROR) |
|
||||
| `ENVIRONMENT` | `production` | Environment name |
|
||||
| `AUTH_CODE_EXPIRY_MINUTES` | `15` | Linking code expiry time |
|
||||
| `SESSION_TIMEOUT_MINUTES` | `60` | User session timeout |
|
||||
| `MAX_CONVERSATION_HISTORY` | `20` | Max messages per session |
|
||||
|
||||
### Applying Configuration Changes
|
||||
|
||||
After editing `.env`:
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service Management
|
||||
|
||||
### Start Service
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Stop Service
|
||||
|
||||
```powershell
|
||||
.\Stop-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Restart Service
|
||||
|
||||
```powershell
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Check Service Status
|
||||
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Detailed info
|
||||
Get-Service ROA2WEB-TelegramBot | Select-Object *
|
||||
```
|
||||
|
||||
### View Logs
|
||||
|
||||
**Real-time Logs** (tail -f equivalent):
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50 -Wait
|
||||
```
|
||||
|
||||
**Error Logs**:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
|
||||
```
|
||||
|
||||
**Backup Logs**:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\backup.log -Tail 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Backup
|
||||
|
||||
### Manual Backup
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Backup-TelegramDB.ps1
|
||||
```
|
||||
|
||||
**Output**:
|
||||
- Backup file: `backups/telegram_bot_backup_YYYYMMDD-HHMMSS.db.zip`
|
||||
- Compressed and timestamped
|
||||
- Integrity tested automatically
|
||||
|
||||
### Setup Automated Daily Backup
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Setup-DailyBackup.ps1
|
||||
```
|
||||
|
||||
**Configuration**:
|
||||
- Runs daily at 2:00 AM
|
||||
- Keeps last 30 days of backups
|
||||
- Runs as SYSTEM account
|
||||
- Logs all operations
|
||||
|
||||
**Verify Scheduled Task**:
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ROA2WEB-TelegramBot-Backup"
|
||||
```
|
||||
|
||||
**Run Backup Manually** (via Task Scheduler):
|
||||
```powershell
|
||||
Start-ScheduledTask -TaskName "ROA2WEB-TelegramBot-Backup"
|
||||
```
|
||||
|
||||
### Restore from Backup
|
||||
|
||||
1. Stop service:
|
||||
```powershell
|
||||
.\Stop-TelegramBot.ps1
|
||||
```
|
||||
|
||||
2. Find backup file:
|
||||
```powershell
|
||||
Get-ChildItem C:\inetpub\wwwroot\roa2web\telegram-bot\backups | Sort-Object LastWriteTime -Descending
|
||||
```
|
||||
|
||||
3. Extract backup (if compressed):
|
||||
```powershell
|
||||
Expand-Archive -Path "backups\telegram_bot_backup_YYYYMMDD-HHMMSS.db.zip" -DestinationPath "temp\"
|
||||
```
|
||||
|
||||
4. Replace database:
|
||||
```powershell
|
||||
Copy-Item -Path "temp\telegram_bot_backup_YYYYMMDD-HHMMSS.db" -Destination "data\telegram_bot.db" -Force
|
||||
```
|
||||
|
||||
5. Start service:
|
||||
```powershell
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Troubleshooting
|
||||
|
||||
### Health Checks
|
||||
|
||||
**Service Health**:
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot | Select-Object Name, Status, StartType
|
||||
```
|
||||
|
||||
**API Health**:
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
**Database Stats**:
|
||||
```powershell
|
||||
(Invoke-WebRequest http://localhost:8002/internal/stats).Content | ConvertFrom-Json
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Service Won't Start
|
||||
|
||||
**Symptoms**: Service shows "Stopped" or "Starting" forever
|
||||
|
||||
**Diagnosis**:
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
|
||||
```
|
||||
|
||||
**Common Causes**:
|
||||
1. **Missing .env file** → Create from `.env.example`
|
||||
2. **Invalid bot token** → Check `TELEGRAM_BOT_TOKEN`
|
||||
3. **Invalid Claude API key** → Check `CLAUDE_API_KEY`
|
||||
4. **Port 8002 already in use** → Change `INTERNAL_API_PORT`
|
||||
5. **Backend not running** → Start ROA2WEB-Backend service
|
||||
|
||||
**Solutions**:
|
||||
```powershell
|
||||
# Fix config
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Check port availability
|
||||
Get-NetTCPConnection -LocalPort 8002
|
||||
|
||||
# Restart service
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Bot Not Responding on Telegram
|
||||
|
||||
**Symptoms**: Bot doesn't reply to messages
|
||||
|
||||
**Diagnosis**:
|
||||
1. Check service status:
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
```
|
||||
2. Check health endpoint:
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
```
|
||||
3. Check logs for errors:
|
||||
```powershell
|
||||
Get-Content logs\stderr.log -Tail 50
|
||||
```
|
||||
|
||||
**Common Causes**:
|
||||
1. **Service stopped** → Start service
|
||||
2. **Invalid bot token** → Update `.env`
|
||||
3. **Network issues** → Check internet connectivity
|
||||
4. **Bot blocked by user** → User must /start bot again
|
||||
|
||||
#### Account Linking Fails
|
||||
|
||||
**Symptoms**: `/link CODE` returns error
|
||||
|
||||
**Diagnosis**:
|
||||
```powershell
|
||||
# Check internal API
|
||||
Invoke-WebRequest http://localhost:8002/internal/stats
|
||||
|
||||
# Check backend connectivity
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
**Common Causes**:
|
||||
1. **Code expired** (15 min) → Generate new code
|
||||
2. **Backend unreachable** → Check ROA2WEB-Backend service
|
||||
3. **Database error** → Check SQLite file permissions
|
||||
|
||||
#### Database Errors
|
||||
|
||||
**Symptoms**: "Database locked" or "Cannot open database"
|
||||
|
||||
**Diagnosis**:
|
||||
```powershell
|
||||
# Check database file
|
||||
Test-Path C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
|
||||
# Check file permissions
|
||||
icacls C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
```
|
||||
|
||||
**Solutions**:
|
||||
```powershell
|
||||
# Stop service
|
||||
.\Stop-TelegramBot.ps1
|
||||
|
||||
# Fix permissions
|
||||
icacls C:\inetpub\wwwroot\roa2web\telegram-bot\data /grant "SYSTEM:(OI)(CI)F" /T
|
||||
|
||||
# Restart service
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Secrets Management
|
||||
|
||||
**NEVER**:
|
||||
- Commit `.env` to git
|
||||
- Share bot token or API keys
|
||||
- Log sensitive data
|
||||
|
||||
**ALWAYS**:
|
||||
- Keep backups of `.env` in secure location
|
||||
- Rotate API keys periodically
|
||||
- Use strong file permissions
|
||||
|
||||
**File Permissions**:
|
||||
```powershell
|
||||
# Restrict .env to SYSTEM and Administrators only
|
||||
icacls C:\inetpub\wwwroot\roa2web\telegram-bot\.env /grant "SYSTEM:F" /grant "Administrators:F" /inheritance:r
|
||||
```
|
||||
|
||||
### Network Security
|
||||
|
||||
- **Internal API (8002)**: Bind to 127.0.0.1 (localhost only)
|
||||
- **Backend API (8000)**: Already on localhost
|
||||
- **No Firewall Rules Needed**: All communication is local
|
||||
|
||||
### Bot Security
|
||||
|
||||
- **Account Linking**: 8-character codes, 15-minute expiry
|
||||
- **JWT Tokens**: Signed and verified by backend
|
||||
- **Rate Limiting**: Built into authentication middleware
|
||||
- **Session Timeout**: 60 minutes of inactivity
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Procedures
|
||||
|
||||
### Updates and Deployments
|
||||
|
||||
1. **Build new deployment package** (dev machine):
|
||||
```bash
|
||||
./Build-TelegramBot.ps1
|
||||
```
|
||||
|
||||
2. **Transfer to server**:
|
||||
```powershell
|
||||
Copy-Item -Path ./deploy-package/telegram-bot -Destination \\10.0.20.36\C$\Temp\telegram-bot-update -Recurse
|
||||
```
|
||||
|
||||
3. **Deploy update** (server):
|
||||
```powershell
|
||||
cd C:\Temp\telegram-bot-update\scripts
|
||||
.\Deploy-TelegramBot.ps1
|
||||
```
|
||||
|
||||
**Deployment Features**:
|
||||
- ✅ Automatic backup before deployment
|
||||
- ✅ Stops service, updates files, restarts service
|
||||
- ✅ Preserves `.env` configuration
|
||||
- ✅ Automatic rollback on failure
|
||||
- ✅ Health check after deployment
|
||||
|
||||
### Log Rotation
|
||||
|
||||
Logs are automatically rotated by Python logging:
|
||||
- **Max size**: 10 MB per file
|
||||
- **Backups**: 5 old log files kept
|
||||
- **Location**: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\`
|
||||
|
||||
**Manual cleanup**:
|
||||
```powershell
|
||||
# Delete old logs (older than 30 days)
|
||||
Get-ChildItem C:\inetpub\wwwroot\roa2web\telegram-bot\logs\*.log |
|
||||
Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-30) } |
|
||||
Remove-Item -Force
|
||||
```
|
||||
|
||||
### Database Maintenance
|
||||
|
||||
**Cleanup expired data** (automatic via scheduled task):
|
||||
- Expired auth codes (older than 15 minutes)
|
||||
- Old sessions (inactive for 60+ minutes)
|
||||
- Runs hourly automatically
|
||||
|
||||
**Manual cleanup**:
|
||||
```sql
|
||||
-- Connect to database
|
||||
sqlite3 C:\inetpub\wwwroot\roa2web\telegram-bot\data\telegram_bot.db
|
||||
|
||||
-- Delete expired codes
|
||||
DELETE FROM telegram_auth_codes WHERE created_at < datetime('now', '-15 minutes');
|
||||
|
||||
-- Delete old sessions
|
||||
DELETE FROM telegram_sessions WHERE updated_at < datetime('now', '-60 minutes');
|
||||
```
|
||||
|
||||
### Service Health Monitoring
|
||||
|
||||
**Daily Checks** (manual or script):
|
||||
```powershell
|
||||
# Service status
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Health endpoint
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
|
||||
# Check logs for errors
|
||||
Get-Content logs\stderr.log -Tail 50 | Select-String "ERROR"
|
||||
|
||||
# Check database size
|
||||
(Get-Item data\telegram_bot.db).Length / 1MB
|
||||
```
|
||||
|
||||
**Weekly Checks**:
|
||||
- Review backup logs
|
||||
- Check backup retention (30 days)
|
||||
- Review disk space usage
|
||||
- Check for Windows updates
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### PowerShell Scripts Reference
|
||||
|
||||
| Script | Purpose |
|
||||
|--------|---------|
|
||||
| `Install-TelegramBot.ps1` | Initial installation |
|
||||
| `Deploy-TelegramBot.ps1` | Deploy updates |
|
||||
| `Build-TelegramBot.ps1` | Build deployment package |
|
||||
| `Start-TelegramBot.ps1` | Start service |
|
||||
| `Stop-TelegramBot.ps1` | Stop service |
|
||||
| `Restart-TelegramBot.ps1` | Restart service |
|
||||
| `Backup-TelegramDB.ps1` | Manual database backup |
|
||||
| `Setup-DailyBackup.ps1` | Configure automated backups |
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Endpoint | Method | Description |
|
||||
|----------|--------|-------------|
|
||||
| `/internal/health` | GET | Health check |
|
||||
| `/internal/stats` | GET | Database statistics |
|
||||
| `/internal/save-code` | POST | Save auth code (from backend) |
|
||||
| `/internal/verify-code` | POST | Verify auth code |
|
||||
|
||||
### Database Schema
|
||||
|
||||
**telegram_users**:
|
||||
```sql
|
||||
CREATE TABLE telegram_users (
|
||||
telegram_user_id INTEGER PRIMARY KEY,
|
||||
oracle_user_id INTEGER NOT NULL,
|
||||
oracle_username TEXT NOT NULL,
|
||||
jwt_token TEXT NOT NULL,
|
||||
jwt_refresh_token TEXT,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
**telegram_auth_codes**:
|
||||
```sql
|
||||
CREATE TABLE telegram_auth_codes (
|
||||
code TEXT PRIMARY KEY,
|
||||
oracle_user_id INTEGER NOT NULL,
|
||||
oracle_username TEXT NOT NULL,
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
expires_at TIMESTAMP NOT NULL,
|
||||
used INTEGER DEFAULT 0
|
||||
);
|
||||
```
|
||||
|
||||
**telegram_sessions**:
|
||||
```sql
|
||||
CREATE TABLE telegram_sessions (
|
||||
telegram_user_id INTEGER PRIMARY KEY,
|
||||
conversation_history TEXT, -- JSON
|
||||
session_data TEXT, -- JSON
|
||||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
**Documentation**:
|
||||
- Project README: `/mnt/e/proiecte/roa2web/roa2web/backend/modules/telegram/README.md`
|
||||
- Progress Tracker: `/mnt/e/proiecte/roa2web/roa2web/development/TELEGRAM_BOT_PROGRESS.md`
|
||||
- Production Deployment Plan: `/mnt/e/proiecte/roa2web/roa2web/development/TELEGRAM_BOT_PRODUCTION_DEPLOYMENT.md`
|
||||
|
||||
**Logs Location**:
|
||||
- Service Output: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log`
|
||||
- Service Errors: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log`
|
||||
- Backups: `C:\inetpub\wwwroot\roa2web\telegram-bot\logs\backup.log`
|
||||
|
||||
**Contact**: ROA2WEB Development Team
|
||||
|
||||
---
|
||||
|
||||
**Document Version**: 1.0
|
||||
**Last Updated**: 2025-10-22
|
||||
**Status**: Production Ready
|
||||
@@ -1,546 +0,0 @@
|
||||
# ROA2WEB Telegram Bot - Windows Deployment Troubleshooting Guide
|
||||
|
||||
> ⚠️ **DEPRECATED ARCHITECTURE**
|
||||
>
|
||||
> This documentation refers to the OLD microservices architecture (port 8002).
|
||||
> The current architecture is an **ultrathin monolith** - everything on port 8000/8001.
|
||||
> Telegram internal API is now at `/api/telegram/internal/*` on the main backend.
|
||||
|
||||
This guide helps diagnose and fix common issues with Telegram bot integration on Windows Server deployments.
|
||||
|
||||
## Problem: "Link invalid sau expirat" (Invalid or expired link)
|
||||
|
||||
When users generate a linking code in the web frontend but the Telegram bot says the code is invalid or expired, this indicates a communication problem between the backend and telegram bot services.
|
||||
|
||||
### Root Cause
|
||||
|
||||
The backend cannot communicate with the Telegram bot's internal API to save the generated linking codes.
|
||||
|
||||
### Diagnostic Steps
|
||||
|
||||
Run these PowerShell commands on the Windows Server (10.0.20.36) to diagnose:
|
||||
|
||||
#### 1. Check Telegram Bot Service Status
|
||||
|
||||
```powershell
|
||||
# Check if service is running
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Expected output:
|
||||
# Status Name DisplayName
|
||||
# ------ ---- -----------
|
||||
# Running ROA2WEB-TelegramBot ROA2WEB Telegram Bot Service
|
||||
```
|
||||
|
||||
If service is **not running**, start it:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### 2. Check Internal API Port (8002)
|
||||
|
||||
```powershell
|
||||
# Check if port 8002 is listening
|
||||
netstat -ano | findstr :8002
|
||||
|
||||
# Expected output (should show LISTENING):
|
||||
# TCP 127.0.0.1:8002 0.0.0.0:0 LISTENING <PID>
|
||||
```
|
||||
|
||||
If port is **not listening**, the telegram bot service may not have started correctly. Check logs:
|
||||
```powershell
|
||||
# View service logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50
|
||||
|
||||
# View error logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 50
|
||||
```
|
||||
|
||||
#### 3. Test Internal API Health Endpoint
|
||||
|
||||
```powershell
|
||||
# Test if internal API responds
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
|
||||
# Expected output:
|
||||
# StatusCode : 200
|
||||
# StatusDescription : OK
|
||||
# Content : {"status":"healthy","timestamp":"2025-...","database_stats":{...}}
|
||||
```
|
||||
|
||||
If this **fails**, the internal API is not running. Check telegram bot service logs.
|
||||
|
||||
#### 4. Check Backend .env Configuration
|
||||
|
||||
```powershell
|
||||
# View backend .env file
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Look for this line:
|
||||
# TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
If the line is **missing or incorrect**, add/fix it:
|
||||
```
|
||||
TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
Then restart backend service:
|
||||
```powershell
|
||||
Restart-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
#### 5. Check Telegram Bot .env Configuration
|
||||
|
||||
```powershell
|
||||
# View telegram bot .env file
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Verify these settings:
|
||||
# TELEGRAM_BOT_TOKEN=<your_production_bot_token>
|
||||
# BACKEND_URL=http://localhost:8000
|
||||
# INTERNAL_API_PORT=8002
|
||||
# INTERNAL_API_HOST=127.0.0.1
|
||||
```
|
||||
|
||||
If TELEGRAM_BOT_TOKEN is wrong (e.g., still using DEV token), update it and restart:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### 6. Test Full Linking Flow
|
||||
|
||||
```powershell
|
||||
# 1. Test backend can reach telegram bot internal API
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'
|
||||
|
||||
# Expected output:
|
||||
# StatusCode: 201 (Created)
|
||||
# Content: {"success":true,"code":"TEST1234","expires_at":"...","message":"..."}
|
||||
|
||||
# 2. Verify code was saved
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234"}'
|
||||
|
||||
# Expected output:
|
||||
# StatusCode: 200 (OK)
|
||||
# Content: {"valid":true,"oracle_username":"testuser","message":"Code is valid"}
|
||||
```
|
||||
|
||||
If step 1 **fails**, there's a network/firewall issue blocking localhost:8002.
|
||||
|
||||
### Solution Checklist
|
||||
|
||||
Fix the issue by following this checklist in order:
|
||||
|
||||
- [ ] **Telegram bot service is running**
|
||||
```powershell
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
# If stopped: cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts; .\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
- [ ] **Internal API port 8002 is listening**
|
||||
```powershell
|
||||
netstat -ano | findstr :8002
|
||||
# Should show LISTENING on 127.0.0.1:8002
|
||||
```
|
||||
|
||||
- [ ] **Internal API responds to health checks**
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
# Should return 200 OK with status "healthy"
|
||||
```
|
||||
|
||||
- [ ] **Backend .env has TELEGRAM_BOT_INTERNAL_API configured**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
# Add: TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
|
||||
```
|
||||
|
||||
- [ ] **Backend service restarted after .env changes**
|
||||
```powershell
|
||||
Restart-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
- [ ] **Telegram bot .env has correct TELEGRAM_BOT_TOKEN**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
# Should have ROA2WEBBot token, not ROA2WEBDEVBot token
|
||||
```
|
||||
|
||||
- [ ] **Test full linking flow from web frontend**
|
||||
- Log in to web frontend (http://10.0.20.36)
|
||||
- Generate linking code
|
||||
- Send code to @ROA2WEBBot via `/start CODE12345`
|
||||
- Should receive success message from bot
|
||||
|
||||
---
|
||||
|
||||
## Problem: "Cannot connect to backend" / Connection Errors
|
||||
|
||||
After successfully generating a linking code, the Telegram bot finds the code but fails to complete the linking with error messages like:
|
||||
|
||||
- `httpcore.ConnectError: All connection attempts failed`
|
||||
- `Cannot connect to backend at http://localhost:8000`
|
||||
- `AttributeError: 'ConnectError' object has no attribute 'response'` (fixed in latest version)
|
||||
|
||||
### Root Cause
|
||||
|
||||
The Telegram bot cannot communicate with the FastAPI backend to verify the Oracle user and obtain a JWT token. This happens when:
|
||||
|
||||
1. Backend service is not running
|
||||
2. Backend is running on wrong port
|
||||
3. BACKEND_URL in telegram bot .env is incorrect
|
||||
4. Firewall blocking communication
|
||||
|
||||
### Diagnostic Steps
|
||||
|
||||
#### 1. Check Backend Service Status
|
||||
|
||||
```powershell
|
||||
# Check if backend service is running
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# Expected output:
|
||||
# Status Name DisplayName
|
||||
# ------ ---- -----------
|
||||
# Running ROA2WEB-Backend ROA2WEB Backend Service
|
||||
```
|
||||
|
||||
If service is **not running**, start it:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\scripts
|
||||
.\Start-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
#### 2. Check Backend Port (8000)
|
||||
|
||||
```powershell
|
||||
# Check if port 8000 is listening
|
||||
netstat -ano | findstr :8000
|
||||
|
||||
# Expected output (should show LISTENING):
|
||||
# TCP 0.0.0.0:8000 0.0.0.0:0 LISTENING <PID>
|
||||
```
|
||||
|
||||
If port is **not listening**, check backend logs:
|
||||
```powershell
|
||||
# View backend service logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50
|
||||
```
|
||||
|
||||
#### 3. Test Backend Health Endpoint
|
||||
|
||||
```powershell
|
||||
# Test if backend API responds
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
|
||||
# Expected output:
|
||||
# StatusCode : 200
|
||||
# Content : {"status":"healthy",...}
|
||||
```
|
||||
|
||||
If this **fails**, backend is not accessible. Check service logs.
|
||||
|
||||
#### 4. Check Telegram Bot BACKEND_URL Configuration
|
||||
|
||||
```powershell
|
||||
# View telegram bot .env file
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Verify this line exists and is correct:
|
||||
# BACKEND_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
**Common mistakes:**
|
||||
- Using `http://localhost:8001` (dev port instead of production port 8000)
|
||||
- Missing `http://` prefix
|
||||
- Using IP address instead of localhost
|
||||
|
||||
If BACKEND_URL is **incorrect**, fix it and restart:
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### 5. Test Backend Verify-User Endpoint
|
||||
|
||||
```powershell
|
||||
# Test the specific endpoint telegram bot uses
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8000/api/telegram/auth/verify-user `
|
||||
-Headers @{"Content-Type"="application/json"} `
|
||||
-Body '{"linking_code":"TESTCODE","oracle_username":"testuser"}'
|
||||
|
||||
# Expected output (will fail with 400/404 for test data, but confirms endpoint is reachable):
|
||||
# StatusCode: 400 or 404 (NOT connection error)
|
||||
```
|
||||
|
||||
If you get **connection error** instead of 400/404, backend is not running or port is wrong.
|
||||
|
||||
### Solution Checklist
|
||||
|
||||
Fix the issue by following this checklist:
|
||||
|
||||
- [ ] **Backend service is running**
|
||||
```powershell
|
||||
Get-Service ROA2WEB-Backend
|
||||
# If stopped: cd C:\inetpub\wwwroot\roa2web\scripts; .\Start-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
- [ ] **Backend port 8000 is listening**
|
||||
```powershell
|
||||
netstat -ano | findstr :8000
|
||||
# Should show LISTENING on 0.0.0.0:8000
|
||||
```
|
||||
|
||||
- [ ] **Backend health check responds**
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
# Should return 200 OK
|
||||
```
|
||||
|
||||
- [ ] **Telegram bot .env has correct BACKEND_URL**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
# Must be: BACKEND_URL=http://localhost:8000
|
||||
```
|
||||
|
||||
- [ ] **Telegram bot service restarted after .env changes**
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
- [ ] **Test full linking flow**
|
||||
- Generate code in web frontend
|
||||
- Send code to @ROA2WEBBot: `/start CODE12345`
|
||||
- Should receive success message (not connection error)
|
||||
|
||||
---
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Issue 1: Port 8002 Already in Use
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot service fails to start
|
||||
- Logs show "Address already in use" or "Port 8002 is already allocated"
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Find process using port 8002
|
||||
netstat -ano | findstr :8002
|
||||
|
||||
# Kill the process (replace <PID> with actual process ID)
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# Restart telegram bot service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Issue 2: Firewall Blocking Localhost
|
||||
|
||||
**Symptoms:**
|
||||
- Backend cannot reach http://localhost:8002
|
||||
- Connection timeout errors in backend logs
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Add firewall rule for port 8002 (localhost only)
|
||||
New-NetFirewallRule -DisplayName "ROA2WEB Telegram Bot Internal API" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow -LocalAddress 127.0.0.1
|
||||
```
|
||||
|
||||
#### Issue 3: Wrong Bot Token
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot service runs but doesn't respond to commands
|
||||
- Logs show "Unauthorized" or "Invalid bot token"
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Update .env with correct token from @BotFather
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Change TELEGRAM_BOT_TOKEN to production bot token:
|
||||
# TELEGRAM_BOT_TOKEN=<production_bot_token>
|
||||
|
||||
# Restart service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Issue 4: SQLite Database Locked
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot logs show "database is locked" errors
|
||||
- Commands fail intermittently
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Stop service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Stop-TelegramBot.ps1
|
||||
|
||||
# Wait 10 seconds for locks to release
|
||||
Start-Sleep -Seconds 10
|
||||
|
||||
# Start service
|
||||
.\Start-TelegramBot.ps1
|
||||
```
|
||||
|
||||
#### Issue 5: Backend Service Not Running
|
||||
|
||||
**Symptoms:**
|
||||
- Telegram bot logs show "Cannot connect to backend" errors
|
||||
- `httpcore.ConnectError: All connection attempts failed`
|
||||
- Linking codes are found but linking fails
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Check backend service status
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# If stopped, start it
|
||||
cd C:\inetpub\wwwroot\roa2web\scripts
|
||||
.\Start-ROA2WEB.ps1
|
||||
|
||||
# Verify backend is listening on port 8000
|
||||
netstat -ano | findstr :8000
|
||||
|
||||
# Test backend health
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
```
|
||||
|
||||
**Check backend logs for startup errors:**
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50
|
||||
```
|
||||
|
||||
**Common backend startup issues:**
|
||||
- Oracle database not accessible
|
||||
- Missing environment variables in backend `.env`
|
||||
- Port 8000 already in use by another process
|
||||
- Python dependencies not installed
|
||||
|
||||
#### Issue 6: Wrong Backend URL in Telegram Bot
|
||||
|
||||
**Symptoms:**
|
||||
- Connection errors to backend
|
||||
- Logs show wrong URL (e.g., `http://localhost:8001` instead of `http://localhost:8000`)
|
||||
|
||||
**Solution:**
|
||||
```powershell
|
||||
# Edit telegram bot .env
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Ensure this line is correct:
|
||||
# BACKEND_URL=http://localhost:8000
|
||||
# (Production uses port 8000, not 8001 which is dev port)
|
||||
|
||||
# Restart telegram bot service
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Verification Steps
|
||||
|
||||
After fixing, verify the complete flow works:
|
||||
|
||||
1. **Backend can save codes to telegram bot:**
|
||||
```powershell
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'
|
||||
```
|
||||
Expected: `201 Created` with success message
|
||||
|
||||
2. **Telegram bot can verify codes:**
|
||||
```powershell
|
||||
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01"}'
|
||||
```
|
||||
Expected: `200 OK` with `"valid":true`
|
||||
|
||||
3. **End-to-end test from web frontend:**
|
||||
- Open web app: http://10.0.20.36
|
||||
- Login with Oracle credentials
|
||||
- Click "Link Telegram Account"
|
||||
- Copy the 8-character code
|
||||
- Send to @ROA2WEBBot: `/start CODE12345`
|
||||
- Should receive: "Contul tău Telegram a fost asociat cu succes!"
|
||||
|
||||
### Getting Help
|
||||
|
||||
If issues persist after following this guide:
|
||||
|
||||
1. **Collect diagnostic information:**
|
||||
```powershell
|
||||
# Service status
|
||||
Get-Service ROA2WEB-TelegramBot | Format-List *
|
||||
|
||||
# Port listening
|
||||
netstat -ano | findstr :8002
|
||||
|
||||
# Recent logs (last 100 lines)
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 100
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
|
||||
|
||||
# Backend logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 100
|
||||
```
|
||||
|
||||
2. **Check configuration files:**
|
||||
```powershell
|
||||
# Backend .env (sanitize sensitive data before sharing!)
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Telegram bot .env (sanitize bot token before sharing!)
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
```
|
||||
|
||||
3. **Contact support** with the collected diagnostic information.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
### Service Management
|
||||
```powershell
|
||||
# Check status
|
||||
Get-Service ROA2WEB-TelegramBot
|
||||
|
||||
# Start
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Start-TelegramBot.ps1
|
||||
|
||||
# Stop
|
||||
.\Stop-TelegramBot.ps1
|
||||
|
||||
# Restart
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```powershell
|
||||
# Watch logs in real-time
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Wait -Tail 50
|
||||
|
||||
# Check health
|
||||
Invoke-WebRequest http://localhost:8002/internal/health
|
||||
|
||||
# Check database stats
|
||||
Invoke-WebRequest http://localhost:8002/internal/stats
|
||||
```
|
||||
|
||||
### Configuration
|
||||
```powershell
|
||||
# Edit backend config
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Edit telegram bot config
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# Restart after changes
|
||||
Restart-Service ROA2WEB-Backend
|
||||
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
|
||||
.\Restart-TelegramBot.ps1
|
||||
```
|
||||
@@ -1,623 +0,0 @@
|
||||
# ROA2WEB - Complete Deployment Workflow (Ultrathin Monolith)
|
||||
|
||||
**Last Updated:** 2025-12-29
|
||||
**Architecture:** Ultrathin Monolith (Single Backend Service)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Overview
|
||||
|
||||
ROA2WEB uses an **automated deployment pipeline** that transfers code from your development machine to the Windows Server and deploys automatically.
|
||||
|
||||
### Architecture Summary
|
||||
|
||||
**Before (Microservices - OBSOLETE):**
|
||||
- 3 separate Windows services (ports 8000, 8002, 8003)
|
||||
- Complex deployment with multiple scripts
|
||||
|
||||
**After (Ultrathin Monolith - CURRENT):**
|
||||
- ✅ **1 Windows service:** `ROA2WEB-Backend` (port 8000)
|
||||
- ✅ **1 unified backend:** All modules (Reports, Data Entry, Telegram)
|
||||
- ✅ **Module control:** Enable/disable via `.env` flags
|
||||
- ✅ **Simplified deployment:** Single service management
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Complete Deployment Workflow
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ STEP 1: BUILD & TRANSFER (Dev Machine) │
|
||||
├──────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Developer runs: │
|
||||
│ .\Publish-And-Deploy.ps1 │
|
||||
│ │ │
|
||||
│ ├──> Calls Build-ROA2WEB.ps1 │
|
||||
│ │ ├── npm run build (Vue.js frontend) │
|
||||
│ │ ├── Copy backend/ (Python FastAPI) │
|
||||
│ │ ├── Copy shared/ (shared modules) │
|
||||
│ │ └── Create ../deploy-package/ │
|
||||
│ │ │
|
||||
│ └──> Transfer to server │
|
||||
│ ├── Try: Windows Share (\\10.0.20.36\Temp) │
|
||||
│ └── Fallback: SSH/SCP (port 22122) │
|
||||
│ │
|
||||
│ Result: deploy-YYYYMMDD-HHmmss/ on server at C:\Temp\ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Package on server
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ STEP 2: AUTO-DETECTION (Windows Server - Scheduled Task) │
|
||||
├──────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Check-And-Deploy.ps1 (runs every 5 minutes) │
|
||||
│ │ │
|
||||
│ ├──> Scan C:\Temp for deploy-* folders │
|
||||
│ ├──> Compare with last deployed (in state file) │
|
||||
│ └──> If NEW package found: │
|
||||
│ Call ROA2WEB-Console.ps1 -Action DeployAll │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ New package detected
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ STEP 3: DEPLOYMENT EXECUTION (ROA2WEB-Console.ps1) │
|
||||
├──────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. STOP SERVICE │
|
||||
│ └─> Stop-Service ROA2WEB-Backend │
|
||||
│ │
|
||||
│ 2. BACKUP │
|
||||
│ ├─> Backup backend/ → backups/backup-All-TIMESTAMP/ │
|
||||
│ ├─> Backup shared/ │
|
||||
│ └─> Backup frontend/ │
|
||||
│ │
|
||||
│ 3. DEPLOY BACKEND │
|
||||
│ ├─> Copy backend/ files │
|
||||
│ ├─> Copy shared/ files │
|
||||
│ └─> Preserve .env file (MODULE flags!) │
|
||||
│ │
|
||||
│ 4. DEPLOY FRONTEND │
|
||||
│ ├─> Copy frontend/ to IIS path │
|
||||
│ └─> Copy web.config │
|
||||
│ │
|
||||
│ 5. START SERVICE │
|
||||
│ ├─> Start-Service ROA2WEB-Backend │
|
||||
│ ├─> Wait for initialization (5 sec) │
|
||||
│ └─> Test health endpoint (http://localhost:8000/health) │
|
||||
│ │
|
||||
│ 6. VERIFY │
|
||||
│ └─> Check service status + module health │
|
||||
│ │
|
||||
└──────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
│ Deployment complete
|
||||
▼
|
||||
✅ PRODUCTION RUNNING
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Script Descriptions
|
||||
|
||||
### Development Machine Scripts
|
||||
|
||||
#### **1. Build-ROA2WEB.ps1**
|
||||
**Purpose:** Create deployment package locally
|
||||
|
||||
**Usage:**
|
||||
```powershell
|
||||
# Interactive menu
|
||||
.\Build-ROA2WEB.ps1
|
||||
|
||||
# Non-interactive
|
||||
.\Build-ROA2WEB.ps1 -Component All -OutputPath "D:\deploy-pkg"
|
||||
```
|
||||
|
||||
**Components:**
|
||||
- `All` - Backend + Frontend (recommended)
|
||||
- `Frontend` - Frontend + Backend (same as All for monolith)
|
||||
- `Backend` - Backend only (includes all modules)
|
||||
|
||||
**Output:** `../deploy-package/` with:
|
||||
```
|
||||
deploy-package/
|
||||
├── backend/ # Unified backend (Reports, Data Entry, Telegram)
|
||||
├── frontend/ # Unified Vue.js SPA
|
||||
├── shared/ # Shared Python modules
|
||||
├── config/ # web.config, .env.example
|
||||
├── scripts/ # Deployment scripts
|
||||
└── README.txt # Deployment instructions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **2. Publish-And-Deploy.ps1**
|
||||
**Purpose:** Build + Transfer to server
|
||||
|
||||
**Usage:**
|
||||
```powershell
|
||||
# Interactive menu (recommended)
|
||||
.\Publish-And-Deploy.ps1
|
||||
|
||||
# Non-interactive (for CI/CD)
|
||||
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component All
|
||||
|
||||
# Force specific transfer method
|
||||
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component All -TransferMethod SSH
|
||||
```
|
||||
|
||||
**Transfer Methods:**
|
||||
- **Auto** (default) - Try Windows Share, fallback to SSH
|
||||
- **WindowsShare** - Fast LAN transfer (`\\10.0.20.36\Temp`)
|
||||
- **SSH** - Secure remote transfer (port 22122)
|
||||
|
||||
**What it does:**
|
||||
1. Calls `Build-ROA2WEB.ps1` internally
|
||||
2. Transfers package to server `C:\Temp\deploy-YYYYMMDD-HHmmss\`
|
||||
3. Server auto-deploys within 5 minutes
|
||||
|
||||
---
|
||||
|
||||
### Server-Side Scripts
|
||||
|
||||
#### **3. Check-And-Deploy.ps1** ⏰
|
||||
**Purpose:** Auto-deploy monitor (scheduled task)
|
||||
|
||||
**Scheduled Task:** Runs every 5 minutes automatically
|
||||
|
||||
**Manual Usage:**
|
||||
```powershell
|
||||
# Interactive mode
|
||||
.\Check-And-Deploy.ps1 -Interactive
|
||||
|
||||
# Check only (no deploy)
|
||||
.\Check-And-Deploy.ps1 -CheckOnly
|
||||
|
||||
# Non-interactive (as scheduled task)
|
||||
.\Check-And-Deploy.ps1
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
1. Scans `C:\Temp` for `deploy-*` folders
|
||||
2. Checks state file: `C:\Temp\ROA2WEB-Scripts\last-deploy.json`
|
||||
3. If NEW package found → calls `ROA2WEB-Console.ps1 -Action DeployAll`
|
||||
4. Saves deployment history
|
||||
|
||||
**State File Location:** `C:\Temp\ROA2WEB-Scripts\last-deploy.json`
|
||||
**Log File:** `C:\Temp\ROA2WEB-Scripts\Logs\check-and-deploy.log`
|
||||
|
||||
---
|
||||
|
||||
#### **4. ROA2WEB-Console.ps1** ⚙️
|
||||
**Purpose:** Unified management console for monolith
|
||||
|
||||
**Interactive Mode:**
|
||||
```powershell
|
||||
.\ROA2WEB-Console.ps1
|
||||
|
||||
# Menu options:
|
||||
[1] Deploy Backend
|
||||
[2] Deploy Frontend
|
||||
[3] Deploy All (Backend + Frontend)
|
||||
[4] Start Service
|
||||
[5] Stop Service
|
||||
[6] Restart Service
|
||||
[7] View Status
|
||||
[8] View Logs
|
||||
[Q] Quit
|
||||
```
|
||||
|
||||
**Non-Interactive Mode:**
|
||||
```powershell
|
||||
# Deploy all
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll -PackagePath "C:\Temp\deploy-20250129-120000"
|
||||
|
||||
# Deploy backend only
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployBackend -PackagePath "C:\Temp\deploy-20250129-120000"
|
||||
|
||||
# Service management
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartService
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action ViewLogs
|
||||
```
|
||||
|
||||
**Actions:**
|
||||
- `DeployBackend` - Deploy backend + shared (stops/starts service)
|
||||
- `DeployFrontend` - Deploy frontend to IIS
|
||||
- `DeployAll` - Full deployment (backend + frontend)
|
||||
- `StartService` - Start ROA2WEB-Backend
|
||||
- `StopService` - Stop ROA2WEB-Backend
|
||||
- `RestartService` - Restart ROA2WEB-Backend
|
||||
- `Status` - Show service status + health check
|
||||
- `ViewLogs` - Display recent logs
|
||||
|
||||
**Service Configuration:**
|
||||
- Service Name: `ROA2WEB-Backend`
|
||||
- Port: `8000`
|
||||
- Health Check: `http://localhost:8000/health`
|
||||
|
||||
**Paths:**
|
||||
- Install Root: `C:\inetpub\wwwroot\roa2web\`
|
||||
- Backend: `C:\inetpub\wwwroot\roa2web\backend\`
|
||||
- Frontend: `C:\inetpub\wwwroot\roa2web\frontend\`
|
||||
- Shared: `C:\inetpub\wwwroot\roa2web\shared\`
|
||||
- Logs: `C:\inetpub\wwwroot\roa2web\logs\`
|
||||
- Backups: `C:\inetpub\wwwroot\roa2web\backups\`
|
||||
|
||||
---
|
||||
|
||||
#### **5. Setup-AutoDeploy.ps1** 🔧
|
||||
**Purpose:** Configure scheduled task for auto-deployment
|
||||
|
||||
**Usage (run once on server):**
|
||||
```powershell
|
||||
.\Setup-AutoDeploy.ps1
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Creates scheduled task: `ROA2WEB-AutoDeploy`
|
||||
- Runs `Check-And-Deploy.ps1` every 5 minutes
|
||||
- Runs as SYSTEM account with highest privileges
|
||||
|
||||
**To verify:**
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ROA2WEB-AutoDeploy"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### **6. Install-ROA2WEB.ps1** 🆕
|
||||
**Purpose:** First-time installation (creates Windows service)
|
||||
|
||||
**Usage (run once during initial setup):**
|
||||
```powershell
|
||||
.\Install-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Creates `ROA2WEB-Backend` Windows service (NSSM)
|
||||
- Configures Python virtual environment
|
||||
- Sets up IIS application
|
||||
- Creates necessary directories
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Common Scenarios
|
||||
|
||||
### Scenario 1: Normal Development Workflow
|
||||
|
||||
**On Dev Machine:**
|
||||
```powershell
|
||||
# Make your code changes, then:
|
||||
.\Publish-And-Deploy.ps1
|
||||
# Select [1] All Components
|
||||
# Select [1] Auto-detect transfer method
|
||||
```
|
||||
|
||||
**On Server:**
|
||||
- Wait 5 minutes (auto-deploy via scheduled task)
|
||||
- OR manually: `.\Check-And-Deploy.ps1 -Interactive` → `[2] Check and Deploy Now`
|
||||
|
||||
**Verify:**
|
||||
- Check health: `http://10.0.20.36:8000/health`
|
||||
- Check logs: `C:\inetpub\wwwroot\roa2web\logs\backend-stdout.log`
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Backend-Only Deployment (Faster)
|
||||
|
||||
**Dev Machine:**
|
||||
```powershell
|
||||
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component Backend
|
||||
```
|
||||
|
||||
**Server (manual):**
|
||||
```powershell
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployBackend -PackagePath "C:\Temp\deploy-YYYYMMDD-HHmmss"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Emergency Rollback
|
||||
|
||||
**Option A: Restore from backup**
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\backups
|
||||
dir # Find latest backup
|
||||
|
||||
Stop-Service ROA2WEB-Backend
|
||||
Copy-Item backup-All-YYYYMMDD-HHmmss\backend\* C:\inetpub\wwwroot\roa2web\backend\ -Recurse -Force
|
||||
Copy-Item backup-All-YYYYMMDD-HHmmss\shared\* C:\inetpub\wwwroot\roa2web\shared\ -Recurse -Force
|
||||
Start-Service ROA2WEB-Backend
|
||||
```
|
||||
|
||||
**Option B: Re-deploy previous package**
|
||||
```powershell
|
||||
cd C:\Temp
|
||||
dir deploy-* # Find previous package
|
||||
|
||||
.\scripts\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll -PackagePath "C:\Temp\deploy-PREVIOUS"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Module Control (Enable/Disable Modules)
|
||||
|
||||
**Edit .env file:**
|
||||
```powershell
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Change flags:
|
||||
MODULE_REPORTS_ENABLED=true # Enable Reports
|
||||
MODULE_DATA_ENTRY_ENABLED=false # Disable Data Entry
|
||||
MODULE_TELEGRAM_ENABLED=true # Enable Telegram
|
||||
```
|
||||
|
||||
**Restart service:**
|
||||
```powershell
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartService
|
||||
```
|
||||
|
||||
**Verify:**
|
||||
```powershell
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
# Shows which modules are enabled/disabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Monitoring & Troubleshooting
|
||||
|
||||
### Check Service Status
|
||||
```powershell
|
||||
# Via Console (recommended)
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
|
||||
# Via Windows Services
|
||||
Get-Service ROA2WEB-Backend
|
||||
|
||||
# Detailed status
|
||||
Get-Service ROA2WEB-Backend | Format-List *
|
||||
```
|
||||
|
||||
### View Logs
|
||||
```powershell
|
||||
# Via Console (recommended - last 30 lines)
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action ViewLogs
|
||||
|
||||
# Manual log access
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stdout.log -Tail 50
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 20
|
||||
```
|
||||
|
||||
### Check Deployment History
|
||||
```powershell
|
||||
# View state file
|
||||
Get-Content C:\Temp\ROA2WEB-Scripts\last-deploy.json | ConvertFrom-Json | Format-List
|
||||
|
||||
# View auto-deploy log
|
||||
Get-Content C:\Temp\ROA2WEB-Scripts\Logs\check-and-deploy.log -Tail 100
|
||||
```
|
||||
|
||||
### Test Health Endpoint
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
Invoke-WebRequest http://localhost:8000/docs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚨 Common Issues
|
||||
|
||||
### Issue 1: Service Won't Start
|
||||
|
||||
**Symptoms:**
|
||||
```powershell
|
||||
Get-Service ROA2WEB-Backend
|
||||
# Status: Stopped
|
||||
```
|
||||
|
||||
**Check:**
|
||||
```powershell
|
||||
# View error logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 30
|
||||
|
||||
# Common causes:
|
||||
# - Port 8000 already in use
|
||||
# - .env file missing/invalid
|
||||
# - Python venv issues
|
||||
# - Oracle connection issues
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```powershell
|
||||
# Check port
|
||||
netstat -ano | findstr :8000
|
||||
|
||||
# Verify .env file
|
||||
Test-Path C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
|
||||
# Restart service
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartService
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 2: Auto-Deploy Not Working
|
||||
|
||||
**Check scheduled task:**
|
||||
```powershell
|
||||
Get-ScheduledTask -TaskName "ROA2WEB-AutoDeploy" | Format-List *
|
||||
Get-ScheduledTaskInfo -TaskName "ROA2WEB-AutoDeploy"
|
||||
```
|
||||
|
||||
**Check logs:**
|
||||
```powershell
|
||||
Get-Content C:\Temp\ROA2WEB-Scripts\Logs\check-and-deploy.log -Tail 50
|
||||
```
|
||||
|
||||
**Manual trigger:**
|
||||
```powershell
|
||||
Start-ScheduledTask -TaskName "ROA2WEB-AutoDeploy"
|
||||
```
|
||||
|
||||
**Re-setup scheduled task:**
|
||||
```powershell
|
||||
.\Setup-AutoDeploy.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Issue 3: Transfer Fails (Publish-And-Deploy)
|
||||
|
||||
**Windows Share not accessible:**
|
||||
```powershell
|
||||
# Test share access
|
||||
Test-Path \\10.0.20.36\Temp
|
||||
|
||||
# If fails, use SSH
|
||||
.\Publish-And-Deploy.ps1 -NonInteractive -Action Build -Component All -TransferMethod SSH
|
||||
```
|
||||
|
||||
**SSH connection fails:**
|
||||
```powershell
|
||||
# Test SSH
|
||||
.\Publish-And-Deploy.ps1 -NonInteractive -Action TestConnections
|
||||
|
||||
# Check SSH key
|
||||
Test-Path ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Deployment Verification Checklist
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
- [ ] **Service Status**
|
||||
```powershell
|
||||
Get-Service ROA2WEB-Backend
|
||||
# Status: Running
|
||||
```
|
||||
|
||||
- [ ] **Health Check**
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8000/health
|
||||
# StatusCode: 200
|
||||
```
|
||||
|
||||
- [ ] **API Docs**
|
||||
```powershell
|
||||
Invoke-WebRequest http://localhost:8000/docs
|
||||
# Should show Swagger UI
|
||||
```
|
||||
|
||||
- [ ] **Module Status**
|
||||
```powershell
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
# Check all enabled modules
|
||||
```
|
||||
|
||||
- [ ] **Frontend Access**
|
||||
- Open browser: `http://10.0.20.36/roa2web`
|
||||
- Verify login page loads
|
||||
|
||||
- [ ] **No Errors in Logs**
|
||||
```powershell
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 10
|
||||
# Should be empty or only INFO/WARNING
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Complete Workflow Diagram
|
||||
|
||||
```
|
||||
DEV MACHINE NETWORK WINDOWS SERVER
|
||||
───────────── ──────── ──────────────
|
||||
|
||||
Code Changes
|
||||
│
|
||||
├─► Build-ROA2WEB.ps1
|
||||
│ │
|
||||
│ ├── npm build
|
||||
│ ├── copy files
|
||||
│ └── ../deploy-package/
|
||||
│
|
||||
├─► Publish-And-Deploy.ps1
|
||||
│ │
|
||||
│ ├── calls Build-ROA2WEB.ps1
|
||||
│ └─► Transfer ───────────────────────► C:\Temp\deploy-*\
|
||||
│
|
||||
│
|
||||
┌─────────▼──────────┐
|
||||
│ Scheduled Task │
|
||||
│ (every 5 minutes) │
|
||||
└────────┬───────────┘
|
||||
│
|
||||
Check-And-Deploy.ps1
|
||||
│
|
||||
├─ Scan C:\Temp
|
||||
├─ Check state
|
||||
└─ If NEW:
|
||||
│
|
||||
ROA2WEB-Console.ps1
|
||||
│
|
||||
┌─────────▼──────────┐
|
||||
│ 1. Stop Service │
|
||||
│ 2. Backup │
|
||||
│ 3. Deploy Backend │
|
||||
│ 4. Deploy Frontend │
|
||||
│ 5. Start Service │
|
||||
│ 6. Health Check │
|
||||
└─────────┬──────────┘
|
||||
│
|
||||
▼
|
||||
✅ DEPLOYMENT COMPLETE
|
||||
|
||||
ROA2WEB-Backend
|
||||
├── Reports Module
|
||||
├── Data Entry Module
|
||||
└── Telegram Module
|
||||
(Port 8000)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- **Main Documentation:** `/deployment/windows/docs/WINDOWS_DEPLOYMENT.md`
|
||||
- **Architecture Guide:** `/CLAUDE.md`
|
||||
- **Troubleshooting:** `/deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md`
|
||||
- **Obsolete Scripts:** `/deployment/windows/scripts/obsolete/` (old microservices setup)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Summary
|
||||
|
||||
**Ultrathin Monolith Benefits:**
|
||||
- ✅ **1 service** instead of 3 (simpler management)
|
||||
- ✅ **Shared resources** (Oracle pool, auth, cache)
|
||||
- ✅ **Faster deployment** (single service restart)
|
||||
- ✅ **Module control** via .env flags (no code changes needed)
|
||||
- ✅ **Automated workflow** (5-minute auto-deploy)
|
||||
- ✅ **Automatic backups** (last 5 kept)
|
||||
- ✅ **Rollback capability** (restore from backup)
|
||||
|
||||
**Key Scripts:**
|
||||
1. `Publish-And-Deploy.ps1` - Dev machine (build + transfer)
|
||||
2. `Check-And-Deploy.ps1` - Server (auto-deploy monitor)
|
||||
3. `ROA2WEB-Console.ps1` - Server (deployment execution + management)
|
||||
|
||||
**Normal Workflow:**
|
||||
1. Make code changes
|
||||
2. Run `Publish-And-Deploy.ps1`
|
||||
3. Wait 5 minutes (auto-deploy)
|
||||
4. Verify deployment
|
||||
|
||||
That's it! 🎉
|
||||
@@ -1,491 +0,0 @@
|
||||
# 🛠️ ROA2WEB Windows Deployment Scripts
|
||||
|
||||
Complete reference for ROA2WEB Windows deployment PowerShell scripts (v2.0 - Unified System).
|
||||
|
||||
## 📋 Script Overview
|
||||
|
||||
### ⭐ Unified Scripts (Recommended)
|
||||
|
||||
#### **Build-ROA2WEB.ps1** - Unified Build System
|
||||
**Purpose**: Build deployment packages for all components with interactive menu
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
# Interactive mode - shows menu
|
||||
.\Build-ROA2WEB.ps1
|
||||
|
||||
# Non-interactive mode - specific component
|
||||
.\Build-ROA2WEB.ps1 -Component All # Complete package
|
||||
.\Build-ROA2WEB.ps1 -Component Frontend # Frontend + Backend
|
||||
.\Build-ROA2WEB.ps1 -Component Backend # Backend only
|
||||
.\Build-ROA2WEB.ps1 -Component TelegramBot # Telegram Bot only
|
||||
|
||||
# Custom output path
|
||||
.\Build-ROA2WEB.ps1 -Component All -OutputPath "D:\builds\roa2web-$(Get-Date -Format 'yyyyMMdd')"
|
||||
```
|
||||
|
||||
**Interactive Menu**:
|
||||
```
|
||||
[1] All Components (Frontend + Backend + Telegram Bot)
|
||||
[2] Frontend + Backend (Vue.js build + FastAPI backend)
|
||||
[3] Backend Only (FastAPI backend + shared modules)
|
||||
[4] Telegram Bot Only (Standalone package)
|
||||
[Q] Quit
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `-Component` All|Frontend|Backend|TelegramBot (optional - shows menu if not specified)
|
||||
- `-OutputPath` (default: `./deploy-package`)
|
||||
- `-Clean` $true|$false (default: $true)
|
||||
|
||||
**Features**:
|
||||
- ✅ Interactive menu for component selection
|
||||
- ✅ Isolated temp directory for frontend builds (doesn't corrupt WSL node_modules)
|
||||
- ✅ Automatic dependency installation (including devDependencies)
|
||||
- ✅ Auto-cleanup after build
|
||||
- ✅ Generates deployment README
|
||||
|
||||
**Output**: Creates `deploy-package/` with complete deployment files
|
||||
|
||||
---
|
||||
|
||||
#### **ROA2WEB-Console.ps1** - Unified Deployment & Management Console
|
||||
**Purpose**: All-in-one console for deploying and managing ROA2WEB services
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
# Interactive mode - shows main menu
|
||||
.\ROA2WEB-Console.ps1
|
||||
|
||||
# Non-interactive mode - specific actions
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployBackend
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployTelegramBot
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action StartAll
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action StopAll
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartAll
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
```
|
||||
|
||||
**Interactive Main Menu**:
|
||||
```
|
||||
[1] Deploy Components
|
||||
- Deploy Backend + Frontend
|
||||
- Deploy Telegram Bot
|
||||
- Deploy All Components
|
||||
|
||||
[2] Manage Services
|
||||
- Start/Stop/Restart All
|
||||
- Start/Stop/Restart Backend
|
||||
- Start/Stop/Restart Telegram Bot
|
||||
|
||||
[3] Check Status
|
||||
- Service status
|
||||
- Health checks
|
||||
|
||||
[Q] Quit
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `-NonInteractive` Switch to enable non-interactive mode
|
||||
- `-Action` DeployBackend|DeployTelegramBot|DeployAll|StartAll|StopAll|RestartAll|Status
|
||||
|
||||
**Features**:
|
||||
- ✅ Unified interface for deploy + management
|
||||
- ✅ Interactive menus with easy navigation
|
||||
- ✅ Automatic backups before deployment
|
||||
- ✅ Smart dependency updates (only if requirements.txt changed)
|
||||
- ✅ Health checks after operations
|
||||
- ✅ Color-coded status output
|
||||
- ✅ Both interactive and non-interactive modes
|
||||
- ✅ Preserves .env configuration files
|
||||
|
||||
**Replaces**:
|
||||
- ❌ `Deploy-ROA2WEB.ps1` (removed)
|
||||
- ❌ `Deploy-TelegramBot.ps1` (removed)
|
||||
- ❌ `Manage-ROA2WEB.ps1` (removed)
|
||||
|
||||
---
|
||||
|
||||
### 🚀 Installation Scripts (First-Time Setup)
|
||||
|
||||
#### **Install-ROA2WEB.ps1**
|
||||
**Purpose**: First-time installation of Backend + Frontend
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
.\Install-ROA2WEB.ps1
|
||||
|
||||
# Custom parameters
|
||||
.\Install-ROA2WEB.ps1 -InstallPath "C:\Apps\roa2web" -ServicePort 8000
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
1. Installs Chocolatey, Python 3.11+, NSSM
|
||||
2. Installs IIS URL Rewrite & ARR modules
|
||||
3. Creates directory structure
|
||||
4. Creates Python virtual environment
|
||||
5. Installs Python dependencies
|
||||
6. Creates Windows Service (ROA2WEB-Backend)
|
||||
7. Configures IIS website & application
|
||||
|
||||
**Parameters**:
|
||||
- `-InstallPath` (default: `C:\inetpub\wwwroot\roa2web`)
|
||||
- `-ServicePort` (default: 8000)
|
||||
- `-IISSiteName`, `-IISAppName`
|
||||
- `-CreateNewSite`, `-SkipPython`, `-SkipIIS`
|
||||
|
||||
---
|
||||
|
||||
#### **Install-TelegramBot.ps1**
|
||||
**Purpose**: First-time installation of Telegram Bot
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
.\Install-TelegramBot.ps1
|
||||
|
||||
# Custom parameters
|
||||
.\Install-TelegramBot.ps1 -InstallPath "C:\Apps\telegram-bot" -ServicePort 8002
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
1. Validates Python 3.11+ installation
|
||||
2. Installs NSSM (if needed)
|
||||
3. Creates directory structure (data/, logs/, backups/)
|
||||
4. Creates Python virtual environment
|
||||
5. Installs Python dependencies
|
||||
6. Creates Windows Service (ROA2WEB-TelegramBot)
|
||||
7. Creates .env template
|
||||
|
||||
**Parameters**:
|
||||
- `-InstallPath` (default: `C:\inetpub\wwwroot\roa2web\telegram-bot`)
|
||||
- `-ServicePort` (default: 8002)
|
||||
- `-SourcePath` (auto-detected)
|
||||
|
||||
---
|
||||
|
||||
### 🛠️ Utility Scripts
|
||||
|
||||
#### **Backup-TelegramDB.ps1**
|
||||
**Purpose**: Backup Telegram bot SQLite database
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
# Basic backup
|
||||
.\Backup-TelegramDB.ps1
|
||||
|
||||
# Compressed backup
|
||||
.\Backup-TelegramDB.ps1 -Compress $true
|
||||
|
||||
# Keep more backups
|
||||
.\Backup-TelegramDB.ps1 -RetentionCount 20
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
1. Stops bot service gracefully
|
||||
2. Creates timestamped backup of `telegram_bot.db`
|
||||
3. Optionally compresses backup
|
||||
4. Restarts service
|
||||
5. Cleans old backups (configurable retention)
|
||||
|
||||
---
|
||||
|
||||
#### **Setup-DailyBackup.ps1**
|
||||
**Purpose**: Schedule automated daily database backups
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
# Setup daily backup at 2 AM
|
||||
.\Setup-DailyBackup.ps1
|
||||
|
||||
# Custom time and retention
|
||||
.\Setup-DailyBackup.ps1 -Time "03:00" -RetentionDays 30
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
1. Creates Windows Scheduled Task
|
||||
2. Runs `Backup-TelegramDB.ps1` daily at specified time
|
||||
3. Configurable time, retention, and compression
|
||||
|
||||
---
|
||||
|
||||
#### **Setup-ClaudeAuth.ps1**
|
||||
**Purpose**: Setup Claude API authentication for Telegram bot
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
.\Setup-ClaudeAuth.ps1
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
1. **Method 1 (Recommended)**: Browser-based Claude Pro/Max login
|
||||
- Runs `claude-code login` if available
|
||||
- Copies credentials to bot installation directory
|
||||
2. **Method 2**: Manual API key entry
|
||||
3. Validates credentials
|
||||
4. Updates .env file
|
||||
5. Restarts bot service
|
||||
|
||||
**Features**:
|
||||
- ✅ Supports both Claude Pro/Max and API key
|
||||
- ✅ Auto-detects credentials location
|
||||
- ✅ Validates authentication before applying
|
||||
|
||||
---
|
||||
|
||||
#### **Enable-HTTPS.ps1**
|
||||
**Purpose**: Enable HTTPS for IIS website
|
||||
|
||||
**Usage**:
|
||||
```powershell
|
||||
# Create self-signed certificate
|
||||
.\Enable-HTTPS.ps1
|
||||
|
||||
# Use existing certificate
|
||||
.\Enable-HTTPS.ps1 -CertPath "C:\Certs\roa2web.pfx" -CertPassword "password"
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
1. Creates/imports SSL certificate
|
||||
2. Configures HTTPS binding (port 443)
|
||||
3. Enables HTTP to HTTPS redirect
|
||||
4. Activates HSTS (HTTP Strict Transport Security)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Reference Guide
|
||||
|
||||
### 📦 First-Time Deployment Workflow
|
||||
|
||||
```powershell
|
||||
# ========================================
|
||||
# STEP 1: Build on Development Machine (WSL/Linux)
|
||||
# ========================================
|
||||
cd deployment/windows/scripts
|
||||
.\Build-ROA2WEB.ps1
|
||||
# Select [1] All Components from menu
|
||||
|
||||
# ========================================
|
||||
# STEP 2: Transfer Package to Windows Server
|
||||
# ========================================
|
||||
# Transfer deploy-package/ to server (e.g., C:\Deploy\roa2web-package)
|
||||
|
||||
# ========================================
|
||||
# STEP 3: Install on Windows Server (as Administrator)
|
||||
# ========================================
|
||||
cd C:\Deploy\roa2web-package\scripts
|
||||
|
||||
# Install Backend + Frontend
|
||||
.\Install-ROA2WEB.ps1
|
||||
|
||||
# Install Telegram Bot
|
||||
.\Install-TelegramBot.ps1
|
||||
|
||||
# ========================================
|
||||
# STEP 4: Configure
|
||||
# ========================================
|
||||
notepad C:\inetpub\wwwroot\roa2web\backend\.env
|
||||
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
|
||||
|
||||
# ========================================
|
||||
# STEP 5: Start Services via Console
|
||||
# ========================================
|
||||
.\ROA2WEB-Console.ps1
|
||||
# Select [2] Manage Services -> [1] Start All Services
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🔄 Deploy Updates Workflow
|
||||
|
||||
```powershell
|
||||
# ========================================
|
||||
# STEP 1: Build New Package on Development Machine
|
||||
# ========================================
|
||||
cd deployment/windows/scripts
|
||||
.\Build-ROA2WEB.ps1
|
||||
# Select component to update from menu
|
||||
|
||||
# ========================================
|
||||
# STEP 2: Transfer to Windows Server
|
||||
# ========================================
|
||||
# Transfer new deploy-package/ to server
|
||||
|
||||
# ========================================
|
||||
# STEP 3: Deploy via Console (as Administrator)
|
||||
# ========================================
|
||||
cd C:\Deploy\new-package\scripts
|
||||
.\ROA2WEB-Console.ps1
|
||||
|
||||
# Option A: Interactive Menu
|
||||
# [1] Deploy Components -> Select what to deploy
|
||||
|
||||
# Option B: Non-Interactive
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 🎛️ Daily Operations via Console
|
||||
|
||||
```powershell
|
||||
# Launch console
|
||||
.\ROA2WEB-Console.ps1
|
||||
|
||||
# Main Menu Navigation:
|
||||
# [1] Deploy Components -> Deploy/update application files
|
||||
# [2] Manage Services -> Start/Stop/Restart services
|
||||
# [3] Check Status -> View service status and health
|
||||
# [Q] Quit
|
||||
|
||||
# Non-Interactive Quick Commands:
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action RestartAll
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 📊 Utility Operations
|
||||
|
||||
```powershell
|
||||
# Backup database
|
||||
.\Backup-TelegramDB.ps1
|
||||
|
||||
# Setup automated daily backups
|
||||
.\Setup-DailyBackup.ps1 -Time "02:00" -RetentionDays 14
|
||||
|
||||
# Configure Claude API
|
||||
.\Setup-ClaudeAuth.ps1
|
||||
|
||||
# Enable HTTPS
|
||||
.\Enable-HTTPS.ps1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Script Comparison: v1.0 vs v2.0
|
||||
|
||||
| Capability | v1.0 (Old) | v2.0 (Unified) |
|
||||
|-----------|-----------|----------------|
|
||||
| **Build Scripts** | 3 separate | 1 unified (`Build-ROA2WEB.ps1`) |
|
||||
| **Deploy Scripts** | 2 separate | 1 unified console (`ROA2WEB-Console.ps1`) |
|
||||
| **Manage Scripts** | 1 basic | Integrated in console |
|
||||
| **Total Scripts** | 13 scripts | 8 scripts |
|
||||
| **Interactive Menus** | ❌ No | ✅ Yes |
|
||||
| **Non-Interactive Mode** | ⚠️ Partial | ✅ Full support |
|
||||
| **Health Checks** | ⚠️ Basic | ✅ Comprehensive |
|
||||
| **Backup Management** | ⚠️ Manual | ✅ Automatic |
|
||||
| **Dependency Updates** | ⚠️ Always reinstall | ✅ Smart (only if changed) |
|
||||
| **WSL Compatibility** | ❌ Corrupts node_modules | ✅ Isolated builds |
|
||||
|
||||
---
|
||||
|
||||
## 🗂️ Complete Script List (v2.0)
|
||||
|
||||
### Core Scripts (2)
|
||||
1. ⭐ **Build-ROA2WEB.ps1** - Unified build system with menu
|
||||
2. ⭐ **ROA2WEB-Console.ps1** - Unified deployment & management console
|
||||
|
||||
### Installation Scripts (2)
|
||||
3. **Install-ROA2WEB.ps1** - First-time Backend + Frontend setup
|
||||
4. **Install-TelegramBot.ps1** - First-time Telegram Bot setup
|
||||
|
||||
### Utility Scripts (4)
|
||||
5. **Backup-TelegramDB.ps1** - Database backup
|
||||
6. **Setup-DailyBackup.ps1** - Automated backup scheduling
|
||||
7. **Setup-ClaudeAuth.ps1** - Claude API configuration
|
||||
8. **Enable-HTTPS.ps1** - HTTPS setup for IIS
|
||||
|
||||
### Removed Scripts (5)
|
||||
- ❌ `Build-Frontend.ps1` → Use `Build-ROA2WEB.ps1 -Component Frontend`
|
||||
- ❌ `Build-TelegramBot.ps1` → Use `Build-ROA2WEB.ps1 -Component TelegramBot`
|
||||
- ❌ `Deploy-ROA2WEB.ps1` → Use `ROA2WEB-Console.ps1` menu option [1] Deploy
|
||||
- ❌ `Deploy-TelegramBot.ps1` → Use `ROA2WEB-Console.ps1` menu option [1] Deploy
|
||||
- ❌ `Manage-ROA2WEB.ps1` → Use `ROA2WEB-Console.ps1` menu option [2] Manage
|
||||
|
||||
---
|
||||
|
||||
## 💡 Best Practices
|
||||
|
||||
### Development Machine (WSL/Linux)
|
||||
```powershell
|
||||
# Always use Build-ROA2WEB.ps1 for building
|
||||
# It isolates npm builds to prevent WSL corruption
|
||||
.\Build-ROA2WEB.ps1
|
||||
```
|
||||
|
||||
### Windows Server
|
||||
```powershell
|
||||
# Use ROA2WEB-Console.ps1 for all operations
|
||||
# Interactive mode for manual operations
|
||||
.\ROA2WEB-Console.ps1
|
||||
|
||||
# Non-interactive mode for automation/scripts
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action DeployAll
|
||||
```
|
||||
|
||||
### Configuration Management
|
||||
- ✅ `.env` files are NEVER overwritten during deployment
|
||||
- ✅ Backups are created automatically before any deployment
|
||||
- ✅ Old backups are auto-cleaned (keeps last 10)
|
||||
- ✅ Dependencies only reinstalled if `requirements.txt` changes
|
||||
|
||||
### Service Management
|
||||
- ✅ Always use ROA2WEB-Console for service operations
|
||||
- ✅ Health checks are automatic after service starts
|
||||
- ✅ Color-coded output makes status clear
|
||||
- ✅ Services can be managed individually or together
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Script Execution Policy Error
|
||||
```powershell
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
### Build Fails on WSL
|
||||
- Ensure Node.js 16+ is installed: `node -v`
|
||||
- Close all IDEs (file locks prevent builds)
|
||||
- Run as Administrator in PowerShell
|
||||
|
||||
### Service Won't Start
|
||||
```powershell
|
||||
# Check status via console
|
||||
.\ROA2WEB-Console.ps1 -NonInteractive -Action Status
|
||||
|
||||
# View backend logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\logs\backend-stderr.log -Tail 50
|
||||
|
||||
# View Telegram bot logs
|
||||
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 50
|
||||
```
|
||||
|
||||
### Deployment Fails
|
||||
```powershell
|
||||
# ROA2WEB-Console.ps1 creates automatic backups
|
||||
# Check backup location if rollback needed
|
||||
Get-ChildItem C:\inetpub\wwwroot\roa2web\backups\ | Sort-Object Name -Descending
|
||||
```
|
||||
|
||||
### Frontend Build Corrupts WSL node_modules
|
||||
- ✅ **Fixed in v2.0!** Build-ROA2WEB.ps1 uses isolated temp directory
|
||||
- The temp directory is automatically cleaned after build
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
- **Quick Start**: [`../README.md`](../README.md)
|
||||
- **Complete Deployment Guide**: [`../docs/WINDOWS_DEPLOYMENT.md`](../docs/WINDOWS_DEPLOYMENT.md)
|
||||
- **Deployment Package Guide**: [`../DEPLOY_PACKAGE.md`](../DEPLOY_PACKAGE.md)
|
||||
- **Telegram Bot Troubleshooting**: [`../docs/TELEGRAM_BOT_TROUBLESHOOTING.md`](../docs/TELEGRAM_BOT_TROUBLESHOOTING.md)
|
||||
- **HTTPS Setup**: [`../docs/HTTPS_SETUP.md`](../docs/HTTPS_SETUP.md)
|
||||
- **Project Documentation**: [`../../../CLAUDE.md`](../../../CLAUDE.md)
|
||||
|
||||
---
|
||||
|
||||
**Version**: 2.0 (Unified System)
|
||||
**Last Updated**: 2025-11-12
|
||||
**Author**: ROA2WEB Team
|
||||
192
docs/DEPLOYMENT.md
Normal file
192
docs/DEPLOYMENT.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
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](../deployment/linux/README.md)
|
||||
|
||||
### Din Windows
|
||||
|
||||
```powershell
|
||||
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/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)
|
||||
|
||||
```bash
|
||||
# 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](./telegram/DEPLOYMENT.md)
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Guides
|
||||
|
||||
| Platform | Guide | Scop |
|
||||
|----------|-------|------|
|
||||
| **Linux/LXC** | [deployment/linux/README.md](../deployment/linux/README.md) | Deploy din container Linux |
|
||||
| **Windows** | [deployment/windows/README.md](../deployment/windows/README.md) | IIS setup, Windows service |
|
||||
| **HTTPS** | [deployment/windows/docs/HTTPS_SETUP.md](../deployment/windows/docs/HTTPS_SETUP.md) | SSL certificate setup |
|
||||
| **2-Tier IIS** | [deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md](../deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md) | Public → Internal architecture |
|
||||
| **Auto-Deploy** | [deployment/windows/docs/DEPLOYMENT_AUTOMATION.md](../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 |
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [ARCHITECTURE-DECISIONS.md](./ARCHITECTURE-DECISIONS.md) - ADR-uri importante
|
||||
- [MONOLITH_ARCHITECTURE.md](./MONOLITH_ARCHITECTURE.md) - Arhitectura detaliată
|
||||
- [telegram/DEPLOYMENT.md](./telegram/DEPLOYMENT.md) - Single worker requirement
|
||||
|
||||
---
|
||||
|
||||
*ROA2WEB - Ultrathin Monolith Architecture*
|
||||
*Last Updated: 2026-01-22*
|
||||
@@ -1,382 +0,0 @@
|
||||
# Data Entry App - Bonuri Fiscale
|
||||
|
||||
Aplicatie pentru introducere bonuri fiscale cu workflow de aprobare si extragere automata date prin OCR.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.10+
|
||||
- Node.js 18+
|
||||
- (Optional) SSH tunnel pentru Oracle nomenclatoare
|
||||
|
||||
### Using Start Script (Recommended)
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
./start-data-entry.sh
|
||||
|
||||
# Or individual commands:
|
||||
./start-data-entry.sh start # Start all
|
||||
./start-data-entry.sh stop # Stop all
|
||||
./start-data-entry.sh status # Check status
|
||||
./start-data-entry.sh restart backend # Restart backend only
|
||||
```
|
||||
|
||||
**Services:**
|
||||
- Backend: http://localhost:8003
|
||||
- Frontend: http://localhost:3010
|
||||
- API Docs: http://localhost:8003/docs
|
||||
|
||||
### Manual Setup
|
||||
|
||||
#### Backend Setup
|
||||
|
||||
```bash
|
||||
cd backend/modules/data_entry/backend
|
||||
|
||||
# Create virtual environment
|
||||
python -m venv venv
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# sau: venv\Scripts\activate # Windows
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Create .env file
|
||||
cp .env.example .env
|
||||
# Edit .env with your settings
|
||||
|
||||
# Run migrations
|
||||
alembic upgrade head
|
||||
|
||||
# Start server
|
||||
uvicorn app.main:app --reload --port 8003
|
||||
```
|
||||
|
||||
#### Frontend Setup
|
||||
|
||||
```bash
|
||||
cd backend/modules/data_entry/frontend
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start dev server
|
||||
npm run dev -- --port 3010
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### Pentru Utilizatori
|
||||
- **OCR Automat** - Extragere automata date din poza bonului (suma, data, furnizor, CUI)
|
||||
- Upload poze bonuri fiscale
|
||||
- Completare date bon (suma, data, furnizor)
|
||||
- Selectie tip cheltuiala
|
||||
- Trimitere spre aprobare
|
||||
|
||||
### Pentru Contabili
|
||||
- Vizualizare bonuri in asteptare
|
||||
- Editare note contabile propuse
|
||||
- Aprobare/Respingere bonuri
|
||||
- Aprobare in masa
|
||||
|
||||
## OCR Feature
|
||||
|
||||
### Cum functioneaza
|
||||
|
||||
1. **Upload imagine** - Trage sau selecteaza poza bonului
|
||||
2. **Procesare OCR** - Click pe "Proceseaza cu OCR"
|
||||
3. **Previzualizare** - Datele extrase sunt afisate cu indicatori de incredere
|
||||
4. **Aplicare** - Click "Aplica datele in formular" pentru auto-fill
|
||||
|
||||
### Campuri extrase automat
|
||||
|
||||
| Camp | Acuratete estimata |
|
||||
|------|-------------------|
|
||||
| Suma (TOTAL) | 90-95% |
|
||||
| Data | 85-90% |
|
||||
| Numar bon | 80-85% |
|
||||
| Furnizor | 70-80% |
|
||||
| CUI | 85-90% |
|
||||
| Tip document | 95%+ |
|
||||
|
||||
### OCR System Dependencies (Linux/Docker)
|
||||
|
||||
Pentru functionarea OCR trebuie instalate:
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
apt-get install -y \
|
||||
tesseract-ocr \
|
||||
tesseract-ocr-ron \
|
||||
tesseract-ocr-eng \
|
||||
poppler-utils \
|
||||
libgl1-mesa-glx \
|
||||
libglib2.0-0
|
||||
|
||||
# Fedora/RHEL
|
||||
dnf install -y \
|
||||
tesseract \
|
||||
tesseract-langpack-ron \
|
||||
tesseract-langpack-eng \
|
||||
poppler-utils
|
||||
```
|
||||
|
||||
**Note:** PaddleOCR (engine principal) se instaleaza automat cu pip. Tesseract este folosit ca fallback.
|
||||
|
||||
### OCR System Dependencies (Windows)
|
||||
|
||||
Pe Windows Server trebuie instalate manual urmatoarele componente:
|
||||
|
||||
#### 1. Poppler (pentru conversie PDF → imagini)
|
||||
|
||||
```powershell
|
||||
# Descarca Poppler pentru Windows
|
||||
# https://github.com/osborn/poppler-windows/releases
|
||||
# sau https://github.com/bblanchon/pdfium-binaries
|
||||
|
||||
# Extrage in C:\Program Files\poppler\
|
||||
# Adauga la PATH: C:\Program Files\poppler\Library\bin
|
||||
```
|
||||
|
||||
#### 2. Tesseract OCR (engine OCR backup)
|
||||
|
||||
```powershell
|
||||
# Descarca installer de la:
|
||||
# https://github.com/UB-Mannheim/tesseract/wiki
|
||||
|
||||
# Instaleaza cu limbile: English + Romanian
|
||||
# Default path: C:\Program Files\Tesseract-OCR\
|
||||
# Adauga la PATH
|
||||
```
|
||||
|
||||
#### 3. Python OCR Dependencies (in venv)
|
||||
|
||||
```powershell
|
||||
cd C:\inetpub\wwwroot\roa2web\data-entry-backend
|
||||
.\venv\Scripts\activate
|
||||
|
||||
# Instaleaza dependentele OCR
|
||||
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
|
||||
|
||||
# Sau din requirements.txt
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
#### 4. Restart serviciu
|
||||
|
||||
```powershell
|
||||
nssm restart ROA2WEB-DataEntry
|
||||
```
|
||||
|
||||
**Note importante Windows:**
|
||||
- Prima rulare PaddleOCR descarca modele (~200MB) - poate dura cateva minute
|
||||
- PaddleOCR necesita ~2GB RAM disponibil
|
||||
- Verifica PATH-ul pentru Poppler si Tesseract dupa instalare
|
||||
- Restart serviciul backend dupa orice modificare PATH
|
||||
|
||||
### OCR API Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | /api/ocr/status | Check OCR service status |
|
||||
| POST | /api/ocr/extract | Extract data from uploaded image |
|
||||
| POST | /api/ocr/extract-attachment/{id} | Re-process existing attachment |
|
||||
|
||||
### Test OCR
|
||||
|
||||
```bash
|
||||
# Check OCR status
|
||||
curl http://localhost:8003/api/ocr/status
|
||||
|
||||
# Extract from image
|
||||
curl -X POST -F "file=@bon.jpg" http://localhost:8003/api/ocr/extract
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
DRAFT → PENDING_REVIEW → APPROVED/REJECTED → (SYNCED in Oracle)
|
||||
```
|
||||
|
||||
1. **DRAFT**: Utilizator completeaza datele (manual sau via OCR)
|
||||
2. **PENDING_REVIEW**: Sistemul genereaza note contabile automat
|
||||
3. **APPROVED**: Contabil a aprobat bonul
|
||||
4. **REJECTED**: Contabil a respins (utilizatorul poate corecta)
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
backend/modules/data_entry/
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI entry point
|
||||
│ │ ├── config.py # Settings
|
||||
│ │ ├── db/
|
||||
│ │ │ ├── database.py # SQLite engine
|
||||
│ │ │ ├── models/ # SQLModel models
|
||||
│ │ │ └── crud/ # CRUD operations
|
||||
│ │ ├── schemas/ # Pydantic schemas
|
||||
│ │ │ └── ocr.py # OCR response schemas
|
||||
│ │ ├── services/
|
||||
│ │ │ ├── receipt_service.py
|
||||
│ │ │ ├── ocr_service.py # OCR orchestration
|
||||
│ │ │ ├── ocr_engine.py # PaddleOCR/Tesseract
|
||||
│ │ │ ├── ocr_extractor.py # Regex patterns RO
|
||||
│ │ │ └── image_preprocessor.py # OpenCV pipeline
|
||||
│ │ └── routers/
|
||||
│ │ ├── receipts.py
|
||||
│ │ └── ocr.py # OCR endpoints
|
||||
│ ├── migrations/ # Alembic migrations
|
||||
│ ├── data/
|
||||
│ │ ├── receipts.db # SQLite database
|
||||
│ │ └── uploads/ # Uploaded files
|
||||
│ └── requirements.txt
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── views/receipts/ # Page components
|
||||
│ │ ├── components/
|
||||
│ │ │ ├── receipts/ # Receipt components
|
||||
│ │ │ └── ocr/ # OCR components
|
||||
│ │ │ ├── OCRUploadZone.vue
|
||||
│ │ │ ├── OCRPreview.vue
|
||||
│ │ │ └── OCRConfidenceIndicator.vue
|
||||
│ │ ├── stores/ # Pinia stores
|
||||
│ │ └── router/ # Vue Router
|
||||
│ ├── package.json
|
||||
│ └── vite.config.js
|
||||
│
|
||||
└── docs/ # Documentation
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Backend (.env)
|
||||
|
||||
```bash
|
||||
# SQLite
|
||||
SQLITE_DATABASE_PATH=data/receipts.db
|
||||
|
||||
# File uploads
|
||||
UPLOAD_PATH=data/uploads
|
||||
MAX_UPLOAD_SIZE_MB=10
|
||||
|
||||
# Oracle (for nomenclatures)
|
||||
ORACLE_USER=CONTAFIN_ORACLE
|
||||
ORACLE_PASSWORD=your_password
|
||||
ORACLE_HOST=localhost
|
||||
ORACLE_PORT=1526
|
||||
ORACLE_SID=ROA
|
||||
|
||||
# JWT (shared with Reports module)
|
||||
JWT_SECRET_KEY=your_secret_key
|
||||
JWT_ALGORITHM=HS256
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Create new migration
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
alembic revision --autogenerate -m "Add new field"
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
### Run tests
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
cd backend && pytest
|
||||
|
||||
# Frontend
|
||||
cd frontend && npm run test
|
||||
```
|
||||
|
||||
## API Documentation
|
||||
|
||||
Full API documentation available at http://localhost:8003/docs when backend is running.
|
||||
|
||||
### Key Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| POST | /api/receipts/ | Create receipt |
|
||||
| GET | /api/receipts/ | List receipts |
|
||||
| GET | /api/receipts/{id} | Get receipt details |
|
||||
| POST | /api/receipts/{id}/submit | Submit for review |
|
||||
| POST | /api/receipts/{id}/approve | Approve receipt |
|
||||
| POST | /api/receipts/{id}/reject | Reject receipt |
|
||||
| POST | /api/receipts/{id}/attachments | Upload attachment |
|
||||
| GET | /api/ocr/status | OCR service status |
|
||||
| POST | /api/ocr/extract | OCR image extraction |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### OCR not working
|
||||
|
||||
1. Check OCR status: `curl http://localhost:8003/api/ocr/status`
|
||||
2. Install system dependencies (tesseract, poppler)
|
||||
3. Verify PaddleOCR installed: `python -c "from paddleocr import PaddleOCR"`
|
||||
|
||||
### OCR Windows - "poppler not in PATH"
|
||||
|
||||
```powershell
|
||||
# Eroare: "Unable to get page count. Is poppler installed and in PATH?"
|
||||
|
||||
# Solutie 1: Adauga Poppler la PATH
|
||||
# System Properties → Environment Variables → System variables → Path → New
|
||||
# Adauga: C:\Program Files\poppler\Library\bin
|
||||
|
||||
# Solutie 2: Restart serviciul dupa modificarea PATH
|
||||
nssm restart ROA2WEB-DataEntry
|
||||
|
||||
# Verificare:
|
||||
pdfinfo --version
|
||||
```
|
||||
|
||||
### OCR Windows - "tesseract not found"
|
||||
|
||||
```powershell
|
||||
# Eroare: "tesseract is not installed or it's not in your PATH"
|
||||
|
||||
# Solutie: Adauga Tesseract la PATH
|
||||
# C:\Program Files\Tesseract-OCR\
|
||||
|
||||
# Verificare:
|
||||
tesseract --version
|
||||
tesseract --list-langs # Trebuie sa arate 'ron' si 'eng'
|
||||
```
|
||||
|
||||
### OCR Windows - PaddleOCR import error
|
||||
|
||||
```powershell
|
||||
# Eroare: "No module named 'paddleocr'"
|
||||
|
||||
cd C:\inetpub\wwwroot\roa2web\data-entry-backend
|
||||
.\venv\Scripts\activate
|
||||
pip install paddlepaddle>=2.5.0
|
||||
pip install paddleocr>=2.7.0
|
||||
|
||||
# Restart serviciu
|
||||
nssm restart ROA2WEB-DataEntry
|
||||
```
|
||||
|
||||
### Low OCR accuracy
|
||||
|
||||
- Ensure good lighting when taking receipt photos
|
||||
- Keep receipt flat (no folds/wrinkles)
|
||||
- Try PDF instead of JPG for scanned documents
|
||||
- Check if text is in focus
|
||||
|
||||
## Phase 2 (Future)
|
||||
|
||||
- Oracle sync for approved receipts
|
||||
- Integration with pack_contafin procedures
|
||||
- Automatic posting to ACT/RUL tables
|
||||
@@ -1,11 +1,7 @@
|
||||
# ROA2WEB Telegram Bot
|
||||
|
||||
> ⚠️ **ARCHITECTURE NOTE**
|
||||
>
|
||||
> This documentation partially references the old standalone bot architecture.
|
||||
> The current architecture is an **ultrathin monolith** where the Telegram bot runs
|
||||
> as a background task within the main backend (`backend/main.py`) on port 8000/8001.
|
||||
> The `INTERNAL_API_PORT` variable is no longer used - internal API is at `/api/telegram/internal/*`.
|
||||
> **Architecture:** Ultrathin Monolith - Telegram bot runs as a background task within the unified backend on port 8000.
|
||||
> See `docs/telegram/DEPLOYMENT.md` for single-worker requirement.
|
||||
|
||||
> **Telegram Frontend for ROA2WEB ERP System** with Direct Command Interface
|
||||
|
||||
@@ -71,78 +67,45 @@ The bot uses a standalone SQLite database for:
|
||||
- **telegram_auth_codes**: Temporary 8-character linking codes (15 min expiry)
|
||||
- **telegram_sessions**: Active company selection and session state
|
||||
|
||||
## Installation & Setup
|
||||
## Setup & Configuration
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- Telegram account
|
||||
- ROA2WEB backend API running (default: http://localhost:8001)
|
||||
- ROA2WEB backend running (the bot runs as part of the unified backend)
|
||||
- Telegram Bot Token (from @BotFather)
|
||||
|
||||
### Step 1: Create Telegram Bot
|
||||
### Step 1: Create Telegram Bot (One-time)
|
||||
|
||||
1. Open Telegram and search for `@BotFather`
|
||||
2. Send `/newbot` command
|
||||
3. Follow prompts to create bot
|
||||
4. Save the bot token provided
|
||||
|
||||
### Step 2: Install Dependencies
|
||||
### Step 2: Configure Environment
|
||||
|
||||
Add to `backend/.env`:
|
||||
|
||||
```bash
|
||||
# Navigate to telegram-bot directory
|
||||
cd backend/modules/telegram
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv venv
|
||||
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate # Linux/Mac
|
||||
# or
|
||||
venv\Scripts\activate # Windows
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Step 3: Configure Environment
|
||||
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env file with your configuration
|
||||
nano .env
|
||||
```
|
||||
|
||||
Required configuration in `.env`:
|
||||
|
||||
```bash
|
||||
# Required
|
||||
# Telegram Bot Configuration
|
||||
MODULE_TELEGRAM_ENABLED=true
|
||||
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
|
||||
BACKEND_URL=http://localhost:8001
|
||||
|
||||
# Database
|
||||
SQLITE_DB_PATH=./data/telegram_bot.db
|
||||
|
||||
# Internal API - DEPRECATED (now served via main backend at /api/telegram/internal/*)
|
||||
# INTERNAL_API_PORT=8002
|
||||
|
||||
# Optional
|
||||
LOG_LEVEL=INFO
|
||||
SENTRY_DSN=https://your-sentry-dsn
|
||||
ENVIRONMENT=production
|
||||
```
|
||||
|
||||
### Step 4: Run the Bot
|
||||
### Step 3: Start the Application
|
||||
|
||||
```bash
|
||||
# Make sure backend is running first
|
||||
# Backend should be at http://localhost:8001 (or configured BACKEND_URL)
|
||||
# From project root - starts backend with Telegram bot integrated
|
||||
./start-prod.sh
|
||||
|
||||
# Run the bot
|
||||
python -m app.main
|
||||
# Or for testing:
|
||||
./start-test.sh
|
||||
```
|
||||
|
||||
The bot starts automatically as a background task when `MODULE_TELEGRAM_ENABLED=true`.
|
||||
|
||||
> **Important:** Backend must run with `--workers 1` for Telegram bot to work correctly.
|
||||
> See `docs/telegram/DEPLOYMENT.md` for details.
|
||||
|
||||
## Usage
|
||||
|
||||
### Available Commands
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,502 +0,0 @@
|
||||
# 🐳 Docker Testing Guide - ROA2WEB Telegram Bot
|
||||
|
||||
> ⚠️ **DEPRECATED ARCHITECTURE**
|
||||
>
|
||||
> This guide references the OLD microservices architecture (separate Telegram container on port 8002).
|
||||
> The current architecture is an **ultrathin monolith** where the Telegram bot runs as a background
|
||||
> task within the main backend (port 8000/8001). No separate Docker container needed for Telegram.
|
||||
|
||||
This guide provides instructions for testing the Telegram bot Docker deployment.
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
Before testing Docker deployment:
|
||||
|
||||
- [ ] Docker Engine installed (version 20.10+)
|
||||
- [ ] Docker Compose installed (version 2.0+)
|
||||
- [ ] At least 2GB RAM available for containers
|
||||
- [ ] At least 10GB disk space available
|
||||
|
||||
## 🔍 Pre-Build Verification
|
||||
|
||||
### 1. Check Dockerfile Syntax
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web/backend/modules/telegram
|
||||
|
||||
# Verify Dockerfile exists and is valid
|
||||
cat Dockerfile
|
||||
|
||||
# Check for common issues
|
||||
grep -n "COPY\|RUN\|ENV" Dockerfile
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Multi-stage build with `builder` and `production` stages
|
||||
- Non-root user `telegrambot` created
|
||||
- All required dependencies installed
|
||||
- Tini init system configured
|
||||
- Health check defined
|
||||
|
||||
### 2. Verify Required Files
|
||||
|
||||
```bash
|
||||
# Check all required files exist
|
||||
ls -la app/
|
||||
ls -la requirements.txt
|
||||
ls -la .env.example
|
||||
ls -la Dockerfile
|
||||
```
|
||||
|
||||
**Required files**:
|
||||
- ✅ `Dockerfile`
|
||||
- ✅ `requirements.txt`
|
||||
- ✅ `.env.example`
|
||||
- ✅ `app/` directory with all modules
|
||||
- ✅ `.dockerignore` (optional but recommended)
|
||||
|
||||
### 3. Check .dockerignore
|
||||
|
||||
```bash
|
||||
cat .dockerignore
|
||||
```
|
||||
|
||||
**Should exclude**:
|
||||
- `venv/`
|
||||
- `__pycache__/`
|
||||
- `*.pyc`
|
||||
- `.env`
|
||||
- `data/*.db`
|
||||
- `.git/`
|
||||
- `tests/`
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Build Tests
|
||||
|
||||
### Test 1: Build Telegram Bot Image
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web/backend/modules/telegram
|
||||
|
||||
# Build the image
|
||||
docker build -t roa2web/telegram-bot:test --target production .
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Build completes without errors
|
||||
- ✅ Both stages (builder + production) execute
|
||||
- ✅ Final image size < 500MB (typically ~300-400MB)
|
||||
- ✅ No security warnings in output
|
||||
|
||||
**Troubleshooting**:
|
||||
- If build fails at requirements install → check `requirements.txt` syntax
|
||||
- If permission errors → ensure Dockerfile uses correct user
|
||||
- If large image size → verify multi-stage build is working
|
||||
|
||||
### Test 2: Inspect Built Image
|
||||
|
||||
```bash
|
||||
# Check image size
|
||||
docker images roa2web/telegram-bot:test
|
||||
|
||||
# Inspect image details
|
||||
docker inspect roa2web/telegram-bot:test
|
||||
|
||||
# Check layers
|
||||
docker history roa2web/telegram-bot:test
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- Image size: 300-450 MB
|
||||
- Base: `python:3.11-slim`
|
||||
- User: `telegrambot` (not root)
|
||||
- Working dir: `/app`
|
||||
- Health check configured
|
||||
|
||||
### Test 3: Build with Docker Compose
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web
|
||||
|
||||
# Build telegram-bot service
|
||||
docker-compose build roa-telegram-bot
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Service builds successfully
|
||||
- ✅ Image tagged as `roa2web/telegram-bot:latest`
|
||||
- ✅ No errors or warnings
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Runtime Tests
|
||||
|
||||
### Test 4: Run Standalone Container (Without Backend)
|
||||
|
||||
```bash
|
||||
# Create test .env file
|
||||
cat > .env.test <<EOF
|
||||
TELEGRAM_BOT_TOKEN=test_token_here
|
||||
CLAUDE_API_KEY=test_api_key_here
|
||||
BACKEND_URL=http://localhost:8000
|
||||
SQLITE_DB_PATH=/app/data/telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
LOG_LEVEL=DEBUG
|
||||
EOF
|
||||
|
||||
# Run container in test mode
|
||||
docker run --rm \
|
||||
--name telegram-bot-test \
|
||||
--env-file .env.test \
|
||||
-p 8002:8002 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
roa2web/telegram-bot:test
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Container starts without errors
|
||||
- ✅ Logs show "Telegram bot starting..."
|
||||
- ✅ Database initialized at `/app/data/telegram_bot.db`
|
||||
- ✅ Internal API listening on port 8002
|
||||
- ⚠️ May fail to connect to Telegram API (expected without valid token)
|
||||
|
||||
**Verify**:
|
||||
```bash
|
||||
# In another terminal:
|
||||
# Check container is running
|
||||
docker ps | grep telegram-bot-test
|
||||
|
||||
# Check logs
|
||||
docker logs telegram-bot-test
|
||||
|
||||
# Test internal API health endpoint
|
||||
curl http://localhost:8002/internal/health
|
||||
```
|
||||
|
||||
### Test 5: Run with Docker Compose (Full Stack)
|
||||
|
||||
```bash
|
||||
cd /path/to/roa2web
|
||||
|
||||
# Ensure .env file exists with all required variables
|
||||
cp .env.example .env
|
||||
# Edit .env and add:
|
||||
# - TELEGRAM_BOT_TOKEN
|
||||
# - CLAUDE_API_KEY
|
||||
# - ORACLE credentials
|
||||
# - JWT secret
|
||||
|
||||
# Start just the telegram-bot service (depends on backend)
|
||||
docker-compose up roa-telegram-bot
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Dependencies start first: `roa-redis`, `roa-ssh-tunnel`, `roa-backend`
|
||||
- ✅ Backend health check passes
|
||||
- ✅ Telegram bot starts and connects to backend
|
||||
- ✅ SQLite database persists in `telegram-bot-data` volume
|
||||
|
||||
**Troubleshooting**:
|
||||
```bash
|
||||
# Check service status
|
||||
docker-compose ps
|
||||
|
||||
# View logs
|
||||
docker-compose logs roa-telegram-bot
|
||||
docker-compose logs roa-backend
|
||||
|
||||
# Check networks
|
||||
docker network ls | grep roa-network
|
||||
docker network inspect roa-network
|
||||
```
|
||||
|
||||
### Test 6: Health Check
|
||||
|
||||
```bash
|
||||
# Wait for service to be healthy
|
||||
docker-compose ps roa-telegram-bot
|
||||
|
||||
# Should show: (healthy)
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Health check passes after ~40 seconds (start_period)
|
||||
- ✅ Health check endpoint returns 200 OK
|
||||
- ✅ Service status shows `(healthy)`
|
||||
|
||||
**Manual health check**:
|
||||
```bash
|
||||
# Access container
|
||||
docker exec -it roa-telegram-bot /bin/bash
|
||||
|
||||
# Inside container:
|
||||
python -c "import httpx; import asyncio; asyncio.run(httpx.AsyncClient().get('http://localhost:8002/internal/health'))"
|
||||
|
||||
# Should output: 200 OK
|
||||
```
|
||||
|
||||
### Test 7: Database Persistence
|
||||
|
||||
```bash
|
||||
# Start service
|
||||
docker-compose up -d roa-telegram-bot
|
||||
|
||||
# Check database file exists
|
||||
docker exec roa-telegram-bot ls -la /app/data/
|
||||
|
||||
# Expected: telegram_bot.db file
|
||||
|
||||
# Stop and remove container
|
||||
docker-compose down
|
||||
|
||||
# Start again
|
||||
docker-compose up -d roa-telegram-bot
|
||||
|
||||
# Verify data persisted
|
||||
docker exec roa-telegram-bot sqlite3 /app/data/telegram_bot.db "SELECT COUNT(*) FROM telegram_users;"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Database file persists across container restarts
|
||||
- ✅ Data remains intact in `telegram-bot-data` volume
|
||||
- ✅ No data loss
|
||||
|
||||
### Test 8: Environment Variables
|
||||
|
||||
```bash
|
||||
# Check environment variables are set
|
||||
docker exec roa-telegram-bot env | grep -E "TELEGRAM|CLAUDE|BACKEND|SQLITE"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```
|
||||
TELEGRAM_BOT_TOKEN=<your_token>
|
||||
CLAUDE_API_KEY=<your_key>
|
||||
BACKEND_URL=http://roa-backend:8000
|
||||
SQLITE_DB_PATH=/app/data/telegram_bot.db
|
||||
INTERNAL_API_PORT=8002
|
||||
```
|
||||
|
||||
### Test 9: Network Connectivity
|
||||
|
||||
```bash
|
||||
# Test bot can reach backend
|
||||
docker exec roa-telegram-bot curl -v http://roa-backend:8000/health
|
||||
|
||||
# Test backend can reach bot internal API
|
||||
docker exec roa-backend curl -v http://roa-telegram-bot:8002/internal/health
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Both services can communicate via `roa-network`
|
||||
- ✅ DNS resolution works (service names resolve)
|
||||
- ✅ Health endpoints return 200 OK
|
||||
|
||||
### Test 10: Logs and Monitoring
|
||||
|
||||
```bash
|
||||
# View real-time logs
|
||||
docker-compose logs -f roa-telegram-bot
|
||||
|
||||
# View last 100 lines
|
||||
docker-compose logs --tail=100 roa-telegram-bot
|
||||
|
||||
# Search for errors
|
||||
docker-compose logs roa-telegram-bot | grep -i error
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Logs are readable and structured
|
||||
- ✅ No critical errors
|
||||
- ✅ Log level respects `LOG_LEVEL` env var
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Tests
|
||||
|
||||
### Test 11: User Permissions
|
||||
|
||||
```bash
|
||||
# Check container is not running as root
|
||||
docker exec roa-telegram-bot whoami
|
||||
# Expected: telegrambot
|
||||
|
||||
# Check file permissions
|
||||
docker exec roa-telegram-bot ls -la /app/
|
||||
# Expected: All files owned by telegrambot:telegrambot
|
||||
```
|
||||
|
||||
### Test 12: Port Exposure
|
||||
|
||||
```bash
|
||||
# Check exposed ports
|
||||
docker port roa-telegram-bot
|
||||
|
||||
# Should only show:
|
||||
# 8002/tcp -> 0.0.0.0:8002
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Only internal API port (8002) exposed
|
||||
- ✅ No unnecessary ports open
|
||||
|
||||
### Test 13: Volume Mounts
|
||||
|
||||
```bash
|
||||
# Check volumes
|
||||
docker volume inspect roa2web_telegram-bot-data
|
||||
|
||||
# Check mount point
|
||||
docker inspect roa-telegram-bot | grep -A 10 Mounts
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
- ✅ Only `/app/data` is mounted
|
||||
- ✅ Volume is named `telegram-bot-data`
|
||||
- ✅ No sensitive files mounted
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Integration Tests
|
||||
|
||||
### Test 14: Full Stack Integration
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
cd /path/to/roa2web
|
||||
docker-compose up -d
|
||||
|
||||
# Wait for all services to be healthy
|
||||
docker-compose ps
|
||||
|
||||
# Test complete flow:
|
||||
# 1. Backend generates auth code
|
||||
# 2. Bot verifies code
|
||||
# 3. User links account
|
||||
# 4. Bot queries backend API
|
||||
```
|
||||
|
||||
**Test Steps**:
|
||||
|
||||
1. **Generate Auth Code via Backend**:
|
||||
```bash
|
||||
curl -X POST http://localhost:8000/api/telegram/auth/generate-code \
|
||||
-H "Authorization: Bearer <jwt_token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"telegram_user_id": 123456}'
|
||||
```
|
||||
|
||||
2. **Verify Code in Bot Database**:
|
||||
```bash
|
||||
docker exec roa-telegram-bot sqlite3 /app/data/telegram_bot.db \
|
||||
"SELECT * FROM telegram_auth_codes WHERE telegram_user_id = 123456;"
|
||||
```
|
||||
|
||||
3. **Link via Telegram Bot**:
|
||||
- Send code to bot via Telegram app
|
||||
- Verify linking succeeds
|
||||
|
||||
4. **Query Dashboard**:
|
||||
- Ask bot: "Show dashboard for company 1"
|
||||
- Verify data is retrieved from backend
|
||||
|
||||
---
|
||||
|
||||
## 🛑 Cleanup
|
||||
|
||||
### Remove Test Containers
|
||||
|
||||
```bash
|
||||
# Stop and remove containers
|
||||
docker-compose down
|
||||
|
||||
# Remove volumes (WARNING: deletes data)
|
||||
docker-compose down -v
|
||||
|
||||
# Remove images
|
||||
docker rmi roa2web/telegram-bot:test
|
||||
docker rmi roa2web/telegram-bot:latest
|
||||
```
|
||||
|
||||
### Clean Build Cache
|
||||
|
||||
```bash
|
||||
# Remove build cache
|
||||
docker builder prune -a
|
||||
|
||||
# Remove unused images
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Results Checklist
|
||||
|
||||
| Test ID | Description | Status | Notes |
|
||||
|---------|-------------|--------|-------|
|
||||
| 1 | Build telegram-bot image | ⬜ | |
|
||||
| 2 | Inspect image | ⬜ | |
|
||||
| 3 | Build with docker-compose | ⬜ | |
|
||||
| 4 | Run standalone container | ⬜ | |
|
||||
| 5 | Run with docker-compose | ⬜ | |
|
||||
| 6 | Health check | ⬜ | |
|
||||
| 7 | Database persistence | ⬜ | |
|
||||
| 8 | Environment variables | ⬜ | |
|
||||
| 9 | Network connectivity | ⬜ | |
|
||||
| 10 | Logs and monitoring | ⬜ | |
|
||||
| 11 | User permissions | ⬜ | |
|
||||
| 12 | Port exposure | ⬜ | |
|
||||
| 13 | Volume mounts | ⬜ | |
|
||||
| 14 | Full stack integration | ⬜ | |
|
||||
|
||||
**Overall Result**: ⬜ PASS ⬜ FAIL
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Common Issues & Solutions
|
||||
|
||||
### Issue 1: Build Fails - "requirements.txt not found"
|
||||
**Solution**: Ensure you're in the correct directory (`telegram-bot/`) when building
|
||||
|
||||
### Issue 2: Permission Denied Errors
|
||||
**Solution**: Check Dockerfile uses correct user and permissions are set with `chown`
|
||||
|
||||
### Issue 3: Health Check Fails
|
||||
**Solution**:
|
||||
- Check internal API is starting on port 8002
|
||||
- Verify httpx is installed in requirements.txt
|
||||
- Check logs: `docker logs roa-telegram-bot`
|
||||
|
||||
### Issue 4: Can't Connect to Backend
|
||||
**Solution**:
|
||||
- Ensure both containers are on `roa-network`
|
||||
- Check backend is healthy before starting bot
|
||||
- Use service name `roa-backend` not `localhost`
|
||||
|
||||
### Issue 5: Database Not Persisting
|
||||
**Solution**:
|
||||
- Verify volume is mounted: `docker inspect roa-telegram-bot`
|
||||
- Check volume exists: `docker volume ls | grep telegram-bot-data`
|
||||
- Ensure `/app/data` has write permissions
|
||||
|
||||
---
|
||||
|
||||
## ✅ Success Criteria
|
||||
|
||||
For Docker deployment to be considered successful:
|
||||
|
||||
- ✅ Image builds without errors
|
||||
- ✅ Container starts and runs stably
|
||||
- ✅ Health checks pass
|
||||
- ✅ Bot connects to Telegram API
|
||||
- ✅ Bot connects to backend API
|
||||
- ✅ Database persists across restarts
|
||||
- ✅ No security warnings or vulnerabilities
|
||||
- ✅ Logs are clean (no critical errors)
|
||||
- ✅ All network connectivity works
|
||||
- ✅ Full stack integration succeeds
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-21
|
||||
@@ -6,29 +6,32 @@ This checklist guides you through manual testing of the Telegram bot functionali
|
||||
|
||||
Before starting manual tests:
|
||||
|
||||
- [ ] Backend API is running (`http://localhost:8001`)
|
||||
- [ ] SSH tunnel to Oracle DB is active
|
||||
- [ ] Telegram bot is running (`python -m app.main`)
|
||||
- [ ] TELEGRAM_BOT_TOKEN is configured in `.env`
|
||||
- [ ] CLAUDE_API_KEY is configured in `.env` (if using real Claude SDK)
|
||||
- [ ] SQLite database is initialized (`data/telegram_bot.db` exists)
|
||||
- [ ] Backend API is running (`http://localhost:8000` or `8001`)
|
||||
- [ ] SSH tunnel to Oracle DB is active (Linux dev only)
|
||||
- [ ] `MODULE_TELEGRAM_ENABLED=true` in `.env`
|
||||
- [ ] `TELEGRAM_BOT_TOKEN` is configured in `.env`
|
||||
- [ ] SQLite database is initialized (auto-created on first run)
|
||||
|
||||
> **Note:** In the **ultrathin monolith** architecture, the Telegram bot runs as a background task
|
||||
> within the unified backend. There's no separate bot process to start.
|
||||
|
||||
## 📱 Test Environment Setup
|
||||
|
||||
### Start Services
|
||||
|
||||
```bash
|
||||
# Terminal 1: Start backend API (from roa2web/)
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --port 8001
|
||||
# From project root - starts everything (SSH tunnel + backend + frontend)
|
||||
./start-prod.sh
|
||||
|
||||
# Terminal 2: Start Telegram bot
|
||||
cd backend/modules/telegram
|
||||
source venv/bin/activate
|
||||
python -m app.main
|
||||
# Or for testing mode:
|
||||
./start-test.sh
|
||||
|
||||
# Check status
|
||||
./status.sh
|
||||
```
|
||||
|
||||
The bot starts automatically with the backend when `MODULE_TELEGRAM_ENABLED=true`.
|
||||
|
||||
### Test User Setup
|
||||
|
||||
- [ ] Create test Oracle user account in Oracle database (if needed)
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
ROA2WEB - IIS Sub-Application Configuration
|
||||
====================================================================
|
||||
|
||||
⚠️ CRITICAL - For IIS Sub-Application Deployment! ⚠️
|
||||
CRITICAL - For IIS Sub-Application Deployment!
|
||||
|
||||
This web.config is for when IIS is configured as SUB-APPLICATION:
|
||||
- IIS Application Path: /roa2web
|
||||
@@ -19,11 +19,11 @@
|
||||
**Production Architecture (2-Tier IIS)**:
|
||||
|
||||
Public Server (10.0.20.122 - roa2web.romfast.ro)
|
||||
└─ Proxies ALL to → https://10.0.20.36/{REQUEST_PATH}
|
||||
- Proxies ALL to -> https://10.0.20.36/{REQUEST_PATH}
|
||||
|
||||
Internal Server (10.0.20.36)
|
||||
└─ IIS Sub-App: /roa2web → Physical: C:\inetpub\wwwroot\roa2web\frontend
|
||||
└─ This web.config proxies /api/* to localhost:8000
|
||||
- IIS Sub-App: /roa2web -> Physical: C:\inetpub\wwwroot\roa2web\frontend
|
||||
- This web.config proxies /api/* to localhost:8000
|
||||
|
||||
See: deployment/windows/docs/TWO-TIER-IIS-DEPLOYMENT.md
|
||||
|
||||
@@ -56,6 +56,30 @@
|
||||
<action type="Rewrite" url="index.html" />
|
||||
</rule>
|
||||
</rules>
|
||||
|
||||
<!-- Outbound rules to set Cache-Control based on request path -->
|
||||
<outboundRules>
|
||||
<!-- API responses: NO caching (let backend cache handle it) -->
|
||||
<rule name="No Cache for API" preCondition="IsAPIRequest">
|
||||
<match serverVariable="RESPONSE_Cache-Control" pattern=".*" />
|
||||
<action type="Rewrite" value="no-store, no-cache, must-revalidate, proxy-revalidate" />
|
||||
</rule>
|
||||
|
||||
<!-- Static assets: cache for 1 year -->
|
||||
<rule name="Cache Static Assets" preCondition="IsStaticAsset">
|
||||
<match serverVariable="RESPONSE_Cache-Control" pattern=".*" />
|
||||
<action type="Rewrite" value="public, max-age=31536000" />
|
||||
</rule>
|
||||
|
||||
<preConditions>
|
||||
<preCondition name="IsAPIRequest">
|
||||
<add input="{URL}" pattern="^/api/" />
|
||||
</preCondition>
|
||||
<preCondition name="IsStaticAsset">
|
||||
<add input="{URL}" pattern="\.(js|css|png|jpg|jpeg|gif|svg|woff|woff2|ttf|ico|webmanifest)$" />
|
||||
</preCondition>
|
||||
</preConditions>
|
||||
</outboundRules>
|
||||
</rewrite>
|
||||
|
||||
<!-- Static content configuration -->
|
||||
@@ -68,12 +92,5 @@
|
||||
<remove fileExtension=".json" />
|
||||
<mimeMap fileExtension=".json" mimeType="application/json" />
|
||||
</staticContent>
|
||||
|
||||
<!-- Client cache for static assets (1 year) -->
|
||||
<httpProtocol>
|
||||
<customHeaders>
|
||||
<add name="Cache-Control" value="public, max-age=31536000" />
|
||||
</customHeaders>
|
||||
</httpProtocol>
|
||||
</system.webServer>
|
||||
</configuration>
|
||||
|
||||
|
Before Width: | Height: | Size: 299 KiB After Width: | Height: | Size: 299 KiB |
|
Before Width: | Height: | Size: 323 KiB After Width: | Height: | Size: 323 KiB |
158
tests/ocr-validation/README.md
Normal file
158
tests/ocr-validation/README.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# OCR Validation Tests
|
||||
|
||||
Teste pentru validarea acurateții extragerii OCR din bonuri fiscale.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Backend-ul trebuie să ruleze** pe `http://localhost:8000`
|
||||
2. **Modulul Data Entry activat** în `.env`: `MODULE_DATA_ENTRY_ENABLED=true`
|
||||
3. **JWT_SECRET_KEY** setat (sau folosește default-ul de test)
|
||||
|
||||
```bash
|
||||
# Pornește backend-ul
|
||||
cd /workspace/roa2web
|
||||
./start-prod.sh
|
||||
# sau
|
||||
./start-test.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Files
|
||||
|
||||
| Fișier | Scop |
|
||||
|--------|------|
|
||||
| `expected_receipts.json` | Expected values pentru fiecare bon (ground truth) |
|
||||
| `ocr-direct-validation.py` | Test individual cu comparare detaliată |
|
||||
| `test_receipts_sequential.py` | Rulează toate bonurile secvențial |
|
||||
| `test_receipts_parallel.py` | Rulează toate bonurile în paralel (performance test) |
|
||||
| `test_receipts_parallel_windows.py` | Versiune Windows cu memory tracking |
|
||||
| `get_raw_ocr_text.py` | Debug tool - afișează raw OCR text |
|
||||
|
||||
**Fixtures:** `tests/fixtures/ocr-samples/` - 30 PDF-uri de bonuri fiscale
|
||||
|
||||
---
|
||||
|
||||
## Cum să rulezi testele
|
||||
|
||||
### 1. Test Individual (Recomandat pentru debug)
|
||||
|
||||
```bash
|
||||
cd /workspace/roa2web
|
||||
|
||||
# Test toate bonurile cu engine doctr_plus
|
||||
python tests/ocr-validation/ocr-direct-validation.py
|
||||
|
||||
# Test cu engine specific
|
||||
python tests/ocr-validation/ocr-direct-validation.py --engine doctr_plus
|
||||
python tests/ocr-validation/ocr-direct-validation.py --engine tesseract
|
||||
|
||||
# Test doar un bon specific
|
||||
python tests/ocr-validation/ocr-direct-validation.py --receipt receipt_01
|
||||
|
||||
# Include și bonuri multi-page
|
||||
python tests/ocr-validation/ocr-direct-validation.py --include-multipage
|
||||
```
|
||||
|
||||
### 2. Test Secvențial (Toate bonurile, unul câte unul)
|
||||
|
||||
```bash
|
||||
python tests/ocr-validation/test_receipts_sequential.py
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Processing: abonament kineterra.pdf
|
||||
✓ Total: MATCH (1900.0 = 1900.0)
|
||||
✓ Date: MATCH (2025-11-10)
|
||||
✗ CUI: MISMATCH (expected: 31180432, got: 3118043)
|
||||
```
|
||||
|
||||
### 3. Test Paralel (Performance benchmark)
|
||||
|
||||
```bash
|
||||
python tests/ocr-validation/test_receipts_parallel.py
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
PARALLEL TEST: 26 receipts
|
||||
Phase 1: Submitting all jobs...
|
||||
Submitted 26 jobs in 2.3s
|
||||
Phase 2: Waiting for results...
|
||||
OK: abonament kineterra.pdf 12.3s conf=95%
|
||||
OK: benzina 14 august.pdf 8.7s conf=92%
|
||||
TOTAL TIME: 45.2s
|
||||
```
|
||||
|
||||
### 4. Debug Raw OCR Text
|
||||
|
||||
```bash
|
||||
# Vezi textul raw extras de OCR
|
||||
python tests/ocr-validation/get_raw_ocr_text.py
|
||||
|
||||
# Sau pentru un fișier specific
|
||||
python tests/ocr-validation/get_raw_ocr_text.py tests/fixtures/ocr-samples/benzina\ 14\ august.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Expected Receipts Format
|
||||
|
||||
`expected_receipts.json` conține ground truth pentru fiecare bon:
|
||||
|
||||
```json
|
||||
{
|
||||
"receipts": [
|
||||
{
|
||||
"id": "receipt_01",
|
||||
"filename": "abonament kineterra.pdf",
|
||||
"furnizor": "KINETERRA CONCEPT SRL",
|
||||
"cui_furnizor": "31180432",
|
||||
"total": 1900.0,
|
||||
"tva_details": [],
|
||||
"total_tva": 0.0,
|
||||
"data_bon": "2025-11-10",
|
||||
"notes": "Neplatitor TVA - abonament terapie"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Adaugă bonuri noi pentru testare
|
||||
|
||||
1. Pune PDF-ul în `tests/fixtures/ocr-samples/`
|
||||
2. Adaugă entry în `expected_receipts.json` cu valorile corecte
|
||||
3. Rulează testul:
|
||||
```bash
|
||||
python tests/ocr-validation/ocr-direct-validation.py --receipt receipt_XX
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Connection refused" sau "Failed to connect"
|
||||
- Backend-ul nu rulează. Pornește cu `./start-prod.sh`
|
||||
|
||||
### "401 Unauthorized"
|
||||
- JWT token invalid. Verifică `JWT_SECRET_KEY` în `.env`
|
||||
|
||||
### "File not found"
|
||||
- Verifică că PDF-urile sunt în `tests/fixtures/ocr-samples/`
|
||||
|
||||
### Rezultate incorecte
|
||||
- Folosește `get_raw_ocr_text.py` pentru a vedea ce text extrage OCR
|
||||
- Verifică dacă bonul e lizibil și de calitate bună
|
||||
|
||||
---
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- **doctr_plus** engine: ~8-15 secunde per bon (GPU accelerated)
|
||||
- **tesseract** engine: ~3-5 secunde per bon (CPU only)
|
||||
- Testul paralel poate procesa ~26 bonuri în ~45 secunde (vs ~5 minute secvențial)
|
||||
@@ -113,10 +113,11 @@ if __name__ == "__main__":
|
||||
print(f"Using JWT token for authentication")
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
# Default: process the two receipts user wants to see
|
||||
# Default: process sample receipts from fixtures
|
||||
fixtures_dir = Path(__file__).parent.parent / "fixtures" / "ocr-samples"
|
||||
receipts = [
|
||||
"/mnt/e/proiecte/ab-worktrees/doctr-ocr-metrics/docs/data-entry/brick igiena 1 sept.pdf",
|
||||
"/mnt/e/proiecte/ab-worktrees/doctr-ocr-metrics/docs/data-entry/brick igiena, electrice consumabile 604.pdf"
|
||||
str(fixtures_dir / "brick igiena 1 sept.pdf"),
|
||||
str(fixtures_dir / "brick igiena, electrice consumabile 604.pdf")
|
||||
]
|
||||
else:
|
||||
receipts = sys.argv[1:]
|
||||
|
||||
@@ -193,7 +193,7 @@ def main():
|
||||
# Paths
|
||||
script_dir = Path(__file__).parent
|
||||
expected_path = script_dir / 'expected_receipts.json'
|
||||
pdf_base_path = script_dir.parent.parent / 'docs' / 'data-entry'
|
||||
pdf_base_path = script_dir.parent.parent / 'tests' / 'fixtures' / 'ocr-samples'
|
||||
|
||||
# JWT secret from environment or default
|
||||
jwt_secret = os.getenv('JWT_SECRET_KEY', 'generate_with_secrets_token_urlsafe_32')
|
||||
|
||||
@@ -10,8 +10,13 @@ from datetime import datetime, timedelta
|
||||
from jose import jwt
|
||||
|
||||
API_BASE = "http://localhost:8000"
|
||||
PDF_FOLDER = "/mnt/e/proiecte/ab-worktrees/doctr-ocr-metrics/docs/data-entry"
|
||||
EXPECTED_FILE = "/mnt/e/proiecte/ab-worktrees/doctr-ocr-metrics/tests/ocr-validation/expected_receipts.json"
|
||||
|
||||
# Paths - relative to project root
|
||||
from pathlib import Path
|
||||
SCRIPT_DIR = Path(__file__).parent
|
||||
PROJECT_ROOT = SCRIPT_DIR.parent.parent
|
||||
PDF_FOLDER = str(PROJECT_ROOT / "tests" / "fixtures" / "ocr-samples")
|
||||
EXPECTED_FILE = str(SCRIPT_DIR / "expected_receipts.json")
|
||||
|
||||
def get_jwt_token():
|
||||
secret_key = os.getenv('JWT_SECRET_KEY', 'generate_with_secrets_token_urlsafe_32')
|
||||
|
||||
@@ -27,7 +27,7 @@ except ImportError:
|
||||
# Paths - relative to backend directory
|
||||
SCRIPT_DIR = Path(__file__).parent
|
||||
BACKEND_DIR = SCRIPT_DIR.parent.parent / "backend"
|
||||
PDF_FOLDER = SCRIPT_DIR.parent.parent / "docs" / "data-entry"
|
||||
PDF_FOLDER = SCRIPT_DIR.parent.parent / "tests" / "fixtures" / "ocr-samples"
|
||||
EXPECTED_FILE = SCRIPT_DIR / "expected_receipts.json"
|
||||
|
||||
|
||||
|
||||
@@ -10,8 +10,13 @@ from datetime import datetime, timedelta
|
||||
from jose import jwt
|
||||
|
||||
API_BASE = "http://localhost:8000"
|
||||
PDF_FOLDER = "/mnt/e/proiecte/ab-worktrees/doctr-ocr-metrics/docs/data-entry"
|
||||
EXPECTED_FILE = "/mnt/e/proiecte/ab-worktrees/doctr-ocr-metrics/tests/ocr-validation/expected_receipts.json"
|
||||
|
||||
# Paths - relative to project root
|
||||
from pathlib import Path
|
||||
SCRIPT_DIR = Path(__file__).parent
|
||||
PROJECT_ROOT = SCRIPT_DIR.parent.parent
|
||||
PDF_FOLDER = str(PROJECT_ROOT / "tests" / "fixtures" / "ocr-samples")
|
||||
EXPECTED_FILE = str(SCRIPT_DIR / "expected_receipts.json")
|
||||
|
||||
def get_jwt_token():
|
||||
"""Create a test JWT token for API authentication."""
|
||||
|
||||
Reference in New Issue
Block a user