// ─── Boolean context flags ────────────────────────────────────
Trigger.isBefore      // true when executing a before trigger
Trigger.isAfter       // true when executing an after trigger
Trigger.isInsert      // true on insert event
Trigger.isUpdate      // true on update event
Trigger.isDelete      // true on delete event
Trigger.isUndelete    // true on undelete event
Trigger.isExecuting   // true if the current context is a trigger

// ─── Record collections ───────────────────────────────────────
// Trigger.new → List<SObject>
// Writable in BEFORE triggers only. Read-only in AFTER triggers.
List<Account> newAccounts = Trigger.new;

// Trigger.old → List<SObject>  (update, delete only)
List<Account> oldAccounts = Trigger.old;

// Trigger.newMap → Map<Id, SObject>  (after insert, before/after update)
Map<Id, Account> newMap = Trigger.newMap;

// Trigger.oldMap → Map<Id, SObject>  (before/after update, before/after delete)
Map<Id, Account> oldMap = Trigger.oldMap;

// ─── Size ────────────────────────────────────────────────────
Integer count = Trigger.size; // total records in this trigger invocation

// ─── Field change detection pattern (update only) ────────────
for (Account acc : Trigger.new) {
    Account oldAcc = Trigger.oldMap.get(acc.Id);
    if (acc.Rating != oldAcc.Rating) {
        // Rating was changed on this record — take action
    }
    if (acc.OwnerId != oldAcc.OwnerId) {
        // Ownership transferred
    }
}

/**
 * AccountTriggerHandler.cls
 * Handles all Account trigger events.
 * Never call DML or SOQL at class level — only inside methods.
 */
public class AccountTriggerHandler {

    // ──────── BEFORE INSERT ─────────────────────────────────────
    public void onBeforeInsert(List<Account> newAccounts) {
        AccountService.setDefaultValues(newAccounts);
        AccountService.validateRequiredFields(newAccounts);
    }

    // ──────── BEFORE UPDATE ─────────────────────────────────────
    public void onBeforeUpdate(
        List<Account> newAccounts,
        Map<Id, Account> newMap,
        Map<Id, Account> oldMap
    ) {
        AccountService.detectFieldChanges(newAccounts, oldMap);
    }

    // ──────── BEFORE DELETE ─────────────────────────────────────
    public void onBeforeDelete(
        List<Account> oldAccounts,
        Map<Id, Account> oldMap
    ) {
        AccountService.preventDeleteIfHasOpportunities(oldAccounts);
    }

    // ──────── AFTER INSERT ──────────────────────────────────────
    public void onAfterInsert(
        List<Account> newAccounts,
        Map<Id, Account> newMap
    ) {
        AccountService.createDefaultContacts(newAccounts);
        AccountService.sendWelcomeNotification(newAccounts);
    }

    // ──────── AFTER UPDATE ──────────────────────────────────────
    public void onAfterUpdate(
        List<Account> newAccounts,
        Map<Id, Account> newMap,
        Map<Id, Account> oldMap
    ) {
        AccountService.syncRelatedContacts(newAccounts, oldMap);
    }

    // ──────── AFTER DELETE ──────────────────────────────────────
    public void onAfterDelete(
        List<Account> oldAccounts,
        Map<Id, Account> oldMap
    ) {
        AccountService.cleanupOrphanedRecords(oldAccounts);
    }

    // ──────── AFTER UNDELETE ────────────────────────────────────
    public void onAfterUndelete(
        List<Account> restoredAccounts,
        Map<Id, Account> restoredMap
    ) {
        AccountService.reactivateRelatedData(restoredAccounts);
    }
}

/**
 * TriggerBypassHandler.cls
 * Uses Custom Metadata (Trigger_Bypass__mdt) to disable
 * specific triggers during data migrations or integrations.
 * No code deployment needed — just activate the record.
 */
public class TriggerBypassHandler {

    // Cache the metadata query result for this transaction
    private static Map<String, Trigger_Bypass__mdt> bypassMap;

    static {
        bypassMap = new Map<String, Trigger_Bypass__mdt>();
        for (Trigger_Bypass__mdt rec : [
            SELECT DeveloperName, Is_Active__c
            FROM Trigger_Bypass__mdt
            WHERE Is_Active__c = true
        ]) {
            bypassMap.put(rec.DeveloperName, rec);
        }
    }

    /**
     * Returns true if this trigger should be skipped.
     * @param triggerName  API name of the trigger, e.g. 'AccountTrigger'
     */
    public static Boolean isBypassed(String triggerName) {
        return bypassMap.containsKey(triggerName);
    }
}

/**
 * TriggerRecursionGuard.cls
 * Prevents the same record from being processed twice
 * within one transaction — handles bulk correctly.
 */
public class TriggerRecursionGuard {

    // Static — lives for the duration of the transaction
    private static Map<String, Set<Id>> processedIds =
        new Map<String, Set<Id>>();

    /**
     * Returns only records that haven't been processed yet.
     * Records their IDs so they won't be processed again.
     *
     * @param context    Unique string, e.g. 'AccountTrigger.afterUpdate'
     * @param records    Trigger.new or Trigger.old
     */
    public static List<SObject> filterNew(
        String context,
        List<SObject> records
    ) {
        if (!processedIds.containsKey(context)) {
            processedIds.put(context, new Set<Id>());
        }
        Set<Id> seen = processedIds.get(context);
        List<SObject> fresh = new List<SObject>();

        for (SObject rec : records) {
            Id recId = (Id) rec.get('Id');
            if (!seen.contains(recId)) {
                fresh.add(rec);
                seen.add(recId);
            }
        }
        return fresh;
    }
}

// Usage in handler:
public void onAfterUpdate(List<Account> newAccounts, ...) {
    List<SObject> unprocessed = TriggerRecursionGuard.filterNew(
        'AccountTrigger.afterUpdate', newAccounts
    );
    if (unprocessed.isEmpty()) return;
    // ... process only unprocessed
}

public static void validateRequiredFields(List<Account> accounts) {
    for (Account acc : accounts) {

        // Field-level error — highlights the specific field in the UI
        if (String.isBlank(acc.Phone)) {
            acc.Phone.addError('Phone is required for all Account records.');
        }

        // Field-level error with i18n-friendly label reference
        if (acc.AnnualRevenue != null && acc.AnnualRevenue < 0) {
            acc.AnnualRevenue.addError('Annual Revenue cannot be negative.');
        }

        // Record-level error — shown at the top of the page layout
        if (acc.Type == null && acc.AnnualRevenue > 1000000) {
            acc.addError(
                'Account Type is required when Annual Revenue exceeds $1M.'
            );
        }
    }
}