@tailor-platform/erp-kit 0.3.0 → 0.4.0

package/src/modules/coa-management/docs/commands/MoveAccountGroup.md

@@ -0,0 +1,57 @@
+# MoveAccountGroup
+
+## Overview
+
+moveAccountGroup reparents an account group by changing its parent reference within the same CoA. The group and all its descendants move together, preserving the subtree structure and all account assignments. Moving to a null parent promotes the group to a root group.
+
+## Business Rules
+
+- Target group must exist
+- Parent CoA must be in DRAFT or ACTIVE status; moving a group under an ARCHIVED CoA is rejected
+- New parent group must exist within the same CoA when specified (null for root promotion)
+- A group cannot be moved under itself or any of its descendants (circular reference prevention)
+- All child groups and their account assignments are preserved during the move
+- Group code and account assignments are unchanged by the move
+- Emits an audit event via the audit module recording the acting user, timestamp, previous parent reference, and new parent reference
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive move request] --> B{Group exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is DRAFT or ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is ARCHIVED]
+    B2 -->|Yes| D{New parent specified?}
+    D -->|Yes| E{New parent exists in same CoA?}
+    E -->|No| F[Return error: parent not found]
+    E -->|Yes| G{New parent is descendant of group?}
+    G -->|Yes| H[Return error: circular reference]
+    G -->|No| I[Update parent reference]
+    D -->|No/null| I[Promote to root]
+    I --> J[Emit audit event]
+    J --> K[Return moved group]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_GROUP_NOT_FOUND**: Specified group ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **PARENT_GROUP_NOT_FOUND**: Specified new parent group ID does not exist or belongs to a different CoA
+- **CIRCULAR_REFERENCE**: New parent is the group itself or one of its descendants
+
+## Test Cases
+
+- returns error when group does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when new parent does not exist
+- returns error when new parent belongs to different CoA
+- returns error when moving group under itself
+- returns error when moving group under its descendant
+- moves group to different parent
+- promotes group to root by setting parent to null
+- emits audit event recording previous and new parent references

package/src/modules/coa-management/docs/commands/ReactivateAccount.md

@@ -0,0 +1,50 @@
+# ReactivateAccount
+
+## Overview
+
+reactivateAccount transitions a GL account from INACTIVE back to ACTIVE status, making it eligible to receive journal postings again. Reactivation clears any previously mapped successor account, as the account is now directly available for use.
+
+## Business Rules
+
+- Target account must exist
+- Parent CoA must be in ACTIVE status; reactivating an account under an ARCHIVED CoA is rejected. Note: the DRAFT CoA case is unreachable because account activation requires an ACTIVE CoA, so an INACTIVE account cannot exist under a DRAFT CoA
+- Target account must be in INACTIVE status
+- Reactivating a DRAFT or ACTIVE account fails with an invalid state transition error
+- Reactivation clears any previously mapped successor account
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, account code, and status transition from INACTIVE to ACTIVE
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Account exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is not ACTIVE]
+    B2 -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Clear successor mapping]
+    F --> G[Update status to ACTIVE]
+    G --> H[Emit audit event]
+    H --> I[Return reactivated account]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ACCOUNT_NOT_FOUND**: Specified account ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **INVALID_STATE_TRANSITION**: Entity is not in the required status for the requested state transition
+
+## Test Cases
+
+- returns error when account does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when account is DRAFT
+- returns error when account is already ACTIVE
+- reactivates an INACTIVE account
+- clears successor mapping on reactivation
+- emits audit event recording status transition from INACTIVE to ACTIVE

package/src/modules/coa-management/docs/commands/UpdateAccount.md

