Initial commit

2025-11-29 18:50:04 +08:00
commit 3e809e35ad
41 changed files with 10010 additions and 0 deletions
--- a/skills/odoo-connector-module-creator/references/patterns.md
+++ b/skills/odoo-connector-module-creator/references/patterns.md
@@ -0,0 +1,562 @@
+# Design Patterns in Odoo Connectors
+
+## 1. Template Method Pattern
+
+**Usage**: Backend model orchestration
+
+**Implementation**:
+```python
+# generic_connector provides template methods
+class GenericBackend(models.Model):
+    def sync_orders(self):
+        """Template method."""
+        self._pre_sync_validation()
+        result = self._sync_orders_implementation()  # Hook
+        self._post_sync_actions()
+        return result
+
+    def _sync_orders_implementation(self):
+        """Override this in concrete implementations."""
+        raise NotImplementedError()
+
+# Concrete connector overrides the hook
+class ShopifyBackend(models.Model):
+    _inherit = 'generic.backend'
+
+    def _sync_orders_implementation(self):
+        """Shopify-specific implementation."""
+        # Actual sync logic here
+        pass
+```
+
+**Benefits**:
+- Enforces consistent workflow
+- Allows customization at specific points
+- Reduces code duplication
+
+## 2. Adapter Pattern
+
+**Usage**: API communication abstraction
+
+**Implementation**:
+```python
+class ShopifyAdapter(GenericAdapter):
+    """Adapts Shopify API to generic interface."""
+
+    def get_orders(self, filters=None):
+        """Translate to Shopify API call."""
+        # Shopify uses /admin/api/2024-01/orders.json
+        endpoint = '/admin/api/2024-01/orders.json'
+        response = self.get(endpoint, params=self._build_params(filters))
+
+        # Shopify wraps response in 'orders' key
+        return response.get('orders', [])
+
+    def _build_params(self, filters):
+        """Transform generic filters to Shopify params."""
+        params = {}
+        if filters and 'created_after' in filters:
+            params['created_at_min'] = filters['created_after']
+        return params
+```
+
+**Benefits**:
+- Hides API differences
+- Provides consistent interface
+- Simplifies testing (mock adapter)
+
+## 3. Strategy Pattern
+
+**Usage**: Different sync strategies per backend
+
+**Implementation**:
+```python
+class GenericImporter(Component):
+    _name = 'generic.importer'
+
+    def run(self, external_id, force=False):
+        """Import strategy can vary."""
+        if self._should_skip_import(external_id, force):
+            return None
+
+        # Different strategies:
+        # - Direct import
+        # - Delayed import
+        # - Batch import
+        return self._import_record(external_id)
+
+class RealtimeImporter(GenericImporter):
+    """Strategy: Import immediately."""
+    _name = 'shopify.realtime.importer'
+
+    def _import_record(self, external_id):
+        # Import synchronously
+        pass
+
+class BatchImporter(GenericImporter):
+    """Strategy: Queue for batch processing."""
+    _name = 'shopify.batch.importer'
+
+    def _import_record(self, external_id):
+        # Queue for later
+        self.with_delay().import_record(external_id)
+```
+
+## 4. Factory Pattern
+
+**Usage**: Component selection based on context
+
+**Implementation**:
+```python
+# Component framework acts as factory
+with backend.work_on('shopify.product.template') as work:
+    # Factory automatically selects appropriate components
+    adapter = work.component(usage='backend.adapter')
+    # Returns ShopifyProductAdapter
+
+    importer = work.component(usage='record.importer')
+    # Returns ShopifyProductImporter
+
+    mapper = work.component(usage='import.mapper')
+    # Returns ShopifyProductImportMapper
+```
+
+**Benefits**:
+- Automatic component selection
+- Decoupled component creation
+- Easy to extend with new components
+
+## 5. Observer Pattern
+
+**Usage**: Webhook event handling
+
+**Implementation**:
+```python
+# Event source (webhook controller)
+class WebhookController(http.Controller):
+    @http.route('/shopify/webhook', type='json', auth='none')
+    def webhook_handler(self):
+        payload = request.jsonrequest
+        event_type = request.httprequest.headers.get('X-Shopify-Topic')
+
+        # Notify observers
+        webhook = request.env['generic.webhook'].sudo().create({
+            'event_type': event_type,
+            'payload': json.dumps(payload),
+            'processing_status': 'pending'
+        })
+        webhook.with_delay().process_webhook()
+
+# Observer (backend model)
+class ShopifyBackend(models.Model):
+    def process_webhook(self, webhook):
+        """Observe and handle webhook events."""
+        handlers = {
+            'orders/create': self._handle_order_created,
+            'products/update': self._handle_product_updated,
+        }
+
+        handler = handlers.get(webhook.event_type)
+        if handler:
+            handler(webhook)
+```
+
+## 6. Delegation Pattern
+
+**Usage**: Multi-level model inheritance
+
+**Implementation**:
+```python
+class GenericBackend(models.Model):
+    _name = 'generic.backend'
+    _inherits = {'connector.base.backend': 'connector_backend_id'}
+
+    connector_backend_id = fields.Many2one(
+        'connector.base.backend',
+        required=True,
+        ondelete='cascade'
+    )
+
+    # Delegates fields: name, version, etc.
+    # Accessing backend.name actually accesses backend.connector_backend_id.name
+```
+
+**Benefits**:
+- Reuse existing model functionality
+- Avoid deep inheritance hierarchies
+- Maintain database normalization
+
+## 7. Mapper Pattern (Data Transfer Object)
+
+**Usage**: Data transformation between systems
+
+**Implementation**:
+```python
+class ProductImportMapper(GenericImportMapper):
+    _name = 'shopify.product.import.mapper'
+
+    # Simple mappings
+    direct = [
+        ('title', 'name'),
+        ('vendor', 'manufacturer'),
+    ]
+
+    # Complex mapping
+    @mapping
+    def description(self, record):
+        """Transform HTML description to plain text."""
+        html_desc = record.get('body_html', '')
+        return {'description': self._strip_html(html_desc)}
+
+    @mapping
+    def price(self, record):
+        """Extract price from variants."""
+        variants = record.get('variants', [])
+        if variants:
+            return {'list_price': float(variants[0].get('price', 0))}
+        return {}
+
+    @only_create
+    def default_code(self, record):
+        """Set SKU only when creating."""
+        return {'default_code': record.get('sku')}
+```
+
+**Benefits**:
+- Centralized data transformation
+- Declarative mapping definitions
+- Reusable transformations
+
+## 8. Retry Pattern
+
+**Usage**: Handling transient failures
+
+**Implementation**:
+```python
+class GenericBinding(models.AbstractModel):
+    retry_count = fields.Integer(default=0)
+    max_retries = fields.Integer(default=3)
+
+    def can_retry_sync(self):
+        """Check if retry is allowed."""
+        return self.retry_count < self.max_retries
+
+    def export_with_retry(self):
+        """Export with automatic retry."""
+        try:
+            self.export_record()
+            self.mark_sync_success()
+        except Exception as e:
+            self.retry_count += 1
+            self.last_error = str(e)
+
+            if self.can_retry_sync():
+                # Retry with exponential backoff
+                delay = 60 * (2 ** self.retry_count)
+                self.with_delay(eta=delay).export_with_retry()
+            else:
+                self.mark_sync_failed(str(e))
+```
+
+**Benefits**:
+- Resilient to temporary failures
+- Configurable retry behavior
+- Exponential backoff prevents API overload
+
+## 9. Rate Limiting Pattern
+
+**Usage**: Respect API rate limits
+
+**Implementation**:
+```python
+from datetime import datetime, timedelta
+from cachetools import TTLCache
+
+class RateLimitedAdapter(GenericAdapter):
+    # Class-level cache (shared across instances)
+    _rate_limit_cache = TTLCache(maxsize=100, ttl=60)
+
+    def make_request(self, method, endpoint, **kwargs):
+        """Make request with rate limiting."""
+        cache_key = f"{self.backend_record.id}:requests"
+
+        # Get request count in current window
+        request_count = self._rate_limit_cache.get(cache_key, 0)
+        max_requests = self.backend_record.rate_limit_calls or 100
+
+        if request_count >= max_requests:
+            # Wait for next window
+            raise RateLimitExceeded(f"Rate limit of {max_requests}/min exceeded")
+
+        # Make request
+        response = super().make_request(method, endpoint, **kwargs)
+
+        # Increment counter
+        self._rate_limit_cache[cache_key] = request_count + 1
+
+        return response
+```
+
+**Variants**:
+- **Token Bucket**: For bursty traffic
+- **Leaky Bucket**: For steady rate
+- **Sliding Window**: For precise limits
+
+## 10. Circuit Breaker Pattern
+
+**Usage**: Prevent cascading failures
+
+**Implementation**:
+```python
+class CircuitBreaker:
+    def __init__(self, failure_threshold=5, timeout=60):
+        self.failure_threshold = failure_threshold
+        self.timeout = timeout
+        self.failures = 0
+        self.last_failure_time = None
+        self.state = 'CLOSED'  # CLOSED, OPEN, HALF_OPEN
+
+    def call(self, func, *args, **kwargs):
+        if self.state == 'OPEN':
+            if datetime.now() - self.last_failure_time > timedelta(seconds=self.timeout):
+                self.state = 'HALF_OPEN'
+            else:
+                raise CircuitBreakerOpen("Circuit breaker is OPEN")
+
+        try:
+            result = func(*args, **kwargs)
+            if self.state == 'HALF_OPEN':
+                self.state = 'CLOSED'
+                self.failures = 0
+            return result
+        except Exception as e:
+            self.failures += 1
+            self.last_failure_time = datetime.now()
+
+            if self.failures >= self.failure_threshold:
+                self.state = 'OPEN'
+            raise
+
+class ResilientAdapter(GenericAdapter):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.circuit_breaker = CircuitBreaker()
+
+    def make_request(self, *args, **kwargs):
+        return self.circuit_breaker.call(
+            super().make_request,
+            *args,
+            **kwargs
+        )
+```
+
+## 11. Saga Pattern
+
+**Usage**: Distributed transaction management
+
+**Implementation**:
+```python
+class OrderImportSaga:
+    """Multi-step order import with compensation."""
+
+    def __init__(self, backend, external_order_id):
+        self.backend = backend
+        self.external_order_id = external_order_id
+        self.steps_completed = []
+
+    def execute(self):
+        """Execute saga steps."""
+        try:
+            # Step 1: Import customer
+            customer = self._import_customer()
+            self.steps_completed.append(('customer', customer.id))
+
+            # Step 2: Import order
+            order = self._import_order(customer)
+            self.steps_completed.append(('order', order.id))
+
+            # Step 3: Import order lines
+            lines = self._import_order_lines(order)
+            self.steps_completed.append(('lines', [l.id for l in lines]))
+
+            # Step 4: Confirm order
+            order.action_confirm()
+
+            return order
+
+        except Exception as e:
+            # Compensate (rollback completed steps)
+            self._compensate()
+            raise
+
+    def _compensate(self):
+        """Rollback completed steps."""
+        for step_type, record_ids in reversed(self.steps_completed):
+            if step_type == 'order':
+                self.env['sale.order'].browse(record_ids).action_cancel()
+            elif step_type == 'customer':
+                # Mark as not synced (don't delete)
+                partner = self.env['res.partner'].browse(record_ids)
+                partner.write({'active': False})
+```
+
+## 12. Repository Pattern
+
+**Usage**: Centralize data access logic
+
+**Implementation**:
+```python
+class ProductBindingRepository:
+    """Repository for product bindings."""
+
+    def __init__(self, env, backend):
+        self.env = env
+        self.backend = backend
+        self.model = env['shopify.product.template']
+
+    def find_by_external_id(self, external_id):
+        """Find binding by external ID."""
+        return self.model.search([
+            ('backend_id', '=', self.backend.id),
+            ('external_id', '=', str(external_id))
+        ], limit=1)
+
+    def find_by_sku(self, sku):
+        """Find binding by SKU."""
+        return self.model.search([
+            ('backend_id', '=', self.backend.id),
+            ('default_code', '=', sku)
+        ], limit=1)
+
+    def find_or_create(self, external_id, defaults=None):
+        """Find existing or create new binding."""
+        binding = self.find_by_external_id(external_id)
+        if not binding:
+            values = {'backend_id': self.backend.id, 'external_id': str(external_id)}
+            if defaults:
+                values.update(defaults)
+            binding = self.model.create(values)
+        return binding
+
+    def find_pending_export(self, limit=100):
+        """Find bindings pending export."""
+        return self.model.search([
+            ('backend_id', '=', self.backend.id),
+            ('sync_status', '=', 'pending'),
+            ('external_id', '=', False)
+        ], limit=limit)
+```
+
+## Pattern Selection Guidelines
+
+| Use Case | Pattern | Reason |
+|----------|---------|--------|
+| Define sync workflow | Template Method | Consistent process, extensible hooks |
+| API communication | Adapter | Abstract API differences |
+| Different import modes | Strategy | Pluggable algorithms |
+| Select components | Factory | Automatic selection based on context |
+| Handle webhooks | Observer | Event-driven architecture |
+| Extend core models | Delegation | Reuse without deep inheritance |
+| Transform data | Mapper | Declarative transformations |
+| Handle failures | Retry + Circuit Breaker | Resilient operations |
+| Respect API limits | Rate Limiting | Prevent API throttling |
+| Multi-step operations | Saga | Rollback on failure |
+| Data access | Repository | Centralized queries |
+
+## Anti-Patterns to Avoid
+
+### ❌ Direct Odoo Record Modification
+```python
+# BAD: Directly modify product
+product = self.env['product.template'].browse(product_id)
+product.write({'name': external_data['title']})
+```
+
+```python
+# GOOD: Use binding
+binding = self.env['shopify.product.template'].search([
+    ('odoo_id', '=', product_id)
+])
+binding.write({'name': external_data['title']})
+```
+
+### ❌ Synchronous Long Operations
+```python
+# BAD: Block user while importing 1000 products
+def import_all_products(self):
+    for product_id in range(1, 1000):
+        self.import_product(product_id)  # Takes 30 minutes!
+```
+
+```python
+# GOOD: Queue async job
+def import_all_products(self):
+    self.with_delay().import_products_batch()
+```
+
+### ❌ No Error Handling
+```python
+# BAD: Unhandled API errors crash sync
+def sync_orders(self):
+    response = adapter.get_orders()  # What if API is down?
+    for order in response:
+        self.import_order(order)
+```
+
+```python
+# GOOD: Graceful error handling
+def sync_orders(self):
+    try:
+        response = adapter.get_orders()
+    except requests.HTTPError as e:
+        _logger.error("Failed to fetch orders: %s", e)
+        return False
+
+    for order in response:
+        try:
+            self.import_order(order)
+        except Exception as e:
+            _logger.error("Failed to import order %s: %s", order['id'], e)
+            continue  # Continue with next order
+```
+
+### ❌ Hardcoded Configuration
+```python
+# BAD: Hardcoded values
+API_URL = 'https://api.shopify.com'
+API_KEY = 'hardcoded-key-123'
+```
+
+```python
+# GOOD: Backend configuration
+api_url = self.backend_record.api_url
+api_key = self.backend_record.api_key
+```
+
+### ❌ God Object
+```python
+# BAD: Backend does everything
+class ShopifyBackend(models.Model):
+    def sync_orders(self):
+        # 500 lines of code doing:
+        # - API calls
+        # - Data transformation
+        # - Validation
+        # - Record creation
+        # - Email notifications
+        # etc.
+```
+
+```python
+# GOOD: Separated concerns
+class ShopifyBackend(models.Model):
+    def sync_orders(self):
+        # Orchestration only
+        with self.work_on('shopify.sale.order') as work:
+            importer = work.component(usage='batch.importer')
+            return importer.run()
+
+# Adapter handles API
+# Mapper handles transformation
+# Importer handles record creation
+```