@salesforce/afv-skills 1.4.0 → 1.5.1

package/skills/generating-apex/references/AccountDeduplicationBatch.cls

@@ -0,0 +1,148 @@
+/**
+ * @description Batch Apex class for identifying and flagging duplicate Account records.
+ *              Compares Accounts by Name and BillingPostalCode to find potential duplicates.
+ *              Flags duplicates by setting the Is_Potential_Duplicate__c checkbox.
+ *              Implements Database.Stateful to track results across batch chunks.
+ * @author Generated by Apex Class Writer Skill
+ *
+ * @example
+ * // Run with default batch size (200)
+ * Id jobId = AccountDeduplicationBatch.run();
+ *
+ * // Run with smaller batch size for complex processing
+ * Database.executeBatch(new AccountDeduplicationBatch(), 50);
+ */
+public with sharing class AccountDeduplicationBatch implements Database.Batchable<SObject>, Database.Stateful {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final Integer DEFAULT_BATCH_SIZE = 200;
+
+    // ─── Stateful Tracking ───────────────────────────────────────────────
+    private Integer totalScanned = 0;
+    private Integer duplicatesFound = 0;
+    private Integer totalErrors = 0;
+    private List<String> errorMessages = new List<String>();
+
+    // ─── Batchable Interface ─────────────────────────────────────────────
+
+    /**
+     * @description Queries all active Accounts that haven't already been flagged
+     * @param bc The batch context
+     * @return QueryLocator scoped to unflagged active Accounts
+     */
+    public Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator([
+            SELECT Id, Name, BillingPostalCode, Is_Potential_Duplicate__c
+            FROM Account
+            WHERE IsDeleted = FALSE
+            AND Is_Potential_Duplicate__c = FALSE
+            ORDER BY Name ASC
+        ]);
+    }
+
+    /**
+     * @description Processes each batch by building a duplicate key and checking for matches.
+     *              Uses a composite key of normalized Name + BillingPostalCode.
+     * @param bc The batch context
+     * @param scope List of Account records in the current batch
+     */
+    public void execute(Database.BatchableContext bc, List<Account> scope) {
+        totalScanned += scope.size();
+
+        // Build duplicate keys for this batch
+        Map<String, List<Account>> dupeKeyMap = new Map<String, List<Account>>();
+        for (Account acct : scope) {
+            String key = buildDuplicateKey(acct);
+            if (String.isNotBlank(key)) {
+                if (!dupeKeyMap.containsKey(key)) {
+                    dupeKeyMap.put(key, new List<Account>());
+                }
+                dupeKeyMap.get(key).add(acct);
+            }
+        }
+
+        // Flag records that share a key with another record
+        List<Account> toUpdate = new List<Account>();
+        for (String key : dupeKeyMap.keySet()) {
+            List<Account> group = dupeKeyMap.get(key);
+            if (group.size() > 1) {
+                for (Account acct : group) {
+                    toUpdate.add(new Account(
+                        Id = acct.Id,
+                        Is_Potential_Duplicate__c = true
+                    ));
+                }
+            }
+        }
+
+        if (!toUpdate.isEmpty()) {
+            List<Database.SaveResult> results = Database.update(toUpdate, false);
+            processResults(results);
+        }
+    }
+
+    /**
+     * @description Logs a summary of the deduplication batch run
+     * @param bc The batch context
+     */
+    public void finish(Database.BatchableContext bc) {
+        String summary = String.format(
+            'AccountDeduplicationBatch completed. Scanned: {0}, Duplicates flagged: {1}, Errors: {2}',
+            new List<Object>{ totalScanned, duplicatesFound, totalErrors }
+        );
+
+        System.debug(LoggingLevel.INFO, summary);
+
+        if (!errorMessages.isEmpty()) {
+            System.debug(LoggingLevel.ERROR, 'Error details:\n' + String.join(errorMessages, '\n'));
+        }
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * @description Builds a normalized composite key for duplicate detection
+     * @param acct The Account record
+     * @return Normalized key string, or null if insufficient data
+     */
+    private String buildDuplicateKey(Account acct) {
+        if (String.isBlank(acct.Name)) {
+            return null;
+        }
+
+        String normalizedName = acct.Name.trim().toUpperCase().replaceAll('\\s+', ' ');
+        String postalCode = (acct.BillingPostalCode ?? '').trim().toUpperCase();
+
+        return normalizedName + '|' + postalCode;
+    }
+
+    /**
+     * @description Processes DML results, tracking successes and failures
+     * @param results List of Database.SaveResult from update operation
+     */
+    private void processResults(List<Database.SaveResult> results) {
+        for (Database.SaveResult sr : results) {
+            if (sr.isSuccess()) {
+                duplicatesFound++;
+            } else {
+                totalErrors++;
+                for (Database.Error err : sr.getErrors()) {
+                    errorMessages.add(
+                        'Record ' + sr.getId() + ': ' +
+                        err.getStatusCode() + ' - ' + err.getMessage()
+                    );
+                }
+            }
+        }
+    }
+
+    // ─── Static Helpers ──────────────────────────────────────────────────
+
+    /**
+     * @description Convenience method to execute with default batch size
+     * @return The batch job Id
+     */
+    public static Id run() {
+        return Database.executeBatch(new AccountDeduplicationBatch(), DEFAULT_BATCH_SIZE);
+    }
+}

