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

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

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

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

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

API Эндпоинты

1. Регистрация пользователя

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. Получение информации о пользователе

GET /users
Content-Type: application/json

{
  "user_id": "12345"
}

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

3. Генерация изображения

POST /generate_image/{user_id}
Content-Type: multipart/form-data

file: binary

Response (200):
"string" (prompt_id)

4. Получение списка изображений

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"
  }
]

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

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[Пользователь]

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

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

// Интерфейс для работы с 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

// 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));
  }
};

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

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

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

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;
}

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

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

Оптимизации

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

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

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

5.7 KiB Raw Blame History Unescape Escape