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>
2025-12-29 23:48:14 +02:00
parent 2a101f1ef5
commit c5e051ad80
378 changed files with 7566 additions and 73730 deletions
--- a/docs/telegram/testing/MANUAL_TESTING_CHECKLIST.md
+++ b/docs/telegram/testing/MANUAL_TESTING_CHECKLIST.md
@@ -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