interview-demo-code/.cursor/rules/architecture.md

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

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 с префиксом megapay_

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