# Обзор проекта StickerBot

## Общее описание

StickerBot - это Telegram MiniApp для генерации стикеров из пользовательских изображений. Приложение позволяет пользователям загружать свои фотографии, обрезать их, выбирать стиль и образ для генерации стикеров, а затем получать готовые стикеры.

## Архитектура проекта

Проект построен на принципе разделения клиентской и серверной логики:

```mermaid
graph TD
    A[Клиент/MiniApp] --> B[Telegram WebApp API]
    A --> C[Сервер]
    C --> D[API генерации]
    
    B -- "user_id, username" --> C
    C -- "статус, результаты" --> A
```

### Технологический стек

- **Фронтенд**: React + TypeScript + Vite
- **Маршрутизация**: React Router
- **Стили**: CSS Modules
- **API**: REST API

## Структура проекта

### Основные директории

- **src/components/** - компоненты пользовательского интерфейса
  - **blocks/** - переиспользуемые блоки UI (кнопки, поля ввода, загрузка фото)
  - **layout/** - компоненты макета (заголовок, навигация)
  - **shared/** - общие компоненты (просмотр изображений, обработка ошибок)
- **src/screens/** - экраны приложения
- **src/config/** - конфигурации (стили, экраны)
- **src/constants/** - константы (базовый воркфлоу)
- **src/services/** - сервисы для работы с API
- **src/types/** - типы TypeScript
- **src/assets/** - статические ресурсы (изображения, промпты)

### Ключевые файлы

- **src/App.tsx** - основной компонент приложения с маршрутизацией
- **src/main.tsx** - точка входа в приложение
- **src/screens/Home.tsx** - домашний экран
- **src/screens/CropPhoto.tsx** - экран обрезки фото
- **src/services/api.ts** - сервис для работы с API
- **src/config/homeScreen.ts** - конфигурация домашнего экрана
- **src/config/stylePresets.ts** - предустановленные стили для стикеров
- **src/constants/baseWorkflow.ts** - базовый воркфлоу для генерации стикеров
- **src/assets/prompts.ts** - промпты для генерации стикеров

## Маршрутизация

Приложение использует React Router для навигации между экранами:

- **Онбординг**:
  - `/onboarding/welcome` - приветственный экран
  - `/onboarding/how-to` - инструкции по использованию
  - `/onboarding/sticker-packs` - информация о наборах стикеров
- **Основные экраны**:
  - `/` - домашний экран
  - `/create` - создание стикера
  - `/gallery` - галерея сгенерированных стикеров
  - `/packs` - наборы стикеров
  - `/profile` - профиль пользователя
  - `/history` - история генераций
  - `/crop-photo` - обрезка фото

## Компонентная структура

### Блоки UI

Приложение использует компонентный подход с блоками UI, которые рендерятся через компонент BlockRenderer:

- **ScrollableButtonsBlock** - блок с прокручиваемыми кнопками
- **GridButtonsBlock** - блок с сеткой кнопок
- **UploadPhotoBlock** - блок для загрузки фото
- **DividerBlock** - разделитель
- **TextInputBlock** - блок для ввода текста
- **GenerateButton** - кнопка для генерации стикеров
- **StepTitle** - заголовок шага

### Макет

Компонент Layout обеспечивает общую структуру интерфейса:

- **Header** - заголовок
- **Navigation** - навигация
- **ErrorBoundary** - обработка ошибок
- **Suspense** - обработка состояния загрузки

## Процесс генерации стикера

```mermaid
graph TD
    A[Загрузка фото] -->|Перенаправление на экран обрезки| B[Обрезка фото]
    B -->|Возврат на главный экран| C[Выбор стиля]
    C --> D[Выбор образа]
    D --> E[Генерация стикера]
    E -->|API запрос| F[Получение результата]
```

1. **Загрузка изображения**:
   - Пользователь загружает фото через компонент UploadPhotoBlock
   - Поддерживается перетаскивание и выбор файла

2. **Обрезка изображения**:
   - Пользователь перенаправляется на экран CropPhoto
   - Возможность масштабирования и перемещения изображения
   - Выбор области для стикера
   - Преобразование в base64 и передача на главный экран

3. **Выбор стиля**:
   - Доступные стили: чиби, реализм, эмоции
   - Каждый стиль имеет свои предустановленные образы

4. **Выбор образа**:
   - Для стиля "чиби": спорткар, скейтборд, кофе, цветы и т.д.
   - Для стиля "реализм": деловой, повседневный, спортивный и т.д.
   - Для стиля "эмоции": радость, грусть, злость и т.д.

5. **Генерация стикера**:
   - Отправка запроса на сервер через API
   - Использование базового воркфлоу с заменой изображения и промпта

## Взаимодействие с API

### API Эндпоинты

- **POST /generate_image** - генерация изображения
- **GET /images_links/{user_id}** - получение списка изображений

### Сервис API

Сервис apiService предоставляет методы:

- **getGeneratedImages** - получение списка сгенерированных изображений
- **generateImage** - генерация нового изображения

### Процесс генерации

1. Создание копии базового воркфлоу
2. Вставка изображения в формате base64
3. Замена промпта в зависимости от выбранного образа
4. Отправка запроса на сервер
5. Получение результата

## Стили и образы

### Стили

- **chibi** - стиль чиби (мультяшный, милый)
- **realism** - реалистичный стиль
- **emotions** - стиль эмоций

### Образы для стиля "чиби"

- спорткар
- скейтборд
- кофе
- цветы
- шарик
- книга
- мороженое
- зонт
- коктейль
- подарок
- собака
- газета
- велосипед
- серфер
- детектив
- байкер
- фея
- ученый
- ковбой
- рыцарь
- балерина
- пожарный
- шеф-повар

### Образы для стиля "реализм"

- деловой
- повседневный
- спортивный
- вечерний
- пляжный
- зимний
- ретро
- киберпанк
- военный
- стимпанк

### Образы для стиля "эмоции"

- радость
- грусть
- злость
- любовь
- удивление
- страх
- сонный
- крутой
- глупый
- думающий

## Технические особенности

### Конфигурационный подход

Интерфейс строится на основе конфигурации (homeScreenConfig), что позволяет легко изменять структуру экранов без изменения кода.

### Компонент BlockRenderer

Рендерит различные блоки в зависимости от их типа, что обеспечивает гибкость и переиспользуемость компонентов.

### Воркфлоу генерации

Сложная конфигурация для нейросети (baseWorkflow), которая включает в себя различные модели и операции для генерации стикеров.

### Обработка изображений

- Локальная обработка изображений перед отправкой
- Кэширование результатов в галерее
- Отложенная загрузка изображений
- Обработка состояний загрузки и ошибок

## Безопасность

1. Все API запросы выполняются только через сервер
2. Клиент не имеет прямого доступа к API генерации
3. Валидация пользователя происходит на сервере
4. Проверка баланса выполняется на сервере перед генерацией

## Дальнейшее развитие

1. Добавление новых стилей генерации
2. Система рейтинга стикеров
3. Социальные функции (шаринг, коллекции)
4. Интеграция с другими сервисами Telegram