Squashed commit message

.cursor/rules/architecture.md

@@ -0,0 +1,201 @@
+# Архитектурные правила
+
+## 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 с префиксом `megapay_`
+
+### 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();
+});
+```
+