refactor(docs): consolidate and cleanup documentation

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

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

View File

@@ -1,11 +1,7 @@
# ROA2WEB Telegram Bot
> ⚠️ **ARCHITECTURE NOTE**
>
> This documentation partially references the old standalone bot architecture.
> The current architecture is an **ultrathin monolith** where the Telegram bot runs
> as a background task within the main backend (`backend/main.py`) on port 8000/8001.
> The `INTERNAL_API_PORT` variable is no longer used - internal API is at `/api/telegram/internal/*`.
> **Architecture:** Ultrathin Monolith - Telegram bot runs as a background task within the unified backend on port 8000.
> See `docs/telegram/DEPLOYMENT.md` for single-worker requirement.
> **Telegram Frontend for ROA2WEB ERP System** with Direct Command Interface
@@ -71,78 +67,45 @@ The bot uses a standalone SQLite database for:
- **telegram_auth_codes**: Temporary 8-character linking codes (15 min expiry)
- **telegram_sessions**: Active company selection and session state
## Installation & Setup
## Setup & Configuration
### Prerequisites
- Python 3.11+
- Telegram account
- ROA2WEB backend API running (default: http://localhost:8001)
- ROA2WEB backend running (the bot runs as part of the unified backend)
- Telegram Bot Token (from @BotFather)
### Step 1: Create Telegram Bot
### Step 1: Create Telegram Bot (One-time)
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
### Step 2: Configure Environment
Add to `backend/.env`:
```bash
# Navigate to telegram-bot directory
cd backend/modules/telegram
# 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 Configuration
MODULE_TELEGRAM_ENABLED=true
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
BACKEND_URL=http://localhost:8001
# Database
SQLITE_DB_PATH=./data/telegram_bot.db
# Internal API - DEPRECATED (now served via main backend at /api/telegram/internal/*)
# INTERNAL_API_PORT=8002
# Optional
LOG_LEVEL=INFO
SENTRY_DSN=https://your-sentry-dsn
ENVIRONMENT=production
```
### Step 4: Run the Bot
### Step 3: Start the Application
```bash
# Make sure backend is running first
# Backend should be at http://localhost:8001 (or configured BACKEND_URL)
# From project root - starts backend with Telegram bot integrated
./start-prod.sh
# Run the bot
python -m app.main
# Or for testing:
./start-test.sh
```
The bot starts automatically as a background task when `MODULE_TELEGRAM_ENABLED=true`.
> **Important:** Backend must run with `--workers 1` for Telegram bot to work correctly.
> See `docs/telegram/DEPLOYMENT.md` for details.
## Usage
### Available Commands