انتقل إلى المحتوى الرئيسي

Tax Entity Deletion

Overview​

This document describes the comprehensive deletion validation system for tax-related entities in the General Ledger module. The system ensures referential integrity and audit trail preservation by preventing deletion of tax configurations that are currently in use across the ERP system.

Business Goal​

Maintain data integrity while allowing administrators to clean up unused tax configurations. The system must prevent deletion of any tax entity that would break existing transaction references or master data assignments, while providing clear feedback about usage constraints.

Tax Entity Hierarchy​

Deletion Rules by Entity​

1. TaxPostingGroup​

Purpose: Defines GL accounts for tax transactions Deletion Rule: Can only be deleted if not assigned to any TaxCode

2. TaxCode​

Purpose: Represents specific tax rates and links to posting groups Deletion Rule: Can only be deleted if:

  • Not a member of any TaxGroup
  • Not a member of any TaxItemGroup
  • Not referenced in any transactions (posted or unposted)

3. TaxGroup​

Purpose: Assigned to entities (Customers/Vendors) to determine tax obligations Deletion Rule: Can only be deleted if:

  • Not assigned to any Customer or Vendor
  • Not referenced in any transactions
  • Not used in subledger transactions

4. TaxItemGroup​

Purpose: Assigned to products/services to determine taxability Deletion Rule: Can only be deleted if:

  • Not assigned to any Items/Products
  • Not referenced in any transactions
  • Not used in subledger transaction lines

Validation Architecture​

Cross-Module Validation Strategy​

The system uses the ITaxUsageValidator interface pattern to check usage across modules without creating tight coupling:

Validation Flow Steps​

  1. Entity Retrieval: Retrieve the tax entity to be deleted
  2. Direct Usage Validation: Check for direct relationships within the same module
  3. Cross-Module Validation: Use ITaxUsageValidator implementations to check usage across modules
  4. Transaction Validation: Verify no posted or unposted transactions reference the entity
  5. Decision: Allow deletion if no blocking usage found, otherwise throw domain exception

Implementation Details​

Domain Exceptions​

Each tax entity has a specific exception type that provides detailed usage information:

  • TaxPostingGroupInUseException
  • TaxCodeInUseException
  • TaxGroupInUseException
  • TaxItemGroupInUseException

These exceptions include:

  • List of specific usage violations
  • User-friendly error messages
  • Entity identification details

Validation Results​

The TaxUsageValidationResult class provides structured information about usage:

public class TaxUsageValidationResult
{
    public int UsageCount { get; init; }
    public string UsageDescription { get; init; }
    public bool HasBlockingUsage { get; init; }
    public IReadOnlyDictionary<string, object> Metadata { get; init; }
    public string ModuleName { get; init; }
}

Safety Mechanisms​

  1. Validation Errors as Blocking: If a validator throws an exception, the system treats it as blocking usage for safety
  2. Comprehensive Logging: All validation steps are logged for audit and debugging
  3. Clear Error Messages: Users receive specific information about what prevents deletion
  4. Fail-Safe Design: Unknown validation states default to preventing deletion

Module Responsibilities​

GeneralLedger Module​

  • Validates usage in ledger journal lines
  • Checks tax code memberships in tax groups/item groups
  • Manages the deletion command handlers

AccountsReceivable Module​

  • Validates customer assignments
  • Checks sales invoice usage
  • Implements ITaxUsageValidator for AR-specific validation

AccountsPayable Module​

  • Validates vendor assignments
  • Checks purchase invoice usage
  • Implements ITaxUsageValidator for AP-specific validation

Inventory Module​

  • Validates item/product assignments
  • Implements ITaxUsageValidator for inventory-specific validation

Error Handling Strategy​

User-Friendly Messages​

Cannot delete tax group 'VAT-DOMESTIC' because it is currently being used. 
Usage found: AccountsReceivable: Assigned to 3 customer(s): C0001, C0002, C0003; 
GeneralLedger: Referenced in 15 ledger journal line(s)

Granular Violation Reporting​

  • Each module reports specific usage details
  • Error messages include entity counts and examples
  • Large lists are truncated with "and X others" notation

Performance Considerations​

Validation Efficiency​

  • Validators use count queries rather than loading full entity sets
  • Cross-module validation runs in parallel where possible
  • Caching strategies for frequently validated entities

Transaction Scope​

  • Deletion operations run within database transactions
  • Validation occurs before any deletion attempts
  • Rollback capabilities for failed operations

Key Architectural Decisions​

Why ITaxUsageValidator Pattern​

  • Loose Coupling: Modules can validate usage without depending on each other
  • Extensibility: New modules can easily add validation by implementing the interface
  • Consistency: Standardized validation approach across the system
  • Testability: Each validator can be unit tested independently

Why Domain Exceptions​

  • Business Logic Enforcement: Exceptions represent violated business rules
  • Rich Information: Include detailed usage information for user feedback
  • Type Safety: Specific exception types for different violation scenarios
  • Error Handling: Standardized exception handling across command handlers

Why Cross-Module Validation​

  • Data Integrity: Prevents orphaned references across module boundaries
  • Audit Trail Preservation: Protects historical transaction references
  • Business Continuity: Ensures ongoing operations aren't disrupted by configuration deletions
  • Compliance: Maintains regulatory audit trail requirements