sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/cursor/.cursor/rules/sfra-models.mdc

@@ -1,412 +0,0 @@
----
-description: Enhanced SFRA model development patterns and best practices with 26+ SFRA documents and model architecture guidance
-globs: cartridges/**/models/*.js
-alwaysApply: false
----
-
-# Enhanced SFRA Model Development
-
-Use this rule when creating or modifying SFRA models. Now with access to 26+ SFRA documents, smart categorization, and comprehensive model architecture best practices.
-
-## 🎯 SFRA Model Override Requirements - MANDATORY MCP VERIFICATION
-
-**CRITICAL**: For ANY SFRA model override, verify paths and patterns with MCP tools:
-
-### Model Override MCP Workflow:
-```
-MANDATORY sequence for model overrides:
-1. → mcp_sfcc-dev_get_best_practice_guide(guideName: "sfra_models")
-2. → Review "Model Customization Strategies" section
-3. → Confirm proper superModule usage: var base = module.superModule;
-4. → Verify exact override path: cartridge/models/[exact_base_path]
-5. → Generate model ONLY after MCP verification
-```
-
-### Model Override Rules from MCP Guide:
-- **Use module.superModule**: Always import base model with `var base = module.superModule;`
-- **Extend, Don't Replace**: Call base constructor and extend functionality
-- **Maintain Interface**: Keep same public API as base model for template compatibility
-- **Override Complete Path**: Place model in exact same path as base cartridge
-
-**NEVER create SFRA model overrides without MCP tool verification!**
-
-## ⚠️ CRITICAL: Decorator Index.js File Warning
-
-**DANGER**: Avoid creating `index.js` files in the `decorators` folder. This can accidentally override SFRA's main `index.js` file, causing application failures and unexpected behavior.
-
-### The Problem:
-- SFRA relies on its core `index.js` file for proper initialization
-- Adding an `index.js` in decorators can interfere with SFRA's module resolution
-- Can lead to silent failures that are difficult to debug
-
-### Safe Alternative - Direct Import Pattern:
-```javascript
-'use strict';
-
-var base = module.superModule;
-// ✅ SAFE: Import decorator directly
-var customDecorator = require('*/cartridge/scripts/decorators/customDecorator');
-var productDecorator = require('*/cartridge/scripts/decorators/productDecorator');
-
-function CustomProduct(product, options) {
-    base.call(this, product, options);
-    
-    // ✅ Apply decorators directly
-    customDecorator(this);
-    productDecorator(this);
-}
-
-module.exports = CustomProduct;
-```
-
-### What NOT to do:
-```javascript
-// ❌ DANGEROUS: Avoid this pattern
-var decorators = require('*/cartridge/scripts/decorators'); // Could conflict with SFRA
-```
-
-### Best Practices for Decorators:
-1. **Import Explicitly**: Always import specific decorator files by name
-2. **Use Full Paths**: Specify complete paths to decorator modules
-3. **No Index Files**: Never create `index.js` in decorators folder
-4. **Namespace Decorators**: Use descriptive names like `productPriceDecorator.js`
-
-## 🚀 Enhanced MCP Tools Sequence
-
-**BEFORE writing ANY SFRA model code:**
-
-### Phase 1: Explore SFRA Model Architecture
-1. `mcp_sfcc-dev_get_sfra_categories` - Discover all 7 SFRA documentation categories
-2. `mcp_sfcc-dev_get_best_practice_guide` with guideName: "sfra_models" - Get comprehensive model patterns and architecture
-3. `mcp_sfcc-dev_get_best_practice_guide` with guideName: "performance" - Performance optimization for models
-
-### Phase 2: Research Core SFRA Components
-4. `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "core" - Get core SFRA classes for model integration
-5. `mcp_sfcc-dev_get_sfra_document` with documentName: "render" - Template rendering with model data
-6. `mcp_sfcc-dev_get_sfra_document` with documentName: "querystring" - URL parameter handling in models
-
-### Phase 3: Model Category-Specific Research (based on model type)
-
-**For Product Models:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "product"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "product-full" - Complete product model structure
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "product-bundle" - Bundle product modeling
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "product-tile" - Lightweight product display models
-- `mcp_sfcc-dev_search_sfra_documentation` with query: "variation" - Product variation handling
-
-**For Cart/Order Models:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "order"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "cart" - Cart model architecture
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "billing" - Billing address models
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "shipping" - Shipping models and calculations
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "totals" - Order totals and tax models
-
-**For Customer Models:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "customer"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "account" - Customer account models
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "address" - Address model patterns
-
-**For Pricing Models:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "pricing"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "price-default" - Standard pricing models
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "price-range" - Price range modeling
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "price-tiered" - Tiered pricing structures
-
-**For Store/Location Models:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "store"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "store" - Individual store models
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "stores" - Store collection models
-
-### Phase 4: Security and Performance
-7. `mcp_sfcc-dev_search_best_practices` with query: "security" - Model security patterns
-8. `mcp_sfcc-dev_search_best_practices` with query: "performance" - Model performance optimization
-9. `mcp_sfcc-dev_search_best_practices` with query: "validation" - Input validation in models
-10. `mcp_sfcc-dev_search_sfra_documentation` with query: [specific functionality] - Find relevant model patterns
-
-## 📂 SFRA Model Documentation Categories (26+ documents)
-
-### Available Categories for Model Development:
-- **Core** (5 docs): server, request, response, querystring, render - Integration patterns
-- **Product** (5 docs): product-full, product-bundle, product-tile, product-search, product-line-items - Product modeling
-- **Order** (6 docs): cart, order, billing, shipping, payment, totals - Commerce flow models
-- **Customer** (2 docs): account, address - Customer data models
-- **Pricing** (3 docs): price-default, price-range, price-tiered - Pricing logic models
-- **Store** (2 docs): store, stores - Store/location models
-- **Other** (3+ docs): categories, content, locale - Supporting models
-
-## MCP-Enhanced Model Development Workflows
-
-### Workflow 1: Product Model Development
-```
-1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models"
-2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "product"
-3. mcp_sfcc-dev_get_sfra_document with documentName: "product-full"
-4. mcp_sfcc-dev_search_sfra_documentation with query: "decorator"
-5. mcp_sfcc-dev_search_best_practices with query: "performance"
-```
-
-### Workflow 2: Cart/Order Model Development
-```
-1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models"
-2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "order"
-3. mcp_sfcc-dev_get_sfra_document with documentName: "cart"
-4. mcp_sfcc-dev_get_sfra_document with documentName: "totals"
-5. mcp_sfcc-dev_search_best_practices with query: "validation"
-```
-
-### Workflow 3: Customer Account Model Development
-```
-1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models"
-2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "customer"
-3. mcp_sfcc-dev_get_sfra_document with documentName: "account"
-4. mcp_sfcc-dev_search_best_practices with query: "security"
-```
-
-### Workflow 4: Custom Pricing Model Development
-```
-1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models"
-2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "pricing"
-3. mcp_sfcc-dev_get_sfra_document with documentName: "price-default"
-4. mcp_sfcc-dev_search_sfra_documentation with query: "promotion"
-```
-
-## Enhanced MCP-Guided Model Template
-
-```javascript
-'use strict';
-
-/**
- * [Model Name] Model
- * Purpose: [Brief description of model functionality and data transformation]
- *
- * Implementation based on Enhanced SFRA Model Documentation:
- * - mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models"
- * - mcp_sfcc-dev_get_sfra_categories (discovered 7 categories)
- * - mcp_sfcc-dev_get_sfra_documents_by_category with category: "[relevant_category]"
- * - mcp_sfcc-dev_search_best_practices with query: "performance"
- * - mcp_sfcc-dev_search_best_practices with query: "security"
- * - mcp_sfcc-dev_search_best_practices with query: "validation"
- */
-
-var base = module.superModule;
-
-/**
- * Model Constructor
- * @param {dw.catalog.Product|dw.order.Basket|dw.customer.Customer|Object} sourceObject - Source SFCC API object
- * @param {Object} options - Configuration options for model transformation
- * @constructor
- *
- * Model Architecture Pattern:
- * 1. Extend base SFRA model when applicable
- * 2. Transform SFCC API objects to JSON-ready structures
- * 3. Apply decorators for additional functionality
- * 4. Implement caching strategies for performance
- * 5. Add validation for data integrity
- */
-function [ModelName](sourceObject, options) {
-    base.call(this, sourceObject, options);
-
-    // Model-specific transformations based on MCP research:
-    // - Followed patterns from mcp_sfcc-dev_get_sfra_document with documentName: "[relevant_document]"
-    // - Applied security patterns from mcp_sfcc-dev_search_best_practices with query: "security"
-    // - Implemented performance optimizations from best practice guide
-
-    if (sourceObject) {
-        this.transformSourceObject(sourceObject, options);
-    }
-}
-
-/**
- * Transform source SFCC object to model properties
- * @param {Object} sourceObject - Source SFCC API object
- * @param {Object} options - Transformation options
- * @private
- */
-[ModelName].prototype.transformSourceObject = function (sourceObject, options) {
-    // Implement transformation logic following SFRA model patterns
-    // Pattern discovered from: mcp_sfcc-dev_get_sfra_document with documentName: "[base_model]"
-
-    // Security consideration: Sanitize sensitive data
-    // Pattern from: mcp_sfcc-dev_search_best_practices with query: "security"
-
-    // Performance consideration: Lazy load expensive properties
-    // Pattern from: mcp_sfcc-dev_search_best_practices with query: "performance"
-};
-
-/**
- * Apply decorators for additional functionality
- * @param {Array} decorators - Array of decorator functions
- * @returns {[ModelName]} Enhanced model instance
- */
-[ModelName].prototype.applyDecorators = function (decorators) {
-    // Decorator pattern implementation
-    // Based on research: mcp_sfcc-dev_search_sfra_documentation with query: "decorator"
-
-    var self = this;
-    decorators.forEach(function (decorator) {
-        if (typeof decorator === 'function') {
-            decorator(self);
-        }
-    });
-
-    return this;
-};
-
-/**
- * Validate model data integrity
- * @returns {Object} Validation result with errors array
- */
-[ModelName].prototype.validate = function () {
-    // Validation logic following SFRA patterns
-    // Based on: mcp_sfcc-dev_search_best_practices with query: "validation"
-
-    var errors = [];
-
-    // Implement validation rules specific to model type
-    // Pattern from relevant SFRA model documentation
-
-    return {
-        valid: errors.length === 0,
-        errors: errors
-    };
-};
-
-/**
- * Convert model to JSON-ready object for template rendering
- * @returns {Object} Plain object suitable for JSON serialization
- */
-[ModelName].prototype.toJSON = function () {
-    // JSON serialization following SFRA patterns
-    // Ensure circular references are handled
-    // Remove functions and private properties
-
-    var result = {};
-
-    // Copy public properties only
-    Object.keys(this).forEach(function (key) {
-        if (key.charAt(0) !== '_' && typeof this[key] !== 'function') {
-            result[key] = this[key];
-        }
-    }.bind(this));
-
-    return result;
-};
-
-module.exports = [ModelName];
-```
-
-## SFRA Model Development Best Practices
-
-### 1. Model Architecture Patterns
-- **Extend Base Models**: Leverage existing SFRA models when possible
-- **Decorator Pattern**: Use decorators for optional functionality
-- **Factory Pattern**: Implement factory methods for complex model creation
-- **Builder Pattern**: Use builders for models with many optional properties
-
-### 2. Performance Optimizations
-- **Lazy Loading**: Load expensive properties only when needed
-- **Caching Strategy**: Implement appropriate caching for frequently accessed data
-- **Batch Operations**: Process multiple items efficiently
-- **Index-Friendly APIs**: Use SFCC APIs that leverage database indexes
-
-### 3. Security Considerations
-- **Data Sanitization**: Always sanitize user input
-- **Sensitive Data Handling**: Never expose passwords or tokens
-- **Input Validation**: Validate all input parameters
-- **XSS Prevention**: Escape output for template rendering
-
-### 4. Model Testing Patterns
-```javascript
-// Example test structure for SFRA models
-describe('[ModelName] Model', function () {
-    it('should transform source object correctly', function () {
-        // Test transformation logic
-    });
-
-    it('should validate input properly', function () {
-        // Test validation rules
-    });
-
-    it('should apply decorators correctly', function () {
-        // Test decorator application
-    });
-
-    it('should serialize to JSON properly', function () {
-        // Test JSON conversion
-    });
-});
-```
-
-## Common Model Implementation Patterns
-
-### Product Model Extension
-```javascript
-// Pattern from: mcp_sfcc-dev_get_sfra_document with documentName: "product-full"
-function CustomProduct(product, options) {
-    base.call(this, product, options);
-
-    // Add custom properties
-    this.customAttribute = product.custom.customAttribute;
-    this.calculatedProperty = this.calculateCustomValue();
-}
-```
-
-### Cart Model Enhancement
-```javascript
-// Pattern from: mcp_sfcc-dev_get_sfra_document with documentName: "cart"
-function CustomCart(basket, options) {
-    base.call(this, basket, options);
-
-    // Add custom totals calculation
-    this.customTotals = this.calculateCustomTotals(basket);
-    this.loyaltyPoints = this.calculateLoyaltyPoints();
-}
-```
-
-### Customer Model Customization
-```javascript
-// Pattern from: mcp_sfcc-dev_get_sfra_document with documentName: "account"
-function CustomAccount(customer, options) {
-    base.call(this, customer, options);
-
-    // Add customer segment information
-    this.segment = this.determineCustomerSegment();
-    this.preferences = this.buildPreferenceModel();
-}
-```
-
-## Advanced Model Patterns
-
-### 1. Composite Models
-Combine multiple SFCC objects into a single model for complex views.
-
-### 2. View Models
-Create specialized models optimized for specific template rendering needs.
-
-### 3. Command Models
-Implement models that encapsulate business logic and operations.
-
-### 4. Event-Driven Models
-Models that respond to system events and update accordingly.
-
-## Integration with Controllers
-```javascript
-// Controller integration pattern
-server.get('Show', function (req, res, next) {
-    // Use MCP-researched model patterns
-    var customModel = new CustomModel(sourceObject, {
-        // Options based on MCP research
-    });
-
-    // Apply decorators discovered through MCP tools
-    customModel.applyDecorators(['decorator1', 'decorator2']);
-
-    res.render('template', {
-        model: customModel
-    });
-
-    next();
-});
-```
-
-Remember: Always research existing SFRA model patterns using the MCP tools before implementing custom solutions. This ensures consistency with SFRA architecture and leverages proven patterns for optimal performance and maintainability.