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:

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

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

### Service Providers

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

```php
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`:

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

### Handlers (Controllers)

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

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

### Models

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

```php
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 содержат бизнес-логику:

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

### Migrations

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

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

### Query Builder

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

```php
// ✅ Правильно
$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

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

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

### Configuration

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

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

### Caching

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

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