init commit

docs/DEVELOPMENT.md

@@ -0,0 +1,388 @@
+# 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