bc-code-intelligence-mcp 1.3.4 → 1.3.6

package/embedded-knowledge/domains/alex-architect/samples/facade-pattern.md

@@ -0,0 +1,320 @@
+# AL Facade Pattern for External API Integration - Examples
+
+## Basic Facade Structure
+
+```al
+// Facade Pattern: External API Integration Manager
+// Provides simplified interface for complex external API operations
+// Centralizes authentication, error handling, and business logic
+codeunit 50300 "External API Manager"
+{
+    // Public business methods - simplified interface for consumers
+    procedure GetCustomerData(CustomerNo: Code[20]; var CustomerData: Record "Customer"): Boolean
+    var
+        JsonResponse: JsonObject;
+    begin
+        // Business-focused method signature - hides API complexity
+        if not CallCustomerAPI(CustomerNo, JsonResponse) then
+            exit(false);
+
+        exit(ParseCustomerResponse(JsonResponse, CustomerData));
+    end;
+
+    procedure SyncOrderStatus(SalesOrderNo: Code[20]): Boolean
+    var
+        JsonResponse: JsonObject;
+        OrderStatus: Text;
+    begin
+        // Single method for complex order synchronization process
+        if not CallOrderStatusAPI(SalesOrderNo, JsonResponse) then
+            exit(false);
+
+        if not ExtractOrderStatus(JsonResponse, OrderStatus) then
+            exit(false);
+
+        exit(UpdateLocalOrderStatus(SalesOrderNo, OrderStatus));
+    end;
+
+    procedure ValidateProductCatalog(ItemNo: Code[20]; var IsValid: Boolean; var ErrorMessage: Text): Boolean
+    var
+        JsonResponse: JsonObject;
+    begin
+        // Centralized validation with business-friendly error messages
+        if not CallProductValidationAPI(ItemNo, JsonResponse) then begin
+            ErrorMessage := 'Unable to validate product with external system';
+            IsValid := false;
+            exit(false);
+        end;
+
+        exit(ProcessValidationResponse(JsonResponse, IsValid, ErrorMessage));
+    end;
+
+    // Private implementation methods - hidden complexity
+    local procedure CallCustomerAPI(CustomerNo: Code[20]; var JsonResponse: JsonObject): Boolean
+    var
+        HttpClient: HttpClient;
+        RequestMessage: HttpRequestMessage;
+        ResponseMessage: HttpResponseMessage;
+        ApiUrl: Text;
+    begin
+        // Handle authentication automatically
+        if not EnsureAuthenticated() then
+            exit(false);
+
+        // Construct API endpoint with proper formatting
+        ApiUrl := StrSubstNo('%1/customers/%2', GetBaseApiUrl(), CustomerNo);
+
+        // Configure authenticated request
+        if not PrepareAuthenticatedRequest(RequestMessage, 'GET', ApiUrl) then
+            exit(false);
+
+        // Execute with retry logic and error handling
+        if not ExecuteApiCall(HttpClient, RequestMessage, ResponseMessage) then
+            exit(false);
+
+        exit(ParseJsonResponse(ResponseMessage, JsonResponse));
+    end;
+}
+```
+
+## API Call Abstraction
+
+```al
+// Private methods handling technical API details
+codeunit 50301 "API Technical Layer"
+{
+    var
+        AuthToken: Text;
+        BaseApiUrl: Text;
+        LastAuthTime: DateTime;
+        TokenExpiryMinutes: Integer;
+
+    // Authentication management - hidden from business logic
+    local procedure EnsureAuthenticated(): Boolean
+    var
+        CurrentTime: DateTime;
+        MinutesSinceAuth: Integer;
+    begin
+        CurrentTime := CurrentDateTime;
+        MinutesSinceAuth := (CurrentTime - LastAuthTime) / 60000;
+
+        // Token refresh logic
+        if (AuthToken = '') or (MinutesSinceAuth >= TokenExpiryMinutes) then
+            exit(RefreshAuthToken());
+
+        exit(AuthToken <> '');
+    end;
+
+    local procedure RefreshAuthToken(): Boolean
+    var
+        HttpClient: HttpClient;
+        RequestMessage: HttpRequestMessage;
+        ResponseMessage: HttpResponseMessage;
+        AuthEndpoint: Text;
+        RequestBody: Text;
+        Content: HttpContent;
+        JsonResponse: JsonObject;
+        TokenValue: JsonToken;
+        Headers: HttpHeaders;
+    begin
+        AuthEndpoint := GetBaseApiUrl() + '/auth/token';
+        RequestBody := StrSubstNo('{"client_id": "%1", "client_secret": "%2", "grant_type": "client_credentials"}',
+                                 GetClientId(), GetClientSecret());
+
+        Content.WriteFrom(RequestBody);
+        Content.GetHeaders(Headers);
+        Headers.Clear();
+        Headers.Add('Content-Type', 'application/json');
+
+        RequestMessage.Method := 'POST';
+        RequestMessage.SetRequestUri(AuthEndpoint);
+        RequestMessage.Content := Content;
+
+        if not HttpClient.Send(RequestMessage, ResponseMessage) then begin
+            LogError('Authentication request failed');
+            exit(false);
+        end;
+
+        if not ResponseMessage.IsSuccessStatusCode() then begin
+            LogError(StrSubstNo('Authentication failed with status: %1', ResponseMessage.HttpStatusCode()));
+            exit(false);
+        end;
+
+        if not ParseJsonResponse(ResponseMessage, JsonResponse) then
+            exit(false);
+
+        if JsonResponse.Get('access_token', TokenValue) then begin
+            AuthToken := TokenValue.AsValue().AsText();
+            LastAuthTime := CurrentDateTime;
+            TokenExpiryMinutes := 55; // Refresh before 60-minute expiry
+            exit(true);
+        end;
+
+        LogError('Access token not found in authentication response');
+        exit(false);
+    end;
+
+    // Generic API call execution with retry logic
+    local procedure ExecuteApiCall(var HttpClient: HttpClient; RequestMessage: HttpRequestMessage; var ResponseMessage: HttpResponseMessage): Boolean
+    var
+        RetryCount: Integer;
+        MaxRetries: Integer;
+        Success: Boolean;
+        StatusCode: Integer;
+    begin
+        MaxRetries := 3;
+        RetryCount := 0;
+
+        repeat
+            Success := HttpClient.Send(RequestMessage, ResponseMessage);
+
+            if Success then begin
+                StatusCode := ResponseMessage.HttpStatusCode();
+
+                // Success status codes
+                if (StatusCode >= 200) and (StatusCode < 300) then
+                    exit(true);
+
+                // Retryable status codes (temporary failures)
+                if (StatusCode = 429) or (StatusCode >= 500) then begin
+                    RetryCount += 1;
+                    if RetryCount < MaxRetries then begin
+                        Sleep(RetryCount * 2000); // Exponential backoff: 2s, 4s, 6s
+                        continue;
+                    end;
+                end;
+            end;
+
+            RetryCount += 1;
+            if RetryCount < MaxRetries then
+                Sleep(RetryCount * 2000);
+
+        until RetryCount >= MaxRetries;
+
+        LogError(StrSubstNo('API call failed after %1 retries', MaxRetries));
+        exit(false);
+    end;
+}
+```
+
+## Error Handling and Authentication
+
+```al
+// Centralized error handling with business-friendly messages
+codeunit 50302 "API Error Handler"
+{
+    // Business-friendly error handling
+    procedure HandleApiError(var ErrorMessage: Text; HttpStatusCode: Integer; ApiResponse: Text): Boolean
+    var
+        JsonResponse: JsonObject;
+        ErrorToken: JsonToken;
+        ErrorCode: Text;
+        DetailedMessage: Text;
+    begin
+        // Parse error response if JSON
+        if JsonResponse.ReadFrom(ApiResponse) then begin
+            if JsonResponse.Get('error_code', ErrorToken) then
+                ErrorCode := ErrorToken.AsValue().AsText();
+
+            if JsonResponse.Get('message', ErrorToken) then
+                DetailedMessage := ErrorToken.AsValue().AsText();
+        end;
+
+        // Convert technical errors to business messages
+        case HttpStatusCode of
+            400:
+                ErrorMessage := GetBusinessErrorMessage('INVALID_REQUEST', ErrorCode, DetailedMessage);
+            401:
+                ErrorMessage := 'Authentication failed. Please check system configuration.';
+            403:
+                ErrorMessage := 'Access denied. Insufficient permissions for this operation.';
+            404:
+                ErrorMessage := 'The requested resource was not found in the external system.';
+            409:
+                ErrorMessage := 'Data conflict detected. The record may have been modified by another user.';
+            422:
+                ErrorMessage := GetBusinessErrorMessage('VALIDATION_FAILED', ErrorCode, DetailedMessage);
+            429:
+                ErrorMessage := 'External system is busy. Please try again in a few minutes.';
+            500, 502, 503:
+                ErrorMessage := 'External system is temporarily unavailable. Please try again later.';
+            else
+                ErrorMessage := StrSubstNo('Unexpected error occurred (Code: %1). Please contact your administrator.', HttpStatusCode);
+        end;
+
+        // Log technical details for troubleshooting (not shown to user)
+        LogTechnicalError(HttpStatusCode, ApiResponse);
+
+        exit(false); // Always return false for error conditions
+    end;
+}
+```
+
+## Anti-Pattern: Direct API Calls
+
+```al
+// ANTI-PATTERN: What NOT to do - Scattered API calls throughout codebase
+// Problems: Code duplication, inconsistent error handling, tight coupling
+
+// BAD EXAMPLE: Direct API calls in business logic
+codeunit 50400 "Sales Order Processing" // DON'T DO THIS
+{
+    procedure ProcessSalesOrder(var SalesHeader: Record "Sales Header")
+    var
+        HttpClient: HttpClient;
+        RequestMessage: HttpRequestMessage;
+        ResponseMessage: HttpResponseMessage;
+        CustomerNo: Code[20];
+        AuthToken: Text;
+        ApiUrl: Text;
+    begin
+        CustomerNo := SalesHeader."Sell-to Customer No.";
+
+        // PROBLEM: Authentication logic scattered everywhere
+        AuthToken := GetAuthTokenSomehow(); // Duplicated in multiple places
+
+        // PROBLEM: URL construction repeated in many methods
+        ApiUrl := 'https://api.external.com/customers/' + CustomerNo;
+
+        RequestMessage.Method := 'GET';
+        RequestMessage.SetRequestUri(ApiUrl);
+
+        // PROBLEM: No standardized error handling
+        if not HttpClient.Send(RequestMessage, ResponseMessage) then
+            Error('Something went wrong'); // Unhelpful error message
+
+        // Business logic mixed with technical concerns
+        ProcessCustomerData(ResponseMessage);
+    end;
+}
+
+/*
+PROBLEMS WITH ANTI-PATTERN APPROACH:
+
+1. Code Duplication:
+   - Authentication logic repeated in every method
+   - URL construction patterns scattered throughout
+   - Response parsing duplicated everywhere
+
+2. Maintenance Nightmare:
+   - Changes to API authentication require updates in multiple places
+   - URL changes affect many different files
+   - Error handling improvements need to be replicated everywhere
+
+3. Poor Separation of Concerns:
+   - Business logic mixed with technical HTTP details
+   - UI components directly calling APIs
+   - Reports tightly coupled to external systems
+
+4. Testing Difficulties:
+   - Cannot easily mock external API calls
+   - Business logic testing requires network setup
+   - Integration tests become complex and brittle
+
+CORRECT APPROACH: Use the Facade Pattern shown above
+- Centralized API management
+- Consistent error handling
+- Separated concerns
+- Testable components
+*/
+```