package/skills/generating-apex/references/AccountSelector.cls

@@ -0,0 +1,193 @@
+/**
+ * @description Selector class for Account queries.
+ *              Encapsulates all SOQL for Account records.
+ *              All methods return bulkified results (Lists or Maps).
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class AccountSelector {
+
+    // ─── Field Lists ─────────────────────────────────────────────────────
+
+    /**
+     * @description Returns the default set of fields to query for Account.
+     *              Centralizes field references to keep queries DRY.
+     * @return Comma-separated field list as a String
+     */
+    private static String getDefaultFields() {
+        return String.join(
+            new List<String>{
+                'Id',
+                'Name',
+                'AccountNumber',
+                'Type',
+                'Industry',
+                'AnnualRevenue',
+                'NumberOfEmployees',
+                'Phone',
+                'Website',
+                'OwnerId',
+                'CreatedDate',
+                'LastModifiedDate'
+            },
+            ', '
+        );
+    }
+
+    /**
+     * @description Returns fields needed for billing/territory operations
+     * @return Comma-separated field list as a String
+     */
+    private static String getBillingFields() {
+        return String.join(
+            new List<String>{
+                'Id',
+                'Name',
+                'BillingStreet',
+                'BillingCity',
+                'BillingState',
+                'BillingPostalCode',
+                'BillingCountry',
+                'Territory__c'
+            },
+            ', '
+        );
+    }
+
+    // ─── Query Methods ───────────────────────────────────────────────────
+
+    /**
+     * @description Selects Account records by their Ids
+     * @param recordIds Set of Account Ids to query
+     * @return List of Account records matching the provided Ids
+     * @example
+     * Set<Id> ids = new Set<Id>{ '001xx000003DGbY' };
+     * List<Account> results = AccountSelector.selectByIds(ids);
+     */
+    public static List<Account> selectByIds(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM Account' +
+            ' WHERE Id IN :recordIds'
+        );
+    }
+
+    /**
+     * @description Selects Account records as a Map keyed by Id
+     * @param recordIds Set of Account Ids to query
+     * @return Map of Id to Account
+     */
+    public static Map<Id, Account> selectMapByIds(Set<Id> recordIds) {
+        return new Map<Id, Account>(selectByIds(recordIds));
+    }
+
+    /**
+     * @description Selects Accounts with billing address fields for territory assignment
+     * @param recordIds Set of Account Ids to query
+     * @return List of Account records with billing address fields populated
+     */
+    public static List<Account> selectWithBillingAddress(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return Database.query(
+            'SELECT ' + getBillingFields() +
+            ' FROM Account' +
+            ' WHERE Id IN :recordIds'
+        );
+    }
+
+    /**
+     * @description Selects Accounts by Account Type
+     * @param accountTypes Set of Account Type values to filter by
+     * @return List of matching Account records
+     * @example
+     * List<Account> prospects = AccountSelector.selectByType(
+     *     new Set<String>{ 'Prospect', 'Customer - Direct' }
+     * );
+     */
+    public static List<Account> selectByType(Set<String> accountTypes) {
+        if (accountTypes == null || accountTypes.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM Account' +
+            ' WHERE Type IN :accountTypes' +
+            ' ORDER BY Name ASC'
+        );
+    }
+
+    /**
+     * @description Selects Accounts by Industry with a minimum annual revenue
+     * @param industries Set of Industry values to filter by
+     * @param minRevenue Minimum AnnualRevenue threshold
+     * @return List of matching Account records ordered by revenue descending
+     * @example
+     * List<Account> techAccounts = AccountSelector.selectByIndustryAndRevenue(
+     *     new Set<String>{ 'Technology' },
+     *     1000000
+     * );
+     */
+    public static List<Account> selectByIndustryAndRevenue(Set<String> industries, Decimal minRevenue) {
+        if (industries == null || industries.isEmpty()) {
+            return new List<Account>();
+        }
+
+        Decimal revenueThreshold = minRevenue ?? 0;
+
+        return Database.query(
+            'SELECT ' + getDefaultFields() +
+            ' FROM Account' +
+            ' WHERE Industry IN :industries' +
+            ' AND AnnualRevenue >= :revenueThreshold' +
+            ' ORDER BY AnnualRevenue DESC'
+        );
+    }
+
+    /**
+     * @description Selects Accounts with their related Contacts (subquery)
+     * @param recordIds Set of Account Ids to query
+     * @return List of Account records with nested Contacts
+     */
+    public static List<Account> selectWithContacts(Set<Id> recordIds) {
+        if (recordIds == null || recordIds.isEmpty()) {
+            return new List<Account>();
+        }
+
+        return [
+            SELECT Id, Name, Type, Industry,
+                   (SELECT Id, FirstName, LastName, Email, Title
+                    FROM Contacts
+                    ORDER BY LastName ASC)
+            FROM Account
+            WHERE Id IN :recordIds
+        ];
+    }
+
+    // ─── Aggregate Queries ───────────────────────────────────────────────
+
+    /**
+     * @description Returns a count of Accounts grouped by Industry
+     * @return List of AggregateResult with Industry and record count
+     * @example
+     * List<AggregateResult> results = AccountSelector.countByIndustry();
+     * for (AggregateResult ar : results) {
+     *     System.debug(ar.get('Industry') + ': ' + ar.get('cnt'));
+     * }
+     */
+    public static List<AggregateResult> countByIndustry() {
+        return [
+            SELECT Industry, COUNT(Id) cnt
+            FROM Account
+            WHERE Industry != NULL
+            GROUP BY Industry
+            ORDER BY COUNT(Id) DESC
+        ];
+    }
+}

