StickerAI-Front/ARCHITECTURE.md

# Архитектура Telegram MiniApp для генерации стикеров

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

Приложение представляет собой Telegram MiniApp для генерации стикеров из пользовательских изображений. Архитектура построена на принципе разделения клиентской и серверной логики, где все API запросы выполняются через сервер.

## Компоненты системы

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

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

### 1. Регистрация пользователя
```http
POST /users
Content-Type: application/json

{
  "user_id": 12345,
  "username": "john_doe",
  "chat_id": 123456789,
  "balance": 0
}

Response (201):
{
  "user_id": 1,
  "username": "john_doe",
  "chat_id": 123456789,
  "balance": 100
}
```

### 2. Получение информации о пользователе
```http
GET /users
Content-Type: application/json

{
  "user_id": "12345"
}

Response (200):
{
  "user_id": 12345,
  "username": "john_doe",
  "chat_id": 123456789,
  "balance": 0
}
```

### 3. Генерация изображения
```http
POST /generate_image/{user_id}
Content-Type: multipart/form-data

file: binary

Response (200):
"string" (prompt_id)
```

### 4. Получение списка изображений
```http
GET /images_links/{user_id}

Response (200):
[
  {
    "id": 0,
    "link": "string",
    "path": "string",
    "prompt_id": "string",
    "status": "string",
    "created_at": "2025-02-24T13:22:11.690Z"
  }
]
```

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

```mermaid
graph TD
    A[Клиент] -->|1. Выбор фото| B[Локальная обработка]
    B -->|2. Кроп фото| C[Подготовка данных]
    C -->|3. WebApp.sendData| D[Ваш сервер]
    D -->|4. Запрос к API| E[API генерации]
    E -->|5. Результат| D
    D -->|6. Ответ боту| F[Telegram бот]
    F -->|7. Уведомление| G[Пользователь]
```

## Структуры данных

### Клиентская часть

```typescript
// Интерфейс для работы с Telegram WebApp
interface WebAppUser {
  id: number;
  username: string;
  // другие поля из WebApp
}

// Запрос на генерацию
interface GenerationRequest {
  photo: Blob;
  style: string;
  userId: number;
  username: string;
}

// Результат генерации
interface GenerationResult {
  status: 'success' | 'error';
  stickerUrl?: string;
  error?: string;
}

// Информация об изображении
interface GeneratedImage {
  id: number;
  link: string;
  path: string;
  prompt_id: string;
  status: string;
  created_at: string;
}
```

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

```typescript
// src/services/webApp.ts
const webAppService = {
  // Получение информации о пользователе
  getUserInfo(): WebAppUser {
    return window.Telegram.WebApp.initDataUnsafe.user;
  },

  // Показ уведомления
  showAlert(message: string): void {
    window.Telegram.WebApp.showAlert(message);
  },

  // Показ подтверждения
  showConfirm(message: string): Promise<boolean> {
    return window.Telegram.WebApp.showConfirm(message);
  },

  // Отправка данных на сервер
  sendData(data: GenerationRequest): void {
    window.Telegram.WebApp.sendData(JSON.stringify(data));
  }
};
```

## Процесс обработки изображения

1. **Клиентская часть:**
   - Загрузка изображения
   - Локальная обработка (кроп, ресайз)
   - Подготовка данных для отправки
   - Отправка через WebApp.sendData()

2. **Серверная часть:**
   - Получение данных от WebApp
   - Валидация пользователя
   - Проверка баланса
   - Отправка запроса на генерацию
   - Сохранение результата
   - Отправка уведомления через бота

## Обработка ошибок

```typescript
enum ApiErrorType {
  USER_NOT_FOUND = 'USER_NOT_FOUND',
  VALIDATION_ERROR = 'VALIDATION_ERROR',
  NETWORK_ERROR = 'NETWORK_ERROR',
  GENERATION_FAILED = 'GENERATION_FAILED'
}

interface ApiError {
  type: ApiErrorType;
  message: string;
  details?: any;
}
```

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

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

## Оптимизации

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

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

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