@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/accounting/docs/features/budget-management.md

@@ -0,0 +1,147 @@
+# Budget Management
+
+## Overview
+
+Budget Management provides the planning and control capabilities of the accounting module, enabling organizations to create budgets with line items per cost element, manage approval workflows, track multiple budget versions, and compare budgeted amounts against actual postings from finance-ledger. A budget entity carries a name, budget holder, fiscal year, period range, total amount, status, version type, and a cost object reference (cost center, profit center, or internal order). Each budget contains one or more BudgetLineItem records that specify a cost element, planned amount, and accounting period. The corresponding GL account for each line item is derived automatically from the primary cost element's one-to-one GL account mapping defined in cost-element-management, ensuring a single authoritative planning axis while preserving traceability to the general ledger. A PlanVersion entity (BUDGET, FORECAST, or SIMULATION) supports multi-version planning so organizations can maintain an approved operating budget alongside rolling forecasts and what-if simulations.
+
+Budgets follow a five-stage lifecycle — DRAFT, SUBMITTED, APPROVED, ACTIVE, CLOSED — enforcing segregation of duties between budget creation, approval, and cost posting. Budgetary control (funds check) provides real-time validation that prevents transactions from exceeding approved budget amounts, using the BudgetAvailability formula: `Available = Budget - (Actual + Commitments + Encumbrances)`. Actual amounts are sourced from posted journal entries in finance-ledger. Commitments represent outstanding purchase order amounts received from the purchase module via commitment events; encumbrances represent purchase requisition amounts (future extension). This three-bucket model aligns with SAP availability control and Oracle budgetary control patterns. Budget periods reference finance-ledger FiscalYear and AccountingPeriod entities for period alignment, and budget lock at period-end integrates with finance-ledger period close. All budgets are scoped to a Company.
+
+## Business Purpose
+
+Organizations need a structured budgeting process to plan expenditures, control costs, and measure financial performance against targets:
+
+- **Expenditure planning**: Budgets translate strategic objectives into quantified financial plans by allocating planned amounts to cost elements across accounting periods, providing a financial roadmap for the fiscal year. The corresponding GL account is derived from each primary cost element's GL mapping, ensuring consistency between management and financial accounting without requiring dual-axis maintenance
+- **Approval workflow enforcement**: The DRAFT to SUBMITTED to APPROVED progression ensures budgets are reviewed and authorized before activation, enforcing segregation of duties required by SOX and internal control frameworks — budget approval must be separate from budget creation and cost posting
+- **Multi-version planning**: PlanVersion support (BUDGET, FORECAST, SIMULATION) allows organizations to maintain an approved operating budget alongside rolling forecasts and what-if simulations, enabling agile financial planning without altering the baseline commitment
+- **Budgetary control (funds check)**: Real-time validation prevents transactions from exceeding available budget using the formula `Available = Budget - (Actual + Commitments + Encumbrances)`. This three-bucket availability check catches overspend at entry time, including amounts committed via purchase orders that have not yet been invoiced, preventing the common failure mode where PO-committed funds are double-spent
+- **Commitment tracking**: Outstanding purchase order amounts are tracked as commitments that reduce available budget. When the purchase module confirms, receives, or invoices a PO, commitment amounts are consumed and reclassified as actuals. This integration requires consuming commitment events from the purchase module (PO confirmed, goods received, invoice matched)
+- **Budget vs. actual comparison**: Comparing budgeted amounts against actual postings from finance-ledger journal entries surfaces variances early, enabling corrective action before period close
+- **Cost object alignment**: Budgets reference cost centers, profit centers, or internal orders, linking financial plans to the organizational and project structures managed by the accounting module
+- **Period alignment with finance-ledger**: Budget periods reference FiscalYear and AccountingPeriod from finance-ledger, ensuring budget and actual data share the same temporal boundaries for accurate variance analysis
+- **Budget lock at period-end**: Closing a budget period prevents further modifications to planned amounts, integrating with finance-ledger period close to produce a frozen baseline for reporting and audit
+- **Audit trail**: Every lifecycle transition — creation, submission, approval, activation, closure — is recorded with the acting user and timestamp, supporting internal and external audit requirements
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createBudget
+    Draft --> Draft: updateBudget / addLineItem / removeLineItem
+    Draft --> Submitted: submitBudget
+    Submitted --> Approved: approveBudget
+    Submitted --> Draft: rejectBudget
+    Approved --> Active: activateBudget
+    Active --> Closed: closeBudget
+    Draft --> [*]: deleteBudget
+```
+
+```mermaid
+flowchart TD
+    A[Define budget scope: fiscal year, cost object, version type] --> B[Create Budget in DRAFT with header fields]
+    B --> C[Add BudgetLineItem records per cost element and period]
+    C --> D{All periods and cost elements covered?}
+    D -- No --> C
+    D -- Yes --> E[Submit budget for approval]
+    E --> F{Approver reviews budget}
+    F -- Reject --> G[Return to DRAFT with rejection reason]
+    G --> C
+    F -- Approve --> H[Budget status set to APPROVED]
+    H --> I[Activate budget for budgetary control]
+    I --> J[Funds check enabled: transactions validated against budget]
+    J --> K{Period-end reached?}
+    K -- No --> J
+    K -- Yes --> L[Lock budget period and run variance analysis]
+    L --> M{All periods complete?}
+    M -- No --> K
+    M -- Yes --> N[Close budget]
+```
+
+```mermaid
+flowchart TD
+    A[Transaction submitted against cost element] --> B{Budget exists and ACTIVE for cost object?}
+    B -- No --> C[Transaction proceeds without funds check]
+    B -- Yes --> D[Compute BudgetAvailability]
+    D --> D1[Available = Budget - Actual + Commitments + Encumbrances]
+    D1 --> E{Available >= transaction amount?}
+    E -- Yes --> F[Transaction passes funds check]
+    E -- No --> G[Transaction rejected: budget exceeded]
+```
+
+```mermaid
+flowchart TD
+    A[Purchase Order confirmed in purchase module] --> B[Commitment event received by accounting]
+    B --> C[Record commitment amount against cost element + cost object + period]
+    C --> D[BudgetAvailability reduced by commitment amount]
+    D --> E{Goods receipt or invoice posted?}
+    E -- Goods Receipt --> F[Reduce commitment, increase actual by received amount]
+    E -- Invoice Matched --> G[Reduce remaining commitment, actual reflects invoiced amount]
+    E -- PO Cancelled --> H[Release commitment amount back to available budget]
+```
+
+## Scenario Patterns
+
+- **Annual Operating Budget Creation**: A finance manager creates a new budget for fiscal year 2026 scoped to a cost center, adds line items for each cost element (salaries, travel, office supplies) distributed across twelve monthly periods, submits for department head approval, and activates upon approval to enable funds checking
+- **Rolling Forecast Update**: A financial analyst creates a FORECAST plan version based on the approved BUDGET version, adjusts planned amounts for Q3 and Q4 to reflect revised revenue projections, and submits the forecast for review — the original BUDGET version remains unchanged as the committed baseline
+- **What-If Simulation**: A planning team creates a SIMULATION plan version to model the financial impact of opening a new office, copying the current budget as a base and adding incremental line items for rent, staffing, and equipment — the simulation is never activated but serves as decision support
+- **Budget Rejection and Revision**: A department submits a budget that exceeds the company-wide allocation. The finance director rejects it with a note to reduce travel expenses by 15%. The budget returns to DRAFT, the submitter adjusts the travel line items, and resubmits for approval
+- **Funds Check Blocking an Overspend**: An employee submits a purchase order for office furniture. The funds check computes BudgetAvailability as `Budget - (Actual + Commitments + Encumbrances)` for the office supplies cost element in the current period. The available budget is insufficient after accounting for existing PO commitments, and the transaction is rejected with a budget exceeded error
+- **Commitment Tracking from Purchase Orders**: A department issues a PO for consulting services worth $50,000. The purchase module emits a commitment event, and accounting records a $50,000 commitment against the consulting cost element budget. When the first invoice for $20,000 is matched, the commitment reduces by $20,000 and actual increases by $20,000, keeping BudgetAvailability unchanged. When the PO is fully invoiced, the commitment reaches zero
+- **Mid-Year Budget Transfer**: A budget holder reallocates planned amounts between cost elements within the same budget (e.g., moving unused travel budget to training) by updating line items while the budget is ACTIVE, subject to approval controls
+- **Budget vs. Actual Variance Report**: At month-end, a controller compares budgeted amounts against actual postings from finance-ledger journal entries for each cost element and period. The comparison highlights a 20% overrun in consulting expenses, triggering a management review
+- **Period-End Budget Lock**: As the finance-ledger accounting period for January is closed, the corresponding budget period is locked, freezing planned amounts for January and preventing retroactive adjustments to the baseline
+- **Multi-Cost-Object Budgeting**: A company creates separate budgets for three profit centers within the same fiscal year, each with its own line items and approval chain, enabling decentralized budget ownership while maintaining company-level consolidation
+
+## Test Cases
+
+- Budget lifecycle follows DRAFT -> SUBMITTED -> APPROVED -> ACTIVE -> CLOSED state machine
+- Budget can only be created in DRAFT status
+- Budget requires a valid companyId; the company must be in ACTIVE status
+- Budget requires a valid fiscal year reference from finance-ledger
+- Budget requires a name, budget holder, and cost object reference (cost center, profit center, or internal order)
+- Budget must reference a valid PlanVersion (BUDGET, FORECAST, or SIMULATION)
+- A DRAFT budget can be updated (name, description, budget holder, line items)
+- A DRAFT budget can be deleted; deletion removes all associated line items
+- Submitting a budget transitions status from DRAFT to SUBMITTED
+- A budget with no line items cannot be submitted
+- Only a user different from the budget creator can approve the budget (segregation of duties)
+- Approving a budget transitions status from SUBMITTED to APPROVED
+- Rejecting a budget transitions status from SUBMITTED back to DRAFT
+- Rejection requires a reason text
+- Activating an APPROVED budget transitions status to ACTIVE and enables funds checking
+- Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year
+- Multiple FORECAST or SIMULATION versions can coexist for the same cost object and fiscal year
+- Closing an ACTIVE budget transitions status to CLOSED; no further modifications are permitted
+- A CLOSED budget cannot be reopened
+- BudgetLineItem requires a valid cost element reference; the cost element must be a PRIMARY type in ACTIVE status
+- BudgetLineItem derives its GL account automatically from the referenced primary cost element's GL account mapping; no separate GL account field is required
+- BudgetLineItem requires a valid accounting period reference from finance-ledger
+- BudgetLineItem planned amount must be a positive value
+- Line items can be added to or removed from a DRAFT budget
+- Line items cannot be added to or removed from a SUBMITTED, APPROVED, or CLOSED budget
+- Duplicate line items (same account and period) within a single budget are rejected
+- Funds check computes BudgetAvailability as `Budget - (Actual + Commitments + Encumbrances)` for the target cost element, period, and cost object
+- A transaction that exceeds BudgetAvailability is rejected with a budget exceeded error when budgetary control is active
+- A transaction against a cost element with no corresponding budget line item is flagged as unbudgeted
+- Commitment amounts are recorded when a purchase order confirmation event is received from the purchase module
+- Commitment amounts are reduced and actual amounts are increased when a goods receipt or invoice match event is received from the purchase module
+- Commitment amounts are fully released when a purchase order cancellation event is received from the purchase module
+- Encumbrances (purchase requisition amounts) are tracked as a future extension; the availability formula reserves the field but the initial implementation treats encumbrances as zero
+- Budget vs. actual comparison retrieves actual amounts from finance-ledger posted journal entries matching the budget's cost object, cost element, and period
+- Variance is computed as planned amount minus actual amount; positive variance indicates underspend, negative indicates overspend
+- Budget periods align with finance-ledger AccountingPeriod boundaries; misaligned periods are rejected
+- Locking a budget period prevents further modifications to planned amounts for that period
+- Budget lock integrates with finance-ledger period close; closing an accounting period triggers the corresponding budget period lock
+- PlanVersion of type FORECAST or SIMULATION can reference a base version from which line items are copied
+- Creating a budget emits an audit event recording the acting user, timestamp, and initial field values
+- Submitting, approving, rejecting, activating, and closing a budget each emit audit events recording the status transition and acting user
+- Budgets are scoped to a company; budgets from different companies are fully isolated
+- Only users with appropriate permissions can create, submit, approve, activate, or close budgets
+- Unauthorized users receive a permission denied error when attempting budget operations
+
+## Reference Links
+
+- [SAP S/4HANA Budget Management and Availability Control](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/4dbfa293944e410aa3ca0e0905bda494/d0b843994f0d1014a585e2078de58ced.html)
+- [Oracle Fusion Financials Budgetary Control](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/budgetary-control.html)
+- [Odoo Budget Management](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/budget.html)
+- [NetSuite Budgets Overview](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N2169498.html)
+- [Sage Intacct Budgeting and Planning](https://www.sage.com/en-us/sage-business-cloud/intacct/features/budgeting-and-planning/)

package/src/modules/accounting/docs/features/cost-allocation.md

@@ -0,0 +1,129 @@
+# Cost Allocation
+
+## Overview
+
+Cost Allocation is the process of distributing overhead costs from sender cost centers to receiver cost objects (cost centers, profit centers, or internal orders) using configurable allocation cycles and rules. The module supports two distinct allocation methods: assessment, which posts using secondary cost elements (aggregating the original cost elements into a single overhead category on the receiver), and distribution, which preserves the original primary cost elements on the receiver side for full cost transparency.
+
+An allocation cycle groups a set of allocation rules, each defining a sender cost center, one or more receiver cost objects, and the allocation basis (fixed percentage or amount-based factor). Cycles progress through a controlled lifecycle — DRAFT, VALIDATED, EXECUTED, POSTED, and optionally REVERSED — ensuring that allocations are reviewed and tested before they affect the general ledger. Execution first runs in test mode to preview results, then in actual mode to generate immutable allocation result records. Posting creates journal entries through the finance-ledger subledger integration pattern, and corrections are handled exclusively via reversal and re-posting, never by deletion.
+
+## Business Purpose
+
+Organizations need a structured cost allocation mechanism to accurately assign indirect and overhead costs to the business areas that consume them:
+
+- **Overhead cost distribution**: Shared service costs (IT, facilities, HR) must be allocated to the operating units that benefit from them, enabling accurate product and service costing
+- **Assessment vs distribution flexibility**: Assessment simplifies receiver-side reporting by consolidating costs under secondary cost elements, while distribution preserves original cost element detail for granular cost analysis — organizations choose based on their reporting requirements
+- **Allocation rule governance**: Configurable rules with percentage-based or factor-based allocation bases ensure that cost distribution reflects actual resource consumption or agreed-upon sharing ratios
+- **Percentage completeness validation**: Allocation rules for a given sender must have receiver percentages summing to exactly 100%, preventing under- or over-allocation of costs
+- **Test run capability**: Executing an allocation cycle in test mode allows controllers to review projected results before committing actual postings, reducing the risk of errors in the general ledger
+- **Immutable audit trail**: Allocation results are recorded as immutable records linking cycle, sender, receiver, allocated amount, and cost element, satisfying internal control and external audit requirements
+- **Correction via reversal**: Posted allocations cannot be modified or deleted — corrections require reversing the entire cycle and re-executing with corrected rules, preserving full traceability of all cost movements
+- **Period and company scoping**: Allocation cycles are scoped to a specific company and accounting period, ensuring that cost distributions align with the correct reporting boundaries
+- **Ledger integration**: Allocation postings flow through the finance-ledger journal entry system, maintaining consistency between the cost accounting subledger and the general ledger
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAllocationCycle
+    Draft --> Draft: updateAllocationCycle / addAllocationRule / removeAllocationRule
+    Draft --> Validated: validateAllocationCycle
+    Validated --> Draft: invalidateAllocationCycle
+    Validated --> Executed: executeAllocationCycle (ACTUAL)
+    Executed --> Posted: postAllocationCycle
+    Posted --> Reversed: reverseAllocationCycle
+```
+
+```mermaid
+flowchart TD
+    A[Define allocation cycle with type and period] --> B[Add allocation rules: sender, receivers, percentages]
+    B --> C{All sender rules sum to 100%?}
+    C -- No --> D[Adjust rule percentages]
+    D --> B
+    C -- Yes --> E[Validate allocation cycle]
+    E --> F[Execute in TEST_RUN mode]
+    F --> G{Review test results acceptable?}
+    G -- No --> H[Return to DRAFT and adjust rules]
+    H --> B
+    G -- Yes --> I[Execute in ACTUAL mode]
+    I --> J[Immutable AllocationResult records created]
+    J --> K[Post allocation cycle]
+    K --> L{Assessment or Distribution?}
+    L -- Assessment --> M[Create journal entries with secondary cost elements]
+    L -- Distribution --> N[Create journal entries preserving original cost elements]
+    M --> O[Journal entries posted via finance-ledger]
+    N --> O
+    O --> P[Allocation complete]
+```
+
+```mermaid
+flowchart TD
+    A[Select posted allocation cycle to reverse] --> B[Create reversal journal entries with inverted amounts]
+    B --> C{Reversal period OPEN or FUTURE_ENTERABLE?}
+    C -- No --> D[Select valid reversal period]
+    D --> C
+    C -- Yes --> E[Post reversal entries via finance-ledger]
+    E --> F[Allocation cycle status set to REVERSED]
+    F --> G[Original allocation amounts offset to zero]
+```
+
+## Scenario Patterns
+
+- **IT Department Overhead Assessment**: The IT cost center incurs infrastructure and support costs that serve multiple business units. An assessment cycle allocates these costs to the Sales, Manufacturing, and R&D cost centers using secondary cost element "IT Overhead Assessment" with fixed percentages (40%, 35%, 25%). Receivers see a single aggregated IT overhead line rather than individual cost element details
+- **Facilities Cost Distribution**: Building maintenance, utilities, and security costs from the Facilities cost center are distributed to three profit centers based on floor space ratios. Distribution method preserves the original cost elements (rent, electricity, cleaning) on the receiver side, enabling profit center managers to see the detailed breakdown of facility costs they are consuming
+- **Shared Services Assessment to Internal Orders**: A central HR shared services cost center allocates recruitment and training costs to project-based internal orders using assessment. Each internal order receives an overhead charge under a secondary cost element, enabling project managers to see the total loaded cost of their initiatives
+- **Multi-Receiver Percentage Allocation**: A logistics cost center distributes warehousing costs to five regional profit centers using percentages derived from order volume (30%, 25%, 20%, 15%, 10%). The controller validates that percentages total 100%, runs a test execution to verify amounts, and then executes and posts the actual allocation
+- **Test Run Review and Adjustment**: A cost controller sets up an allocation cycle for administrative overhead but notices during the test run that one receiver cost center has been decommissioned. The controller returns the cycle to DRAFT, updates the rules to redirect that portion to the successor cost center, re-validates, and executes again
+- **Allocation Reversal and Correction**: After posting a quarterly assessment cycle, a controller discovers that the allocation percentages were based on outdated headcount data. The controller reverses the posted cycle, creates a new cycle with corrected percentages, validates, executes, and posts the corrected allocation — both the original and corrected postings remain in the ledger for full auditability
+- **Period-End Overhead Allocation**: At month-end close, the accounting team executes multiple allocation cycles to distribute all overhead cost centers before generating management reports. Each cycle targets the current accounting period and is posted sequentially to ensure dependent allocations (e.g., secondary cost centers that received allocations themselves) are captured correctly
+
+## Test Cases
+
+- Allocation cycle lifecycle follows DRAFT -> VALIDATED -> EXECUTED -> POSTED state machine; posted cycles can transition to REVERSED
+- Allocation cycle can only be created in DRAFT status
+- Allocation cycle requires a valid type (ASSESSMENT or DISTRIBUTION)
+- Allocation cycle requires a valid name
+- Allocation cycle must reference a valid companyId; the company must be in ACTIVE status
+- Allocation cycle must reference a valid accounting period
+- Allocation rules can be added to or removed from a DRAFT allocation cycle
+- Allocation rules cannot be added to or removed from a VALIDATED, EXECUTED, POSTED, or REVERSED cycle
+- Each allocation rule must reference a valid sender cost center
+- Each allocation rule must reference a valid receiver cost object (cost center, profit center, or internal order)
+- A sender cost center cannot also appear as a receiver within the same allocation rule set
+- Allocation rule percentages for a given sender must sum to exactly 100%
+- Allocation rules with percentages not summing to 100% for any sender cause validation to fail
+- Allocation rule percentage values must be positive (greater than zero)
+- Validating a DRAFT cycle with valid rules transitions its status to VALIDATED
+- Validating a cycle with no allocation rules fails
+- A VALIDATED cycle can be returned to DRAFT for further editing
+- Executing an allocation cycle in TEST_RUN mode generates preview results without changing cycle status to EXECUTED
+- Executing an allocation cycle in ACTUAL mode transitions its status from VALIDATED to EXECUTED
+- Execution in ACTUAL mode creates immutable AllocationResult records for each sender-receiver-amount combination
+- AllocationResult records cannot be modified or deleted after creation
+- Each AllocationResult references the allocation cycle, sender, receiver, allocated amount, and cost element used
+- Executing a cycle that is not in VALIDATED status fails with an invalid status transition error
+- Posting an EXECUTED cycle creates journal entries through the finance-ledger subledger integration
+- Assessment-type allocation postings use secondary cost elements in the generated journal entries
+- Distribution-type allocation postings preserve the original primary cost elements in the generated journal entries
+- Posting transitions the cycle status from EXECUTED to POSTED
+- Posting a cycle that is not in EXECUTED status fails with an invalid status transition error
+- Journal entries created by posting reference the allocation cycle as the source document
+- Reversing a POSTED cycle creates reversal journal entries with inverted amounts
+- Reversal transitions the cycle status from POSTED to REVERSED
+- Reversing a cycle that is not in POSTED status fails with an invalid status transition error
+- Reversal journal entries must target a period that is in OPEN or FUTURE_ENTERABLE status
+- A REVERSED cycle cannot be reversed again
+- Allocation cycles are scoped to a company; cycles from different companies are fully isolated
+- Allocation cycles reference a specific accounting period; the period must be in OPEN or FUTURE_ENTERABLE status for posting
+- Posting an allocation cycle to a CLOSED or PERMANENTLY_CLOSED period is rejected
+- Updating allocation cycle fields (name, rules) is only permitted while the cycle is in DRAFT status
+- Deleting an allocation cycle is only permitted while in DRAFT status
+- Creating an allocation cycle emits an audit event recording the acting user, timestamp, and initial field values
+- Validating, executing, posting, and reversing an allocation cycle each emit audit events recording the status transition and acting user
+- Only users with appropriate permissions can create, validate, execute, post, or reverse allocation cycles
+
+## Reference Links
+
+- [SAP Cost Center Accounting: Assessment and Distribution](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/b867e2f9b57c4dc3b7ec7356aca3bb4e.html)
+- [SAP Allocation Cycles in Controlling](https://help.sap.com/docs/SAP_ERP/29e50beaa37a447f8e4c13b0c5a15f32/42a07c62b9f343e0e10000000a11466f.html)
+- [Oracle Fusion Cost Allocation Manager](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/cost-allocation.html)
+- [Odoo Analytic Accounting and Cost Distribution](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/analytic_accounting.html)

package/src/modules/accounting/docs/features/cost-center-management.md

@@ -0,0 +1,118 @@
+# cost-center-management
+
+## Overview
+
+Cost Center Management is the foundational feature of the accounting module, providing the ability to create, maintain, and hierarchically organize cost centers for overhead cost accumulation and management accounting reporting. A cost center represents a responsibility area within a company that accumulates costs — such as an IT department, a production floor, or a facilities group. Each cost center carries a code, name, description, category (e.g., overhead, production, administration, sales), responsible person, optional department reference, validity period (valid-from/to dates), and a position within a cost center hierarchy.
+
+Cost centers are distinct from organizational departments: a single cost center can span multiple departments, and a single department can map to multiple cost centers. This separation allows management accounting structures to evolve independently of the organizational chart. Cost centers are scoped to a Company (from the organization module) and serve as the primary receiver for overhead costs, acting as the foundational cost object referenced by cost allocation, budget management, variance analysis, and internal order settlement. A standard cost center hierarchy must be established before cost centers can be created, following the SAP CO pattern where a hierarchy root is a prerequisite for cost center master data.
+
+## Business Purpose
+
+Organizations need a structured cost center framework to track and control overhead costs for internal decision-making:
+
+- **Overhead cost accumulation**: Cost centers collect indirect costs (rent, utilities, salaries, depreciation) that cannot be directly assigned to products or services, providing visibility into where overhead costs originate
+- **Management responsibility assignment**: Each cost center has a designated responsible person, enabling accountability for cost control at the organizational unit level and supporting delegation of budgetary authority
+- **Hierarchical roll-up reporting**: Cost center hierarchies allow costs to be aggregated from leaf-level cost centers up through intermediate grouping nodes to the root, enabling management reporting at any level of granularity
+- **Foundation for cost allocation**: Cost centers serve as senders and receivers in cost allocation cycles (assessment and distribution), making them prerequisites for the cost-allocation feature
+- **Budget anchoring**: Budgets are created against cost centers and their associated cost elements, making cost center master data a prerequisite for the budget-management feature
+- **Variance analysis basis**: Plan-vs-actual comparisons are performed at the cost center level, requiring stable cost center definitions with clear validity periods
+- **Separation from organizational structure**: Decoupling cost centers from departments allows the management accounting structure to reflect cost responsibility boundaries rather than HR reporting lines, supporting matrix organizations and shared service models
+- **Temporal validity**: Valid-from and valid-to dates enable cost centers to be introduced for new organizational units or retired when restructuring occurs, without deleting historical cost data
+- **Category-based classification**: Cost center categories (overhead, production, administration, sales, research) enable filtering, default cost element assignment, and category-specific reporting across the management accounting module
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> HierarchyCreated: createCostCenterHierarchy
+    HierarchyCreated --> HierarchyActive: addRootNode
+    HierarchyActive --> HierarchyActive: addChildNode / removeNode / reorganizeNodes
+```
+
+```mermaid
+flowchart TD
+    A[Establish cost center hierarchy] --> B[Create hierarchy with name and version]
+    B --> C[Define root node]
+    C --> D[Add child nodes to build grouping structure]
+    D --> E{Hierarchy complete?}
+    E -- No --> D
+    E -- Yes --> F[Hierarchy ready for cost center assignment]
+```
+
+```mermaid
+flowchart TD
+    A[Create cost center master data] --> B[Assign code, name, category]
+    B --> C[Set responsible person and optional department reference]
+    C --> D[Define valid-from and valid-to dates]
+    D --> E[Assign to hierarchy node]
+    E --> F{Hierarchy node exists?}
+    F -- No --> G[Create or select hierarchy node]
+    G --> E
+    F -- Yes --> H[Cost center created and active]
+    H --> I[Available for cost postings, budgets, and allocations]
+```
+
+```mermaid
+flowchart TD
+    A[Update cost center] --> B{Change type?}
+    B -- Master data update --> C[Update name, description, category, responsible person]
+    C --> D[Audit trail records field changes]
+    B -- Hierarchy reassignment --> E[Move cost center to different hierarchy node]
+    E --> D
+    B -- Retirement --> F[Set valid-to date to end validity]
+    F --> G[Cost center excluded from future postings]
+    G --> D
+```
+
+## Scenario Patterns
+
+- **Initial Setup for New Company**: A newly onboarded company establishes its cost center hierarchy by creating a root node (e.g., "Company ABC Cost Centers"), adding intermediate grouping nodes for each functional area (Administration, Production, Sales, R&D), and then creating individual cost centers under each group. This hierarchy becomes the prerequisite for all subsequent budgeting and cost allocation activities
+- **Shared Service Center**: An IT department provides services to multiple business units. A single cost center "IT Services" is created under the overhead grouping node, accumulating all IT-related costs. This cost center later serves as the sender in cost allocation cycles that distribute IT costs to receiving cost centers based on headcount or usage metrics
+- **Production Floor Cost Tracking**: A manufacturing company creates cost centers for each production line (Line A, Line B, Line C) under a "Production" grouping node. Each cost center has the category "production" and a designated line supervisor as the responsible person. Overhead costs like machine depreciation and maintenance are accumulated per line for variance analysis against planned production costs
+- **Organizational Restructuring**: Following a merger, the company reorganizes its cost center hierarchy by moving several cost centers from one grouping node to another. Existing cost centers retain their historical cost data, while the hierarchy reflects the new organizational reality. Cost centers belonging to dissolved units have their valid-to dates set to the reorganization date
+- **Seasonal Operations**: A retail company creates a cost center for a seasonal pop-up store with a valid-from date of November 1 and valid-to date of January 31. The cost center accumulates costs only during the holiday season and is excluded from allocations and postings outside its validity window
+- **Cross-Department Responsibility**: A quality assurance function spans both the production and engineering departments. A single cost center "Quality Assurance" is created and assigned to a responsible person from the QA team, independent of department boundaries. This illustrates the separation between cost centers and organizational departments
+- **Multi-Version Hierarchy Planning**: The company maintains two hierarchy versions — "Current" reflecting the active cost center structure, and "Planned Q3" reflecting a proposed reorganization. The planned version allows management to model allocation impacts before committing to the restructuring
+
+## Test Cases
+
+- A cost center hierarchy must be created before any cost centers can be created within a company
+- A cost center hierarchy requires a name and version identifier
+- A cost center hierarchy is scoped to a company; hierarchies from different companies are fully isolated
+- A hierarchy root node must be established before child nodes can be added
+- Hierarchy nodes support parent-child relationships with a sort order and level attribute
+- A hierarchy node cannot be its own parent (no self-referencing)
+- A hierarchy node cannot create a circular reference (child cannot be an ancestor of its parent)
+- Deleting a hierarchy node that has child nodes or assigned cost centers is rejected
+- A cost center requires a unique code within the company scope
+- A cost center requires a name and a valid category
+- A cost center must reference a valid hierarchy node within the same company's hierarchy
+- A cost center must reference a valid companyId; the company must be in ACTIVE status
+- A cost center has a valid-from date that must be earlier than or equal to its valid-to date
+- A cost center with no valid-to date is treated as indefinitely active from its valid-from date
+- A cost center optionally references a responsible person (from user-management)
+- A cost center optionally references a department (from the organization module) for informational mapping
+- Creating a cost center emits an audit event recording the acting user, timestamp, and initial field values
+- Updating a cost center (name, description, category, responsible person, department, hierarchy node) emits an audit event recording previous and new field values
+- A cost center code cannot be changed after creation to preserve referential integrity across budgets, allocations, and postings
+- A cost center whose valid-to date has passed cannot receive new cost postings
+- A cost center whose valid-from date is in the future cannot receive cost postings until that date is reached
+- Moving a cost center to a different hierarchy node updates the hierarchy assignment and emits an audit event
+- A cost center can only be assigned to a hierarchy node within the same company's hierarchy
+- Multiple cost centers can be assigned to the same hierarchy node
+- Cost center categories must be from a defined set (e.g., overhead, production, administration, sales, research)
+- Changing a cost center's category is permitted and emits an audit event
+- A cost center cannot be deleted if it has associated cost postings, budget line items, or allocation rules referencing it
+- A cost center with no dependent records can be deleted; deletion emits an audit event
+- Hierarchy roll-up reporting aggregates costs from child nodes up through parent nodes to the root
+- A cost center hierarchy can have multiple versions within the same company
+- Only users with appropriate permissions (from user-management) can create, update, or delete cost centers and hierarchy nodes
+- Unauthorized users receive a permission denied error when attempting cost center operations
+
+## Reference Links
+
+- [SAP S/4HANA Cost Center Accounting](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/40ff4b3e8d2c4a2b8b3af8a4aa862a5e/65b18f9c49cc1014e10000000a174cb4.html)
+- [SAP Cost Center Standard Hierarchy](https://help.sap.com/docs/SAP_S4HANA_CLOUD/21c2b8c1e03d4e6eba4d34de9eccf41d/65b18f9c49cc1014e10000000a174cb4.html)
+- [Oracle Fusion Cost Center Segment](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/cost-centers.html)
+- [Odoo Analytic Accounting (Cost Center Equivalent)](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/analytic_accounting.html)
+- [SAP CO Cost Center Planning](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/40ff4b3e8d2c4a2b8b3af8a4aa862a5e/65b18f9c49cc1014e10000000a174cb4.html)

package/src/modules/accounting/docs/features/cost-element-management.md

@@ -0,0 +1,114 @@
+# Cost Element Management
+
+## Overview
+
+Cost Element Management provides the foundational classification layer for management accounting within the accounting module. Cost elements define the types of costs that can be recorded, allocated, and analyzed across cost centers, profit centers, and internal orders. The module distinguishes two fundamental categories: primary cost elements, which are mapped one-to-one to GL accounts from coa-management and represent costs that appear in both financial and management accounting (e.g., material costs, labor costs, depreciation), and secondary cost elements, which exist exclusively within the controlling domain and are used solely for internal cost allocation activities such as assessment, distribution, and settlement.
+
+Every cost posting or allocation in the accounting module requires a valid cost element, making this feature a prerequisite for all downstream management accounting processes. Primary cost elements bridge financial accounting and controlling by linking each cost type to its corresponding GL account, ensuring consistency between the general ledger and cost reports. Secondary cost elements enable internal cost flows that have no counterpart in financial reporting, allowing organizations to model overhead distribution, activity-based costing, and inter-departmental service charges. Cost elements are scoped to a Company and carry validity periods to support time-dependent cost classifications.
+
+## Business Purpose
+
+Organizations need a structured cost element catalog to classify and control cost flows in management accounting:
+
+- **Cost type classification**: Cost elements categorize expenditures into meaningful types (overhead, material, labor, depreciation for primary; assessment, distribution, internal activity allocation, settlement for secondary), enabling consistent cost reporting and analysis across the organization
+- **Bridge between financial and management accounting**: Primary cost elements maintain a mandatory one-to-one mapping to GL accounts from coa-management, ensuring that every cost recorded in the general ledger can be consumed by controlling processes without discrepancy
+- **Internal allocation enablement**: Secondary cost elements provide cost types that exist only within controlling, allowing organizations to model internal cost flows (e.g., IT department charging other departments for services) without polluting financial statements
+- **Prerequisite for cost postings**: No cost can be posted to a cost center, profit center, or internal order without a valid cost element. This gating mechanism enforces a complete and auditable cost classification before any transaction occurs
+- **Time-dependent validity**: Valid-from and valid-to dates on cost elements allow organizations to phase in new cost types or retire obsolete ones without deleting historical data, supporting period-accurate cost reporting
+- **Company-scoped isolation**: Cost elements are defined per company, ensuring that each legal entity maintains its own cost classification structure aligned with its chart of accounts and management reporting requirements
+- **Regulatory and ERP alignment**: The primary/secondary distinction mirrors the cost element model used by SAP, Oracle, and other major ERP systems, facilitating migration, integration, and compliance with established management accounting practices
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createCostElement
+    Draft --> Draft: updateCostElement
+    Draft --> Active: activateCostElement
+    Active --> Inactive: deactivateCostElement
+    Inactive --> Active: reactivateCostElement
+    Draft --> [*]: deleteCostElement
+```
+
+```mermaid
+flowchart TD
+    A[Identify cost type to classify] --> B{Primary or Secondary?}
+    B -- Primary --> C[Select GL account from coa-management]
+    C --> D[Create primary cost element with GL account reference]
+    B -- Secondary --> E[Create secondary cost element without GL account]
+    D --> F[Set category, validity period, and description]
+    E --> F
+    F --> G[Activate cost element]
+    G --> H[Cost element available for cost postings and allocations]
+```
+
+```mermaid
+flowchart TD
+    A[Cost posting or allocation initiated] --> B{Cost element specified?}
+    B -- No --> C[Reject: cost element required]
+    B -- Yes --> D{Cost element active and within validity period?}
+    D -- No --> E[Reject: invalid or expired cost element]
+    D -- Yes --> F{Primary cost element?}
+    F -- Yes --> G{Referenced GL account active in active CoA?}
+    G -- No --> H[Reject: GL account invalid]
+    G -- Yes --> I[Accept cost posting]
+    F -- No --> J{Used in allocation context only?}
+    J -- No --> K[Reject: secondary elements for internal allocation only]
+    J -- Yes --> I
+```
+
+## Scenario Patterns
+
+- **Overhead Cost Element Setup**: A controller creates a primary cost element for "Office Rent" mapped to the corresponding rent expense GL account. The element is categorized as an overhead cost, given a validity period spanning the fiscal year, and activated. All rent postings to cost centers now reference this cost element for consistent overhead reporting
+- **Material Cost Classification**: During initial system setup, the accounting team creates primary cost elements for each material cost category (raw materials, packaging, consumables), each mapped to its respective GL account from the chart of accounts. These elements enable material cost tracking across cost centers and internal orders
+- **Labor Cost Tracking**: Primary cost elements are created for different labor cost types (salaries, wages, overtime, benefits), each referencing the appropriate payroll expense GL account. Cost center managers can then analyze labor costs by type within their responsibility areas
+- **Depreciation Cost Element**: A primary cost element for asset depreciation is created and mapped to the depreciation expense GL account. This enables depreciation charges calculated by the asset module to flow into cost center reports as a distinct cost type
+- **Assessment Cycle Preparation**: A controller creates a secondary cost element of category "assessment" to be used in the monthly overhead assessment cycle. This element does not reference any GL account and will only appear in cost center reports when the assessment allocation distributes shared service costs
+- **Internal Activity Allocation**: A secondary cost element of category "internal activity allocation" is created for IT services. When the IT cost center allocates its costs to receiving cost centers based on service hours, this secondary element classifies the allocated amounts, keeping them separate from primary cost postings
+- **Settlement to Profitability**: A secondary cost element of category "settlement" is created to settle accumulated costs from an internal order to a profit center. The settlement posting uses this element to classify the cost transfer, which remains invisible in financial accounting
+- **Cost Element Retirement**: At the end of a fiscal year, a controller deactivates a cost element that is no longer relevant due to organizational restructuring. Existing historical postings referencing this element remain intact, but no new postings can use it
+- **Cross-Company Cost Element Alignment**: Two subsidiaries each maintain their own cost element catalogs. Although the element codes and categories may align for consolidated reporting, each company's primary cost elements reference GL accounts from their respective charts of accounts
+
+## Test Cases
+
+- Cost element can be created in DRAFT status with a unique code within the company scope
+- Cost element requires a valid companyId; the company must be in ACTIVE status
+- Cost element code must be unique within the same company
+- Cost element requires a name and a type (PRIMARY or SECONDARY)
+- Cost element requires a category appropriate to its type (overhead, material, labor, depreciation for PRIMARY; assessment, distribution, internal_activity_allocation, settlement for SECONDARY)
+- Primary cost element must reference a valid GL account from an ACTIVE Chart of Accounts
+- Primary cost element GL account reference must point to an active GL account
+- Primary cost element creation fails if the GL account reference is missing
+- Primary cost element creation fails if the referenced GL account does not exist or is inactive
+- Secondary cost element must not reference a GL account; providing a GL account reference for a secondary element is rejected
+- Cost element valid-from date must be before or equal to valid-to date
+- Cost element valid-from and valid-to dates are optional; omitting them means the element is valid indefinitely
+- Cost element description is optional and can be updated while in DRAFT or ACTIVE status
+- Activating a DRAFT cost element transitions its status to ACTIVE
+- Activating an already ACTIVE cost element fails with an invalid status transition error
+- Deactivating an ACTIVE cost element transitions its status to INACTIVE
+- Reactivating an INACTIVE cost element transitions its status back to ACTIVE
+- Only DRAFT cost elements can be deleted; ACTIVE and INACTIVE elements cannot be deleted
+- Deleting a DRAFT cost element removes it and emits an audit event
+- Cost postings referencing a cost element that is INACTIVE or outside its validity period are rejected
+- Cost postings referencing a cost element that is ACTIVE and within its validity period are accepted
+- A primary cost element cannot be assigned a secondary category (assessment, distribution, internal_activity_allocation, settlement)
+- A secondary cost element cannot be assigned a primary category (overhead, material, labor, depreciation)
+- Changing the type of a cost element (PRIMARY to SECONDARY or vice versa) after activation is not permitted
+- Changing the GL account reference of a primary cost element after activation is not permitted
+- Secondary cost elements can only be used in internal allocation contexts (assessment, distribution, activity allocation, settlement)
+- Attempting to use a secondary cost element for a direct cost posting (non-allocation) is rejected
+- Cost elements are scoped to a company; elements from different companies are fully isolated
+- A primary cost element's GL account must belong to the same company's chart of accounts
+- Two primary cost elements within the same company cannot reference the same GL account
+- Updating the category of an ACTIVE cost element is not permitted
+- Cost element creation emits an audit event recording the acting user, timestamp, and initial field values
+- Cost element activation emits an audit event recording the status transition and acting user
+- Cost element deactivation emits an audit event recording the status transition and acting user
+
+## Reference Links
+
+- [SAP Cost Element Accounting](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4cae4c5eecaa7286e10000000a42189b.html)
+- [SAP Primary and Secondary Cost Elements](https://help.sap.com/docs/SAP_ERP/ba879a6e2ea04d9bb94c7ccd7cdac446/89d8463bf4f84033e10000000a174cb4.html)
+- [Oracle Cost Management Overview](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/cost-management.html)
+- [Controlling with Cost Elements in SAP S/4HANA](https://community.sap.com/topics/s4hana/cost-elements)