feat: Migrate to ultrathin monolith architecture
Consolidate 3 separate applications (reports-app, data-entry-app, telegram-bot) into a unified
architecture with single backend and frontend:
Backend Changes:
- Unified FastAPI backend at backend/ with modular structure
- Modules: reports, data_entry, telegram in backend/modules/
- Centralized config.py and main.py with all routers registered
- Single worker mode (--workers 1) for Telegram bot compatibility
- Shared Oracle connection pool and JWT authentication
- Unified requirements.txt and environment configuration
Frontend Changes:
- Single Vue.js SPA with module-based routing
- Unified frontend at src/ with modules in src/modules/{reports,data-entry}/
- Shared components and stores in src/shared/
- Error boundaries for module isolation
- Dual API proxy in Vite for module communication
Infrastructure:
- New unified startup scripts: start-prod.sh, start-test.sh, start-backend.sh
- Environment templates: .env.dev.example, .env.test.example, .env.prod.example
- Updated deployment scripts for Windows IIS
- Simplified SSH tunnel management
Documentation:
- Comprehensive CLAUDE.md with architecture overview
- Module-specific docs in docs/{data-entry,telegram}/
- Architecture decision records in docs/ARCHITECTURE-DECISIONS.md
- Deployment guides consolidated in deployment/windows/docs/
This migration reduces complexity, improves maintainability, and enables easier
deployment while maintaining all existing functionality.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
429
docs/telegram/README.md
Normal file
429
docs/telegram/README.md
Normal file
@@ -0,0 +1,429 @@
|
||||
# ROA2WEB Telegram Bot
|
||||
|
||||
> **Telegram Frontend for ROA2WEB ERP System** with Direct Command Interface
|
||||
|
||||
## Overview
|
||||
|
||||
ROA2WEB Telegram Bot provides a command-based interface to the ROA2WEB Financial ERP system through Telegram. Users can access dashboards, invoices, treasury data, and company information using simple slash commands.
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Direct Command Interface**: Simple `/` commands for all operations
|
||||
- **Simplified Authentication** 🆕: Multiple linking methods (Deep Link, QR Code, Manual) - 77% faster than before!
|
||||
- **One-Click Connection**: Deep link automatically opens Telegram with pre-populated code
|
||||
- **QR Code Support**: Scan from mobile to link instantly (cross-device)
|
||||
- **Secure Authentication**: Account linking with Oracle backend and JWT token management
|
||||
- **Financial Data Access**: Query dashboards, invoices, treasury data, and company information
|
||||
- **Company Selection**: Set active company for all subsequent queries
|
||||
- **Multi-language**: Romanian and English support
|
||||
- **Session Management**: Active company persistence with SQLite database
|
||||
- **Docker Ready**: Containerized deployment with Docker Compose
|
||||
|
||||
## Architecture
|
||||
|
||||
### System Components
|
||||
|
||||
```
|
||||
telegram-bot/
|
||||
├── app/
|
||||
│ ├── agent/ # Session management
|
||||
│ │ └── session.py # Active company persistence
|
||||
│ ├── api/ # Backend API client
|
||||
│ │ └── client.py # HTTP client for ROA2WEB backend
|
||||
│ ├── auth/ # Authentication & linking
|
||||
│ │ └── linking.py # Account linking logic
|
||||
│ ├── bot/ # Telegram bot handlers
|
||||
│ │ ├── handlers.py # Command handlers
|
||||
│ │ ├── helpers.py # Helper functions
|
||||
│ │ ├── formatters.py # Response formatting
|
||||
│ │ └── keyboards.py # Inline keyboard helpers
|
||||
│ ├── db/ # SQLite database (standalone)
|
||||
│ │ ├── database.py # Connection & schema
|
||||
│ │ └── operations.py # CRUD operations
|
||||
│ ├── internal_api.py # FastAPI for backend communication
|
||||
│ └── main.py # Main entry point
|
||||
├── data/ # SQLite database storage (gitignored)
|
||||
├── tests/ # Unit & integration tests
|
||||
├── Dockerfile # Container configuration
|
||||
├── requirements.txt # Python dependencies
|
||||
└── .env.example # Environment variables template
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. **User sends command** → Telegram → Bot Command Handlers
|
||||
2. **Authentication check** → SQLite database → JWT validation
|
||||
3. **API calls** → ROA2WEB Backend → Oracle database
|
||||
4. **Response formatting** → Telegram user
|
||||
|
||||
### Database Schema (SQLite)
|
||||
|
||||
The bot uses a standalone SQLite database for:
|
||||
|
||||
- **telegram_users**: User accounts and Oracle account linking
|
||||
- **telegram_auth_codes**: Temporary 8-character linking codes (15 min expiry)
|
||||
- **telegram_sessions**: Active company selection and session state
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.11+
|
||||
- Telegram account
|
||||
- ROA2WEB backend API running (default: http://localhost:8001)
|
||||
|
||||
### Step 1: Create Telegram Bot
|
||||
|
||||
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
|
||||
|
||||
```bash
|
||||
# Navigate to telegram-bot directory
|
||||
cd reports-app/telegram-bot
|
||||
|
||||
# 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_TOKEN=your_bot_token_from_botfather
|
||||
BACKEND_URL=http://localhost:8001
|
||||
|
||||
# Database
|
||||
SQLITE_DB_PATH=./data/telegram_bot.db
|
||||
|
||||
# Internal API (for backend communication)
|
||||
INTERNAL_API_PORT=8002
|
||||
|
||||
# Optional
|
||||
LOG_LEVEL=INFO
|
||||
SENTRY_DSN=https://your-sentry-dsn
|
||||
ENVIRONMENT=production
|
||||
```
|
||||
|
||||
### Step 4: Run the Bot
|
||||
|
||||
```bash
|
||||
# Make sure backend is running first
|
||||
# Backend should be at http://localhost:8001 (or configured BACKEND_URL)
|
||||
|
||||
# Run the bot
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Available Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/start [code]` | Start bot or link account with 8-char code |
|
||||
| `/help` | Show available commands and usage guide |
|
||||
| `/companies` | View accessible companies/firms |
|
||||
| `/selectcompany [name]` | Select or search for active company |
|
||||
| `/dashboard` | View financial dashboard for active company |
|
||||
| `/sold` | View balance (alias for `/dashboard`) |
|
||||
| `/facturi [filter]` | View invoices (optional filters: neplatite, platite) |
|
||||
| `/trezorerie` | View treasury/payment data |
|
||||
| `/clear` | Clear active company selection |
|
||||
| `/unlink` | Unlink Telegram account from Oracle |
|
||||
|
||||
### Authentication Flow (Updated 2025 - FAZA 1 Improvements)
|
||||
|
||||
The bot now supports **3 easy methods** for account linking:
|
||||
|
||||
#### Method 1: Deep Link (Recommended - One Click) 🚀
|
||||
|
||||
1. **Login** to ROA2WEB web application at http://localhost:3000
|
||||
2. **Navigate** to `/telegram` (Settings → Telegram)
|
||||
3. **Click** "Generează Cod" button
|
||||
4. **Click** "🚀 Deschide în Telegram" button
|
||||
5. **Telegram opens automatically** with code pre-populated
|
||||
6. **Done!** Account linked in <30 seconds
|
||||
|
||||
**Benefits:**
|
||||
- ⚡ **Zero manual copying** - code is pre-filled
|
||||
- 🎯 **One click** - Telegram opens automatically
|
||||
- ⏱️ **Super fast** - complete in ~30 seconds
|
||||
- 📱 **Works on desktop and mobile** (same device)
|
||||
|
||||
#### Method 2: QR Code (Cross-Device) 📷
|
||||
|
||||
Perfect when working on desktop but have Telegram on mobile:
|
||||
|
||||
1. **Login** to ROA2WEB web app (desktop)
|
||||
2. **Navigate** to `/telegram`
|
||||
3. **Click** "Generează Cod"
|
||||
4. **Scan QR Code** displayed on screen with Telegram on mobile
|
||||
5. **Telegram opens** with code pre-populated
|
||||
6. **Done!** Account linked
|
||||
|
||||
**Benefits:**
|
||||
- 📱 **Cross-device** - desktop browser → mobile Telegram
|
||||
- 📷 **Easy scanning** - just point camera at screen
|
||||
- ✅ **No typing** - code automatically loaded
|
||||
|
||||
#### Method 3: Manual (Traditional Fallback) ⌨️
|
||||
|
||||
If deep link or QR code don't work:
|
||||
|
||||
1. **Login** to ROA2WEB web application
|
||||
2. **Navigate** to `/telegram`
|
||||
3. **Click** "Generează Cod"
|
||||
4. **Click** copy button (📋) to copy code
|
||||
5. **Open Telegram** manually
|
||||
6. **Send code** to bot:
|
||||
- **Direct input**: `ABC123XY` (just paste)
|
||||
- **Classic format**: `/start ABC123XY`
|
||||
7. **Done!** Account linked
|
||||
|
||||
**Technical Details:**
|
||||
- Backend generates **8-character code** (valid 15 minutes)
|
||||
- Backend saves code to telegram-bot via internal API (`POST /internal/save-code`)
|
||||
- Bot verifies code and links accounts in SQLite database
|
||||
- Bot receives **JWT token** from backend
|
||||
- User can now use commands to query financial data
|
||||
|
||||
**Improvement Metrics:**
|
||||
- ⏱️ Time: **3 minutes → 40 seconds** (77% reduction)
|
||||
- 📉 Steps: **7 → 4** (43% reduction)
|
||||
- ✅ Manual copying: **Eliminated** (with Method 1 or 2)
|
||||
|
||||
### Usage Examples
|
||||
|
||||
```
|
||||
User: /companies
|
||||
Bot: Lists all accessible companies with ID, name, and CUI
|
||||
|
||||
User: /selectcompany ACME
|
||||
Bot: Shows selection keyboard for companies matching "ACME"
|
||||
[User clicks company button]
|
||||
Bot: Company selected: ACME SRL
|
||||
|
||||
User: /dashboard
|
||||
Bot: Displays dashboard statistics for ACME SRL:
|
||||
- Total balance
|
||||
- Invoices issued/paid/unpaid
|
||||
- Total collections and payments
|
||||
|
||||
User: /facturi neplatite
|
||||
Bot: Shows list of unpaid invoices for ACME SRL
|
||||
|
||||
User: /trezorerie
|
||||
Bot: Displays treasury data (cash balance, bank accounts, etc.)
|
||||
|
||||
User: /clear
|
||||
Bot: Active company cleared. Use /selectcompany to select another.
|
||||
```
|
||||
|
||||
## Docker Deployment
|
||||
|
||||
### Build Image
|
||||
|
||||
```bash
|
||||
# From telegram-bot directory
|
||||
docker build -t roa-telegram-bot .
|
||||
```
|
||||
|
||||
### Run Container
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name roa-telegram-bot \
|
||||
-e TELEGRAM_BOT_TOKEN=your_token \
|
||||
-e BACKEND_URL=http://backend:8001 \
|
||||
-v $(pwd)/data:/app/data \
|
||||
roa-telegram-bot
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
See `docker-compose.yml` in project root for full orchestration with backend and database.
|
||||
|
||||
## Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
- **app/main.py**: Bot entry point and Telegram application setup
|
||||
- **app/bot/handlers.py**: All command handlers (`/start`, `/dashboard`, etc.)
|
||||
- **app/bot/helpers.py**: Helper functions for company selection and prompts
|
||||
- **app/bot/formatters.py**: Response formatting utilities
|
||||
- **app/auth/linking.py**: Account linking and JWT management
|
||||
- **app/api/client.py**: HTTP client for backend API calls
|
||||
- **app/agent/session.py**: Session management (active company persistence)
|
||||
- **app/db/**: SQLite database operations
|
||||
- **app/internal_api.py**: FastAPI for backend callbacks
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pytest tests/ -v
|
||||
|
||||
# Run specific test suites
|
||||
pytest tests/test_auth.py -v # Authentication tests
|
||||
pytest tests/test_session_company.py -v # Session & company tests
|
||||
pytest tests/test_helpers.py -v # Helper function tests
|
||||
pytest tests/test_formatters.py -v # Formatter tests
|
||||
|
||||
# Run with coverage
|
||||
pytest tests/ --cov=app --cov-report=html
|
||||
```
|
||||
|
||||
### Adding New Commands
|
||||
|
||||
1. Add handler function in `app/bot/handlers.py`:
|
||||
```python
|
||||
async def my_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
|
||||
# Implementation
|
||||
pass
|
||||
```
|
||||
|
||||
2. Register handler in `app/main.py`:
|
||||
```python
|
||||
application.add_handler(CommandHandler("mycommand", my_command))
|
||||
```
|
||||
|
||||
3. Add to `__all__` export in `handlers.py`
|
||||
|
||||
## User Experience Improvements (2025)
|
||||
|
||||
### FAZA 1: Authentication Simplification ✅
|
||||
|
||||
**Implemented:** January 2025
|
||||
**Status:** Production Ready
|
||||
|
||||
**What Changed:**
|
||||
- Added **Deep Link** button - one-click Telegram opening
|
||||
- Added **QR Code** generation for cross-device linking
|
||||
- Improved **Manual method** with copy button
|
||||
- Reduced linking time by **77%** (3 min → 40 sec)
|
||||
- Reduced steps by **43%** (7 → 4 steps)
|
||||
|
||||
**Documentation:**
|
||||
- **Complete Plan:** [TELEGRAM_AUTH_IMPROVEMENT_PLAN.md](./TELEGRAM_AUTH_IMPROVEMENT_PLAN.md)
|
||||
- **Testing Guide:** [TESTING_INSTRUCTIONS_FAZA1.md](./TESTING_INSTRUCTIONS_FAZA1.md)
|
||||
- **Implementation Summary:** [FAZA1_IMPLEMENTATION_SUMMARY.md](./FAZA1_IMPLEMENTATION_SUMMARY.md)
|
||||
|
||||
**Frontend Changes:**
|
||||
- `reports-app/frontend/src/views/TelegramView.vue` - Complete UI refactor
|
||||
- Added `qrcode.vue` dependency for QR generation
|
||||
- Environment variable: `VITE_TELEGRAM_BOT_USERNAME`
|
||||
|
||||
### FAZA 2: Email Magic Link (Optional - Future)
|
||||
|
||||
**Status:** Planned
|
||||
**Estimated:** 3.5 hours development
|
||||
|
||||
**What's Planned:**
|
||||
- Email with magic link option
|
||||
- Professional HTML email template
|
||||
- Auto-detect SMTP configuration
|
||||
- Checkbox "Send code via email"
|
||||
|
||||
**Prerequisites:**
|
||||
- SMTP server configuration (Gmail, SendGrid, AWS SES)
|
||||
- User email addresses in Oracle database
|
||||
|
||||
**Note:** FAZA 2 is completely optional. FAZA 1 provides excellent UX for most users.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot Not Responding
|
||||
|
||||
- Check bot is running: `ps aux | grep python.*main.py`
|
||||
- Check logs: `tail -f logs/telegram-bot.log`
|
||||
- Verify TELEGRAM_BOT_TOKEN is correct
|
||||
- Ensure backend is accessible at BACKEND_URL
|
||||
|
||||
### Authentication Issues
|
||||
|
||||
- Check auth code expiry (15 minutes)
|
||||
- Verify backend internal API is accessible (port 8002)
|
||||
- Check SQLite database permissions
|
||||
- **Deep Link not working?** Browser may block protocol handler - click "Allow" when prompted
|
||||
- **QR Code not scanning?** Ensure good lighting and camera focus
|
||||
- **Manual method always works** as fallback
|
||||
|
||||
### Database Issues
|
||||
|
||||
- Ensure `data/` directory exists and is writable
|
||||
- Check database file: `sqlite3 data/telegram_bot.db ".schema"`
|
||||
- Automatic cleanup runs hourly for expired data
|
||||
|
||||
### Deep Link Issues (FAZA 1)
|
||||
|
||||
**Problem:** Deep link button doesn't open Telegram
|
||||
|
||||
**Solutions:**
|
||||
1. **Desktop:** Browser may ask permission - click "Allow" to open Telegram
|
||||
2. **Mobile:** Ensure Telegram app is installed
|
||||
3. **Fallback:** Use QR Code (Method 2) or Manual (Method 3)
|
||||
|
||||
**Browser Compatibility:**
|
||||
- ✅ Chrome/Edge - Works perfectly
|
||||
- ⚠️ Firefox - May show permission prompt
|
||||
- ⚠️ Safari - May show permission prompt
|
||||
- ✅ Mobile browsers - Works on all major browsers
|
||||
|
||||
**Problem:** QR Code doesn't display
|
||||
|
||||
**Solutions:**
|
||||
1. Check browser console for errors (F12)
|
||||
2. Ensure `qrcode.vue` package is installed: `npm list qrcode.vue`
|
||||
3. Rebuild frontend: `cd frontend && npm run build`
|
||||
4. **Fallback:** Use Manual method (always works)
|
||||
|
||||
## API Integration
|
||||
|
||||
The bot communicates with ROA2WEB backend via HTTP API:
|
||||
|
||||
- `POST /api/telegram/auth/verify-user` - Verify user_id
|
||||
- `POST /api/telegram/auth/refresh-token` - Refresh JWT
|
||||
- `GET /api/companies` - Get user companies
|
||||
- `GET /api/dashboard/{company_id}` - Dashboard data
|
||||
- `GET /api/invoices/{company_id}` - Invoice list
|
||||
- `GET /api/treasury/{company_id}` - Treasury data
|
||||
|
||||
All requests include JWT token in Authorization header (except verify-user endpoint).
|
||||
|
||||
## Security
|
||||
|
||||
- JWT tokens are stored encrypted in SQLite
|
||||
- Auth codes expire after 15 minutes
|
||||
- Sessions are automatically cleaned up
|
||||
- Environment variables never committed to git
|
||||
- Rate limiting on authentication endpoints
|
||||
|
||||
## License
|
||||
|
||||
See main project LICENSE file.
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or contributions, see the main ROA2WEB project documentation.
|
||||
1928
docs/telegram/TELEGRAM_BUTTON_INTERFACE_PLAN.md
Normal file
1928
docs/telegram/TELEGRAM_BUTTON_INTERFACE_PLAN.md
Normal file
File diff suppressed because it is too large
Load Diff
496
docs/telegram/testing/DOCKER_TESTING_GUIDE.md
Normal file
496
docs/telegram/testing/DOCKER_TESTING_GUIDE.md
Normal file
@@ -0,0 +1,496 @@
|
||||
# 🐳 Docker Testing Guide - ROA2WEB Telegram Bot
|
||||
|
||||
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/reports-app/telegram-bot
|
||||
|
||||
# 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/reports-app/telegram-bot
|
||||
|
||||
# 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
|
||||
365
docs/telegram/testing/MANUAL_TESTING_CHECKLIST.md
Normal file
365
docs/telegram/testing/MANUAL_TESTING_CHECKLIST.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# 📋 Manual Testing Checklist - ROA2WEB Telegram Bot
|
||||
|
||||
This checklist guides you through manual testing of the Telegram bot functionality.
|
||||
|
||||
## 🔧 Prerequisites
|
||||
|
||||
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)
|
||||
|
||||
## 📱 Test Environment Setup
|
||||
|
||||
### Start Services
|
||||
|
||||
```bash
|
||||
# Terminal 1: Start backend API (from roa2web/)
|
||||
cd reports-app/backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --port 8001
|
||||
|
||||
# Terminal 2: Start Telegram bot
|
||||
cd reports-app/telegram-bot
|
||||
source venv/bin/activate
|
||||
python -m app.main
|
||||
```
|
||||
|
||||
### Test User Setup
|
||||
|
||||
- [ ] Create test Oracle user account in Oracle database (if needed)
|
||||
- [ ] Have test Telegram account ready (@testuser or similar)
|
||||
- [ ] Know the Telegram user ID (can be found via bot command `/start`)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Test Cases
|
||||
|
||||
### 1. Bot Discovery & Initial Contact
|
||||
|
||||
**Test 1.1: Start Bot**
|
||||
- [ ] Open Telegram and search for `@ROA2WEBBot`
|
||||
- [ ] Click "Start" or send `/start` command
|
||||
- [ ] **Expected**: Bot responds with welcome message explaining linking process
|
||||
- [ ] **Expected**: Bot asks for authentication code
|
||||
|
||||
**Test 1.2: Help Command**
|
||||
- [ ] Send `/help` command
|
||||
- [ ] **Expected**: Bot shows list of available commands with descriptions
|
||||
- [ ] **Expected**: Includes `/start`, `/help`, `/clear`, `/companies`, `/unlink`
|
||||
|
||||
---
|
||||
|
||||
### 2. Authentication Flow
|
||||
|
||||
**Test 2.1: Generate Linking Code (via Web)**
|
||||
- [ ] Open web frontend (Vue.js app)
|
||||
- [ ] Login with Oracle credentials
|
||||
- [ ] Navigate to Telegram linking page (if available)
|
||||
- [ ] Click "Generate Telegram Linking Code"
|
||||
- [ ] **Expected**: 8-character code is displayed (e.g., `ABC23456`)
|
||||
- [ ] **Expected**: Code expires in 5 minutes message shown
|
||||
|
||||
**Test 2.2: Link Account with Valid Code**
|
||||
- [ ] In Telegram bot, send the 8-character code from Step 2.1
|
||||
- [ ] **Expected**: Bot responds with "Successfully linked to Oracle account [username]"
|
||||
- [ ] **Expected**: Bot shows list of companies you have access to
|
||||
- [ ] **Expected**: User is now authenticated and can use bot features
|
||||
|
||||
**Test 2.3: Try to Link with Invalid Code**
|
||||
- [ ] Send an invalid code like `INVALID1`
|
||||
- [ ] **Expected**: Bot responds with "Invalid or expired code" message
|
||||
- [ ] **Expected**: Bot prompts to generate new code via web
|
||||
|
||||
**Test 2.4: Try to Link with Expired Code**
|
||||
- [ ] Generate a code via web
|
||||
- [ ] Wait 6+ minutes (past expiration)
|
||||
- [ ] Send expired code to bot
|
||||
- [ ] **Expected**: Bot responds with "Code has expired" message
|
||||
- [ ] **Expected**: Bot suggests generating new code
|
||||
|
||||
**Test 2.5: Try to Reuse Code**
|
||||
- [ ] Generate new code and link successfully
|
||||
- [ ] Unlink account (`/unlink`)
|
||||
- [ ] Try to use the same code again
|
||||
- [ ] **Expected**: Bot rejects code with "Code already used" message
|
||||
|
||||
---
|
||||
|
||||
### 3. User Commands (When Linked)
|
||||
|
||||
**Test 3.1: Companies Command**
|
||||
- [ ] Send `/companies` command
|
||||
- [ ] **Expected**: Bot lists all companies user has access to
|
||||
- [ ] **Expected**: Shows company ID, name, and CUI
|
||||
- [ ] **Expected**: Format is clear and readable
|
||||
|
||||
**Test 3.2: Clear History Command**
|
||||
- [ ] Have some conversation history with bot
|
||||
- [ ] Send `/clear` command
|
||||
- [ ] **Expected**: Bot confirms conversation history cleared
|
||||
- [ ] **Expected**: Bot resets context for new conversation
|
||||
|
||||
**Test 3.3: Unlink Command**
|
||||
- [ ] Send `/unlink` command
|
||||
- [ ] **Expected**: Bot shows confirmation warning
|
||||
- [ ] **Expected**: Shows inline keyboard with "Yes" / "No" buttons
|
||||
- [ ] Press "No" button
|
||||
- [ ] **Expected**: Unlinking cancelled, account still linked
|
||||
- [ ] Send `/unlink` again and press "Yes"
|
||||
- [ ] **Expected**: Account unlinked successfully
|
||||
- [ ] **Expected**: Bot requires new authentication code to continue
|
||||
|
||||
---
|
||||
|
||||
### 4. Conversational Queries (Claude Agent)
|
||||
|
||||
**Note**: These tests require Claude Agent SDK integration to be complete.
|
||||
|
||||
**Test 4.1: Simple Dashboard Query**
|
||||
- [ ] Send message: "Show me the dashboard for company 1"
|
||||
- [ ] **Expected**: Bot retrieves dashboard data
|
||||
- [ ] **Expected**: Shows total balance, invoices count, payments, etc.
|
||||
- [ ] **Expected**: Data is formatted in Romanian language
|
||||
|
||||
**Test 4.2: Invoice Search Query**
|
||||
- [ ] Send: "Find unpaid invoices from October 2025"
|
||||
- [ ] **Expected**: Bot searches invoices with filters
|
||||
- [ ] **Expected**: Returns list of matching invoices
|
||||
- [ ] **Expected**: Shows invoice number, date, client, amount, status
|
||||
|
||||
**Test 4.3: Treasury Query**
|
||||
- [ ] Send: "What's the current treasury status for company 1?"
|
||||
- [ ] **Expected**: Bot retrieves treasury data
|
||||
- [ ] **Expected**: Shows cash balance, bank accounts, payments
|
||||
|
||||
**Test 4.4: Export Request**
|
||||
- [ ] Send: "Export unpaid invoices to Excel"
|
||||
- [ ] **Expected**: Bot generates Excel file
|
||||
- [ ] **Expected**: Sends file via Telegram
|
||||
- [ ] **Expected**: File name includes report type and timestamp
|
||||
- [ ] **Expected**: File can be downloaded and opened
|
||||
|
||||
**Test 4.5: Complex Multi-Step Query**
|
||||
- [ ] Send: "Show me the dashboard, then find invoices over 5000 RON, and export them to PDF"
|
||||
- [ ] **Expected**: Bot handles multi-step request correctly
|
||||
- [ ] **Expected**: Executes each tool in sequence
|
||||
- [ ] **Expected**: Provides updates on progress
|
||||
- [ ] **Expected**: Final PDF file is sent
|
||||
|
||||
**Test 4.6: Romanian Language Support**
|
||||
- [ ] Send messages in Romanian
|
||||
- [ ] **Expected**: Bot understands and responds in Romanian
|
||||
- [ ] **Expected**: Romanian characters displayed correctly (ă, â, î, ș, ț)
|
||||
|
||||
---
|
||||
|
||||
### 5. Error Handling
|
||||
|
||||
**Test 5.1: Query Before Authentication**
|
||||
- [ ] Start new bot conversation (or use fresh account)
|
||||
- [ ] Send query without linking: "Show dashboard"
|
||||
- [ ] **Expected**: Bot responds with "Please authenticate first"
|
||||
- [ ] **Expected**: Bot provides instructions to link account
|
||||
|
||||
**Test 5.2: Invalid Company ID**
|
||||
- [ ] Send: "Show dashboard for company 9999"
|
||||
- [ ] **Expected**: Bot responds with "Company not found" or "No access" message
|
||||
- [ ] **Expected**: Suggests using `/companies` to see available companies
|
||||
|
||||
**Test 5.3: Backend API Offline**
|
||||
- [ ] Stop backend API server
|
||||
- [ ] Try to send query to bot
|
||||
- [ ] **Expected**: Bot responds with "Service temporarily unavailable" message
|
||||
- [ ] **Expected**: Suggests trying again later
|
||||
|
||||
**Test 5.4: Token Expiration**
|
||||
- [ ] Link account and wait for JWT token to expire (30 minutes)
|
||||
- [ ] Send query after expiration
|
||||
- [ ] **Expected**: Bot automatically refreshes token
|
||||
- [ ] **Expected**: Query succeeds without re-authentication
|
||||
|
||||
**Test 5.5: Invalid Export Format**
|
||||
- [ ] Send: "Export dashboard to invalidformat"
|
||||
- [ ] **Expected**: Bot responds with supported formats (xlsx, csv, pdf)
|
||||
- [ ] **Expected**: Asks user to specify valid format
|
||||
|
||||
---
|
||||
|
||||
### 6. Session Management
|
||||
|
||||
**Test 6.1: Conversation Context**
|
||||
- [ ] Send: "Show dashboard for company 1"
|
||||
- [ ] Bot responds with data
|
||||
- [ ] Send follow-up: "Now show invoices"
|
||||
- [ ] **Expected**: Bot remembers company 1 from context
|
||||
- [ ] **Expected**: Shows invoices for company 1
|
||||
|
||||
**Test 6.2: Session Persistence**
|
||||
- [ ] Have conversation with bot
|
||||
- [ ] Stop and restart Telegram bot application
|
||||
- [ ] Resume conversation
|
||||
- [ ] **Expected**: User is still linked (SQLite data persists)
|
||||
- [ ] **Expected**: Can immediately send queries without re-authentication
|
||||
|
||||
**Test 6.3: Multiple Users**
|
||||
- [ ] Use two different Telegram accounts
|
||||
- [ ] Link both to different Oracle users
|
||||
- [ ] Send queries from both accounts simultaneously
|
||||
- [ ] **Expected**: Each user gets their own data
|
||||
- [ ] **Expected**: No data mixing between users
|
||||
- [ ] **Expected**: Sessions isolated correctly
|
||||
|
||||
---
|
||||
|
||||
### 7. Database Operations
|
||||
|
||||
**Test 7.1: Check User Record**
|
||||
```bash
|
||||
# In terminal
|
||||
sqlite3 data/telegram_bot.db
|
||||
SELECT * FROM telegram_users;
|
||||
```
|
||||
- [ ] **Expected**: User record exists with telegram_user_id
|
||||
- [ ] **Expected**: oracle_username is populated after linking
|
||||
- [ ] **Expected**: jwt_token and token_expires_at are set
|
||||
|
||||
**Test 7.2: Check Auth Codes**
|
||||
```sql
|
||||
SELECT * FROM telegram_auth_codes WHERE oracle_username = 'testuser';
|
||||
```
|
||||
- [ ] **Expected**: Used codes have `used_at` timestamp
|
||||
- [ ] **Expected**: Expired codes have `expires_at` in the past
|
||||
|
||||
**Test 7.3: Database Cleanup**
|
||||
- [ ] Generate expired auth code (wait 6 minutes or manually update DB)
|
||||
- [ ] Wait for cleanup task to run (runs hourly)
|
||||
- [ ] **Expected**: Expired codes are removed from database
|
||||
- [ ] **Expected**: Database size doesn't grow indefinitely
|
||||
|
||||
---
|
||||
|
||||
### 8. Performance & Reliability
|
||||
|
||||
**Test 8.1: Response Time**
|
||||
- [ ] Send simple query: "Show dashboard"
|
||||
- [ ] Measure time from send to receive response
|
||||
- [ ] **Expected**: Response within 3-5 seconds
|
||||
- [ ] **Expected**: No timeouts
|
||||
|
||||
**Test 8.2: Large Data Export**
|
||||
- [ ] Request export of large dataset (100+ invoices)
|
||||
- [ ] **Expected**: Bot handles large exports gracefully
|
||||
- [ ] **Expected**: File generates successfully
|
||||
- [ ] **Expected**: File size is reasonable (<10MB for typical data)
|
||||
|
||||
**Test 8.3: Concurrent Requests**
|
||||
- [ ] Send multiple queries rapidly (3-4 in quick succession)
|
||||
- [ ] **Expected**: All queries are processed
|
||||
- [ ] **Expected**: Responses arrive in correct order
|
||||
- [ ] **Expected**: No crashes or errors
|
||||
|
||||
---
|
||||
|
||||
### 9. Security Tests
|
||||
|
||||
**Test 9.1: Unauthorized Access**
|
||||
- [ ] Without linking, try to call backend API directly with fake token
|
||||
- [ ] **Expected**: Backend rejects request with 401 Unauthorized
|
||||
|
||||
**Test 9.2: Token in Database**
|
||||
```bash
|
||||
sqlite3 data/telegram_bot.db
|
||||
SELECT jwt_token FROM telegram_users LIMIT 1;
|
||||
```
|
||||
- [ ] **Expected**: Token exists in database
|
||||
- [ ] **Note**: Ensure database file is properly secured in production
|
||||
- [ ] **Note**: Database should not be committed to git
|
||||
|
||||
**Test 9.3: Code Security**
|
||||
- [ ] Generate linking code
|
||||
- [ ] Try to guess codes by brute force
|
||||
- [ ] **Expected**: Codes are random and hard to guess (8 chars, no ambiguous chars)
|
||||
- [ ] **Expected**: Codes expire after 5 minutes
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Results
|
||||
|
||||
### Summary
|
||||
|
||||
| Test Category | Total Tests | Passed | Failed | Skipped |
|
||||
|--------------|-------------|--------|--------|---------|
|
||||
| Bot Discovery | 2 | - | - | - |
|
||||
| Authentication Flow | 5 | - | - | - |
|
||||
| User Commands | 3 | - | - | - |
|
||||
| Conversational Queries | 6 | - | - | - |
|
||||
| Error Handling | 5 | - | - | - |
|
||||
| Session Management | 3 | - | - | - |
|
||||
| Database Operations | 3 | - | - | - |
|
||||
| Performance | 3 | - | - | - |
|
||||
| Security | 3 | - | - | - |
|
||||
| **TOTAL** | **33** | **0** | **0** | **0** |
|
||||
|
||||
### Failed Tests
|
||||
|
||||
_List any failed tests here with details:_
|
||||
|
||||
| Test ID | Description | Error | Notes |
|
||||
|---------|-------------|-------|-------|
|
||||
| - | - | - | - |
|
||||
|
||||
### Notes & Issues
|
||||
|
||||
_Document any issues discovered during testing:_
|
||||
|
||||
-
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Reporting Issues
|
||||
|
||||
If you find bugs during manual testing:
|
||||
|
||||
1. **Document**:
|
||||
- Test case ID
|
||||
- Steps to reproduce
|
||||
- Expected behavior
|
||||
- Actual behavior
|
||||
- Error messages (if any)
|
||||
- Screenshots (if applicable)
|
||||
|
||||
2. **Check Database State**:
|
||||
```bash
|
||||
sqlite3 data/telegram_bot.db
|
||||
# Inspect relevant tables
|
||||
```
|
||||
|
||||
3. **Check Logs**:
|
||||
- Telegram bot logs (console output)
|
||||
- Backend API logs
|
||||
- SQLite database queries
|
||||
|
||||
4. **Create Issue**:
|
||||
- File bug in project issue tracker
|
||||
- Include all documentation from step 1
|
||||
|
||||
---
|
||||
|
||||
## ✅ Test Completion
|
||||
|
||||
**Tester Name**: _______________
|
||||
|
||||
**Date**: _______________
|
||||
|
||||
**Overall Result**: [ ] PASS [ ] FAIL
|
||||
|
||||
**Sign-off**: _______________
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-21
|
||||
213
docs/telegram/testing/README_INTEGRATION_TESTS.md
Normal file
213
docs/telegram/testing/README_INTEGRATION_TESTS.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Integration Tests Guide
|
||||
|
||||
This directory contains both **unit tests** (with mocks) and **integration tests** (with real data).
|
||||
|
||||
## Test Categories
|
||||
|
||||
### Unit Tests (Default)
|
||||
- **Files**: `test_*.py` (except `*_real*.py`)
|
||||
- **Dependencies**: None (all mocked)
|
||||
- **Speed**: Fast (~2-3 seconds)
|
||||
- **Run by**: CI/CD, developers
|
||||
- **Command**: `pytest` (runs by default)
|
||||
|
||||
**Examples**:
|
||||
- `test_auth.py` - Authentication flow tests
|
||||
- `test_tools.py` - Claude Agent tools tests
|
||||
- `test_helpers.py` - Bot helper functions tests
|
||||
- `test_formatters.py` - Response formatters tests
|
||||
- `test_session_company.py` - Session management tests
|
||||
|
||||
### Integration Tests (Manual)
|
||||
- **Files**: `test_helpers_real*.py`
|
||||
- **Dependencies**: Backend API + Database/Environment
|
||||
- **Speed**: Slower (~10-30 seconds)
|
||||
- **Run by**: Developers manually
|
||||
- **Command**: `pytest -m integration`
|
||||
- **Marked with**: `@pytest.mark.integration`
|
||||
|
||||
**Examples**:
|
||||
- `test_helpers_real.py` - Integration tests with SQLite DB
|
||||
- `test_helpers_real_simple.py` - Integration tests with direct API auth
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Run All Unit Tests (Default)
|
||||
```bash
|
||||
# Runs all tests EXCEPT integration tests
|
||||
pytest
|
||||
|
||||
# Explicit: run only unit tests
|
||||
pytest -m "not integration"
|
||||
```
|
||||
|
||||
### Run Integration Tests
|
||||
```bash
|
||||
# Run only integration tests
|
||||
pytest -m integration
|
||||
|
||||
# Run specific integration test file
|
||||
pytest tests/test_helpers_real.py -m integration
|
||||
|
||||
# Run as standalone script (alternative)
|
||||
python tests/test_helpers_real_simple.py
|
||||
```
|
||||
|
||||
### Run ALL Tests (Unit + Integration)
|
||||
```bash
|
||||
# Override default filter
|
||||
pytest -m ""
|
||||
```
|
||||
|
||||
## Integration Test Requirements
|
||||
|
||||
### For `test_helpers_real.py`:
|
||||
- ✅ Backend API running on `localhost:8001`
|
||||
- ✅ SQLite database (`data/telegram_bot.db`) with at least one linked user
|
||||
- ⚠️ Requires existing user session in database
|
||||
|
||||
### For `test_helpers_real_simple.py`:
|
||||
- ✅ Backend API running on `localhost:8001`
|
||||
- ✅ Environment variables set:
|
||||
```bash
|
||||
export TEST_USERNAME="your_oracle_username"
|
||||
export TEST_PASSWORD="your_oracle_password"
|
||||
```
|
||||
- ✅ Valid Oracle credentials for backend authentication
|
||||
|
||||
## Setting Up Integration Tests
|
||||
|
||||
### 1. Start Backend API
|
||||
```bash
|
||||
cd roa2web/reports-app/backend
|
||||
source venv/bin/activate
|
||||
uvicorn app.main:app --reload --port 8001
|
||||
```
|
||||
|
||||
### 2. Set Credentials (for `test_helpers_real_simple.py`)
|
||||
```bash
|
||||
# In your shell or .env file
|
||||
export TEST_USERNAME="MARIUS M" # Your Oracle username
|
||||
export TEST_PASSWORD="your_password" # Your Oracle password
|
||||
```
|
||||
|
||||
### 3. Run Integration Tests
|
||||
```bash
|
||||
cd roa2web/reports-app/telegram-bot
|
||||
source venv/bin/activate
|
||||
pytest -m integration -v
|
||||
```
|
||||
|
||||
## CI/CD Configuration
|
||||
|
||||
Integration tests are **automatically skipped** in CI/CD pipelines because:
|
||||
- They require external services (backend API, database)
|
||||
- They need real credentials
|
||||
- Default pytest configuration excludes them: `-m "not integration"`
|
||||
|
||||
To run them in CI/CD, you would need to:
|
||||
1. Set up backend API service
|
||||
2. Provide TEST_USERNAME and TEST_PASSWORD as secrets
|
||||
3. Override pytest command: `pytest -m ""`
|
||||
|
||||
## Markers Reference
|
||||
|
||||
Defined in `pytest.ini`:
|
||||
|
||||
```ini
|
||||
markers =
|
||||
unit: Unit tests with mocks (fast, no external dependencies)
|
||||
integration: Integration tests with real backend/database (slow, requires setup)
|
||||
slow: Slow tests that take more than 1 second
|
||||
```
|
||||
|
||||
**Usage**:
|
||||
```bash
|
||||
pytest -m unit # Run only unit tests
|
||||
pytest -m integration # Run only integration tests
|
||||
pytest -m slow # Run only slow tests
|
||||
pytest -m "not slow" # Skip slow tests
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### When Writing Tests
|
||||
|
||||
**Unit Tests (Preferred for most cases)**:
|
||||
- ✅ Fast and reliable
|
||||
- ✅ No external dependencies
|
||||
- ✅ Use mocks (`unittest.mock`, `AsyncMock`)
|
||||
- ✅ Test one component at a time
|
||||
- ✅ Run in CI/CD
|
||||
|
||||
**Integration Tests (Use sparingly)**:
|
||||
- ⚠️ Slower and can be flaky
|
||||
- ⚠️ Require full environment setup
|
||||
- ⚠️ Test multiple components together
|
||||
- ⚠️ Manual execution only
|
||||
- ✅ Useful for validation before releases
|
||||
- ✅ Document real usage patterns
|
||||
|
||||
### Coverage Goals
|
||||
|
||||
- **Unit tests**: Aim for 80%+ code coverage
|
||||
- **Integration tests**: Focus on critical paths and end-to-end flows
|
||||
- Don't duplicate: If unit tests cover it well, integration tests may be redundant
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Integration Tests Fail
|
||||
1. **Check backend is running**: `curl http://localhost:8001/health`
|
||||
2. **Verify credentials**: Ensure `TEST_USERNAME` and `TEST_PASSWORD` are set
|
||||
3. **Check database**: Ensure `data/telegram_bot.db` exists and has users
|
||||
4. **Review logs**: Check backend logs for API errors
|
||||
|
||||
### Integration Tests Skipped
|
||||
- This is normal! They're skipped by default.
|
||||
- Use `pytest -m integration` to run them explicitly.
|
||||
|
||||
### Import Errors
|
||||
```bash
|
||||
# Make sure you're in the right directory
|
||||
cd /mnt/e/proiecte/roa2web/roa2web/reports-app/telegram-bot
|
||||
|
||||
# Activate virtual environment
|
||||
source venv/bin/activate
|
||||
|
||||
# Install dependencies
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
## Example Output
|
||||
|
||||
### Unit Tests (Default)
|
||||
```bash
|
||||
$ pytest
|
||||
============================= test session starts ==============================
|
||||
collected 93 items / 5 deselected / 88 selected
|
||||
|
||||
tests/test_auth.py ............ [ 13%]
|
||||
tests/test_formatters.py ................ [ 31%]
|
||||
tests/test_helpers.py .................. [ 51%]
|
||||
tests/test_session_company.py .................. [ 72%]
|
||||
tests/test_tools.py .................. [100%]
|
||||
|
||||
======================== 88 passed, 5 deselected in 3.42s ======================
|
||||
```
|
||||
|
||||
### Integration Tests (Explicit)
|
||||
```bash
|
||||
$ pytest -m integration
|
||||
============================= test session starts ==============================
|
||||
collected 93 items / 88 deselected / 5 selected
|
||||
|
||||
tests/test_helpers_real.py .... [ 80%]
|
||||
tests/test_helpers_real_simple.py . [100%]
|
||||
|
||||
======================== 5 passed, 88 deselected in 12.37s =====================
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-22
|
||||
**Author**: Claude Code Session
|
||||
Reference in New Issue
Block a user