Squashed commit message

.cursor/prompts/api-generation.md

@@ -0,0 +1,127 @@
+# Prompts for API generation
+
+## Creating a new API endpoint
+
+```
+Create a new API endpoint [ENDPOINT_NAME] for [DESCRIPTION]:
+
+1. Handler in [HANDLER_PATH]:
+   - Method handle() accepts Request
+   - Validate input data
+   - Use a Service for business logic
+   - Return JsonResponse with correct structure
+   - Handle errors with logging
+
+2. Service in [SERVICE_PATH]:
+   - Business logic
+   - Work with Model
+   - Data validation
+   - Exception handling
+
+3. Model in [MODEL_PATH] (if needed):
+   - Methods for working with the database
+   - Use Query Builder
+   - Proper method typing
+
+4. Route in routes.php:
+   - Add a route with the correct name
+
+5. Migration (if a new table is needed):
+   - Create a migration in database/migrations/
+   - Use fixed acmeshop_ prefix for the table
+   - Add indexes where necessary
+
+Follow the project MVC-L architecture and reuse existing patterns.
+```
+
+## Creating a CRUD API
+
+```
+Create a full CRUD API for entity [ENTITY_NAME]:
+
+1. Handler with methods:
+   - list() – list with pagination and filtering
+   - get() – fetch a single record
+   - create() – create
+   - update() – update
+   - delete() – delete
+
+2. Service with business logic for all operations
+
+3. Model with methods:
+   - findAll() – list
+   - findById() – by ID
+   - create() – create
+   - update() – update
+   - delete() – delete
+
+4. DTO for data validation
+
+5. Migration for table [TABLE_NAME]
+
+6. Routes for all endpoints
+
+Use server-side pagination, filtering, and sorting for list().
+```
+
+## Creating an Admin API endpoint
+
+```
+Create an Admin API endpoint [ENDPOINT_NAME] in bastion/Handlers/:
+
+1. Handler in bastion/Handlers/[HANDLER_NAME].php:
+   - Use Request to read parameters
+   - Validate data
+   - Call a Service for business logic
+   - Return JsonResponse with structure { data: { data: [...], totalRecords: ... } }
+   - Handle errors
+
+2. Service in bastion/Services/ (if needed):
+   - Admin-specific business logic
+   - Work with Models
+
+3. Route in bastion/routes.php
+
+4. Frontend component (if UI is needed):
+   - Vue component in frontend/admin/src/views/
+   - Use PrimeVue components
+   - Server-side pagination/filtering
+   - Error handling with toast notifications
+
+Follow existing project patterns.
+```
+
+## Creating a Frontend API client
+
+```
+Create a function for working with API endpoint [ENDPOINT_NAME]:
+
+1. In frontend/[admin|spa]/src/utils/http.js:
+   - api[Method] function to call the endpoint
+   - Proper error handling
+   - Return a structured response
+
+2. Usage:
+   - Import in components
+   - Handle loading states
+   - Show toast notifications on errors
+
+Follow existing patterns in http.js.
+```
+
+## Creating a migration
+
+```
+Create a migration for table [TABLE_NAME]:
+
+1. File: database/migrations/[TIMESTAMP]_[DESCRIPTION].php
+2. Use fixed acmeshop_ prefix for the table
+3. Add all required fields with correct types
+4. Add indexes for frequently used fields
+5. Use utf8mb4_unicode_ci collation
+6. Use InnoDB engine
+7. Add created_at and updated_at timestamps
+8. Do not create foreign keys (use indexes only)
+
+Follow the structure of existing migrations.
+```

.cursor/prompts/changelog.md

