@tailor-platform/erp-kit 0.6.0 → 0.7.0

package/src/modules/finance-ledger/docs/commands/VerifySubledgerTransfers.md

@@ -0,0 +1,59 @@
+# VerifySubledgerTransfers
+
+## 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**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in IN_PROGRESS status; only IN_PROGRESS can transition to SUBLEDGERS_VERIFIED
+- **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

package/src/modules/finance-ledger/docs/commands/VerifyTrialBalance.md

@@ -0,0 +1,53 @@
+# VerifyTrialBalance
+
+## Overview
+
+verifyTrialBalance checks that the period's trial balance is balanced (total debits equal total credits across all accounts) and transitions the PeriodClose from ADJUSTMENTS_POSTED to TRIAL_BALANCE_VERIFIED status. This step ensures the integrity of double-entry bookkeeping before financial statements can be generated. If the trial balance has a non-zero discrepancy, the verification fails.
+
+## Business Rules
+
+- PeriodClose record must exist and be in ADJUSTMENTS_POSTED status
+- Only ADJUSTMENTS_POSTED records can transition to TRIAL_BALANCE_VERIFIED
+- Verification generates or retrieves the trial balance for the period
+- Verification fails if the trial balance has a non-zero difference between total debits and total credits
+- Verification succeeds when debits equal credits across all accounts for the period
+- Updates completionPercentage to reflect progress
+- Records the userId of the operator who performed the verification
+- Emits an audit event recording the acting user, timestamp, trial balance result, and status transition
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive verify trial balance request] --> B{PeriodClose record exists?}
+    B -->|No| C[Return error: period close not found]
+    B -->|Yes| D{PeriodClose in ADJUSTMENTS_POSTED status?}
+    D -->|No| E[Return error: invalid status transition]
+    D -->|Yes| F[Generate or retrieve trial balance for the period]
+    F --> G{Total debits equal total credits?}
+    G -->|No| H[Return error: trial balance imbalanced with discrepancy amount]
+    G -->|Yes| I[Transition PeriodClose to TRIAL_BALANCE_VERIFIED]
+    I --> J[Update completionPercentage]
+    J --> K[Emit audit event]
+    K --> L[Return updated PeriodClose]
+```
+
+## External Dependencies
+
+- [coa-management::getChartOfAccounts](../../../coa-management/docs/queries/GetChartOfAccounts.md) - Retrieves the active CoA for trial balance generation
+
+## Error Scenarios
+
+- **PERIOD_CLOSE_NOT_FOUND**: No PeriodClose record matches the given id
+- **INVALID_STATUS_TRANSITION**: PeriodClose is not in ADJUSTMENTS_POSTED status; only ADJUSTMENTS_POSTED can transition to TRIAL_BALANCE_VERIFIED
+- **TRIAL_BALANCE_IMBALANCED**: The period's trial balance has a non-zero difference between total debits and total credits; includes the discrepancy amount
+
+## Test Cases
+
+- returns error when PeriodClose record does not exist
+- returns error when PeriodClose is in SUBLEDGERS_VERIFIED status
+- returns error when PeriodClose is already in TRIAL_BALANCE_VERIFIED status
+- returns error when trial balance has a non-zero debit-credit discrepancy
+- transitions ADJUSTMENTS_POSTED to TRIAL_BALANCE_VERIFIED when trial balance is balanced
+- updates completionPercentage after successful verification
+- emits audit event recording trial balance result and status transition

package/src/modules/finance-ledger/docs/features/accounting-period-management.md

@@ -0,0 +1,110 @@
+# Accounting Period Management
+
+## Overview
+
+Accounting Period Management defines and controls the lifecycle of fiscal periods within the finance-ledger module. Each accounting period represents a discrete time segment (typically a month, quarter, or custom interval) within a fiscal year, scoped to a single company via `companyId`. Periods carry a start date, end date, period name, period type, and a five-state status that governs whether journal entries can be posted. The five-state lifecycle (NEVER_OPENED, FUTURE_ENTERABLE, OPEN, CLOSED, PERMANENTLY_CLOSED) mirrors the industry-standard model used by Oracle Financials and provides granular control over when and how transactions flow into each period.
+
+Accounting periods are the temporal backbone of the general ledger. Every journal entry must reference a valid period, and the period's current status determines whether that posting is accepted or rejected. This module is responsible for defining the fiscal calendar structure (including support for non-calendar fiscal years such as 4-4-5 week schemes or 13-period years), exposing period status queries that upstream modules (purchase, sales, inventory, manufacturing) use to validate posting eligibility, and enforcing the sequential integrity of period transitions. Period management is a compliance requirement under GAAP, IFRS, and most local regulations — locking closed periods prevents backdated entries that would compromise financial statement integrity.
+
+## Business Purpose
+
+Organizations need disciplined period management to maintain accurate, auditable, and regulation-compliant financial records:
+
+- **Posting control**: The period status determines whether journal entries are accepted. Only periods in FUTURE_ENTERABLE or OPEN status allow postings, preventing accidental or unauthorized entries into periods that have been reconciled or reported
+- **Five-state lifecycle granularity**: The NEVER_OPENED state distinguishes periods that have been defined but not yet activated from those that are FUTURE_ENTERABLE (accepting advance postings such as recurring journals or accruals). The distinction between CLOSED (reversible, allowing period reopening for adjustments) and PERMANENTLY_CLOSED (irreversible, enforcing hard cutoff for audited periods) gives finance teams flexibility while maintaining audit integrity
+- **Fiscal year flexibility**: Support for non-calendar fiscal years (e.g., April-to-March, 4-4-5 week structures, 13-period years) ensures the system accommodates diverse organizational and jurisdictional requirements. A fiscal year is a logical grouping of periods scoped to a company, carrying a year name and start/end boundaries
+- **Cross-module posting validation**: Upstream modules (purchase, sales, inventory, manufacturing) query the accounting period status before creating journal entries. This centralized validation ensures consistent enforcement of period restrictions across the entire ERP without duplicating temporal logic in each module
+- **Period locking layers**: Periods can be locked incrementally — first for the accounting team (preventing routine postings while allowing supervisor adjustments), then fully closed, and finally permanently closed after external audit. This layered approach supports the month-end and year-end close workflow
+- **Adjustment period support**: Special adjustment periods (period 13 or period 0) can be defined for year-end adjusting entries, audit adjustments, and closing entries without contaminating the regular operating periods
+- **Compliance and audit trail**: Period status transitions are auditable events. Regulators and auditors rely on period locking to verify that reported financial statements were not altered after issuance. GAAP, IFRS, and local regulations require demonstrable period close controls
+- **Company scoping**: Each fiscal year and its periods are isolated to a legal entity, supporting multi-entity deployments where subsidiaries may have different fiscal calendars and close schedules
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> NeverOpened: createAccountingPeriod
+    NeverOpened --> FutureEnterable: openForAdvanceEntry
+    FutureEnterable --> Open: openPeriod
+    NeverOpened --> Open: openPeriod
+    Open --> Closed: closePeriod
+    Closed --> Open: reopenPeriod
+    Closed --> PermanentlyClosed: permanentlyClosePeriod
+    PermanentlyClosed --> [*]
+```
+
+```mermaid
+flowchart TD
+    A[Define fiscal year for company] --> B[Generate accounting periods]
+    B --> C[Periods created in NEVER_OPENED status]
+    C --> D{Advance postings needed?}
+    D -- Yes --> E[Transition to FUTURE_ENTERABLE]
+    D -- No --> F[Transition directly to OPEN]
+    E --> F[Transition to OPEN when period begins]
+    F --> G[Accept journal postings]
+    G --> H[Month-end reconciliation complete]
+    H --> I[Close period]
+    I --> J{Adjustments needed?}
+    J -- Yes --> K[Reopen period]
+    K --> G
+    J -- No --> L{Audit finalized?}
+    L -- No --> M[Period remains CLOSED]
+    L -- Yes --> N[Permanently close period]
+    N --> O[No further changes permitted]
+```
+
+## Scenario Patterns
+
+- **Standard Monthly Close**: A company operates on a calendar fiscal year with 12 monthly periods. At month-end, the accounting team completes reconciliations, posts final accruals, and transitions the period from OPEN to CLOSED. After the external auditor reviews Q1, periods January through March are permanently closed
+- **Non-Calendar Fiscal Year Setup**: A retailer with a February-to-January fiscal year (aligned to post-holiday reporting) defines a fiscal year starting February 1. Twelve monthly periods are generated with date boundaries matching the non-calendar cycle. Each period follows the same five-state lifecycle regardless of the calendar alignment
+- **4-4-5 Week Period Structure**: A retail organization uses a 4-4-5 week fiscal calendar where each quarter consists of two 4-week periods followed by one 5-week period (13 periods per year). Custom period boundaries are defined rather than calendar month boundaries, and all period lifecycle rules apply identically
+- **Advance Posting for Recurring Journals**: Before a new fiscal year begins, the controller transitions upcoming periods to FUTURE_ENTERABLE to allow automated recurring journal entries (e.g., monthly rent, depreciation) to be posted in advance. The periods remain in FUTURE_ENTERABLE until the actual period start date, when they transition to OPEN
+- **Year-End Adjustment Period**: An adjustment period (period 13) is created for year-end closing entries and audit adjustments. This period shares the same end date as the final regular period but is designated as an adjustment type, isolating audit-related entries from operating activity
+- **Period Reopen for Late Invoice**: After closing March, the AP team discovers an unrecorded vendor invoice dated March 15. The controller reopens March (CLOSED to OPEN), posts the invoice, and re-closes the period. This is only possible because March was not yet permanently closed
+- **Multi-Entity Close Coordination**: A parent company with three subsidiaries coordinates period close across all entities. Each subsidiary's periods are independently managed — subsidiary A closes March on April 5, while subsidiary B closes on April 8 — reflecting their separate fiscal period scoping by companyId
+- **Preventing Backdated Entries**: A sales team attempts to post a revenue entry to a permanently closed period to inflate prior-quarter results. The system rejects the posting because the period status is PERMANENTLY_CLOSED, enforcing financial statement integrity
+
+## Test Cases
+
+- Accounting period lifecycle follows NEVER_OPENED -> FUTURE_ENTERABLE -> OPEN -> CLOSED -> PERMANENTLY_CLOSED state machine
+- Accounting period can only be created in NEVER_OPENED status
+- Period name is required and must be non-empty
+- Period must have a valid start date and end date, with start date strictly before end date
+- Period must reference a valid companyId from the organization module
+- Period must belong to a fiscal year that is scoped to the same company
+- Periods within the same fiscal year must not have overlapping date ranges
+- Periods within the same fiscal year must cover the full fiscal year date range without gaps
+- Transitioning a NEVER_OPENED period to FUTURE_ENTERABLE succeeds and allows advance postings
+- Transitioning a NEVER_OPENED period directly to OPEN succeeds (skipping FUTURE_ENTERABLE)
+- Transitioning a FUTURE_ENTERABLE period to OPEN succeeds
+- Transitioning an OPEN period to CLOSED succeeds
+- Transitioning a CLOSED period back to OPEN (reopen) succeeds
+- Transitioning a CLOSED period to PERMANENTLY_CLOSED succeeds
+- Transitioning a PERMANENTLY_CLOSED period to any other status is rejected with an irreversible status error
+- Transitioning an OPEN period directly to PERMANENTLY_CLOSED (skipping CLOSED) is rejected with an invalid status transition error
+- Transitioning a NEVER_OPENED period directly to CLOSED is rejected with an invalid status transition error
+- Journal entries can be posted to a period in OPEN status
+- Journal entries can be posted to a period in FUTURE_ENTERABLE status (advance postings)
+- Journal entries are rejected when the target period is in NEVER_OPENED status
+- Journal entries are rejected when the target period is in CLOSED status
+- Journal entries are rejected when the target period is in PERMANENTLY_CLOSED status
+- A period cannot be deleted if it has any associated journal entries regardless of status
+- Reopening a CLOSED period emits an audit event recording the status transition and acting user
+- Closing a period emits an audit event recording the status transition from OPEN to CLOSED
+- Permanently closing a period emits an audit event recording the irreversible transition
+- Creating a fiscal year with 12 monthly periods generates periods with correct start and end date boundaries
+- Creating a fiscal year with 13 periods (adjustment period) generates 12 operating periods and 1 adjustment period
+- Adjustment periods share the same end date as the final regular period but are typed as adjustment
+- A non-calendar fiscal year (e.g., April-to-March) generates periods with correct non-calendar date boundaries
+- Period status query returns the current status for a given date and company, enabling upstream modules to validate posting eligibility
+- Periods are scoped to a company; period records from different companies are isolated
+- Two periods in the same fiscal year cannot have identical start and end dates unless one is an adjustment period
+- All period status transitions emit audit events via the audit module recording the acting user, timestamp, and previous and new status values
+
+## Reference Links
+
+- [Oracle Fusion Open and Close Periods](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/manage-accounting-periods.html)
+- [SAP S/4HANA Fiscal Year and Posting Periods](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4cf37e593e3d2944e10000000a42189b.html)
+- [Odoo Fiscal Year and Period Lock](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/opening.html)
+- [NetSuite Accounting Period Management](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1553839.html)
+- [Oracle EBS Open and Close Periods Overview](https://docs.oracle.com/en/applications/jd-edwards/cross-application/9.2/eoagl/opening-and-closing-fiscal-periods.html)

package/src/modules/finance-ledger/docs/features/financial-statement-generation.md

@@ -0,0 +1,115 @@
+# Financial Statement Generation
+
+## Overview
+
+Financial statement generation produces the three core financial reports — Balance Sheet (statement of financial position), Profit & Loss (income statement), and Cash Flow Statement — from the finance-ledger module's trial balance data. Each statement is scoped to a single company, denominated in the company's base currency, and structured according to the account group hierarchy defined in the coa-management module. The Balance Sheet reports asset, liability, and equity positions as of a specific date. The Profit & Loss statement aggregates revenue and expense activity over a date range (typically a fiscal period or year-to-date). The Cash Flow Statement derives cash movements over a period using either the direct or indirect method, reconciling operating, investing, and financing activities to the net change in cash.
+
+A `FinancialStatement` entity represents a generated report. It stores the statement type, the generation parameters (reporting date or date range, method for cash flow), a lifecycle status, and the generated output comprising line items organized by account group sections. Statement generation consumes trial balance data — specifically the period-end balances and movements for each GL account — and maps each account to the appropriate report section based on the account's type (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) and its position within the coa-management account group hierarchy. This feature covers standard fixed-format statement generation; configurable report builders and custom financial statement versions (FSV) are out of scope and belong to a future reporting module.
+
+## Business Purpose
+
+Organizations need accurate, standards-compliant financial statements for external reporting, internal decision-making, and regulatory compliance:
+
+- **Regulatory compliance**: IAS 1 (IFRS) and local GAAP frameworks require entities to produce a complete set of financial statements including a statement of financial position, income statement, and cash flow statement. This feature satisfies the core statement production requirement
+- **Period-end reporting**: After trial balance generation and period-end close, financial statements are the primary deliverable that summarizes the company's financial position and performance for stakeholders including management, auditors, tax authorities, and investors
+- **Account type-driven placement**: Each GL account's type (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) determines which statement and section it appears in. This automatic classification eliminates manual mapping errors and ensures consistency between the ledger and the reports
+- **Hierarchy-based structure**: The account group hierarchy from coa-management defines the presentation structure of each statement. Groups such as "Current Assets", "Non-Current Liabilities", or "Operating Expenses" provide the section headings and subtotals that give statements their standard shape
+- **Comparative periods**: IAS 1 requires comparative information for the preceding period. Statement generation supports including prior-period balances alongside the current period, enabling period-over-period analysis on a single report
+- **Cash flow method selection**: The Cash Flow Statement can be generated using the direct method (classifying actual cash receipts and payments) or the indirect method (adjusting net income for non-cash items and working capital changes). Both are permitted under IFRS and US GAAP; the indirect method is more commonly used in practice
+- **Company scoping and currency**: Each statement is scoped to a single legal entity and denominated in the company's base currency (inherited via the CoA from the organization module), ensuring that statement figures are consistent with the underlying ledger
+- **Audit trail**: Every statement generation event is recorded, preserving a traceable link between the report output, the trial balance data it consumed, and the parameters used to produce it
+
+## Process Flow
+
+The following diagram shows the end-to-end flow for generating a financial statement from trial balance data.
+
+```mermaid
+flowchart TD
+    A[Request statement generation] --> B{Statement type?}
+    B -- Balance Sheet --> C[Retrieve trial balance as-of date]
+    B -- Profit & Loss --> D[Retrieve trial balance for date range]
+    B -- Cash Flow --> E[Retrieve trial balance for date range]
+    C --> F[Load account group hierarchy from coa-management]
+    D --> F
+    E --> F
+    F --> G[Map accounts to statement sections by account type]
+    G --> H[Aggregate balances per account group]
+    H --> I{Include comparative period?}
+    I -- Yes --> J[Retrieve prior period trial balance]
+    J --> K[Align prior period to same sections]
+    K --> L[Assemble statement line items]
+    I -- No --> L
+    L --> M{Validation passed?}
+    M -- Yes --> N[Create FinancialStatement entity in DRAFT]
+    M -- No --> O[Return validation errors]
+    N --> P[Review and finalize]
+    P --> Q[Finalize statement]
+    Q --> R[Statement FINALIZED — immutable]
+```
+
+The following diagram shows the Cash Flow Statement generation sub-process, which differs depending on the selected method.
+
+```mermaid
+flowchart TD
+    A[Cash Flow generation requested] --> B{Method?}
+    B -- Direct --> C[Classify cash receipts and payments from ledger entries]
+    C --> D[Group into Operating / Investing / Financing]
+    B -- Indirect --> E[Start with net income from P&L]
+    E --> F[Adjust for non-cash items: depreciation, amortization]
+    F --> G[Adjust for working capital changes]
+    G --> D
+    D --> H[Calculate net change in cash]
+    H --> I[Reconcile to opening and closing cash balances]
+    I --> J[Return cash flow line items]
+```
+
+## Scenario Patterns
+
+- **Monthly Balance Sheet**: At month-end close, a controller generates a Balance Sheet as of the last day of the month. The system retrieves the trial balance closing balances for all ASSET, LIABILITY, and EQUITY accounts, structures them according to the account group hierarchy (Current Assets, Non-Current Assets, Current Liabilities, Long-Term Liabilities, Equity), and produces a report where total assets equal total liabilities plus equity
+- **Year-End Income Statement**: At fiscal year-end, a Profit & Loss statement is generated for the full year date range. REVENUE accounts appear as income sections and EXPENSE accounts as cost/expense sections, with subtotals for gross profit, operating profit, and net income derived from the group hierarchy
+- **Quarterly Comparative P&L**: A finance manager generates a Q3 income statement with comparative data from Q3 of the prior year. Both periods' figures appear side-by-side, enabling variance analysis of revenue growth and cost changes
+- **Cash Flow Statement (Indirect Method)**: An auditor requests a cash flow statement for the fiscal year. The system starts with net income from the P&L, adjusts for non-cash charges (depreciation, amortization, provisions), accounts for changes in working capital (receivables, payables, inventory), and classifies investing and financing activities to arrive at the net cash movement reconciled to the opening and closing cash balances
+- **Cash Flow Statement (Direct Method)**: A company required by its regulator to use the direct method generates a cash flow statement that classifies actual cash inflows (customer receipts, interest received) and outflows (supplier payments, wages, taxes) into operating, investing, and financing categories
+- **Multi-Entity Consolidation Preparation**: Each subsidiary generates its own set of financial statements in its base currency. These entity-level statements serve as inputs for a future consolidation process (out of scope for this feature)
+- **Draft Review and Correction**: A statement is generated in DRAFT status. During review, the controller identifies a missing accrual entry, posts a correcting journal entry, regenerates the trial balance, and regenerates the statement before finalizing
+
+## Test Cases
+
+- FinancialStatement entity requires a valid companyId referencing an ACTIVE company
+- FinancialStatement entity requires a valid chartOfAccountsId referencing an ACTIVE CoA
+- Statement type must be one of: BALANCE_SHEET, PROFIT_AND_LOSS, CASH_FLOW
+- Balance Sheet generation requires a single reporting date (as-of date)
+- Profit & Loss generation requires a date range (start date and end date)
+- Cash Flow Statement generation requires a date range and a method (DIRECT or INDIRECT)
+- The reporting date or date range must fall within a closed or active accounting period
+- A Balance Sheet includes only accounts of type ASSET, LIABILITY, and EQUITY
+- A Profit & Loss includes only accounts of type REVENUE and EXPENSE
+- A Cash Flow Statement derives from ledger data covering all account types relevant to cash movements
+- On a correctly generated Balance Sheet, total assets equal total liabilities plus total equity (the accounting equation holds)
+- Statement line items are structured according to the account group hierarchy from coa-management
+- Accounts not assigned to any account group are reported in an "Unclassified" section and flagged as warnings
+- Comparative period data, when requested, is aligned to the same account group sections as the current period
+- If comparative period trial balance data is unavailable, generation fails with a descriptive error
+- FinancialStatement is created in DRAFT status
+- A DRAFT statement can be regenerated (replaced) with updated trial balance data
+- Finalizing a DRAFT statement transitions it to FINALIZED status
+- A FINALIZED statement is immutable — its line items, parameters, and output cannot be modified
+- Finalizing an already FINALIZED statement fails with an invalid status transition error
+- Generating a statement for a period with no posted journal entries fails with a validation error
+- Statement output includes subtotals at each level of the account group hierarchy
+- Cash Flow Statement (indirect method) starts with net income and adjusts for non-cash items and working capital changes
+- Cash Flow Statement reconciles to the net change between opening and closing cash balances
+- Statement generation emits an audit event via the audit module recording the acting user, timestamp, statement type, and parameters
+- Finalizing a statement emits an audit event recording the status transition from DRAFT to FINALIZED
+- All monetary amounts in the statement are denominated in the company's base currency
+- Statement generation for a company with no trial balance data for the requested period returns a validation error
+- Each statement records a reference to the trial balance snapshot it was generated from, ensuring traceability
+
+## Reference Links
+
+- [IAS 1 Presentation of Financial Statements (IFRS)](https://www.ifrs.org/issued-standards/list-of-standards/ias-1-presentation-of-financial-statements/)
+- [IAS 7 Statement of Cash Flows (IFRS)](https://www.ifrs.org/issued-standards/list-of-standards/ias-7-statement-of-cash-flows/)
+- [SAP Financial Statement Versions (FSV)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee5c9e37ff4f4e33a6c7e2c32f8fc3b5/577f8c2a397b4ce589e1ad03a64eb1ae.html)
+- [Oracle Financial Statement Generator (FSG)](https://docs.oracle.com/en/cloud/saas/financials/24d/oaglg/financial-reporting.html)
+- [Odoo Financial Reporting](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting.html)
+- [NetSuite Financial Statements](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1583498.html)

package/src/modules/finance-ledger/docs/features/journal-entry-management.md

@@ -0,0 +1,138 @@
+# Journal Entry Management
+
+## Overview
+
+Journal Entry Management is the core transactional capability of the finance-ledger module, implementing double-entry bookkeeping for all financial postings. A journal entry consists of a header record (JournalEntry) carrying the entry date, journal type, reference number, status, posting period, description, and optional source document reference, along with one or more line records (JournalLine) that each specify a GL account (from coa-management), debit or credit amount, currency, exchange rate, functional currency amount, and line-level description. Every journal entry must satisfy the fundamental accounting constraint: total debits must equal total credits in the functional currency before it can be posted.
+
+Journal entries follow a lifecycle of DRAFT to POSTED, with posted entries eligible for reversal via a mirror entry that produces a REVERSED status on the original. The feature supports six journal types (Sales, Purchase, Cash, Bank, Miscellaneous, Opening) to categorize entries by their business origin, and handles multi-currency postings by converting foreign currency amounts to the company's functional currency using a specified exchange rate. All mutations are recorded in an immutable audit trail, ensuring regulatory compliance and full traceability from entry creation through posting and reversal.
+
+## Business Purpose
+
+Organizations need a rigorous, auditable journal entry system to record financial transactions and maintain the integrity of their general ledger:
+
+- **Double-entry enforcement**: Every journal entry must balance total debits against total credits in the functional currency, preventing one-sided postings that would corrupt the trial balance and financial statements
+- **Journal type categorization**: Classifying entries by type (Sales, Purchase, Cash, Bank, Miscellaneous, Opening) mirrors the journal/book structure used by all major ERPs (Odoo, SAP, Oracle) and enables filtering, reporting, and access control by transaction origin
+- **Lifecycle gating**: The DRAFT to POSTED progression ensures entries can be reviewed and corrected before they affect account balances. Only posted entries contribute to the general ledger, trial balance, and financial statements
+- **Immutable posted entries**: Once posted, a journal entry cannot be modified or deleted — only reversed. This preserves the audit trail required by GAAP, IFRS, and local accounting regulations
+- **Reversal via mirror entry**: Reversing a posted entry creates a new journal entry with inverted debit/credit lines rather than deleting the original, maintaining a complete history of all postings and corrections
+- **Multi-currency support**: Companies operating across borders must record transactions in the original foreign currency while converting to the functional (base) currency for consolidated reporting. Exchange rate capture at posting time ensures accurate currency translation
+- **Period-aware posting**: Journal entries reference an accounting period and can only be posted to periods that are in OPEN or FUTURE_ENTERABLE status, enforcing the period lifecycle managed by the accounting-period-management feature
+- **Source document traceability**: Optional source document references (e.g., invoice number, bill ID) link journal entries back to their originating business transactions, supporting audit inquiries and subledger reconciliation
+- **GL account validation with successor mapping**: Journal lines must reference active GL accounts from an active Chart of Accounts. When a GL account has been deprecated with a successor account mapping (from coa-management), postings are redirected to the successor account, ensuring continuity without manual re-entry
+- **Audit trail**: Every state change — creation, update, posting, reversal — is recorded with the acting user, timestamp, and field-level details via the audit module, satisfying internal control and external audit requirements
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createJournalEntry
+    Draft --> Draft: updateJournalEntry / addJournalLine / removeJournalLine
+    Draft --> Posted: postJournalEntry
+    Posted --> Reversed: reverseJournalEntry
+    Draft --> [*]: deleteJournalEntry
+```
+
+```mermaid
+flowchart TD
+    A[Identify transaction to record] --> B[Create JournalEntry header in DRAFT]
+    B --> C[Add JournalLine records with debit/credit amounts]
+    C --> D{Multi-currency?}
+    D -- Yes --> E[Specify foreign currency and exchange rate per line]
+    E --> F[System converts to functional currency amounts]
+    D -- No --> F
+    F --> G{Debits = Credits in functional currency?}
+    G -- No --> C
+    G -- Yes --> H{GL accounts valid and active?}
+    H -- No --> I[Resolve account issues]
+    I --> C
+    H -- Yes --> J{Target period OPEN or FUTURE_ENTERABLE?}
+    J -- No --> K[Select valid posting period]
+    K --> J
+    J -- Yes --> L[Post journal entry]
+    L --> M[Account balances updated]
+```
+
+```mermaid
+flowchart TD
+    A[Select posted journal entry to reverse] --> B[Create mirror entry with inverted debits/credits]
+    B --> C{Reversal period OPEN or FUTURE_ENTERABLE?}
+    C -- No --> D[Select valid reversal period]
+    D --> C
+    C -- Yes --> E[Post reversal entry]
+    E --> F[Original entry status set to REVERSED]
+    F --> G[Original entry balances offset to zero]
+```
+
+## Scenario Patterns
+
+- **Manual Miscellaneous Entry**: An accountant creates a miscellaneous journal entry to record an adjusting entry (e.g., accrual or reclassification) that does not originate from a subledger. The entry is created in DRAFT, journal lines are added with appropriate debit/credit accounts and amounts, the balance is verified, and the entry is posted to the current open period
+- **Sales Invoice Posting**: The sales module generates a journal entry of type Sales with a debit to Accounts Receivable and a credit to Revenue, referencing the sales invoice as the source document. The entry flows through the subledger integration contract and is posted automatically upon invoice confirmation
+- **Purchase Bill Recording**: A purchase bill triggers a journal entry of type Purchase with a debit to the relevant expense or inventory account and a credit to Accounts Payable. The source document reference links back to the purchase bill for reconciliation
+- **Multi-Currency Transaction**: A company records a purchase invoice denominated in a foreign currency. The journal lines capture both the foreign currency amount and the exchange rate, with the system computing the functional currency equivalent. The entry balances in the functional currency, and any rounding difference is posted to a designated exchange gain/loss account
+- **Opening Balance Entry**: During initial system setup or at the start of a new fiscal year, an Opening-type journal entry is created to establish beginning balances for all balance sheet accounts. This entry typically carries a posting date matching the first day of the new fiscal period
+- **Error Correction via Reversal**: A posted journal entry is discovered to contain an incorrect account assignment. The accountant reverses the original entry (creating a mirror posting that offsets all amounts) and then creates a new corrective entry with the correct accounts. The original entry, its reversal, and the correction all remain in the ledger for full auditability
+- **Cash Receipt Recording**: A cash payment received from a customer is recorded as a Cash-type journal entry, debiting the bank/cash account and crediting Accounts Receivable. The source document reference links to the customer payment record
+- **Bank Transaction Entry**: A bank fee or interest charge is recorded as a Bank-type journal entry, debiting bank charges expense and crediting the bank account, referencing the bank statement line as the source document
+- **Successor Account Redirect**: An accountant creates a journal line referencing a GL account that has been deprecated with a successor mapping in coa-management. The system automatically redirects the posting to the successor account, logs the redirect in the audit trail, and posts the entry without requiring manual correction
+- **Period Boundary Posting**: An entry needs to be recorded in a future accounting period that is in FUTURE_ENTERABLE status. The entry is created and posted to that period, allowing advance preparation of known transactions before the current period closes
+
+## Test Cases
+
+- Journal entry lifecycle follows DRAFT -> POSTED state machine; posted entries can transition to REVERSED
+- Journal entry can only be created in DRAFT status
+- Journal entry requires a valid journal type (Sales, Purchase, Cash, Bank, Miscellaneous, Opening)
+- Journal entry requires a valid entry date
+- Journal entry requires a reference number that is unique within the company scope
+- Journal entry must reference a valid companyId; the company must be in ACTIVE status
+- Journal entry must reference a valid accounting period; the period must be in OPEN or FUTURE_ENTERABLE status for posting
+- Journal entry description is optional and can be updated while in DRAFT status
+- Source document reference is optional and can be set on creation or update in DRAFT status
+- A journal entry must have at least two journal lines before it can be posted
+- Each journal line must reference a valid GL account from an ACTIVE Chart of Accounts
+- Each journal line must specify either a debit amount or a credit amount (not both, and not zero for both)
+- Debit and credit amounts must be positive values
+- Total debits must equal total credits in the functional currency for posting to succeed
+- An unbalanced journal entry (debits != credits in functional currency) cannot be posted
+- Posting a balanced DRAFT journal entry transitions its status to POSTED
+- Posting an already POSTED journal entry fails with an invalid status transition error
+- Posted journal entries cannot be modified (no field updates, no line additions or removals)
+- Posted journal entries cannot be deleted; only reversal is permitted
+- DRAFT journal entries can be deleted; deletion removes all associated journal lines
+- Deleting a DRAFT journal entry emits an audit event recording the deletion and acting user
+- Journal lines can be added to or removed from a DRAFT journal entry
+- Journal lines cannot be added to or removed from a POSTED or REVERSED journal entry
+- Updating a journal line (account, amount, description) is only permitted while the parent entry is in DRAFT status
+- Reversing a posted entry creates a new journal entry with all debit/credit amounts inverted
+- The reversal entry references the original entry and is automatically posted
+- The original entry status transitions from POSTED to REVERSED upon successful reversal
+- Reversing an entry that is already REVERSED fails with an invalid status transition error
+- Reversing a DRAFT entry fails with an invalid status transition error
+- The reversal entry must target a period that is in OPEN or FUTURE_ENTERABLE status
+- Multi-currency journal lines must specify a currency code and exchange rate
+- The functional currency amount is computed as the foreign amount multiplied by the exchange rate
+- Journal lines without an explicit currency default to the company's functional (base) currency with an exchange rate of 1.0
+- Balance validation for multi-currency entries is performed on the functional currency amounts, not the foreign currency amounts
+- Posting a journal entry to a CLOSED or PERMANENTLY_CLOSED period is rejected
+- Posting a journal entry to a NEVER_OPENED period is rejected
+- Journal lines referencing an inactive or draft GL account are rejected at posting time
+- Journal lines referencing a deprecated GL account with a successor mapping are redirected to the successor account at posting time
+- Successor account redirect is recorded in the audit trail with the original and successor account references
+- If the successor account is itself inactive or deprecated without a further successor, the posting is rejected
+- Creating a journal entry emits an audit event via the audit module recording the acting user, timestamp, and initial field values
+- Updating a journal entry (header fields or line changes) emits an audit event recording previous and new field values
+- Posting a journal entry emits an audit event recording the status transition from DRAFT to POSTED and the posting user
+- Reversing a journal entry emits an audit event recording the status transition from POSTED to REVERSED, the reversal entry reference, and the acting user
+- Journal entries are scoped to a company; entries from different companies are fully isolated
+- Only users with appropriate permissions (from user-management) can create, post, or reverse journal entries
+- Unauthorized users receive a permission denied error when attempting journal entry operations
+- A journal entry with a single line (only debit or only credit) cannot be posted
+- Journal type cannot be changed after the entry is posted
+- The entry date cannot be changed after the entry is posted
+
+## Reference Links
+
+- [Odoo Journal Entries and Journal Types](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/cheat_sheet.html)
+- [SAP S/4HANA Journal Entry Processing](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4cae4cc1ecaa7286e10000000a42189b.html)
+- [Oracle Fusion General Ledger Journal Entries](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/journal-entries.html)
+- [NetSuite Journal Entry Overview](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3444641.html)
+- [Sage Intacct Journal Entries](https://www.sage.com/en-us/blog/what-is-a-journal-entry-in-accounting/)

package/src/modules/finance-ledger/docs/features/period-end-close.md

@@ -0,0 +1,102 @@
+# Period End Close
+
+## Overview
+
+Period-end close is a structured, checklist-driven workflow that transitions an accounting period from open (accepting postings) to permanently closed (immutable). The process is modeled through a `PeriodClose` entity that tracks the close status, the user who initiated and completed each step, timestamps, and overall checklist completion percentage. Each close operation is scoped to a single `AccountingPeriod` within a company's active Chart of Accounts, ensuring that all financial activity for the period has been captured, verified, and reconciled before the period is locked. The workflow enforces a deterministic sequence of steps: subledger transfer verification, pending journal batch posting, adjusting entry creation (accruals, deferrals, reclassifications), trial balance verification, preliminary financial statement generation, review and approval, soft lock for the accounting team, final advisor adjustments, and permanent close.
+
+Adjusting entries created during the close process are flagged with an `adjustingEntryType` (ACCRUAL, DEFERRAL, or RECLASSIFICATION) to distinguish them from regular operational entries for reporting and audit purposes. The soft-lock stage supports segregation of duties by allowing the accounting team to finalize routine entries while reserving a window for external auditors or advisors to post final adjustments before the period is permanently closed. Once permanently closed, no further journal entries can be posted regardless of role, preserving the immutability and auditability of the period's financial data.
+
+## Business Purpose
+
+Organizations require a disciplined period-close process to ensure the accuracy and integrity of their financial records:
+
+- **Financial statement reliability**: A structured close checklist ensures all transactions are captured and verified before financial statements are generated, preventing material misstatements and supporting accurate reporting to stakeholders
+- **Regulatory compliance**: Public companies and regulated entities must close periods within defined timelines (e.g., SEC 10-Q/10-K deadlines). A tracked, step-by-step workflow provides evidence of due diligence and process adherence for external auditors
+- **Subledger completeness**: Verifying that all subledger modules (accounts payable, accounts receivable, inventory, manufacturing) have transferred their transactions to the general ledger prevents omissions that would distort the trial balance
+- **Adjusting entry transparency**: Separating accruals, deferrals, and reclassifications from regular entries allows auditors and management to isolate period-end adjustments and assess their impact on reported figures
+- **Data immutability after close**: Locking a closed period prevents accidental or unauthorized postings that would alter previously reported figures, preserving the audit trail and historical comparability
+- **Multi-step approval**: The soft-lock and final-advisor-adjustment stages support segregation of duties, allowing the accounting team to finalize routine entries while reserving a window for external auditors or advisors to post final adjustments before permanent close
+- **Cross-module coordination**: Period close status is consumed by other modules (purchase, sales, inventory, manufacturing) to determine whether they can post transactions to a given period, creating a unified control point for posting eligibility
+
+## Process Flow
+
+The period-close lifecycle follows a linear state machine with defined checkpoints at each stage:
+
+```mermaid
+stateDiagram-v2
+    [*] --> NotStarted: initiatePeriodClose
+    NotStarted --> InProgress: beginClose
+    InProgress --> SubledgersVerified: verifySubledgerTransfers
+    SubledgersVerified --> AdjustmentsPosted: postAdjustingEntries
+    AdjustmentsPosted --> TrialBalanceVerified: verifyTrialBalance
+    TrialBalanceVerified --> UnderReview: generatePreliminaryStatements
+    UnderReview --> SoftLocked: approveAndLockPeriod
+    SoftLocked --> PermanentlyClosed: finalCloseAndLockPeriod
+    PermanentlyClosed --> [*]
+```
+
+The following flowchart details the end-to-end close checklist:
+
+```mermaid
+flowchart TD
+    A[Initiate period close for AccountingPeriod] --> B[Verify all subledger transactions transferred to GL]
+    B --> C{All subledgers reconciled?}
+    C -- No --> B
+    C -- Yes --> D[Post all pending journal batches]
+    D --> E[Create adjusting entries: accruals, deferrals, reclassifications]
+    E --> F[Run trial balance and verify debits equal credits]
+    F --> G{Trial balance balanced?}
+    G -- No --> E
+    G -- Yes --> H[Generate preliminary financial statements]
+    H --> I[Management review and approval]
+    I --> J[Soft-lock period: block accounting team postings]
+    J --> K[Final advisor/auditor adjustments]
+    K --> L[Permanently close period]
+    L --> M[Period is immutable - no further postings allowed]
+```
+
+## Scenario Patterns
+
+- **Standard Monthly Close**: The accounting team initiates the close for January, verifies that AP and AR subledgers have posted all invoices, creates accrual entries for unbilled services received, verifies the trial balance, obtains controller approval, and permanently closes the period within five business days of month-end
+- **Quarter-End Close with Reclassifications**: At the end of Q1, the accounting team identifies that certain expenses were posted to the wrong cost center. They create reclassification adjusting entries during the close process, rerun the trial balance, and generate preliminary quarterly financial statements for management review before soft-locking the period
+- **Soft Lock with Auditor Adjustments**: The accounting team completes the monthly close checklist and soft-locks the period. An external auditor identifies a material adjustment and posts a correcting entry during the advisor-adjustment window. The period is then permanently closed with the auditor's entry included
+- **Failed Subledger Verification**: During the close process, the system detects that the inventory module has pending cost-of-goods-sold entries that have not been transferred to the GL. The close cannot proceed past the subledger verification step until the inventory team completes the transfer and the close operator re-verifies
+- **Reopening a Soft-Locked Period**: The controller discovers that an accrual was double-counted after the period was soft-locked but before permanent close. The period is reverted from soft-locked to in-progress, the duplicate accrual is reversed, the trial balance is re-verified, and the period is re-locked and permanently closed
+- **Adjusting Entry for Deferred Revenue**: During the close, the accounting team recognizes a portion of deferred revenue that was earned during the period. They create an adjusting entry flagged as DEFERRAL that debits the deferred revenue liability and credits the revenue account, ensuring the income statement reflects revenue earned in the correct period
+
+## Test Cases
+
+- PeriodClose can only be initiated for an AccountingPeriod that is in OPEN status
+- PeriodClose cannot be initiated for an AccountingPeriod that is already CLOSED or has an existing close in progress
+- PeriodClose lifecycle follows NOT_STARTED -> IN_PROGRESS -> SUBLEDGERS_VERIFIED -> ADJUSTMENTS_POSTED -> TRIAL_BALANCE_VERIFIED -> UNDER_REVIEW -> SOFT_LOCKED -> PERMANENTLY_CLOSED state machine
+- PeriodClose cannot skip steps; transitioning from NOT_STARTED directly to TRIAL_BALANCE_VERIFIED is rejected
+- Subledger verification step fails if any registered subledger module has pending unposted transactions for the period
+- Subledger verification step succeeds when all registered subledger modules confirm transfer completion
+- Adjusting entries created during the close process must have a valid adjustingEntryType (ACCRUAL, DEFERRAL, or RECLASSIFICATION)
+- Adjusting entries are flagged distinctly from regular journal entries for audit trail purposes
+- Adjusting entries must be balanced (total debits equal total credits) before the close can proceed
+- Trial balance verification step fails if the period's trial balance has a non-zero difference between total debits and total credits
+- Trial balance verification step succeeds when debits equal credits across all accounts for the period
+- Preliminary financial statements can only be generated after the trial balance is verified
+- Approval step requires a user with the appropriate authorization role (e.g., controller or finance manager)
+- Soft-locking a period prevents the accounting team from posting new journal entries to that period
+- Soft-locked period still allows postings from users with the advisor/auditor role
+- Final advisor adjustments posted during the soft-locked phase are recorded with an audit trail identifying the advisor
+- Permanently closing a period makes it fully immutable; no further journal entries can be posted regardless of role
+- Attempting to post a journal entry to a permanently closed period is rejected with a period-closed error
+- PeriodClose records the userId of the operator who initiated the close and the userId who completed each checklist step
+- PeriodClose tracks a completionPercentage that increments as each checklist step is completed
+- Each state transition in the PeriodClose lifecycle emits an audit event recording the acting user, timestamp, previous status, and new status
+- Reverting a soft-locked period to in-progress is permitted only before permanent close and emits an audit event
+- Reverting a permanently closed period is not permitted
+- PeriodClose is scoped to a single AccountingPeriod; each period has at most one active PeriodClose record
+- Cross-module posting eligibility check: other modules (purchase, sales, inventory) receive a period-closed signal and reject postings to closed periods
+- Concurrent close attempts for the same period are rejected with a conflict error
+
+## Reference Links
+
+- [SAP Period-End Closing in Financial Accounting](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4588dcd34eab6e37e10000000a42189b.html)
+- [Oracle Fusion General Ledger Close Process](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/general-ledger-close.html)
+- [NetSuite Period Close Checklist](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1581498.html)
+- [Odoo Fiscal Year End and Closing](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/cheat_sheet.html)
+- [Sage Intacct Period-End Close](https://www.sage.com/en-us/sage-business-cloud/intacct/features/general-ledger/)