TG_autoposter/docs/DEVELOPMENT.md

# Development Setup Guide

## Prerequisites

- Python 3.11+
- Docker & Docker Compose
- PostgreSQL 15 (or use Docker)
- Redis 7 (or use Docker)
- Git

## Local Development (Without Docker)

### 1. Clone Repository

```bash
git clone https://github.com/yourusername/TG_autoposter.git
cd TG_autoposter
```

### 2. Create Virtual Environment

```bash
# Using venv
python3.11 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Or using poetry
poetry env use python3.11
poetry shell
```

### 3. Install Dependencies

```bash
# Using pip
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Or using poetry
poetry install
```

### 4. Setup Environment Variables

```bash
cp .env.example .env
# Edit .env with your actual values
nano .env
```

Required variables:
```
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
ADMIN_ID=your_telegram_id
```

### 5. Setup Database

```bash
# Create database
createdb tg_autoposter

# Run migrations
alembic upgrade head
```

### 6. Run Bot

```bash
# Terminal 1: Start Redis
redis-server

# Terminal 2: Start Celery Worker
celery -A app.celery_config worker --loglevel=info

# Terminal 3: Start Celery Beat (Scheduler)
celery -A app.celery_config beat --loglevel=info

# Terminal 4: Start Bot
python -m app
```

### 7. Development with Docker

```bash
# Build and start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Access services:
# - Bot: Running in container
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - Flower (Celery monitoring): http://localhost:5555
```

## Code Style & Linting

```bash
# Format code with black
black app/

# Sort imports with isort
isort app/

# Lint with flake8
flake8 app/

# Type checking with mypy
mypy app/ --ignore-missing-imports

# Run all checks
make lint
```

## Testing

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=app

# Run specific test file
pytest tests/test_handlers.py

# Run in watch mode
pytest-watch

# Run async tests
pytest -v --asyncio-mode=auto
```

## Database Migrations

```bash
# Create new migration
alembic revision --autogenerate -m "Add new column"

# Apply migrations
alembic upgrade head

# Rollback to previous migration
alembic downgrade -1

# Show migration history
alembic current
alembic history
```

## Debugging

### Enable Debug Logging

```bash
# In .env
LOG_LEVEL=DEBUG

# Or set at runtime
export LOG_LEVEL=DEBUG
python -m app
```

### Using pdb

```python
import pdb; pdb.set_trace()
```

### Using VS Code Debugger

Create `.vscode/launch.json`:

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Bot",
            "type": "python",
            "request": "launch",
            "module": "app",
            "justMyCode": true,
            "env": {
                "LOG_LEVEL": "DEBUG"
            }
        }
    ]
}
```

### Celery Debugging

```bash
# Run worker in foreground with verbose output
celery -A app.celery_config worker -l debug --pool=solo

# Inspect tasks
celery -A app.celery_config inspect active

# View task stats
celery -A app.celery_config inspect stats
```

## Common Commands

```bash
# Make targets
make help              # Show all available commands
make up                # Start Docker containers
make down              # Stop Docker containers
make logs              # View Docker logs
make test              # Run tests
make lint              # Run linters
make fmt               # Format code
make shell             # Open Python shell with app context

# Docker commands
docker-compose up -d   # Start services in background
docker-compose logs -f # Follow logs
docker-compose exec bot bash  # Shell into bot container
docker-compose down    # Stop and remove containers
docker-compose ps      # List running services

# Celery commands
celery -A app.celery_config worker --loglevel=info
celery -A app.celery_config beat
celery -A app.celery_config flower
celery -A app.celery_config inspect active_queues
```

## Useful Development Tips

### 1. Hot Reload

For faster development, you can use watchdog:

```bash
pip install watchdog[watchmedo]
watchmedo auto-restart -d app/ -p '*.py' -- python -m app
```

### 2. Interactive Shell

```bash
# Django-like shell with app context
python -c "from app import *; import code; code.interact(local=locals())"

# Or use ipython
pip install ipython
python -m app shell
```

### 3. Database Browser

```bash
# pgAdmin web interface (already in docker-compose)
# Access at http://localhost:5050
# Login with PGADMIN_DEFAULT_EMAIL and PGADMIN_DEFAULT_PASSWORD

# Or use psql
psql -h localhost -U postgres -d tg_autoposter
```

### 4. Monitor Celery Tasks

```bash
# Open Flower dashboard
open http://localhost:5555

# Or monitor from CLI
watch -n 1 'celery -A app.celery_config inspect active'
```

### 5. Create Test Data

```bash
python -c "
import asyncio
from app.db import get_session
from app.models import Group

async def create_test_group():
    async with get_session() as session:
        group = Group(chat_id=123456, title='Test Group')
        session.add(group)
        await session.commit()

asyncio.run(create_test_group())
"
```

## Troubleshooting

### PostgreSQL Connection Issues

```bash
# Check if PostgreSQL is running
docker-compose ps postgres

# Check logs
docker-compose logs postgres

# Restart
docker-compose restart postgres
```

### Redis Connection Issues

```bash
# Check if Redis is running
docker-compose ps redis

# Check Redis connectivity
redis-cli ping

# Flush database (WARNING: clears all data)
redis-cli FLUSHDB
```

### Celery Worker Issues

```bash
# Check active workers
celery -A app.celery_config inspect active_workers

# View pending tasks
celery -A app.celery_config inspect reserved

# Revoke a task
celery -A app.celery_config revoke <task_id>

# Clear queue
celery -A app.celery_config purge
```

### Bot Not Responding

```bash
# Check bot logs
docker-compose logs bot

# Verify bot token in .env
echo $TELEGRAM_BOT_TOKEN

# Test API connection
python -c "
from pyrogram import Client
app = Client('test')
# This will verify API credentials
"
```

## Contributing

1. Create feature branch: `git checkout -b feature/my-feature`
2. Make changes and test locally
3. Format code: `make fmt`
4. Run tests: `make test`
5. Run linters: `make lint`
6. Commit with message: `git commit -m "feat: add my feature"`
7. Push and create Pull Request

## Resources

- [Telegram Bot API Docs](https://core.telegram.org/bots/api)
- [Pyrogram Documentation](https://docs.pyrogram.org/)
- [Telethon Documentation](https://docs.telethon.dev/)
- [Celery Documentation](https://docs.celeryproject.io/)
- [APScheduler Documentation](https://apscheduler.readthedocs.io/)
- [SQLAlchemy Async](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)

## Getting Help

- Check existing issues and discussions
- Review documentation in `/docs` folder
- Look at examples in `/examples` folder
- Check logs for error messages
- Ask in project discussions

## License

MIT License - see LICENSE file for details