@@ -0,0 +1,101 @@
+# Changelog Documentation Rules
+
+## General requirements
+
+- **Format**: Markdown
+- **Structure**: One version = one page
+- **Style**: Professional, concise, without marketing slogans
+- **Language**: English
+- **Target audience**: Developers and store owners
+- **Content**: Only key changes, without unnecessary technical details
+
+## Page structure
+
+### Intro paragraph
+- Short release description (1–2 sentences)
+- Add 1–2 sentences about key changes
+- Mention the main features and improvements
+
+### Sections (strictly in this order)
+
+1. **🚀 Added** – new features and capabilities
+2. **✨ Improved** – improvements to existing features
+3. **🐞 Fixed** – bug fixes
+4. **⚠️ Breaking changes** – non‑backward compatible changes
+5. **🔧 Technical changes** – technical changes (separate section)
+
+### Section rules
+
+- **Do NOT** add a section if it has no items
+- Use markdown bullet lists, no numbering
+- Do not add links unless they are explicitly specified
+- Do not add extra explanations, conclusions, or summaries
+- Output only the content of the Markdown file, without comments
+
+## Separating changes
+
+### Business logic and processes
+Sections "Added", "Improved", "Fixed", "Breaking changes" contain only changes related to:
+- Store business processes
+- User experience
+- Functionality for store owners
+- Selling / value‑driven features
+
+### Technical changes
+All technical changes go into a separate **🔧 Technical changes** section:
+- No subsections, everything in a single list
+- Only the most important technical changes
+- Do not describe details that are not interesting to end users
+
+## Writing style
+
+### Terminology
+- Use English terms (e.g. "navbar", not a localized variant)
+- Avoid low‑level technical terms in business sections (e.g. "customer_id" → "automatic customer linking")
+
+### Descriptions
+
+**For key selling features:**
+- Provide detailed descriptions
+- Highlight capabilities and advantages
+- Emphasize value for the user
+
+**For technical changes:**
+- Be brief and to the point
+- Avoid unnecessary details
+
+**For regular features:**
+- Be concise but informative
+- Focus on user benefit
+
+## Ordering
+
+### In the "Added" section
+Place key selling features **first**:
+1. Main page configuration system based on blocks
+2. Form builder based on FormKit
+3. Yandex.Metrica integration
+4. Privacy policy
+5. Support for coupons and gift certificates
+6. Other features
+
+## Examples of good wording
+
+### ✅ Good
+- "Automatic linking of Telegram customers with ECommerce customers: the system automatically finds and links customers from the Telegram shop with existing customers in ECommerce by email or phone number, creating a unified customer base"
+
+### ❌ Bad
+- "Saving customer_id with the order to link with ECommerce customers: automatic linking of orders from Telegram with customers in ECommerce, unified customer base"
+
+### ✅ Good
+- "Navbar with logo and application name"
+
+### ❌ Bad
+- "Navigation bar with logo and application name" (too verbose, no added value)
+
+## What not to include
+
+- Internal development details (tests, static analysis, obfuscation)
+- Technical details not interesting to users
+- Excessively detailed technical descriptions
+- Marketing slogans and calls to action

.cursor/prompts/documentation.md

@@ -0,0 +1,61 @@
+# Prompts for documentation
+
+## Documenting a class
+
+```
+Add PHPDoc documentation for class [CLASS_NAME]:
+1. Description of the class and its purpose
+2. @package tag
+3. @author tag
+4. Documentation for all public methods
+5. Documentation for public properties
+6. Usage examples where appropriate
+```
+
+## Documenting a method
+
+```
+Add PHPDoc for method [METHOD_NAME]:
+1. Method description
+2. @param for all parameters with types
+3. @return with the return type
+4. @throws for all exceptions
+5. Usage examples if the logic is complex
+```
+
+## Documenting an API endpoint
+
+```
+Create documentation for API endpoint [ENDPOINT_NAME]:
+1. Description of purpose
+2. HTTP method and path
+3. Request parameters (query/body)
+4. Response format (JSON structure)
+5. Error codes
+6. Request/response examples
+7. Authorization requirements
+```
+
+## Documenting a Vue component
+
+```
+Add documentation for Vue component [COMPONENT_NAME]:
+1. Component description
+2. Props with types and descriptions
+3. Emits with descriptions
+4. Slots if present
+5. Usage examples
+6. Dependencies on other components
+```
+
+## Creating a README
+
+```
+Create README.md for [MODULE/COMPONENT]:
+1. Purpose description
+2. Installation/configuration
+3. Usage with examples
+4. API documentation
+5. Configuration options
+6. Troubleshooting
+```

