Squashed commit message

.cursor/rules/architecture.md

@@ -0,0 +1,201 @@
+# Architectural Rules
+
+## ECommerce Framework Architecture
+
+### MVC-L Pattern
+
+The project uses a modified MVC-L pattern (Model-View-Controller-Language):
+
+- **Model**: Classes in `src/Models/` – data access and database operations
+- **View**: Vue components on the frontend, JSON responses on the backend
+- **Controller**: Handlers in `src/Handlers/` and `bastion/Handlers/`
+- **Language**: Translator in `framework/Translator/`
+
+### Dependency Injection
+
+All dependencies are injected via the Container:
+
+```php
+// ✅ Correct
+public function __construct(
+    private Builder $builder,
+    private TelegramCustomer $telegramCustomerModel
+) {}
+
+// ❌ Incorrect
+public function __construct() {
+    $this->builder = new Builder(...);
+}
+```
+
+### Service Providers
+
+Services are registered via 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 are defined in `routes.php`:
+
+```php
+return [
+    'actionName' => [HandlerClass::class, 'methodName'],
+];
+```
+
+### Handlers (Controllers)
+
+Handlers process HTTP requests:
+
+```php
+class MyHandler
+{
+    public function handle(Request $request): JsonResponse
+    {
+        // Validation
+        // Business logic via Services
+        // Return JsonResponse
+    }
+}
+```
+
+### Models
+
+Models work with data:
+
+```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 contain business logic:
+
+```php
+class MyService
+{
+    public function __construct(
+        private MyModel $model
+    ) {}
+    
+    public function doSomething(array $data): array
+    {
+        // Business logic
+        return $this->model->create($data);
+    }
+}
+```
+
+### Migrations
+
+Migrations live in `database/migrations/`:
+
+```php
+return new class extends Migration {
+    public function up(): void
+    {
+        $this->database->statement('CREATE TABLE ...');
+    }
+};
+```
+
+### Query Builder
+
+Always use Query Builder instead of raw SQL:
+
+```php
+// ✅ Correct
+$query = $this->builder->newQuery()
+    ->select(['id', 'name'])
+    ->from('table_name')
+    ->where('status', '=', 'active')
+    ->get();
+
+// ❌ Incorrect
+$result = $this->database->query("SELECT * FROM table_name WHERE status = 'active'");
+```
+
+### Frontend Architecture
+
+#### Admin Panel (Vue 3)
+
+- Composition API
+- Pinia for state management
+- PrimeVue for UI components
+- Axios for HTTP requests
+- Vue Router for navigation
+
+#### SPA (Telegram Mini App)
+
+- Composition API
+- Pinia stores
+- Tailwind CSS for styles
+- Telegram WebApp API
+- Vue Router
+
+### Naming Conventions
+
+- **Classes**: PascalCase (`TelegramCustomerService`)
+- **Methods**: camelCase (`getCustomers`)
+- **Variables**: camelCase (`$customerData`)
+- **Constants**: UPPER_SNAKE_CASE (`MAX_RETRIES`)
+- **Files**: PascalCase for classes, kebab-case for everything else
+- **Tables**: snake_case with `acmeshop_` prefix
+
+### Error Handling
+
+Always handle errors:
+
+```php
+try {
+    $result = $this->service->doSomething();
+} catch (SpecificException $e) {
+    $this->logger->error('Error message', ['exception' => $e]);
+    throw new UserFriendlyException('User message');
+}
+```
+
+### Configuration
+
+Use configuration files in `configs/`:
+
+```php
+$config = $this->app->getConfigValue('app.setting_name');
+```
+
+### Caching
+
+Use Cache Service for caching:
+
+```php
+$cache = $this->app->get(CacheInterface::class);
+$value = $cache->get('key', function() {
+    return expensiveOperation();
+});
+```
+

.cursor/rules/form-builder.md

@@ -0,0 +1,70 @@
+# FormBuilder System Context
+
+## Architectural Overview
+The FormBuilder ecosystem is a strictly typed Vue 3 application module designed to generate standard FormKit Schema JSON. It eschews internal DTOs in favor of direct schema manipulation.
+
+### Core Components
+1.  **FormBuilderView (`views/FormBuilderView.vue`)**:
+    *   **Role**: Smart container / Data fetcher.
+    *   **Responsibility**: Fetches form data from API (`GET /api/admin/forms/{alias}`), handles loading states, and passes data to `FormBuilder`.
+    *   **Contract**: Expects API response `{ data: { schema: Array, is_custom: Boolean, ... } }`.
+
+2.  **FormBuilder (`components/FormBuilder/FormBuilder.vue`)**:
+    *   **Role**: Main Orchestrator / State Owner.
+    *   **Responsibility**: Manages `v-model` (schema), mode switching (Visual/Code/Preview), and provides state to children.
+    *   **State Management**: Uses `defineModel` for `formFields` (schema) and `isCustom` (mode flag). Uses `provide('formFields')` and `provide('selectedFieldId')` for deep dependency injection.
+    *   **Modes**:
+        *   **Visual**: Drag-and-drop interface using `vuedraggable`.
+        *   **Code**: Direct JSON editing of the FormKit schema. Sets `isCustom = true`.
+        *   **Preview**: Renders the current schema using `FormKit`.
+
+3.  **FormCanvas (`components/FormBuilder/FormCanvas.vue`)**:
+    *   **Role**: Visual Editor Surface.
+    *   **Responsibility**: Renders the draggable list of fields.
+    *   **Implementation**: Uses `vuedraggable` bound to `formFields`.
+    *   **UX**: Implements "Ghost" and "Drag" classes for visual feedback. Handles selection logic.
+
+4.  **FieldsPanel (`components/FormBuilder/FieldsPanel.vue`)**:
+    *   **Role**: Component Palette.
+    *   **Responsibility**: Source of truth for available field types.
+    *   **Implementation**: Uses `vuedraggable` with `pull: 'clone', put: false` to spawn new fields.
+
+5.  **FieldSettings (`components/FormBuilder/FieldSettings.vue`)**:
+    *   **Role**: Property Editor.
+    *   **Responsibility**: Edits properties of the `selectedFieldId`.
+    *   **Constraint**: Must use PrimeVue components for all inputs.
+
+## Data Flow & Invariants
+1.  **Schema Authority**: The FormKit Schema JSON is the single source of truth. There is no "internal model" separate from the schema.
+2.  **Reactivity**:
+    *   `formFields` is an Array of Objects.
+    *   Mutations must preserve reactivity. When using `v-model` or `provide/inject`, ensure array methods (splice, push, filter) are used correctly or replace the entire array reference if needed to trigger watchers.
+    *   **Immutability**: `useFormFields` composable uses immutable patterns (returning new array references) to ensure `defineModel` in parent detects changes.
+3.  **Mode Logic**:
+    *   Switching to **Code** mode sets `isCustom = true`.
+    *   Switching to **Visual** mode sets `isCustom = false`.
+    *   **Safety**: Switching modes triggers JSON validation. Invalid JSON prevents mode switch.
+4.  **Drag and Drop**:
+    *   Powered by `vuedraggable` (Sortable.js).
+    *   **Clone Logic**: `FieldsPanel` clones from `availableFields`. `FormCanvas` receives the clone.
+    *   **ID Generation**: Unique IDs are generated upon cloning/addition to ensure key stability.
+
+## Naming & Conventions
+*   **Tailwind**: Use `tw:` prefix for all utility classes (e.g., `tw:flex`, `tw:p-4`).
+*   **Components**: PrimeVue components are the standard UI kit (Button, Panel, InputText, etc.).
+*   **Icons**: FontAwesome (`fa fa-*`).
+*   **Files**: PascalCase for components (`FormBuilder.vue`), camelCase for logic (`useFormFields.js`).
+
+## Integration Rules
+*   **Backend**: The backend stores the JSON blob directly. `FormBuilder` does not transform data before save; it emits the raw schema.
+*   **API**: `useFormsStore` handles API communication.
+
+## Pitfalls & Warnings
+*   **vuedraggable vs @formkit/drag-and-drop**: We strictly use `vuedraggable`. Do not re-introduce `@formkit/drag-and-drop`.
+*   **Watchers**: Avoid `watch` where `computed` or event handlers suffice, to prevent infinite loops in bidirectional data flow.
+*   **Tailwind Config**: Do not use `@apply` with `tw:` prefixed classes in `<style>` blocks; standard CSS properties should be used if custom classes are needed.
+
+## Future Modifications
+*   **Adding Fields**: Update `constants/availableFields.js` and ensure `utils/fieldHelpers.js` supports the new type.
+*   **Validation**: FormKit validation rules string (e.g., "required|email") is edited as a raw string in `FieldSettings`. Complex validation builders would require a new UI component.
+

.cursor/rules/javascript.md

@@ -0,0 +1,332 @@
+# JavaScript/TypeScript Code Style Rules
+
+## JavaScript Version
+
+- ES2020+ features
+- Modern async/await
+- Optional chaining (`?.`)
+- Nullish coalescing (`??`)
+- Template literals
+
+## Code Style
+
+### Variable Declarations
+
+```javascript
+// ✅ Use const by default
+const customers = [];
+const totalRecords = 0;
+
+// ✅ Use let only when reassignment is needed
+let currentPage = 1;
+currentPage = 2;
+
+// ❌ Do not use var
+var oldVariable = 'bad';
+```
+
+### Arrow Functions
+
+```javascript
+// ✅ Preferred for short functions
+const filtered = items.filter(item => item.isActive);
+
+// ✅ For object methods
+const api = {
+  get: async (url) => {
+    return await fetch(url);
+  }
+};
+
+// ✅ For complex logic – use regular functions
+function complexCalculation(data) {
+  // many lines of code
+  return result;
+}
+```
+
+### Template Literals
+
+```javascript
+// ✅ Preferred
+const message = `User ${userId} not found`;
+const url = `${baseUrl}/api/${endpoint}`;
+
+// ❌ Do not use concatenation
+const message = 'User ' + userId + ' not found';
+```
+
+### Optional Chaining
+
+```javascript
+// ✅ Use optional chaining
+const name = user?.profile?.name;
+const count = data?.items?.length ?? 0;
+
+// ❌ Avoid long nested checks
+const name = user && user.profile && user.profile.name;
+```
+
+### Nullish Coalescing
+
+```javascript
+// ✅ Use ?? for default values
+const page = params.page ?? 1;
+const name = user.name ?? 'Unknown';
+
+// ❌ Do not use || for numbers/booleans
+const page = params.page || 1; // 0 will be replaced with 1
+```
+
+### Destructuring
+
+```javascript
+// ✅ Use destructuring
+const { data, totalRecords } = response.data;
+const [first, second] = items;
+
+// ✅ In function parameters
+function processUser({ id, name, email }) {
+  // ...
+}
+
+// ✅ With default values
+const { page = 1, limit = 20 } = params;
+```
+
+### Async/Await
+
+```javascript
+// ✅ Preferred
+async function loadCustomers() {
+  try {
+    const response = await apiGet('getCustomers', params);
+    return response.data;
+  } catch (error) {
+    console.error('Error:', error);
+    throw error;
+  }
+}
+
+// ❌ Avoid .then() chains
+function loadCustomers() {
+  return apiGet('getCustomers', params)
+    .then(response => response.data)
+    .catch(error => console.error(error));
+}
+```
+
+## Vue.js 3 Composition API
+
+### Script Setup
+
+```vue
+<script setup>
+// ✅ Use <script setup>
+import { ref, computed, onMounted } from 'vue';
+import { apiGet } from '@/utils/http.js';
+
+const customers = ref([]);
+const loading = ref(false);
+
+const totalRecords = computed(() => customers.value.length);
+
+async function loadCustomers() {
+  loading.value = true;
+  try {
+    const result = await apiGet('getCustomers');
+    customers.value = result.data || [];
+  } finally {
+    loading.value = false;
+  }
+}
+
+onMounted(() => {
+  loadCustomers();
+});
+</script>
+```
+
+### Reactive State
+
+```javascript
+// ✅ Use ref for primitives
+const count = ref(0);
+const name = ref('');
+
+// ✅ Use reactive for objects
+import { reactive } from 'vue';
+const state = reactive({
+  customers: [],
+  loading: false
+});
+
+// ✅ Or ref for objects (preferred)
+const state = ref({
+  customers: [],
+  loading: false
+});
+```
+
+### Computed Properties
+
+```javascript
+// ✅ Use computed for derived values
+const filteredCustomers = computed(() => {
+  return customers.value.filter(c => c.isActive);
+});
+
+// ❌ Do not use methods for derived values
+function filteredCustomers() {
+  return customers.value.filter(c => c.isActive);
+}
+```
+
+### Props
+
+```vue
+<script setup>
+// ✅ Define props with types
+const props = defineProps({
+  customerId: {
+    type: Number,
+    required: true
+  },
+  showDetails: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+```
+
+### Emits
+
+```vue
+<script setup>
+// ✅ Define emits
+const emit = defineEmits(['update', 'delete']);
+
+function handleUpdate() {
+  emit('update', data);
+}
+</script>
+```
+
+## Pinia Stores
+
+```javascript
+// ✅ Use setup stores
+import { defineStore } from 'pinia';
+import { ref, computed } from 'vue';
+
+export const useCustomersStore = defineStore('customers', () => {
+  const customers = ref([]);
+  const loading = ref(false);
+  
+  const totalRecords = computed(() => customers.value.length);
+  
+  async function loadCustomers() {
+    loading.value = true;
+    try {
+      const result = await apiGet('getCustomers');
+      customers.value = result.data || [];
+    } finally {
+      loading.value = false;
+    }
+  }
+  
+  return {
+    customers,
+    loading,
+    totalRecords,
+    loadCustomers
+  };
+});
+```
+
+## Error Handling
+
+```javascript
+// ✅ Always handle errors
+async function loadData() {
+  try {
+    const result = await apiGet('endpoint');
+    if (result.success) {
+      return result.data;
+    } else {
+      throw new Error(result.error);
+    }
+  } catch (error) {
+    console.error('Failed to load data:', error);
+    toast.error('Failed to load data');
+    throw error;
+  }
+}
+```
+
+## Naming Conventions
+
+### Variables and Functions
+
+```javascript
+// ✅ camelCase
+const customerData = {};
+const totalRecords = 0;
+function loadCustomers() {}
+
+// ✅ Constants in UPPER_SNAKE_CASE
+const MAX_RETRIES = 3;
+const API_BASE_URL = '/api';
+```
+
+### Components
+
+```vue
+<!-- ✅ PascalCase for components -->
+<CustomerCard />
+<ProductsList />
+```
+
+### Files
+
+```javascript
+// ✅ Use kebab-case for files
+// customers-view.vue
+// http-utils.js
+// customer-service.js
+```
+
+## Imports
+
+```javascript
+// ✅ Group imports
+// 1. Vue core
+import { ref, computed, onMounted } from 'vue';
+
+// 2. Third-party
+import { apiGet } from '@/utils/http.js';
+import { useToast } from 'primevue';
+
+// 3. Local components
+import CustomerCard from '@/components/CustomerCard.vue';
+
+// 4. Types (if using TypeScript)
+import type { Customer } from '@/types';
+```
+
+## TypeScript (where used)
+
+```typescript
+// ✅ Use types
+interface Customer {
+  id: number;
+  name: string;
+  email?: string;
+}
+
+function getCustomer(id: number): Promise<Customer> {
+  return apiGet(`customers/${id}`);
+}
+```
+

.cursor/rules/php.md

@@ -0,0 +1,243 @@
+# PHP Code Style Rules
+
+## PHP Version
+
+The project supports PHP 7.4+
+
+## PSR Standards
+
+- **PSR-1**: Basic Coding Standard
+- **PSR-4**: Autoloading Standard
+- **PSR-12**: Extended Coding Style
+
+## Code Style
+
+### Type Declarations
+
+```php
+// ✅ Correct – strict typing
+public function getCustomers(Request $request): JsonResponse
+{
+    $id = (int) $request->get('id');
+    return new JsonResponse(['data' => $customers]);
+}
+
+// ❌ Incorrect – no types
+public function getCustomers($request)
+{
+    return ['data' => $customers];
+}
+```
+
+### Nullable Types
+
+```php
+// ✅ Correct
+public function findById(?int $id): ?array
+{
+    if ($id === null) {
+        return null;
+    }
+    return $this->query->where('id', '=', $id)->firstOrNull();
+}
+```
+
+### Strict Types
+
+Always use `declare(strict_types=1);`:
+
+```php
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services;
+```
+
+### Array Syntax
+
+```php
+// ✅ Preferred – short syntax
+$array = ['key' => 'value'];
+
+// ❌ Do not use
+$array = array('key' => 'value');
+```
+
+### String Interpolation
+
+```php
+// ✅ Preferred
+$message = "User {$userId} not found";
+
+// ✅ Alternative
+$message = sprintf('User %d not found', $userId);
+```
+
+### Arrow Functions (PHP 7.4+)
+
+```php
+// ✅ For simple operations
+$filtered = array_filter($items, fn($item) => $item->isActive());
+
+// ❌ For complex logic – use regular functions
+```
+
+### Nullsafe Operator (PHP 8.0+)
+
+```php
+// ✅ For PHP 7.4
+$name = $user && $user->profile ? $user->profile->name : null;
+```
+
+## Naming Conventions
+
+### Classes
+
+```php
+// ✅ PascalCase
+class TelegramCustomerService {}
+class UserRepository {}
+```
+
+### Methods
+
+```php
+// ✅ camelCase
+public function getCustomers(): array {}
+public function saveOrUpdate(array $data): array {}
+```
+
+### Variables
+
+```php
+// ✅ camelCase
+$customerData = [];
+$totalRecords = 0;
+```
+
+### Constants
+
+```php
+// ✅ UPPER_SNAKE_CASE
+private const MAX_RETRIES = 3;
+public const DEFAULT_PAGE_SIZE = 20;
+```
+
+### Private Properties
+
+```php
+// ✅ camelCase with visibility modifier
+private string $tableName;
+private Builder $builder;
+```
+
+## Documentation
+
+### PHPDoc
+
+```php
+/**
+ * @throws ValidationException If parameters are invalid
+ */
+public function getCustomers(Request $request): JsonResponse
+{
+    // ...
+}
+```
+
+### Inline Comments
+
+```php
+// ✅ Useful comments
+// Apply filters to calculate total number of records
+$countQuery = $this->buildCountQuery($filters);
+
+// ❌ Obvious comments
+// Get data
+$data = $this->getData();
+```
+
+## Error Handling
+
+### Exceptions
+
+```php
+// ✅ Specific exceptions
+if (!$userId) {
+    throw new InvalidArgumentException('User ID is required');
+}
+
+// ✅ Logging
+try {
+    $result = $this->service->process();
+} catch (Exception $e) {
+    $this->logger->error('Processing failed', [
+        'exception' => $e,
+        'context' => $context,
+    ]);
+    throw new ProcessingException('Failed to process', 0, $e);
+}
+```
+
+## Query Builder Usage
+
+### Always Use Query Builder
+
+```php
+// ✅ Correct
+$customers = $this->builder->newQuery()
+    ->select(['id', 'name', 'email'])
+    ->from('acmeshop_customers')
+    ->where('status', '=', 'active')
+    ->orderBy('created_at', 'DESC')
+    ->get();
+
+// In edge cases raw SQL may be used
+$result = $this->database->query("SELECT * FROM acmeshop_customers");
+```
+
+### Parameter Binding
+
+```php
+// ✅ Query Builder automatically binds parameters
+$query->where('name', 'LIKE', "%{$search}%");
+
+// ❌ Never concatenate values into SQL, avoid SQL Injection.
+```
+
+## Array Access
+
+### Safe Array Access
+
+```php
+// ✅ Use Arr::get()
+use Acme\ECommerceFramework\Support\Arr;
+
+$value = Arr::get($data, 'key', 'default');
+
+// ❌ Unsafe
+$value = $data['key']; // may trigger an error
+```
+
+## Return Types
+
+```php
+// ✅ Always specify return type
+public function getData(): array {}
+public function findById(int $id): ?array {}
+public function process(): void {}
+
+// ❌ Without type
+public function getData() {}
+```
+
+## Visibility Modifiers
+
+```php
+// ✅ Always specify visibility modifier
+private string $tableName;
+protected Builder $builder;
+public function getData(): array {}
+```
+

.cursor/rules/vue.md

@@ -0,0 +1,370 @@
+# Vue.js 3 Rules
+
+## Component Structure
+
+### Template
+
+```vue
+<template>
+  <!-- ✅ Logical structure -->
+  <div class="container">
+    <header>
+      <h2>{{ title }}</h2>
+    </header>
+    
+    <main>
+      <DataTable :value="items" />
+    </main>
+    
+    <footer>
+      <Button @click="handleSave">Save</Button>
+    </footer>
+  </div>
+</template>
+```
+
+### Script Setup
+
+```vue
+<script setup>
+// ✅ Always use <script setup>
+import { ref, computed, onMounted } from 'vue';
+import DataTable from 'primevue/datatable';
+import { apiGet } from '@/utils/http.js';
+
+// Props
+const props = defineProps({
+  title: {
+    type: String,
+    required: true
+  }
+});
+
+// Emits
+const emit = defineEmits(['update', 'delete']);
+
+// State
+const items = ref([]);
+const loading = ref(false);
+
+// Computed
+const totalItems = computed(() => items.value.length);
+
+// Methods
+async function loadItems() {
+  loading.value = true;
+  try {
+    const result = await apiGet('getItems');
+    items.value = result.data || [];
+  } finally {
+    loading.value = false;
+  }
+}
+
+// Lifecycle
+onMounted(() => {
+  loadItems();
+});
+</script>
+```
+
+### Styles
+
+```vue
+<style scoped>
+/* ✅ Use scoped styles */
+.container {
+  padding: 1rem;
+}
+
+/* ✅ Use :deep() to style nested components */
+:deep(.p-datatable) {
+  border: 1px solid #ccc;
+}
+</style>
+```
+
+## Component Naming
+
+```vue
+<!-- ✅ PascalCase for components -->
+<CustomerCard />
+<ProductsList />
+<OrderDetails />
+
+<!-- ✅ kebab-case in templates also works -->
+<customer-card />
+```
+
+## Props
+
+```vue
+<script setup>
+// ✅ Always define types and validation
+const props = defineProps({
+  customerId: {
+    type: Number,
+    required: true,
+    validator: (value) => value > 0
+  },
+  showDetails: {
+    type: Boolean,
+    default: false
+  },
+  items: {
+    type: Array,
+    default: () => []
+  }
+});
+</script>
+```
+
+## Emits
+
+```vue
+<script setup>
+// ✅ Define emits with types
+const emit = defineEmits<{
+  update: [id: number, data: object];
+  delete: [id: number];
+  cancel: [];
+}>();
+
+// ✅ Or with validation
+const emit = defineEmits({
+  update: (id: number, data: object) => {
+    if (id > 0 && typeof data === 'object') {
+      return true;
+    }
+    console.warn('Invalid emit arguments');
+    return false;
+  }
+});
+</script>
+```
+
+## Reactive State
+
+```vue
+<script setup>
+// ✅ ref for primitives
+const count = ref(0);
+const name = ref('');
+
+// ✅ ref for objects (preferred)
+const customer = ref({
+  id: null,
+  name: '',
+  email: ''
+});
+
+// ✅ Use reactive only when necessary
+import { reactive } from 'vue';
+const state = reactive({
+  items: [],
+  loading: false
+});
+</script>
+```
+
+## Computed Properties
+
+```vue
+<script setup>
+// ✅ Use computed for derived values
+const filteredItems = computed(() => {
+  return items.value.filter(item => item.isActive);
+});
+
+// ✅ Computed with getter/setter
+const fullName = computed({
+  get: () => `${firstName.value} ${lastName.value}`,
+  set: (value) => {
+    const parts = value.split(' ');
+    firstName.value = parts[0];
+    lastName.value = parts[1];
+  }
+});
+</script>
+```
+
+## Event Handlers
+
+```vue
+<template>
+  <!-- ✅ Use kebab-case for events -->
+  <Button @click="handleClick" />
+  <Input @input="handleInput" />
+  <Form @submit.prevent="handleSubmit" />
+</template>
+
+<script setup>
+// ✅ Name handlers with handle* prefix
+function handleClick() {
+  // ...
+}
+
+function handleInput(event) {
+  // ...
+}
+
+function handleSubmit() {
+  // ...
+}
+</script>
+```
+
+## Conditional Rendering
+
+```vue
+<template>
+  <!-- ✅ Use v-if for conditional rendering -->
+  <div v-if="loading">
+    <LoadingSpinner />
+  </div>
+  
+  <!-- ✅ v-show for frequent toggling -->
+  <div v-show="hasItems">
+    <ItemsList :items="items" />
+  </div>
+  
+  <!-- ✅ v-else for alternatives -->
+  <div v-else>
+    <EmptyState />
+  </div>
+</template>
+```
+
+## Lists
+
+```vue
+<template>
+  <!-- ✅ Always use :key -->
+  <div v-for="item in items" :key="item.id">
+    {{ item.name }}
+  </div>
+  
+  <!-- ✅ For index-based lists -->
+  <div v-for="(item, index) in items" :key="`item-${index}`">
+    {{ item.name }}
+  </div>
+</template>
+```
+
+## Form Handling
+
+```vue
+<template>
+  <form @submit.prevent="handleSubmit">
+    <!-- ✅ Use v-model -->
+    <InputText v-model="form.name" />
+    <Textarea v-model="form.description" />
+    
+    <!-- ✅ For custom components -->
+    <CustomInput v-model="form.email" />
+  </form>
+</template>
+
+<script setup>
+const form = ref({
+  name: '',
+  description: '',
+  email: ''
+});
+
+function handleSubmit() {
+  // Validation and submit
+}
+</script>
+```
+
+## PrimeVue Components
+
+```vue
+<template>
+  <!-- ✅ Use PrimeVue components in the admin panel -->
+  <DataTable
+    :value="customers"
+    :loading="loading"
+    paginator
+    :rows="20"
+    @page="onPage"
+  >
+    <Column field="name" header="Name" sortable />
+  </DataTable>
+</template>
+```
+
+## Styling
+
+```vue
+<style scoped>
+/* ✅ Use scoped -->
+.container {
+  padding: 1rem;
+}
+
+/* ✅ :deep() for nested components */
+:deep(.p-datatable) {
+  border: 1px solid #ccc;
+}
+
+/* ✅ :slotted() for slots */
+:slotted(.header) {
+  font-weight: bold;
+}
+</style>
+```
+
+## Composition Functions
+
+```vue
+<script setup>
+// ✅ Extract complex logic into composables
+import { useCustomers } from '@/composables/useCustomers.js';
+
+const {
+  customers,
+  loading,
+  loadCustomers,
+  totalRecords
+} = useCustomers();
+
+onMounted(() => {
+  loadCustomers();
+});
+</script>
+```
+
+## Error Handling
+
+```vue
+<script setup>
+import { useToast } from 'primevue';
+
+const toast = useToast();
+
+async function loadData() {
+  try {
+    const result = await apiGet('endpoint');
+    if (result.success) {
+      data.value = result.data;
+    } else {
+      toast.add({
+        severity: 'error',
+        summary: 'Error',
+        detail: result.error
+      });
+    }
+  } catch (error) {
+    console.error('Error:', error);
+    toast.add({
+      severity: 'error',
+      summary: 'Error',
+      detail: 'Failed to load data'
+    });
+  }
+}
+</script>
+```
+