package/embedded-knowledge/domains/alex-architect/samples/subscriber-organization.md

@@ -0,0 +1,102 @@
+# Subscriber Codeunit Size Optimization - AL Code Samples
+
+## Anti-Pattern: Monolithic Subscriber
+
+```al
+codeunit 50500 "Monolithic Event Subscriber"
+{
+    // ANTI-PATTERN: All subscribers in one large codeunit
+    
+    [EventSubscriber(ObjectType::Table, Database::Customer, 'OnBeforeInsertEvent', '', false, false)]
+    local procedure OnBeforeCustomerInsert(var Rec: Record Customer; RunTrigger: Boolean)
+    begin
+        ValidateCustomerData(Rec);
+        CheckCustomerCreditLimit(Rec);
+        UpdateCustomerStatistics(Rec);
+        LogCustomerCreation(Rec);
+        // Many more operations creating a massive procedure
+    end;
+
+    [EventSubscriber(ObjectType::Table, Database::Item, 'OnBeforeInsertEvent', '', false, false)]
+    local procedure OnBeforeItemInsert(var Rec: Record Item; RunTrigger: Boolean)
+    begin
+        ValidateItemData(Rec);
+        SetupItemDefaults(Rec);
+        CheckItemInventory(Rec);
+        // Many more operations
+    end;
+}
+```
+
+## Optimized Pattern: Focused Subscribers
+
+```al
+codeunit 50501 "Customer Event Subscriber"
+{
+    // Single responsibility: Handle only customer-related events
+    
+    [EventSubscriber(ObjectType::Table, Database::Customer, 'OnBeforeInsertEvent', '', false, false)]
+    local procedure OnBeforeCustomerInsert(var Rec: Record Customer; RunTrigger: Boolean)
+    begin
+        if not RunTrigger then exit;
+        
+        CustomerValidationHandler.ValidateNewCustomer(Rec);
+        CustomerSetupHandler.ApplyDefaultSettings(Rec);
+        CustomerNotificationHandler.NotifyNewCustomer(Rec);
+    end;
+    
+    var
+        CustomerValidationHandler: Codeunit "Customer Validation Handler";
+        CustomerSetupHandler: Codeunit "Customer Setup Handler";
+        CustomerNotificationHandler: Codeunit "Customer Notification Handler";
+}
+
+codeunit 50502 "Item Event Subscriber"
+{
+    // Single responsibility: Handle only item-related events
+    
+    [EventSubscriber(ObjectType::Table, Database::Item, 'OnBeforeInsertEvent', '', false, false)]
+    local procedure OnBeforeItemInsert(var Rec: Record Item; RunTrigger: Boolean)
+    begin
+        if not RunTrigger then exit;
+        
+        ItemValidationHandler.ValidateNewItem(Rec);
+        ItemSetupHandler.ApplyDefaultSettings(Rec);
+    end;
+    
+    var
+        ItemValidationHandler: Codeunit "Item Validation Handler";
+        ItemSetupHandler: Codeunit "Item Setup Handler";
+}
+```
+
+## Specialized Handler Pattern
+
+```al
+codeunit 50510 "Customer Validation Handler"
+{
+    // Focused on customer validation logic only
+    
+    procedure ValidateNewCustomer(var Customer: Record Customer)
+    begin
+        ValidateRequiredFields(Customer);
+        ValidateBusinessRules(Customer);
+        ValidateDataIntegrity(Customer);
+    end;
+    
+    local procedure ValidateRequiredFields(var Customer: Record Customer)
+    begin
+        if Customer.Name = '' then
+            Error('Customer name is required');
+            
+        if Customer."Country/Region Code" = '' then
+            Error('Country/Region Code is required');
+    end;
+    
+    local procedure ValidateBusinessRules(var Customer: Record Customer)
+    begin
+        if (Customer."Credit Limit (LCY)" > 100000) and (Customer."Payment Terms Code" = '') then
+            Error('Payment terms required for customers with credit limit over 100,000');
+    end;
+}
+```