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

// Filename: docs/concepts/tax-settlement-to-ap-invoice.concept.md

Concept: Tax Settlement to Accounts Payable Invoice Flow

1. Overview​

This document outlines the cross-module process that transforms a calculated tax liability from the General Ledger (GL) module into a payable vendor invoice in the Accounts Payable (AP) module. This allows the organization to pay its tax liabilities using the standard vendor payment process.

The core principle is to treat the Tax Authority as a Vendor. The net tax liability for a period becomes a service-based invoice that the AP department pays.

2. Process Flow​

The flow is initiated after a tax settlement journal is posted in the General Ledger.

  1. GL: Journal Posted: The TaxSettlementJournalPostedEventHandler in the GL module listens for LedgerJournalPostedDomainEvent.
  2. GL: Event Published: If the posted journal is a TaxSettlement type, the handler calculates the net liability and publishes a TaxSettlementPayableCreatedIntegrationEvent to the message bus. This event contains the Tax Authority's Vendor Account ID, the payable amount, and the GL settlement voucher number.
  3. AP: Event Consumed: The TaxSettlementPayableCreatedIntegrationEventHandler in the AP module consumes this event.
  4. AP: Invoice Creation: The handler performs the following actions: a. Requests a new Purchase Invoice number from the Number Sequence service. b. Calls the PurchaseInvoiceHeader.CreateForTaxSettlement() factory method. c. This factory method creates a new PurchaseInvoiceHeader with a single, non-stock line representing the total tax liability. d. Crucially, it populates the TaxSettlementVoucher property on the invoice header with the voucher from the GL event. This serves as an audit trail and a flag to bypass inventory logic. e. The new invoice is saved to the database in an Open (draft) state.
  5. AP: Invoice Posting (User Action): An AP user reviews and posts the newly created tax invoice via the standard UI/API.
  6. AP: Inventory Posting Bypass: When the invoice's Post method is called, it eventually triggers the VendorInvoiceInventoryPostingInitiatedDomainEvent.
  7. AP: Logic Check: The handler for this event, PurchaseInvoiceInventoryPostingInitiatedDomainEventHandler, checks if the TaxSettlementVoucher property is populated.
  8. AP: Workflow Continuation: Because the property is not null, the handler immediately calls invoice.CompleteInventoryPosting() and exits without publishing an event to the Inventory module. This allows the posting workflow to proceed directly to the final GL posting step.
  9. Final GL Posting: The standard process for posting the vendor invoice to the GL continues, debiting the tax settlement clearing account and crediting the Accounts Payable control account.

3. Sequence Diagram​