Files

Nikita Kiselev 9a93cc7342 feat: add Telegram customers management system with admin panel

Implement comprehensive Telegram customers storage and management functionality:

Backend:
- Add database migration for telecart_customers table with indexes
- Create TelegramCustomer model with CRUD operations
- Implement TelegramCustomerService for business logic
- Add TelegramCustomerHandler for API endpoint (saveOrUpdate)
- Add TelegramCustomersHandler for admin API (getCustomers with pagination, filtering, sorting)
- Add SendMessageHandler for sending messages to customers via Telegram
- Create custom exceptions: TelegramCustomerNotFoundException, TelegramCustomerWriteNotAllowedException
- Refactor TelegramInitDataDecoder to separate decoding logic
- Add TelegramHeader enum for header constants
- Update SignatureValidator to use TelegramInitDataDecoder
- Register new routes in bastion/routes.php and src/routes.php

Frontend (Admin):
- Add CustomersView.vue component with PrimeVue DataTable
- Implement advanced filtering (text, date, boolean filters)
- Add column visibility toggle functionality
- Add global search with debounce
- Implement message sending dialog with validation
- Add Russian locale for PrimeVue components
- Add navigation link in App.vue
- Register route in router

Frontend (SPA):
- Add saveTelegramCustomer utility function
- Integrate automatic customer data saving on app initialization
- Extract user data from Telegram.WebApp.initDataUnsafe

The system automatically saves/updates customer data when users access the Telegram Mini App,
and provides admin interface for viewing, filtering, and messaging customers.

BREAKING CHANGE: None

2025-11-23 21:30:51 +03:00

4.4 KiB

Raw Blame History

Архитектурные правила

OpenCart Framework Architecture

MVC-L Pattern

Проект использует модифицированный паттерн MVC-L (Model-View-Controller-Language):

Model: Классы в src/Models/ - работа с данными, доступ к БД
View: Vue компоненты на фронтенде, JSON ответы на бэкенде
Controller: Handlers в src/Handlers/ и bastion/Handlers/
Language: Переводчик в framework/Translator/

Dependency Injection

Все зависимости внедряются через Container:

// ✅ Правильно
public function __construct(
    private Builder $builder,
    private TelegramCustomer $telegramCustomerModel
) {}

// ❌ Неправильно
public function __construct() {
    $this->builder = new Builder(...);
}

Service Providers

Регистрация сервисов через Service Providers:

class MyServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(MyService::class, function ($app) {
            return new MyService($app->get(Dependency::class));
        });
    }
}

Routes

Маршруты определяются в routes.php:

return [
    'actionName' => [HandlerClass::class, 'methodName'],
];

Handlers (Controllers)

Handlers обрабатывают HTTP запросы:

class MyHandler
{
    public function handle(Request $request): JsonResponse
    {
        // Валидация
        // Бизнес-логика через Services
        // Возврат JsonResponse
    }
}

Models

Models работают с данными:

class MyModel
{
    public function __construct(
        private ConnectionInterface $database,
        private Builder $builder
    ) {}
    
    public function findById(int $id): ?array
    {
        return $this->builder->newQuery()
            ->from($this->tableName)
            ->where('id', '=', $id)
            ->firstOrNull();
    }
}

Services

Services содержат бизнес-логику:

class MyService
{
    public function __construct(
        private MyModel $model
    ) {}
    
    public function doSomething(array $data): array
    {
        // Бизнес-логика
        return $this->model->create($data);
    }
}

Migrations

Миграции в database/migrations/:

return new class extends Migration {
    public function up(): void
    {
        $this->database->statement('CREATE TABLE ...');
    }
};

Query Builder

Всегда используй Query Builder вместо прямых SQL:

// ✅ Правильно
$query = $this->builder->newQuery()
    ->select(['id', 'name'])
    ->from('table_name')
    ->where('status', '=', 'active')
    ->get();

// ❌ Неправильно
$result = $this->database->query("SELECT * FROM table_name WHERE status = 'active'");

Frontend Architecture

Admin Panel (Vue 3)

Composition API
Pinia для state management
PrimeVue для UI компонентов
Axios для HTTP запросов
Vue Router для навигации

SPA (Telegram Mini App)

Composition API
Pinia stores
Tailwind CSS для стилей
Telegram WebApp API
Vue Router

Naming Conventions

Classes: PascalCase (TelegramCustomerService)
Methods: camelCase (getCustomers)
Variables: camelCase ($customerData)
Constants: UPPER_SNAKE_CASE (MAX_RETRIES)
Files: PascalCase для классов, kebab-case для остального
Tables: snake_case с префиксом telecart_

Error Handling

Всегда обрабатывай ошибки:

try {
    $result = $this->service->doSomething();
} catch (SpecificException $e) {
    $this->logger->error('Error message', ['exception' => $e]);
    throw new UserFriendlyException('User message');
}

Configuration

Используй конфигурационные файлы в configs/:

$config = $this->app->getConfigValue('app.setting_name');

Caching

Используй Cache Service для кэширования:

$cache = $this->app->get(CacheInterface::class);
$value = $cache->get('key', function() {
    return expensiveOperation();
});

4.4 KiB Raw Blame History Unescape Escape