245 lines
10 KiB
Markdown
245 lines
10 KiB
Markdown
# Обзор проекта 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
|