package/skills/generating-apex/references/AccountService.cls

@@ -0,0 +1,201 @@
+/**
+ * @description Service class for Account business logic.
+ *              Provides account deduplication, enrichment, and territory assignment.
+ *              Delegates queries to AccountSelector and SObject manipulation to AccountDomain.
+ * @author Generated by Apex Class Writer Skill
+ */
+public with sharing class AccountService {
+
+    // ─── Constants ───────────────────────────────────────────────────────
+    private static final String ERROR_NULL_INPUT = 'Input cannot be null or empty.';
+    private static final String ERROR_MERGE_FAILED = 'Account merge failed for master Id: ';
+    private static final Integer MAX_MERGE_BATCH = 3;
+
+    // ─── Public API ──────────────────────────────────────────────────────
+
+    /**
+     * @description Merges duplicate Account records into a master record.
+     *              The master record retains its field values; child records are reparented.
+     * @param masterIds Map of master Account Id to Set of duplicate Account Ids to merge
+     * @return List of master Account Ids that were successfully merged
+     * @throws AccountServiceException if merge processing fails
+     * @example
+     * Map<Id, Set<Id>> mergeMap = new Map<Id, Set<Id>>{
+     *     masterAcctId => new Set<Id>{ dupeId1, dupeId2 }
+     * };
+     * List<Id> mergedIds = AccountService.mergeAccounts(mergeMap);
+     */
+    public static List<Id> mergeAccounts(Map<Id, Set<Id>> mergeMap) {
+        if (mergeMap == null || mergeMap.isEmpty()) {
+            throw new AccountServiceException(ERROR_NULL_INPUT);
+        }
+
+        // Collect all Ids for a single query
+        Set<Id> allIds = new Set<Id>();
+        allIds.addAll(mergeMap.keySet());
+        for (Set<Id> dupeIds : mergeMap.values()) {
+            allIds.addAll(dupeIds);
+        }
+
+        // Query all records at once via Selector
+        Map<Id, Account> accountMap = AccountSelector.selectMapByIds(allIds);
+
+        List<Id> successfulMerges = new List<Id>();
+        List<String> errors = new List<String>();
+
+        for (Id masterId : mergeMap.keySet()) {
+            Account master = accountMap.get(masterId);
+            if (master == null) {
+                errors.add('Master account not found: ' + masterId);
+                continue;
+            }
+
+            List<Account> duplicates = new List<Account>();
+            for (Id dupeId : mergeMap.get(masterId)) {
+                Account dupe = accountMap.get(dupeId);
+                if (dupe != null) {
+                    duplicates.add(dupe);
+                }
+            }
+
+            try {
+                // Apex merge supports up to 3 records at a time
+                for (List<Account> chunk : chunkAccounts(duplicates, MAX_MERGE_BATCH)) {
+                    Database.merge(master, chunk);
+                }
+                successfulMerges.add(masterId);
+            } catch (DmlException e) {
+                errors.add(ERROR_MERGE_FAILED + masterId + ' - ' + e.getMessage());
+            }
+        }
+
+        if (!errors.isEmpty()) {
+            System.debug(LoggingLevel.WARN, 'Merge errors: ' + String.join(errors, '\n'));
+        }
+
+        return successfulMerges;
+    }
+
+    /**
+     * @description Assigns accounts to territories based on Billing State/Country.
+     *              Uses Custom Metadata Type (Territory_Mapping__mdt) for mappings.
+     * @param accountIds Set of Account Ids to assign territories for
+     * @return Number of accounts successfully updated
+     * @throws AccountServiceException if territory assignment fails
+     */
+    public static Integer assignTerritories(Set<Id> accountIds) {
+        if (accountIds == null || accountIds.isEmpty()) {
+            throw new AccountServiceException(ERROR_NULL_INPUT);
+        }
+
+        List<Account> accounts = AccountSelector.selectWithBillingAddress(accountIds);
+        Map<String, String> territoryMap = loadTerritoryMappings();
+
+        List<Account> toUpdate = new List<Account>();
+        for (Account acct : accounts) {
+            String key = buildTerritoryKey(acct.BillingState, acct.BillingCountry);
+            String territory = territoryMap.get(key);
+
+            if (territory != null && territory != acct.Territory__c) {
+                toUpdate.add(new Account(
+                    Id = acct.Id,
+                    Territory__c = territory
+                ));
+            }
+        }
+
+        if (!toUpdate.isEmpty()) {
+            List<Database.SaveResult> results = Database.update(toUpdate, false);
+            return countSuccesses(results);
+        }
+
+        return 0;
+    }
+
+    // ─── Convenience Overloads ───────────────────────────────────────────
+
+    /**
+     * @description Single-account territory assignment convenience method
+     * @param accountId The Account Id to assign a territory for
+     * @return 1 if updated, 0 if no change needed
+     */
+    public static Integer assignTerritory(Id accountId) {
+        return assignTerritories(new Set<Id>{ accountId });
+    }
+
+    // ─── Private Helpers ─────────────────────────────────────────────────
+
+    /**
+     * @description Loads territory mappings from Custom Metadata
+     * @return Map of territory key (State:Country) to territory name
+     */
+    private static Map<String, String> loadTerritoryMappings() {
+        Map<String, String> mappings = new Map<String, String>();
+        for (Territory_Mapping__mdt mapping : Territory_Mapping__mdt.getAll().values()) {
+            String key = buildTerritoryKey(mapping.State__c, mapping.Country__c);
+            mappings.put(key, mapping.Territory_Name__c);
+        }
+        return mappings;
+    }
+
+    /**
+     * @description Builds a consistent territory lookup key
+     * @param state The billing state
+     * @param country The billing country
+     * @return A normalized key string
+     */
+    private static String buildTerritoryKey(String state, String country) {
+        return (state ?? '').toUpperCase() + ':' + (country ?? '').toUpperCase();
+    }
+
+    /**
+     * @description Chunks a list of Accounts into sublists of the given size
+     * @param accounts The accounts to chunk
+     * @param chunkSize Maximum chunk size
+     * @return List of account sublists
+     */
+    private static List<List<Account>> chunkAccounts(List<Account> accounts, Integer chunkSize) {
+        List<List<Account>> chunks = new List<List<Account>>();
+        List<Account> current = new List<Account>();
+
+        for (Account acct : accounts) {
+            current.add(acct);
+            if (current.size() == chunkSize) {
+                chunks.add(current);
+                current = new List<Account>();
+            }
+        }
+        if (!current.isEmpty()) {
+            chunks.add(current);
+        }
+        return chunks;
+    }
+
+    /**
+     * @description Counts successful results from a DML operation
+     * @param results List of Database.SaveResult
+     * @return Count of successful operations
+     */
+    private static Integer countSuccesses(List<Database.SaveResult> results) {
+        Integer count = 0;
+        for (Database.SaveResult sr : results) {
+            if (sr.isSuccess()) {
+                count++;
+            } else {
+                for (Database.Error err : sr.getErrors()) {
+                    System.debug(LoggingLevel.WARN,
+                        'Update failed for ' + sr.getId() + ': ' + err.getMessage()
+                    );
+                }
+            }
+        }
+        return count;
+    }
+
+    // ─── Exception ───────────────────────────────────────────────────────
+
+    /**
+     * @description Custom exception for AccountService errors
+     */
+    public class AccountServiceException extends Exception {}
+}