.cursor/prompts/refactoring.md

@@ -0,0 +1,87 @@
+# Prompts for refactoring
+
+## General refactoring
+
+```
+Analyze the code in file [FILE_PATH] and perform refactoring:
+1. Remove duplicated code
+2. Improve readability
+3. Apply SOLID principles
+4. Add error handling where necessary
+5. Improve typing
+6. Add documentation for public methods
+7. Ensure the code follows the project's MVC-L architecture
+8. Use existing utilities and services instead of creating new ones
+```
+
+## Refactoring a Handler
+
+```
+Refactor Handler [HANDLER_NAME]:
+1. Extract business logic into a separate Service
+2. Add validation for input data
+3. Improve error handling with logging
+4. Use DTOs for data transfer
+5. Add PHPDoc comments
+6. Ensure Dependency Injection is used
+7. Optimize database queries if needed
+```
+
+## Refactoring a Model
+
+```
+Refactor Model [MODEL_NAME]:
+1. Ensure all queries use the Query Builder
+2. Add methods for common operations (findBy, findAll, create, update)
+3. Add data validation before saving
+4. Improve method typing
+5. Add PHPDoc comments
+6. Use transactions for complex operations
+```
+
+## Refactoring a Vue component
+
+```
+Refactor Vue component [COMPONENT_NAME]:
+1. Extract logic into composable functions
+2. Improve typing for props and emits
+3. Optimize computed properties
+4. Add error handling
+5. Improve template structure
+6. Add loading states
+7. Use existing project utilities
+```
+
+## Removing duplication
+
+```
+Find and remove code duplication in:
+- [FILE_PATH_1]
+- [FILE_PATH_2]
+- [FILE_PATH_3]
+
+Create shared utilities/services where appropriate, following the project architecture.
+```
+
+## Improving performance
+
+```
+Analyze performance of the code in [FILE_PATH]:
+1. Optimize database queries (use indexes, avoid N+1)
+2. Add caching where appropriate
+3. Optimize algorithms
+4. Reduce the number of API calls
+5. Use lazy loading on the frontend
+```
+
+## Improving security
+
+```
+Improve security of the code in [FILE_PATH]:
+1. Add validation for all input data
+2. Use prepared statements (Query Builder)
+3. Add CSRF protection where necessary
+4. Validate access rights
+5. Sanitize output data
+6. Add rate limiting where necessary
+```

.cursor/prompts/testing.md

@@ -0,0 +1,52 @@
+# Prompts for testing
+
+## Creating a unit test
+
+```
+Create a unit test for [CLASS_NAME] in tests/Unit/:
+
+1. Use PHPUnit
+2. Cover all public methods
+3. Test successful scenarios
+4. Test error handling
+5. Use mocks for dependencies
+6. Follow the structure of existing tests
+7. Use the project's base TestCase class
+```
+
+## Creating an integration test
+
+```
+Create an integration test for [FEATURE_NAME] in tests/Integration/:
+
+1. Test the full flow from request to response
+2. Use a test database
+3. Clean up data after tests
+4. Test real-life usage scenarios
+5. Verify data validation
+6. Verify error handling
+```
+
+## Creating a Vue component test
+
+```
+Create a test for Vue component [COMPONENT_NAME] in frontend/[admin|spa]/tests/:
+
+1. Use Vitest
+2. Test component rendering
+3. Test props
+4. Test events (emits)
+5. Test user interactions
+6. Use mocks for API calls
+7. Follow the structure of existing tests
+```
+
+## Test coverage
+
+```
+Analyze test coverage for [FILE_PATH]:
+1. Determine which methods are not covered by tests
+2. Create tests for critical methods
+3. Ensure edge cases are tested
+4. Add tests for error handling
+```