# Product Image Carousel Feature

## Overview
The TeleBot now supports displaying products with images in beautiful carousel format, making the shopping experience more visual and engaging.

## Features

### 🖼️ Image Carousels
- **Product Images**: Automatically displays product images from the API
- **Media Groups**: Groups up to 10 products per carousel for optimal viewing
- **Image Caching**: Downloads and caches images locally for faster loading
- **Fallback Support**: Gracefully falls back to text-only display if images fail

### 🛍️ Enhanced Browsing
- **New Command**: `/products` - Browse all products with images
- **Category Support**: `/products <categoryId>` - Browse specific category with images
- **Pagination**: Navigate through multiple pages of products
- **Single Product View**: Individual products shown with high-quality images

### 🎨 User Experience
- **Visual Appeal**: Products displayed with images, names, prices, and descriptions
- **Interactive Buttons**: Easy navigation and product selection
- **Responsive Design**: Optimized for mobile and desktop viewing
- **Fast Loading**: Cached images load instantly

## Usage

### Commands
```
/products              - View all products with images
/products <categoryId> - View products in specific category
/browse               - Browse categories (existing functionality)
```

### Menu Options
- **🖼️ View Products with Images** - Main menu option for image browsing
- **🛍️ Browse Categories** - Traditional category browsing

### Callback Data Format
```
products:page:<pageNumber>     - Pagination for all products
products:<categoryId>:<page>   - Pagination for specific category
product:<productId>            - View individual product with image
```

## Technical Implementation

### Services
- **ProductCarouselService**: Handles image downloading, caching, and carousel generation
- **Image Caching**: Local file system caching in `image_cache/` directory
- **HTTP Client**: Configured for downloading product images
- **Error Handling**: Graceful fallback to text-only display

### Image Processing
- **Format Support**: JPG, PNG, WebP, and other common formats
- **Validation**: Checks image URLs before downloading
- **Caching Strategy**: Files cached with product and photo IDs
- **Memory Management**: Streams images efficiently

### Telegram Integration
- **Media Groups**: Uses `SendMediaGroupAsync` for carousels
- **Photo Messages**: Individual products with `SendPhotoAsync`
- **Inline Keyboards**: Navigation and interaction buttons
- **Error Recovery**: Fallback to text messages if media fails

## Configuration

### Required Settings
```json
{
  "LittleShop": {
    "ApiUrl": "https://your-api-url.com"
  }
}
```

### Optional Settings
```json
{
  "Features": {
    "EnableQRCodes": true
  }
}
```

## File Structure
```
TeleBot/
├── Services/
│   └── ProductCarouselService.cs    # Main carousel service
├── Handlers/
│   ├── CommandHandler.cs            # Updated with /products command
│   └── CallbackHandler.cs           # Updated with carousel callbacks
├── UI/
│   ├── MenuBuilder.cs               # Updated with new menu options
│   └── MessageFormatter.cs          # Updated with carousel support
└── image_cache/                     # Local image cache directory
```

## Benefits

### For Users
- **Visual Shopping**: See products before buying
- **Better Experience**: More engaging than text-only browsing
- **Faster Navigation**: Quick access to product images
- **Mobile Friendly**: Optimized for mobile devices

### For Business
- **Higher Conversion**: Visual products increase sales
- **Professional Look**: Modern, polished appearance
- **User Engagement**: More time spent browsing
- **Competitive Edge**: Stand out from text-only bots

## Future Enhancements

### Planned Features
- **Image Optimization**: Automatic resizing and compression
- **Lazy Loading**: Load images on demand
- **Multiple Images**: Support for product galleries
- **Image Search**: Search products by visual similarity
- **Video Support**: Product videos in carousels

### Performance Improvements
- **CDN Integration**: Use CDN for image delivery
- **Progressive Loading**: Show low-res images first
- **Batch Processing**: Optimize multiple image downloads
- **Memory Optimization**: Better memory management

## Troubleshooting

### Common Issues
1. **Images Not Loading**: Check API image URLs and network connectivity
2. **Slow Performance**: Clear image cache or check disk space
3. **Memory Usage**: Monitor cache size and implement cleanup
4. **API Errors**: Verify LittleShop API configuration

### Debug Information
- Check logs for image download errors
- Monitor cache directory size
- Verify product photo data from API
- Test with different image formats

## Support
For issues or questions about the carousel feature, check the logs or contact the development team.
