# 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
```