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

refactor(docs): consolidate and cleanup documentation

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude Agent
2026-01-22 09:14:51 +00:00
parent 1b9ebf1d8f
commit 62f86250cc
55 changed files with 604 additions and 6334 deletions
Download Patch File Download Diff File Expand all files Collapse all files

623
deployment/windows/scripts/README-DEPLOYMENT-WORKFLOW.md
View File

@@ -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! 🎉

491
deployment/windows/scripts/README.md
View File

@@ -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