package/skills/generating-apex-test/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: generating-apex-test
+description: Apex test class generation with TestDataFactory patterns, bulk testing (200+ records), mocking strategies, and assertion best practices. Use this skill when the user asks to create, write, or improve Apex test classes, add coverage, build mocks, or implement testing patterns for triggers, services, batch jobs, queueables, and integrations.
+---
+
+# Apex Test Class Skill
+
+## Core Principles
+
+1. **Bulkify tests** - Always test with 200+ records to catch governor limit issues
+2. **Isolate test data** - Use `@TestSetup` and TestDataFactory; never rely on org data
+3. **Assert meaningfully** - Test behavior, not just coverage; include failure messages
+4. **Mock external dependencies** - Use `HttpCalloutMock`, `Test.setMock()` for integrations
+5. **Test negative paths** - Validate error handling, not just happy paths
+
+## Test Class Structure
+
+```apex
+@isTest
+private class MyServiceTest {
+
+    @TestSetup
+    static void setupTestData() {
+        // Create shared test data using TestDataFactory
+        List<Account> accounts = TestDataFactory.createAccounts(200, true);
+    }
+
+    @isTest
+    static void shouldPerformExpectedBehavior_WhenValidInput() {
+        // Given: Setup specific test state
+        List<Account> accounts = [SELECT Id, Name FROM Account];
+        
+        // When: Execute the code under test
+        Test.startTest();
+        MyService.processAccounts(accounts);
+        Test.stopTest();
+        
+        // Then: Assert expected outcomes
+        List<Account> updated = [SELECT Id, Status__c FROM Account];
+        System.assertEquals(200, updated.size(), 'All accounts should be processed');
+        for (Account acc : updated) {
+            System.assertEquals('Processed', acc.Status__c, 'Status should be updated');
+        }
+    }
+
+    @isTest
+    static void shouldThrowException_WhenInvalidInput() {
+        // Given
+        List<Account> emptyList = new List<Account>();
+        
+        // When/Then
+        Test.startTest();
+        try {
+            MyService.processAccounts(emptyList);
+            System.assert(false, 'Expected MyCustomException to be thrown');
+        } catch (MyCustomException e) {
+            System.assert(e.getMessage().contains('cannot be empty'), 
+                'Exception message should indicate empty input');
+        }
+        Test.stopTest();
+    }
+}
+```
+
+## Naming Convention
+
+Use descriptive method names: `should[ExpectedBehavior]_When[Condition]`
+
+Examples:
+- `shouldCreateContact_WhenAccountIsActive`
+- `shouldThrowException_WhenEmailIsInvalid`
+- `shouldSendNotification_WhenOpportunityClosedWon`
+- `shouldBypassTrigger_WhenRunningAsBatch`
+
+## Test.startTest() / Test.stopTest()
+
+Always wrap the code under test:
+- Resets governor limits for accurate limit testing
+- Executes async operations synchronously (queueables, batch, future)
+- Fires scheduled jobs immediately
+
+## Asset Templates
+
+Ready-to-use scaffolds for common test patterns:
+
+- **[assets/test-class-template.cls](assets/test-class-template.cls)** - Starter test class with positive, negative, bulk, and governor limit test stubs
+- **[assets/test-data-factory-template.cls](assets/test-data-factory-template.cls)** - TestDataFactory with Account, Contact, Opportunity, User factories and field override support
+
+## Reference Files
+
+Detailed patterns for specific scenarios:
+
+- **[references/test-data-factory.md](references/test-data-factory.md)** - TestDataFactory class patterns and field defaults
+- **[references/assertion-patterns.md](references/assertion-patterns.md)** - Assertion best practices and common pitfalls
+- **[references/mocking-patterns.md](references/mocking-patterns.md)** - HttpCalloutMock, Test.setMock(), stubbing
+- **[references/async-testing.md](references/async-testing.md)** - Batch, Queueable, Future, Scheduled job testing
+
+## Quick Reference: What to Test
+
+| Component | Key Test Scenarios |
+|-----------|-------------------|
+| Trigger | Bulk insert/update/delete, recursion, field changes |
+| Service | Valid/invalid inputs, bulk operations, exceptions |
+| Controller | Page load, action methods, view state |
+| Batch | Start/execute/finish, chunking, error records |
+| Queueable | Chaining, bulkification, error handling |
+| Callout | Success response, error response, timeout |
+| Scheduled | Execution, CRON validation |