Add Telegram Bot internal API configuration for Windows deployment

Fix issue where backend cannot communicate with Telegram bot service to save authentication codes during account linking flow. This caused "link invalid or expired" errors when users tried to link Telegram accounts. Changes: - Add TELEGRAM_BOT_INTERNAL_API environment variable to backend .env.example (defaults to http://localhost:8002 for local/Windows deployments) - Update CLAUDE.md with Telegram Bot integration requirements for Windows - Add comprehensive troubleshooting guide for Windows deployment at deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md The troubleshooting guide includes: - Diagnostic steps to verify service health and connectivity - Common issues and solutions (port conflicts, firewall, wrong bot token) - PowerShell commands for Windows Server administration - Verification steps for end-to-end testing This ensures proper backend-to-telegram-bot communication for the auth code linking workflow in production Windows deployments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-27 00:09:37 +02:00
parent b97a650fb4
commit 68459b5c7e
3 changed files with 361 additions and 1 deletions
--- a/deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md
+++ b/deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md
@@ -0,0 +1,342 @@
+# ROA2WEB Telegram Bot - Windows Deployment Troubleshooting Guide
+
+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
+
+### 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
+```
+
+### 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
+```