@@ -0,0 +1,102 @@
+# UpdateAccount
+
+## Overview
+
+updateAccount modifies attributes of an existing GL account. Structural fields (code, type, classification, currency restriction) become immutable once the account has posted transactions. Non-structural fields (name, tags, default tax code, account group assignment) remain updatable regardless of posting history.
+
+## Business Rules
+
+- Target account must exist
+- Parent CoA must be in DRAFT or ACTIVE status; updating an account under an ARCHIVED CoA is rejected
+- Name, when provided, must be non-empty
+- Account code, when changed, must be a valid structured numeric identifier
+- Account code, when changed, must remain unique within the CoA
+- If the account has posted transactions, structural fields (code, type, classification, currency restriction) cannot be changed
+- Classification changes must maintain compatibility with account type
+- Changing classification to RETAINED_EARNINGS is rejected if another account in the CoA already has that classification
+- The reconciliation invariant is enforced on every update: accounts with RECEIVABLE, PAYABLE, or BANK_CASH classification must have reconciliation enabled. Explicitly setting isReconciliation to false on an account that currently has (or is being changed to) one of these classifications is rejected. This applies to three update paths: (1) changing classification to RECEIVABLE/PAYABLE/BANK_CASH while isReconciliation is false, (2) setting isReconciliation to false on an account already classified as RECEIVABLE/PAYABLE/BANK_CASH, and (3) simultaneously changing classification to one of these types and setting isReconciliation to false
+- Classification changes that affect posting constraints must update the stored constraint accordingly: changing to NON_POSTING marks the account as excluded from posting target selection; changing to RECEIVABLE or PAYABLE marks the account as a control account blocking manual postings; changing away from these classifications removes the corresponding constraint (all enforced by downstream posting modules)
+- Currency restriction changes must reference a valid currency from the primitives module. An account with currency restriction only accepts postings in that currency (enforced by downstream posting modules)
+- Account group changes must reference a group in the same CoA, and the account code must fall within the group's number range (if defined)
+- When the account code is changed and the account belongs to an account group (whether the group assignment is also changing or staying the same), the new code must fall within the target group's number range (if defined). This applies to both cases: changing only the code while keeping the current group, and changing both the code and the group simultaneously
+- Emits an audit event via the audit module recording the acting user, timestamp, CoA reference, account code, and previous and new field values for all changed attributes
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Account exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is DRAFT or ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is ARCHIVED]
+    B2 -->|Yes| D{Structural fields changed?}
+    D -->|Yes| E{Account has posted transactions?}
+    E -->|Yes| F[Return error: structural fields immutable]
+    E -->|No| D2{Code changed?}
+    D2 -->|Yes| D3{Valid numeric format?}
+    D3 -->|No| D4[Return error: invalid code format]
+    D3 -->|Yes| D5{Code unique within CoA?}
+    D5 -->|No| D6[Return error: duplicate code]
+    D5 -->|Yes| G{Validate other structural changes}
+    D2 -->|No| G
+    D -->|No| H{Validate non-structural changes}
+    G --> H
+    H --> H2{Reconciliation invariant violated?}
+    H2 -->|Yes| H3[Return error: reconciliation required]
+    H2 -->|No| I[Update account fields]
+    I --> J[Emit audit event]
+    J --> K[Return updated account]
+```
+
+## External Dependencies
+
+- [primitives::getCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validates currency restriction changes
+
+## Error Scenarios
+
+- **ACCOUNT_NOT_FOUND**: Specified account ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **NAME_REQUIRED**: Name is provided but empty
+- **INVALID_ACCOUNT_CODE**: New account code is not a valid structured numeric identifier
+- **DUPLICATE_ACCOUNT_CODE**: An account with the same code already exists in the CoA
+- **STRUCTURAL_FIELD_IMMUTABLE**: Attempted to change a structural field on an account with posted transactions
+- **INCOMPATIBLE_CLASSIFICATION**: New classification is not compatible with the account type
+- **DUPLICATE_RETAINED_EARNINGS**: Another account in the CoA already has RETAINED_EARNINGS classification
+- **RECONCILIATION_REQUIRED**: Cannot disable reconciliation on an account with RECEIVABLE, PAYABLE, or BANK_CASH classification
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist or is not active
+- **ACCOUNT_GROUP_NOT_FOUND**: Referenced account group does not exist or belongs to a different CoA
+- **CODE_OUT_OF_RANGE**: Account code does not fall within the target group's number range (applies when changing the group, changing the code, or changing both)
+
+## Test Cases
+
+- returns error when account does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when name is empty
+- returns error when new account code is not a valid numeric identifier
+- returns error when new account code already exists in the CoA
+- returns error when changing structural field on account with posted transactions
+- returns error when new classification is incompatible with type
+- returns error when changing to RETAINED_EARNINGS and another account already has it
+- returns error when new currency does not exist
+- returns error when new group belongs to different CoA
+- updates name of an account
+- updates tags of an account
+- updates default tax code
+- updates account group assignment
+- updates structural fields when no posted transactions exist
+- returns error when setting isReconciliation to false on a RECEIVABLE account
+- returns error when setting isReconciliation to false on a PAYABLE account
+- returns error when setting isReconciliation to false on a BANK_CASH account
+- returns error when changing classification to RECEIVABLE with isReconciliation explicitly set to false
+- enforces reconciliation when classification changes to RECEIVABLE
+- marks account as excluded from posting when classification changes to NON_POSTING
+- marks account as control account blocking manual postings when classification changes to RECEIVABLE
+- marks account as control account blocking manual postings when classification changes to PAYABLE
+- removes posting exclusion when classification changes from NON_POSTING to REGULAR
+- updates currency restriction and posting currency constraint accordingly
+- returns error when account code outside new group number range
+- returns error when changing code to a value outside the current group's number range
+- returns error when changing classification from RECEIVABLE after posted transactions
+- returns error when changing classification from PAYABLE after posted transactions
+- emits audit event recording previous and new field values for all changed attributes
+- passes custom fields through to update

package/src/modules/coa-management/docs/commands/UpdateAccountGroup.md

@@ -0,0 +1,62 @@
+# UpdateAccountGroup
+
+## Overview
+
+updateAccountGroup modifies the mutable fields (name, sort order, number range) of an existing account group. Code is immutable after creation. Number range changes must not conflict with existing account assignments or overlap with other groups' ranges.
+
+## Business Rules
+
+- Target group must exist
+- Parent CoA must be in DRAFT or ACTIVE status; updating a group under an ARCHIVED CoA is rejected
+- Name, when provided, must be non-empty
+- Group code is immutable
+- Number range changes, when provided, require both start and end to be provided together, must remain a valid non-overlapping interval within the CoA
+- Changing a number range must not invalidate existing accounts already assigned to the group (their codes must still fall within the new range)
+- Emits an audit event via the audit module recording the acting user, timestamp, and previous and new field values for all changed attributes
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Group exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| B2{Parent CoA is DRAFT or ACTIVE?}
+    B2 -->|No| B3[Return error: CoA is ARCHIVED]
+    B2 -->|Yes| D{Name valid if provided?}
+    D -->|No| E[Return error: name required]
+    D -->|Yes| F{Number range valid if changed?}
+    F -->|No| G[Return error: invalid or overlapping range]
+    F -->|Yes| H{Existing accounts within new range?}
+    H -->|No| I[Return error: accounts out of range]
+    H -->|Yes| J[Update group fields]
+    J --> K[Emit audit event]
+    K --> L[Return updated group]
+```
+
+## External Dependencies
+
+- [audit](../../../audit/README.md) — Receives audit events emitted by this command
+
+## Error Scenarios
+
+- **ACCOUNT_GROUP_NOT_FOUND**: Specified group ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: Parent CoA is in ARCHIVED status; no modifications are permitted
+- **NAME_REQUIRED**: Name is provided but empty
+- **INVALID_NUMBER_RANGE**: Number range is invalid or overlaps with another group's range
+- **ACCOUNTS_OUT_OF_RANGE**: Existing assigned accounts have codes outside the new number range
+
+## Test Cases
+
+- returns error when group does not exist
+- returns error when parent CoA is ARCHIVED
+- returns error when name is empty
+- returns error when new number range is invalid
+- returns error when updating to one-sided number range (start only)
+- returns error when updating to one-sided number range (end only)
+- returns error when new number range overlaps with another group
+- returns error when existing accounts fall outside new number range
+- updates group name
+- updates sort order
+- updates number range
+- emits audit event recording previous and new field values
+- passes custom fields through to update

