# VerifySubledgerTransfers

## Permission Scope

subledgerHandoff

## Overview

verifySubledgerTransfers checks that all registered subledger modules (purchase, sales, inventory, manufacturing) have completed their transaction transfers to the general ledger for the closing period. If all subledgers are reconciled, the PeriodClose transitions from IN_PROGRESS to SUBLEDGERS_VERIFIED. If any subledger has pending unposted transactions, the verification fails and the close cannot proceed.

## Business Rules

- PeriodClose record must exist and be in IN_PROGRESS status
- Only IN_PROGRESS records can transition to SUBLEDGERS_VERIFIED
- Verification checks all registered subledger modules for pending unposted transactions for the period
- Verification fails if any registered subledger module has pending unposted transactions
- Verification succeeds when all registered subledger modules confirm transfer completion
- Updates completionPercentage to reflect progress
- Records the userId of the operator who performed the verification
- Emits an audit event recording the acting user, timestamp, subledger verification results, and status transition

## Process Flow

```mermaid
flowchart TD
    A[Receive verify subledger transfers request] --> B{PeriodClose record exists?}
    B -->|No| C[Return error: period close not found]
    B -->|Yes| D{PeriodClose in IN_PROGRESS status?}
    D -->|No| E[Return error: invalid status transition]
    D -->|Yes| F[Check all registered subledger modules for pending transactions]
    F --> G{All subledgers reconciled?}
    G -->|No| H[Return error: pending subledger transactions]
    G -->|Yes| I[Transition PeriodClose to SUBLEDGERS_VERIFIED]
    I --> J[Update completionPercentage]
    J --> K[Emit audit event]
    K --> L[Return updated PeriodClose]
```

## External Dependencies

- purchase module — queries pending purchase transactions for the period (contract TBD by purchase module)
- sales module — queries pending sales transactions for the period (contract TBD by sales module)
- inventory module — queries pending inventory transactions for the period (contract TBD by inventory module)
- manufacturing module — queries pending manufacturing transactions for the period (contract TBD by manufacturing module)

## Error Scenarios

- **PERIOD_CLOSE_NOT_FOUND**: Referenced period close does not exist
- **INVALID_STATUS_TRANSITION**: Requested status transition is not allowed from the current status
- **PENDING_SUBLEDGER_TRANSACTIONS**: One or more subledger modules have pending unposted transactions for the period

## Test Cases

- returns error when PeriodClose record does not exist
- returns error when PeriodClose is in NOT_STARTED status
- returns error when PeriodClose is already in SUBLEDGERS_VERIFIED status
- returns error when purchase module has pending unposted transactions
- returns error when sales module has pending unposted transactions
- returns error when inventory module has pending unposted transactions
- returns error when manufacturing module has pending unposted transactions
- transitions IN_PROGRESS to SUBLEDGERS_VERIFIED when all subledgers are reconciled
- updates completionPercentage after successful verification
- emits audit event recording subledger verification results and status transition