package/src/modules/coa-management/docs/commands/UpdateChartOfAccounts.md

@@ -0,0 +1,49 @@
+# UpdateChartOfAccounts
+
+## Overview
+
+updateChartOfAccounts modifies the mutable fields (name, description) of an existing Chart of Accounts. Updates are permitted while the CoA is in DRAFT or ACTIVE status. ARCHIVED CoA records cannot be updated.
+
+## Business Rules
+
+- Target CoA must exist
+- Target CoA must be in DRAFT or ACTIVE status; updating an ARCHIVED CoA is rejected
+- Name, when provided, must be non-empty
+- Description is optional and can be cleared
+- Emits an audit event via the audit module recording the acting user, timestamp, and previous and new field values for all changed attributes
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{CoA exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT or ACTIVE?}
+    D -->|No| E[Return error: CoA is archived]
+    D -->|Yes| F{Name valid if provided?}
+    F -->|No| G[Return error: name required]
+    F -->|Yes| H[Update CoA fields]
+    H --> I[Emit audit event]
+    I --> J[Return updated CoA]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHART_OF_ACCOUNTS_NOT_FOUND**: Specified CoA ID does not exist
+- **CHART_OF_ACCOUNTS_ARCHIVED**: CoA is in ARCHIVED status and cannot be modified
+- **NAME_REQUIRED**: Name is provided but empty
+
+## Test Cases
+
+- returns error when CoA does not exist
+- returns error when CoA is ARCHIVED
+- returns error when name is empty
+- updates name of a DRAFT CoA
+- updates description of an ACTIVE CoA
+- clears description by setting to null
+- emits audit event recording previous and new field values
+- passes custom fields through to update

package/src/modules/coa-management/docs/features/account-group-hierarchy.md

@@ -0,0 +1,81 @@
+# Account Group Hierarchy
+
+## Overview
+
+Account groups organize general ledger (GL) accounts into logical categories and nestable hierarchical tree structures within a Chart of Accounts (CoA). Each group has a code, name, optional parent group reference for nesting, and a sort order that controls display sequencing. Groups define categories such as "Current Assets" or "Long-Term Liabilities" and may constrain the account number ranges assignable to their member accounts.
+
+Groups can be nested to form a multi-level tree hierarchy that provides structural metadata for the CoA. A root group with no parent represents a top-level section (e.g., "Assets"), while child groups subdivide it into progressively finer categories. Accounts are mapped to leaf or intermediate groups. The hierarchy defines the structure; how that structure is consumed — for balance aggregation, financial statement rendering, or period-close validation — is the responsibility of downstream modules (general-ledger, reporting).
+
+## Business Purpose
+
+- **Logical categorization**: Groups classify GL accounts into meaningful business categories (e.g., "Cash and Cash Equivalents", "Accounts Receivable") so that users and downstream modules can reason about accounts collectively
+- **Hierarchical structure**: Nested group trees define the structural organization of accounts. The hierarchy provides the metadata that downstream modules (general-ledger, reporting) consume for balance aggregation and financial statement rendering — this module owns the tree structure, not the aggregation logic
+- **Account number range control**: Groups can define allowed number intervals, ensuring that accounts created within a group fall into the expected numbering range (e.g., 1000-1999 for Assets)
+- **Single operational hierarchy**: Each CoA has one group hierarchy tree that defines the operational categorization of accounts. Financial statement versions (FSV) and multi-GAAP alternative hierarchies are out of scope for this module and belong to a future reporting module
+- **Structural consistency**: Account group assignment is optional per account, but recommended. This module provides a query to list accounts not assigned to any group, enabling downstream consumers to validate completeness according to their own requirements
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Chart of Accounts] --> B[Define Root Groups]
+    B --> C[Create Child Groups under Root]
+    C --> D{More nesting needed?}
+    D -- Yes --> C
+    D -- No --> E[Set Account Number Ranges per Group]
+    E --> F[Assign Accounts to Groups]
+    F --> G[Hierarchy Structure Complete]
+```
+
+```mermaid
+flowchart TD
+    L1[Root Group: Assets]
+    L1 --> L2A[Child Group: Current Assets]
+    L1 --> L2B[Child Group: Non-Current Assets]
+    L2A --> L3A[Leaf Group: Cash and Equivalents]
+    L2A --> L3B[Leaf Group: Accounts Receivable]
+    L3A --> A1[Account 1010: Petty Cash]
+    L3A --> A2[Account 1020: Bank Account]
+    L3B --> A3[Account 1100: Trade Receivables]
+    L2B --> L3C[Leaf Group: Fixed Assets]
+    L3C --> A4[Account 1500: Equipment]
+```
+
+## Scenario Patterns
+
+- **Standard Balance Sheet Structure**: A controller creates root groups for Assets, Liabilities, and Equity, then nests child groups (Current Assets, Non-Current Assets, Current Liabilities, etc.) to define the account organization structure
+- **Income Statement Structure**: Revenue and expense root groups are subdivided into operating and non-operating categories, with leaf groups for specific reporting classes such as operating expenses, non-operating expenses, and revenue subclasses (e.g., product revenue, service revenue)
+- **Operational Hierarchy Setup**: A single group hierarchy is defined for the CoA, structuring accounts into logical sections (Balance Sheet and Income Statement categories). Downstream modules consume this hierarchy for reporting and aggregation
+- **Account Range Enforcement**: An "Accounts Payable" group is configured with the number range 2000-2099; attempting to create an account numbered 3001 within this group is rejected
+- **Reparenting a Group**: A "Short-Term Investments" group is moved from "Non-Current Assets" to "Current Assets" to reflect a reclassification, updating the hierarchy path
+- **Unassigned Account Query**: A query lists all active accounts not assigned to any group, enabling downstream consumers (e.g., reporting module) to validate hierarchy completeness according to their own requirements
+
+## Test Cases
+
+- Every account group belongs to exactly one Chart of Accounts
+- Account group code is required and must be unique within its CoA
+- Account group code is immutable after creation
+- Account group name is required and must be non-empty
+- A group with no parent reference is treated as a root-level group
+- A group with a parent reference must reference a valid group within the same CoA
+- Circular parent references are rejected (a group cannot be its own ancestor)
+- Sort order controls the display sequence of sibling groups under the same parent
+- Deleting a group that contains child groups or assigned accounts is rejected
+- Account number range, when defined on a group, must be a valid non-overlapping interval within the CoA
+- Accounts assigned to a group must have account numbers within the group's allowed range (when a range is defined)
+- Hierarchy depth is not artificially limited but must remain acyclic
+- Moving a group to a new parent within the same CoA updates the hierarchy without breaking existing account assignments
+- A query returns all active accounts within a CoA that are not assigned to any group
+- Account group assignment is optional; accounts can exist in a CoA without belonging to any group
+- The hierarchy tree structure is queryable by downstream modules for consumption (e.g., balance aggregation, report rendering)
+- Creating an account group emits an audit event via the audit module recording the acting user, timestamp, and initial field values
+- Updating an account group (name, sort order, number range) emits an audit event recording previous and new field values; parent changes are handled by the moveAccountGroup operation, not updateAccountGroup
+- Deleting an account group emits an audit event recording the deletion and acting user
+- Moving a group to a new parent emits an audit event recording the previous and new parent references
+
+## Reference Links
+
+- [SAP Account Groups and Number Ranges](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee5c9e37ff4f4e33a6c7e2c32f8fc3b5/4b0d35d32d6b3e41e10000000a42189c.html)
+- [SAP Financial Statement Versions](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee5c9e37ff4f4e33a6c7e2c32f8fc3b5/577f8c2a397b4ce589e1ad03a64eb1ae.html)
+- [Oracle General Ledger Trees and Hierarchies](https://docs.oracle.com/en/cloud/saas/financials/24d/oaglg/overview-of-accounting-hierarchies.html)
+- [Odoo Account Groups](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/chart_of_accounts.html)

package/src/modules/coa-management/docs/features/account-lifecycle.md

@@ -0,0 +1,80 @@
+# Account Lifecycle
+
+## Overview
+
+GL accounts follow a state machine (DRAFT -> ACTIVE <-> INACTIVE) that governs when an account can receive journal postings, be modified, or be deactivated. The lifecycle ensures that accounts are fully validated before they participate in financial transactions, and that historical data is preserved when an account is retired.
+
+Accounts with posted transactions cannot be deleted — they must be deactivated instead. Deactivation prevents new postings while retaining the account for regulatory reporting and audit purposes. An optional successor account mapping allows a replacement to be designated during deactivation; the actual posting redirection behavior is owned by the general-ledger module, which reads the successor mapping from this module. All status transitions emit audit events through the audit module, supporting SOX compliance requirements for change tracking on the chart of accounts.
+
+## Business Purpose
+
+- **Lifecycle gating**: Only ACTIVE accounts can receive new journal postings, preventing use of incomplete or retired accounts in financial transactions. Account activation itself requires the parent CoA to be in ACTIVE status — accounts under a DRAFT CoA remain in DRAFT until the CoA is activated, ensuring safe cascade deletion of DRAFT CoAs
+- **Data preservation**: Accounts with posted transactions are never deleted; deactivation preserves history for regulatory retention requirements (typically 7-10 years)
+- **Deprecation with successor mapping**: When retiring an account, an optional successor account can be designated. This module stores the mapping; the general-ledger module is responsible for reading this mapping and redirecting future postings
+- **Balance verification (integration point)**: Deactivation can optionally verify that the account carries no open or unreconciled balances. The balance truth is owned by the general-ledger module — this module exposes a hook for the GL module to block deactivation when open balances exist
+- **Audit trail**: Every status transition is recorded via the audit module, providing a complete change history for internal controls and external audits
+- **Segregation of duties**: Account creation, modification, and approval of status changes can be assigned to separate roles, satisfying SOX and internal control requirements
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAccount
+    Draft --> Active: activateAccount
+    Active --> Inactive: deactivateAccount
+    Inactive --> Active: reactivateAccount
+    Draft --> [*]: deleteAccount
+```
+
+```mermaid
+stateDiagram-v2
+    state "Deactivation Workflow" as deact {
+        [*] --> VerifyBalances: initiate deactivation
+        VerifyBalances --> MapSuccessor: no open balances
+        VerifyBalances --> Blocked: open balances exist
+        MapSuccessor --> SetInactive: successor mapped (optional)
+        SetInactive --> EmitAuditEvent
+        EmitAuditEvent --> [*]
+        Blocked --> [*]: resolve balances first
+    }
+```
+
+## Scenario Patterns
+
+- **New Account Setup**: A controller creates a GL account in DRAFT, assigns it to the correct account group and hierarchy, then activates it once the parent CoA is ACTIVE (account activation is gated on CoA ACTIVE status) before the first posting period
+- **Account Deprecation with Successor**: A revenue account is being replaced by a more granular set of accounts; the old account is deactivated with a successor mapped. The general-ledger module reads this mapping to redirect any future automated postings to the new account
+- **Balance-Blocked Deactivation (with GL integration)**: An attempt to deactivate an expense account is blocked by the general-ledger module's balance check hook because it still carries an unreconciled balance; the balance must be cleared or transferred before deactivation can proceed
+- **Seasonal Reactivation**: A project-specific account was deactivated at project close but is reactivated when the project resumes, avoiding a duplicate account
+- **Draft Cleanup**: An account created in error is deleted while still in DRAFT before any transactions are posted against it
+- **Regulatory Retention**: A long-inactive account remains in the system with full posting history to satisfy the organization's 7-year data retention policy
+
+## Test Cases
+
+- Account lifecycle follows DRAFT -> ACTIVE <-> INACTIVE state machine
+- Accounts can only be created in DRAFT status
+- Only DRAFT accounts with no posted transactions can be deleted
+- Activating a DRAFT account transitions status to ACTIVE when the parent CoA is ACTIVE
+- Activating an account under a DRAFT CoA fails because account activation requires the parent CoA to be in ACTIVE status
+- Activating an account under an ARCHIVED CoA fails because archived CoAs are immutable
+- Activating an already ACTIVE account fails with an invalid status transition error
+- Deactivating an ACTIVE account transitions status to INACTIVE
+- Deactivating a DRAFT account fails with an invalid status transition error
+- Reactivating an INACTIVE account transitions status to ACTIVE
+- Only ACTIVE accounts can receive new journal postings
+- Deactivation exposes a pre-deactivation hook that the general-ledger module can use to block the transition when open or unreconciled balances exist
+- Without a GL module integrated, deactivation proceeds without balance checks
+- A successor account can be mapped during deactivation; posting redirection is owned by the general-ledger module
+- The successor account must itself be ACTIVE at the time of mapping
+- A successor account mapping is optional; deactivation succeeds without one when balances are clear
+- Deleting an account that has posted transactions fails regardless of current status
+- Each status transition emits an audit event via the audit module
+- Audit events record the previous status, new status, acting user, and timestamp
+- Reactivating an account clears any previously mapped successor account
+- Inactive accounts and their posted transactions remain queryable for reporting
+
+## Reference Links
+
+- [SAP GL Account Master Data](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee8e4a0f52db415aaa43eb0bf5446a35/4b0a1e1c2d6b3e41e10000000a42189c.html)
+- [Odoo Chart of Accounts](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/chart_of_accounts.html)
+- [Oracle GL Account Maintenance](https://docs.oracle.com/en/cloud/saas/financials/24d/oafmg/overview-of-oracle-general-ledger.html)
+- [SOX Section 302 — Internal Controls](https://www.sarbanes-oxley-101.com/sarbanes-oxley-compliance.htm)

package/src/modules/coa-management/docs/features/account-management.md

@@ -0,0 +1,114 @@
+# Account Management
+
+## Overview
+
+Account Management provides CRUD operations for General Ledger (GL) accounts within a Chart of Accounts (CoA). A GL account is the fundamental building block of financial recording — every journal entry, sub-ledger posting, and financial report ultimately references one or more GL accounts. Each account carries a structured numeric code, a descriptive name, an account type drawn from the standard five-category classification (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE), an account classification that describes its operational role (e.g., RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, NON_POSTING, REGULAR), and optional attributes such as currency restriction, reconciliation flag, default tax code reference, and tags.
+
+Accounts are always scoped to a parent CoA and may optionally belong to an account group for hierarchical reporting. The account code follows a structured numbering convention (e.g., 1000-1999 for assets, 2000-2999 for liabilities) that encodes classification directly in the identifier, enabling consistent sorting and range-based queries across the ledger.
+
+## Business Purpose
+
+- **Standardized financial classification**: The five account types (ASSET, LIABILITY, EQUITY, REVENUE, EXPENSE) map directly to the structure of the balance sheet and income statement, ensuring every transaction is categorized correctly
+- **Operational account classification**: Beyond the five financial types, each account carries a classification that describes its operational role in the ERP system. Classifications include RECEIVABLE (sub-ledger integration with AR), PAYABLE (sub-ledger integration with AP), BANK_CASH (cash management and bank reconciliation), FIXED_ASSET (asset accounting integration), RETAINED_EARNINGS (equity roll-forward), NON_POSTING (a postability attribute that marks accounts as excluded from journal entry posting; this is not a hierarchy mechanism — structural hierarchy is owned exclusively by account groups), and REGULAR (general-purpose accounts with no special behavior). This classification drives downstream module behavior — for example, only RECEIVABLE accounts can serve as AR control accounts, and NON_POSTING accounts are excluded from journal entry target selection
+- **Structured code numbering**: Numeric code ranges provide an immediately recognizable, sortable identifier that conveys account classification without requiring a lookup
+- **Currency restriction**: Restricting an account to a specific currency prevents mixed-currency postings and simplifies reconciliation for foreign-currency bank or receivable accounts
+- **Reconciliation control**: The reconciliation flag designates accounts (such as bank, accounts receivable, and accounts payable) where individual line items must be matched and cleared, supporting accurate cash and partner balance tracking. Accounts classified as RECEIVABLE, PAYABLE, or BANK_CASH must have reconciliation enabled — this is enforced as an invariant, not a default
+- **Control account posting restrictions**: Accounts classified as RECEIVABLE or PAYABLE serve as sub-ledger control accounts. Direct manual journal postings to these accounts must be blocked; only automated postings from the AR/AP sub-ledger modules are permitted. This invariant preserves the integrity of the sub-ledger ↔ GL reconciliation and prevents manual entries from creating discrepancies between the sub-ledger detail and the GL summary balance
+- **Structural immutability after posting**: Once an account has received posted transactions, structural fields (account code, account type, account classification, currency restriction) become immutable. This applies to all accounts but is especially critical for control accounts (RECEIVABLE, PAYABLE) where a classification change would break sub-ledger integration
+- **Default tax code**: An optional free-text tax code identifier stored on the account for downstream use. When the `tax-configuration` module is implemented, this field will be migrated to a validated foreign-key reference against the tax code catalog. Until then, this module stores the identifier as free text with no external validation. The migration contract: the `tax-configuration` module will own the validation rule; this module will add a dependency and enforce referential integrity at that time
+- **Tag-based categorization**: Tags provide flexible, cross-cutting labels for filtering and reporting beyond the rigid type and group hierarchy — for example, tagging accounts as "intercompany", "cost-center-allocable", or "cash-flow-relevant"
+- **CoA and group membership**: Scoping accounts to a CoA and optional account group maintains structural integrity and supports hierarchical roll-up in trial balances and financial statements
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Start] --> B[Create Account in CoA]
+    B --> C{All required fields valid?}
+    C -- No --> D[Return validation error]
+    C -- Yes --> E[Account created]
+    E --> F{Update needed?}
+    F -- Yes --> G[Update account attributes]
+    G --> H{Account referenced in journal entries?}
+    H -- Yes --> I[Restrict updates to non-structural fields]
+    H -- No --> J[Allow full update]
+    I --> E
+    J --> E
+    F -- No --> K{Delete requested?}
+    K -- Yes --> L{Account in DRAFT status?}
+    L -- No --> M[Reject deletion — must deactivate instead]
+    L -- Yes --> L2{Account has posted transactions?}
+    L2 -- Yes --> M
+    L2 -- No --> N[Delete account]
+    K -- No --> O[Read / List / Filter accounts]
+```
+
+```mermaid
+flowchart TD
+    subgraph Code Structure
+        A1[1000-1999: ASSET] --> A2[2000-2999: LIABILITY]
+        A2 --> A3[3000-3999: EQUITY]
+        A3 --> A4[4000-4999: REVENUE]
+        A4 --> A5[5000-5999: EXPENSE]
+    end
+```
+
+## Scenario Patterns
+
+- **Standard Account Creation**: A finance team sets up a new CoA and creates GL accounts following the structured numbering convention — cash at 1010 (BANK_CASH), accounts receivable at 1200 (RECEIVABLE), accounts payable at 2100 (PAYABLE), retained earnings at 3100 (RETAINED_EARNINGS), sales revenue at 4000 (REGULAR), and office supplies expense at 5200 (REGULAR)
+- **Foreign Currency Bank Account**: A treasury team creates a bank account (ASSET, BANK_CASH, code 1015) with a currency restriction set to USD, ensuring only USD-denominated entries can be posted to it
+- **Reconcilable Receivable Account**: An accounts receivable control account (ASSET, RECEIVABLE, code 1200) is created with the reconciliation flag enabled, allowing individual customer invoice and payment lines to be matched and cleared. The RECEIVABLE classification marks it as the AR sub-ledger control account
+- **Non-Posting Control Account**: A clearing or suspense account (ASSET, NON_POSTING, code 1000) is created with the NON_POSTING classification, marking it as excluded from journal entry posting. This is strictly a postability control — it prevents the account from being selected as a target in journal entries. Structural grouping, subtotals, and report labels are owned by account groups and downstream reporting modules, not by account classification
+- **Tax-Defaulted Revenue Account**: A domestic sales revenue account (REVENUE, REGULAR, code 4010) is created with a default tax code referencing the standard VAT rate, so journal lines hitting this account auto-populate the correct tax treatment
+- **Tagged Intercompany Account**: An intercompany receivable account is created with RECEIVABLE classification and tagged with "intercompany" to enable cross-entity elimination reports without relying solely on account code ranges
+- **Retained Earnings Account**: An equity account (EQUITY, RETAINED_EARNINGS, code 3100) is designated to receive the net income roll-forward at period close. Only one account per CoA should carry this classification
+- **Fixed Asset Account**: Equipment account (ASSET, FIXED_ASSET, code 1500) is created with the FIXED_ASSET classification, enabling future integration with the fixed-asset module for depreciation scheduling
+- **Account Group Assignment**: Multiple expense accounts (5100 salaries, 5200 rent, 5300 utilities) are assigned to an "Operating Expenses" account group for hierarchical organization
+- **Blocked Manual Posting to Control Account**: A user attempts to create a manual journal entry debiting the AR control account (1200, RECEIVABLE); the posting is rejected because RECEIVABLE accounts only accept automated sub-ledger postings from the AR module
+- **Prevented Deletion of Active Account**: An attempt to delete account 1010 (cash), which is in ACTIVE status, fails because only DRAFT accounts can be deleted; accounts with posted transactions must be deactivated instead
+- **Prevented Structural Change on Posted Control Account**: An attempt to change the classification of account 2100 (PAYABLE) to REGULAR is rejected because the account has posted transactions; the PAYABLE classification is immutable after posting
+- **Bulk Account Setup**: During initial CoA configuration, a batch of accounts is created from a template covering all five types with appropriate classifications, codes, names, and default attributes
+
+## Test Cases
+
+- Creating an account requires a valid parent CoA reference
+- Account code must be unique within the same CoA
+- Account code must be a structured numeric identifier and cannot be empty
+- Account name is required and must be non-empty
+- Account type must be one of ASSET, LIABILITY, EQUITY, REVENUE, or EXPENSE
+- Account classification must be one of REGULAR, RECEIVABLE, PAYABLE, BANK_CASH, FIXED_ASSET, RETAINED_EARNINGS, or NON_POSTING
+- Account classification defaults to REGULAR when not explicitly set
+- Account classification must be compatible with account type: RECEIVABLE and BANK_CASH and FIXED_ASSET require type ASSET; PAYABLE requires type LIABILITY; RETAINED_EARNINGS requires type EQUITY; REGULAR and NON_POSTING are allowed with any account type
+- NON_POSTING accounts cannot receive journal postings — downstream modules must exclude them from posting target selection. NON_POSTING is a postability attribute only; it does not imply parent-child relationships between accounts (hierarchy is owned by account groups)
+- Only one account per CoA may carry the RETAINED_EARNINGS classification
+- Currency restriction, when provided, must reference a valid currency from the primitives module
+- An account with currency restriction only accepts postings in that currency
+- Reconciliation flag defaults to false when not explicitly set for REGULAR, FIXED_ASSET, RETAINED_EARNINGS, and NON_POSTING classifications
+- Accounts with RECEIVABLE, PAYABLE, or BANK_CASH classification must have reconciliation enabled; attempting to set reconciliation to false for these classifications is rejected
+- Creating a RECEIVABLE or PAYABLE account automatically enforces reconciliation enabled as an invariant
+- RECEIVABLE and PAYABLE accounts block direct manual journal postings; only sub-ledger module automated postings are permitted
+- Attempting a direct manual journal posting to a RECEIVABLE or PAYABLE control account is rejected by downstream posting modules (this module marks the constraint; enforcement is at the GL/posting layer)
+- Default tax code is an optional free-text identifier (validation against a tax configuration module is a future integration point)
+- Tags are optional and may contain zero or more string labels
+- An account can optionally belong to an account group within the same CoA
+- Updating an account that has posted journal entries restricts changes to non-structural fields (name, tags, default tax code); structural fields (account code, account type, account classification, currency restriction) become immutable
+- Updating account type, code, or classification is rejected when the account has posted transactions
+- Changing account classification from RECEIVABLE or PAYABLE to any other classification is rejected once the account has posted transactions, preserving sub-ledger integrity
+- Only DRAFT accounts with no posted transactions can be deleted (consistent with account lifecycle state machine)
+- Deleting an ACTIVE or INACTIVE account is rejected regardless of transaction history; these accounts must be deactivated instead
+- Deleting a DRAFT account that has posted transactions is rejected to preserve ledger integrity
+- Listing accounts supports filtering by type, account group, tags, and currency restriction
+- Accounts within a CoA can be retrieved sorted by account code
+- Creating two accounts with the same code in the same CoA fails with a uniqueness constraint error
+- Creating an account with a code outside valid numeric format fails validation
+- Assigning an account to a group that belongs to a different CoA fails validation
+- Creating an account emits an audit event via the audit module recording the acting user, timestamp, and initial field values
+- Updating an account emits an audit event recording the previous and new field values for all changed attributes
+- Deleting a DRAFT account emits an audit event recording the deletion and acting user
+- Audit events for account operations include the CoA reference, account code, and account classification for traceability
+
+## Reference Links
+
+- [SAP GL Account Master Data](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee4e846b9aea4e78b6665038855e5148/4d9a976ecc0e7a30e10000000a15822b.html)
+- [Odoo Chart of Accounts (account.account)](https://www.odoo.com/documentation/19.0/applications/finance/accounting/get_started/chart_of_accounts.html)
+- [IFRS Conceptual Framework — Elements of Financial Statements](https://www.ifrs.org/issued-standards/list-of-standards/conceptual-framework/)