@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/accounting/docs/features/internal-order-management.md

@@ -0,0 +1,111 @@
+# Internal Order Management
+
+## Overview
+
+Internal Order Management provides the ability to create and manage internal orders that serve as temporary cost collectors for tracking expenses associated with specific short-to-medium-term activities such as projects, marketing campaigns, R&D initiatives, and corporate events. Unlike cost centers, which are permanent organizational units for ongoing cost accumulation, internal orders are purpose-bound objects with a defined lifecycle that begins at creation and ends at closure once costs have been fully reviewed.
+
+Each internal order carries a unique order number, an order type (OVERHEAD, INVESTMENT, or ACCRUAL), a description, responsible person, validity dates, and a reference to the responsible cost center within the company. Internal orders follow a four-stage lifecycle: CREATED, RELEASED, TECHNICALLY_COMPLETED, and CLOSED. Cost postings are only permitted while the order is in RELEASED status. Orders may optionally have a budget assigned to control spending limits. Settlement of internal order costs to receivers (such as cost centers, fixed assets, or other orders) is out of scope for this feature and will be addressed in a dedicated settlement feature.
+
+## Business Purpose
+
+Organizations need internal orders to isolate and monitor costs for discrete activities that cut across the permanent cost center structure:
+
+- **Activity-based cost tracking**: Internal orders allow organizations to accumulate costs for specific initiatives (e.g., a trade show, an IT migration project, or a product launch campaign) independently of the department-level cost center hierarchy, providing precise visibility into activity-level spending
+- **Order type classification**: Categorizing orders as OVERHEAD, INVESTMENT, or ACCRUAL mirrors SAP's internal order type model and enables differentiated handling — overhead orders track general expenses, investment orders capitalize costs into fixed assets, and accrual orders manage periodic cost deferrals
+- **Lifecycle gating**: The four-stage lifecycle (CREATED -> RELEASED -> TECHNICALLY_COMPLETED -> CLOSED) ensures that cost postings are only accepted during the appropriate window, preventing premature charges to orders still in setup and accidental postings to orders under final review or already archived
+- **Budget control**: Optional budget assignment to internal orders enables organizations to set spending limits for activities and monitor actual costs against planned budgets, supporting proactive cost governance
+- **Responsible cost center linkage**: Each internal order references a responsible cost center, establishing organizational accountability and ensuring that activity costs can be traced back to the department or unit that owns the initiative
+- **Temporal scoping**: Validity dates (valid-from and valid-to) define the time window during which the order is relevant, supporting planning and ensuring that postings outside the validity period are flagged or rejected
+- **Company-scoped isolation**: Internal orders are scoped to a company, ensuring that cost data for different legal entities remains fully separated
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Created: createInternalOrder
+    Created --> Released: releaseInternalOrder
+    Released --> TechnicallyCompleted: technicallyCompleteInternalOrder
+    TechnicallyCompleted --> Closed: closeInternalOrder
+    Created --> [*]: deleteInternalOrder
+```
+
+```mermaid
+flowchart TD
+    A[Identify activity requiring cost tracking] --> B[Create internal order with type, description, responsible person, and cost center]
+    B --> C{Assign budget?}
+    C -- Yes --> D[Link budget to internal order]
+    C -- No --> E[Internal order in CREATED status]
+    D --> E
+    E --> F[Release internal order]
+    F --> G[Costs posted against the order during activity execution]
+    G --> H{Activity complete?}
+    H -- No --> G
+    H -- Yes --> I[Technically complete the order]
+    I --> J[Final review of accumulated costs]
+    J --> K[Close the order]
+    K --> L[Order archived — no further changes]
+```
+
+```mermaid
+flowchart TD
+    A[Cost posting request targets internal order] --> B{Order status is RELEASED?}
+    B -- No --> C[Reject posting — order not in RELEASED status]
+    B -- Yes --> D{Posting date within validity period?}
+    D -- No --> E[Reject posting — outside validity window]
+    D -- Yes --> F{Budget assigned?}
+    F -- Yes --> G{Posting within budget limit?}
+    G -- No --> H[Reject or warn — budget exceeded]
+    G -- Yes --> I[Accept cost posting]
+    F -- No --> I
+```
+
+## Scenario Patterns
+
+- **Marketing Campaign Tracking**: The marketing department creates an OVERHEAD internal order to track all costs for a product launch campaign — agency fees, print materials, event venue, and travel. The order is released when planning is finalized, costs are posted throughout the campaign period, and the order is technically completed and closed once all invoices are settled and reviewed
+- **Capital Investment Project**: An INVESTMENT internal order is created for a facility renovation project. Costs for construction, equipment, and consulting are accumulated on the order. Upon project completion, the order is technically completed and the accumulated costs are reviewed before closure (settlement to a fixed asset would occur in a future settlement feature)
+- **R&D Initiative**: An R&D team creates an OVERHEAD internal order with a budget to track development costs for a prototype. The budget cap ensures the team stays within the approved spending limit. When the prototype phase ends, the order is technically completed and costs are reviewed against the budget before closure
+- **Corporate Event**: An internal order is created for an annual company conference. Costs for venue rental, catering, speakers, and logistics are posted during the event planning and execution phases. After the event, the order is technically completed, final costs are reconciled, and the order is closed
+- **Accrual Order for Periodic Costs**: An ACCRUAL internal order is created to manage deferred cost recognition for an annual software license paid upfront. The order tracks the periodic accrual postings over the license term
+- **Order Deletion Before Release**: A planned initiative is cancelled before any costs are incurred. The internal order, still in CREATED status, is deleted rather than progressed through the full lifecycle
+- **Budget Overrun Prevention**: A project manager attempts to post costs to an internal order that would exceed the assigned budget. The system rejects the posting, prompting the manager to request a budget increase or reallocate costs to a different order
+
+## Test Cases
+
+- Internal order lifecycle follows CREATED -> RELEASED -> TECHNICALLY_COMPLETED -> CLOSED state machine
+- Internal order can only be created in CREATED status
+- Internal order requires a valid order type (OVERHEAD, INVESTMENT, ACCRUAL)
+- Internal order requires a unique order number within the company scope
+- Internal order requires a description
+- Internal order requires a responsible person
+- Internal order must reference a valid companyId; the company must be in ACTIVE status
+- Internal order must reference a valid responsible cost center within the same company
+- Internal order validity dates (valid-from, valid-to) are optional; when both are provided, valid-from must precede valid-to
+- Budget assignment to an internal order is optional
+- When a budget is assigned, the budget entity must exist and belong to the same company
+- Releasing an internal order transitions its status from CREATED to RELEASED
+- Only CREATED orders can be released; releasing a RELEASED, TECHNICALLY_COMPLETED, or CLOSED order fails with an invalid status transition error
+- Cost postings are only accepted when the internal order is in RELEASED status
+- Cost postings to an order in CREATED, TECHNICALLY_COMPLETED, or CLOSED status are rejected
+- Technically completing an internal order transitions its status from RELEASED to TECHNICALLY_COMPLETED
+- Only RELEASED orders can be technically completed; technically completing a CREATED or CLOSED order fails with an invalid status transition error
+- Closing an internal order transitions its status from TECHNICALLY_COMPLETED to CLOSED
+- Only TECHNICALLY_COMPLETED orders can be closed; closing a CREATED or RELEASED order fails with an invalid status transition error
+- CLOSED orders cannot transition to any other status
+- Internal orders in CREATED status can be deleted
+- Internal orders in RELEASED, TECHNICALLY_COMPLETED, or CLOSED status cannot be deleted
+- Internal order fields (description, responsible person, cost center, validity dates) can be updated while the order is in CREATED or RELEASED status
+- Internal order fields cannot be updated when the order is in TECHNICALLY_COMPLETED or CLOSED status
+- Order type cannot be changed after the order is released
+- Cost postings to an internal order with a budget must not exceed the assigned budget amount
+- Cost postings that would exceed the budget are rejected with a budget exceeded error
+- Internal orders are scoped to a company; orders from different companies are fully isolated
+- Cost postings with a date outside the order's validity period (before valid-from or after valid-to) are rejected when validity dates are set
+- Deleting an internal order in CREATED status removes the order and any associated budget assignment
+- Creating an internal order without a responsible cost center reference fails validation
+
+## Reference Links
+
+- [SAP S/4HANA Internal Orders](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/7ce4944ab36c11d3b44c006094b9ea64.html)
+- [SAP Internal Order Types and Usage](https://help.sap.com/docs/SAP_ERP/3bbd1036dae74238a8e3aab669e0ea3f/2ad1e0af437411d189740000e8323492.html)
+- [Oracle Fusion Project Costing — Cost Collection](https://docs.oracle.com/en/cloud/saas/project-management/24d/oapjm/cost-collection.html)
+- [Odoo Analytic Accounts for Cost Tracking](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/analytic_accounting.html)

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

@@ -0,0 +1,120 @@
+# Profit Center Management
+
+## Overview
+
+Profit Center Management provides the ability to create, maintain, and organize profit centers for internal profit and loss reporting within the accounting module. A profit center represents a discrete business segment — such as a product line, regional division, or service line — for which management can independently evaluate profitability. Each profit center carries a code, name, description, responsible person, validity period (valid-from/to), and an assignment to a profit center hierarchy node. Profit centers are scoped to a Company and follow a lifecycle from DRAFT through ACTIVE to INACTIVE.
+
+Revenue and cost transactions posted in the finance-ledger are tagged with profit center assignments, enabling aggregation of income and expenses at the profit center level. Profit centers are organized into hierarchical groupings (ProfitCenterHierarchy) that form a tree structure, allowing roll-up reporting by business dimension such as region, product line, or service line. This hierarchical structure supports management analyses including return on investment (ROI), economic value added (EVA), and operating profit per segment. Profit centers are distinct from organizational units (sites, departments) managed by the organization module, but may optionally reference them for cross-dimensional reporting.
+
+## Business Purpose
+
+Organizations need profit centers to measure and manage the profitability of individual business segments independently:
+
+- **Segment profitability analysis**: Profit centers enable management to evaluate revenue, costs, and profit/loss for each business segment, supporting informed strategic decisions about resource allocation and investment priorities
+- **Hierarchical roll-up reporting**: The tree-structured profit center hierarchy allows aggregation of results from leaf-level profit centers up through intermediate grouping nodes to the enterprise level, supporting multi-dimensional analysis by region, product line, or service line
+- **Internal P&L and balance sheet**: Profit centers serve as the primary dimension for generating internal profit and loss statements and, where applicable, segment balance sheets — going beyond cost center reporting which tracks only the expense side
+- **ROI and EVA analysis**: By capturing both revenue and cost flows, profit centers provide the data foundation for return on investment, economic value added, and operating margin calculations at the segment level
+- **Responsibility accounting**: Each profit center is assigned a responsible person, establishing clear accountability for the financial performance of that business segment
+- **Validity period control**: Valid-from and valid-to dates ensure that profit centers are only available for transaction assignment during their intended operational period, preventing postings to retired or not-yet-active segments
+- **Separation from organizational structure**: Profit centers are deliberately decoupled from the organizational hierarchy (sites, departments) to allow flexible, cross-cutting profitability views that do not depend on the legal or administrative structure
+- **Transaction tagging for aggregation**: Revenue and cost transactions are tagged with profit center assignments at posting time, enabling automated aggregation without requiring separate ledger entries per segment
+- **Cross-module ownership**: The organization and coa-management modules explicitly defer profit center ownership to the accounting module, establishing a single authoritative source for profit center master data
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createProfitCenter
+    Draft --> Draft: updateProfitCenter
+    Draft --> Active: activateProfitCenter
+    Active --> Active: updateProfitCenter (limited fields)
+    Active --> Inactive: deactivateProfitCenter
+    Inactive --> Active: reactivateProfitCenter
+    Draft --> [*]: deleteProfitCenter
+```
+
+```mermaid
+flowchart TD
+    A[Identify business segment requiring profitability tracking] --> B[Create ProfitCenter in DRAFT status]
+    B --> C[Set code, name, description, responsible person, validity period]
+    C --> D{Profit center hierarchy exists?}
+    D -- No --> E[Create ProfitCenterHierarchy with root node]
+    E --> F[Add grouping nodes for business dimensions]
+    D -- Yes --> F
+    F --> G[Assign profit center to hierarchy node]
+    G --> H[Activate profit center]
+    H --> I[Profit center available for transaction tagging]
+    I --> J[Revenue and cost postings tagged with profit center]
+    J --> K[Aggregate P&L by profit center and hierarchy roll-up]
+```
+
+```mermaid
+flowchart TD
+    A[Define profit center hierarchy structure] --> B[Create hierarchy with root node]
+    B --> C[Add intermediate grouping nodes by dimension]
+    C --> D[Assign profit centers as leaf nodes]
+    D --> E{All segments covered?}
+    E -- No --> C
+    E -- Yes --> F[Hierarchy ready for roll-up reporting]
+    F --> G[Generate segment P&L at any hierarchy level]
+    G --> H[Drill down from group totals to individual profit centers]
+```
+
+## Scenario Patterns
+
+- **Regional Profit Center Setup**: A multinational company creates profit centers for each geographic region (North America, EMEA, APAC) and organizes them under a region-based hierarchy. Revenue and cost transactions are tagged with the appropriate regional profit center, enabling management to compare profitability across regions and identify underperforming markets
+- **Product Line Profitability**: A manufacturing company creates profit centers for each product line (Consumer Electronics, Industrial Equipment, Spare Parts) under a product-based hierarchy. Sales revenue and production costs are assigned to the corresponding profit center, allowing product managers to track gross margins and operating profit per product line
+- **Service Line Segmentation**: A professional services firm creates profit centers for each service offering (Consulting, Implementation, Managed Services) to separately measure revenue realization, utilization rates, and profitability. The hierarchy groups these under a single services division for consolidated reporting
+- **Dual-Hierarchy Analysis**: A company maintains two profit center hierarchies — one by region and one by product line — to enable matrix reporting. The same set of profit centers can be analyzed along either dimension, supporting both geographic and product-oriented management views
+- **Profit Center Retirement**: A business segment is discontinued. The responsible controller deactivates the profit center after the final posting period, ensuring no new transactions can be assigned to it while historical data remains available for comparative reporting
+- **Cross-Departmental Profit Center**: A profit center spans multiple organizational departments (e.g., a product line served by both engineering and sales teams). Because profit centers are independent of the organizational hierarchy, revenue from sales and costs from engineering are both captured under the same profit center for unified profitability measurement
+- **New Venture Tracking**: A company launches a new business initiative and creates a profit center in DRAFT status with a future valid-from date. Once the launch date arrives, the profit center is activated and begins receiving transaction assignments, allowing management to track the venture's financial performance from day one
+- **Responsible Person Change**: The manager responsible for a profit center changes due to organizational restructuring. The responsible person field is updated on the active profit center, and the change is recorded in the audit trail for accountability tracking
+
+## Test Cases
+
+- Profit center lifecycle follows DRAFT -> ACTIVE -> INACTIVE state machine; inactive profit centers can be reactivated to ACTIVE
+- Profit center can only be created in DRAFT status
+- Profit center requires a unique code within the company scope
+- Profit center requires a name
+- Profit center must reference a valid companyId; the company must be in ACTIVE status
+- Profit center description is optional and can be updated in DRAFT or ACTIVE status
+- Profit center responsible person is optional and can be updated in DRAFT or ACTIVE status
+- Valid-from date is required; valid-to date is optional
+- Valid-to date, when specified, must be on or after the valid-from date
+- Activating a DRAFT profit center transitions its status to ACTIVE
+- Activating an already ACTIVE profit center fails with an invalid status transition error
+- Deactivating an ACTIVE profit center transitions its status to INACTIVE
+- Deactivating a DRAFT profit center fails with an invalid status transition error
+- Reactivating an INACTIVE profit center transitions its status to ACTIVE
+- DRAFT profit centers can be deleted; deletion removes the profit center and its hierarchy assignment
+- ACTIVE profit centers cannot be deleted; they must be deactivated first
+- INACTIVE profit centers cannot be deleted
+- Profit center code cannot be changed after activation
+- Only ACTIVE profit centers within their validity period can receive transaction assignments
+- Transactions cannot be assigned to a DRAFT profit center
+- Transactions cannot be assigned to an INACTIVE profit center
+- Transactions cannot be assigned to a profit center outside its validity period (before valid-from or after valid-to)
+- A profit center hierarchy can be created with a root node and a descriptive name
+- Hierarchy nodes can be added as children of existing nodes, forming a tree structure
+- A profit center can be assigned to exactly one node within a given hierarchy
+- A profit center can be assigned to nodes in multiple hierarchies simultaneously
+- Removing a hierarchy node that has child nodes is rejected; children must be reassigned or removed first
+- Removing a hierarchy node that has profit centers assigned is rejected; profit centers must be reassigned first
+- Hierarchy roll-up aggregates financial results from child nodes up to parent nodes
+- Profit centers are scoped to a company; profit centers from different companies are fully isolated
+- Profit center hierarchies are scoped to a company
+- Creating a profit center emits an audit event recording the acting user, timestamp, and initial field values
+- Updating a profit center emits an audit event recording previous and new field values
+- Activating or deactivating a profit center emits an audit event recording the status transition and acting user
+- Assigning or reassigning a profit center to a hierarchy node emits an audit event
+- Profit centers are independent of organizational units (sites, departments) but may optionally reference an organizational unit
+- Only users with appropriate permissions can create, activate, deactivate, or update profit centers
+
+## Reference Links
+
+- [SAP Profit Center Accounting](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/4cae5a88ecaa7286e10000000a42189b.html)
+- [SAP Profit Center Master Data](https://help.sap.com/docs/SAP_S4HANA_CLOUD/59463d9fe28a4e5f8b38557e1e2bafbb/577ab0e06d6d1014b3fc9283b0e91070.html)
+- [Oracle Fusion Profit Center Reporting](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/segment-reporting.html)
+- [Odoo Analytic Accounting for Profit Centers](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/analytic_accounting.html)
+- [NetSuite Department and Class Segmentation](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3444641.html)

package/src/modules/accounting/docs/features/variance-analysis.md

@@ -0,0 +1,130 @@
+# Variance Analysis
+
+## Overview
+
+Variance Analysis is the management accounting capability of the accounting module that compares planned (budget) amounts against actual costs and revenues by cost object and accounting period. A VarianceReport entity captures the cost object reference (cost center, profit center, or internal order), the accounting period, report status (DRAFT or FINAL), and summary totals (total planned, total actual, total variance). Each VarianceReport contains one or more VarianceReportLine child records, each keyed by cost element and accounting period, that capture the planned amount, actual amount, computed variance amount, variance percentage, and variance direction (FAVORABLE or UNFAVORABLE). This cost-element-level detail enables managers to diagnose which cost types are driving deviations rather than only seeing aggregate totals. Actual amounts are sourced from posted journal entries in the finance-ledger module, aggregated by cost element, period, and cost object. Planned amounts are sourced from BudgetLineItems in the budget-management module, which use cost elements as their planning axis.
+
+The feature follows a five-step workflow: collect actuals from posted journal entries, collect plan amounts from budget line items, calculate variance per cost element as the difference between actual and planned, categorize the variance direction based on account type, and generate a management report with detail lines. Variance reports are scoped to a Company and reference a specific AccountingPeriod. Reports can be generated at the individual cost object level or aggregated up cost center and profit center hierarchies. Variance analysis typically runs as a period-end process after all postings for the period are complete. Detailed variance categorization (input price, input quantity, volume, mix) and manufacturing-specific variances (price, usage, efficiency) are out of scope for this feature.
+
+## Business Purpose
+
+Organizations need systematic variance analysis to monitor financial performance against plans and enable timely corrective action:
+
+- **Budget adherence monitoring**: Comparing actual costs and revenues against budgeted amounts by cost object reveals where spending is on track and where deviations require management attention
+- **Favorable/unfavorable categorization**: Automatically classifying variances as favorable (actual costs below plan, or actual revenue above plan) or unfavorable (the inverse) provides immediate directional context for decision-makers without manual interpretation
+- **Cost element detail**: VarianceReportLine records break down variances by cost element (salaries, travel, materials, etc.) within each cost object, enabling managers to identify exactly which cost type is driving deviations rather than only seeing an aggregate total — this is essential for actionable root-cause analysis
+- **Cost object granularity**: Generating variance reports per cost center, profit center, or internal order allows managers to pinpoint exactly which organizational unit or project is driving deviations from plan
+- **Hierarchy aggregation**: Rolling up variances along cost center and profit center hierarchies enables both detailed drill-down analysis and executive-level summary reporting in a single feature
+- **Period-end management reporting**: Running variance analysis after all period postings are complete produces accurate, comprehensive reports that inform budget revisions, resource reallocation, and strategic decisions for subsequent periods
+- **Variance quantification**: Calculating both absolute variance amounts and variance percentages allows managers to assess deviations in context — a large absolute variance on a small budget line signals a different issue than the same amount on a large budget line
+- **Draft-to-final lifecycle**: The DRAFT to FINAL status progression allows controllers to review and validate variance reports before distributing them to management, preventing premature or incorrect reporting
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> CollectActuals: initiateVarianceAnalysis
+    CollectActuals --> CollectPlan: actuals aggregated
+    CollectPlan --> CalculateVariance: plan amounts retrieved
+    CalculateVariance --> Categorize: variance computed
+    Categorize --> GenerateReport: direction assigned
+    GenerateReport --> [*]: VarianceReport created (DRAFT)
+```
+
+```mermaid
+flowchart TD
+    A[Period-end: all postings complete] --> B[Collect actual amounts from posted journal entries]
+    B --> C[Aggregate actuals by cost element + cost object + period]
+    C --> D[Collect planned amounts from budget-management BudgetLineItems by cost element]
+    D --> E[Match actuals to plan by cost element, cost object, and period]
+    E --> F[Calculate variance per cost element: Actual - Planned]
+    F --> G{Account type?}
+    G -- Cost/Expense --> H{Actual < Planned?}
+    H -- Yes --> I[FAVORABLE]
+    H -- No --> J[UNFAVORABLE]
+    G -- Revenue --> K{Actual > Planned?}
+    K -- Yes --> L[FAVORABLE]
+    K -- No --> M[UNFAVORABLE]
+    I --> N[Compute variance percentage]
+    J --> N
+    L --> N
+    M --> N
+    N --> O[Create VarianceReportLine per cost element]
+    O --> O2[Create VarianceReport in DRAFT with summary totals and detail lines]
+    O2 --> P{Review and validate}
+    P -- Approved --> Q[Finalize report: status FINAL]
+    P -- Issues found --> R[Investigate and correct source data]
+    R --> A
+```
+
+```mermaid
+flowchart TD
+    A[Select reporting scope] --> B{Report level?}
+    B -- Individual cost object --> C[Generate report for single cost center / profit center / internal order]
+    B -- Hierarchy --> D[Retrieve child cost objects from hierarchy]
+    D --> E[Generate individual reports per child]
+    E --> F[Aggregate variances up hierarchy levels]
+    F --> G[Produce consolidated hierarchy report]
+    C --> H[VarianceReport ready for review]
+    G --> H
+```
+
+## Scenario Patterns
+
+- **Monthly cost center review**: At month-end close, the controller initiates variance analysis for all cost centers within a company for the current accounting period. The system collects posted journal entry totals by cost center, retrieves corresponding budget line items, computes variances, and generates DRAFT variance reports. The controller reviews and finalizes each report before distributing to cost center managers
+- **Profit center profitability check**: A division head requests a variance report for their profit center to compare actual revenue and costs against the annual plan. The report's detail lines show revenue above plan (FAVORABLE) but the material cost element significantly above plan (UNFAVORABLE), enabling the manager to pinpoint supplier pricing changes as the root cause without needing a separate drill-down report
+- **Internal order cost overrun detection**: A project manager reviews the variance report for an internal order representing a capital project. The report reveals actual spending at 120% of the planned amount with two periods remaining, triggering a budget revision request and scope review
+- **Hierarchy roll-up for executive reporting**: The CFO requests a consolidated variance report across all profit centers. The system generates individual profit center variance reports and then aggregates them up the profit center hierarchy, producing a company-level summary showing total planned vs. actual with net variance amounts and percentages
+- **Cross-period trend analysis**: A controller generates variance reports for the same cost center across multiple consecutive periods to identify whether an unfavorable variance is a one-time event or a recurring trend, informing whether a structural budget adjustment is needed
+- **Revenue variance investigation**: A sales manager receives a variance report showing actual revenue below plan (UNFAVORABLE) for their profit center. The variance percentage of -15% triggers a review of sales pipeline and customer order patterns to understand the shortfall
+- **Period-end sequential processing**: The accounting team completes all journal entry postings and subledger reconciliations for the period, then runs variance analysis as the final step before period close. This sequence ensures variance reports reflect the complete and accurate financial picture for the period
+
+## Test Cases
+
+- Variance report can only be created for a valid Company that is in ACTIVE status
+- Variance report must reference a valid AccountingPeriod
+- Variance report must reference a valid cost object (cost center, profit center, or internal order)
+- Variance report is created in DRAFT status
+- Variance report can transition from DRAFT to FINAL
+- Variance report in FINAL status cannot be transitioned back to DRAFT
+- A VarianceReport contains one or more VarianceReportLine child records, each keyed by cost element and accounting period
+- Each VarianceReportLine records: cost element reference, accounting period, planned amount, actual amount, variance amount, variance percentage, and variance direction
+- VarianceReport summary totals (total planned, total actual, total variance) are computed from the sum of its detail lines
+- Variance amount on each VarianceReportLine is calculated as actual amount minus planned amount
+- Variance percentage on each VarianceReportLine is calculated as (actual - planned) / planned * 100
+- When planned amount is zero and actual amount is non-zero on a detail line, variance percentage is handled gracefully (not division by zero)
+- For cost/expense cost elements, variance direction is FAVORABLE when actual amount is less than planned amount
+- For cost/expense cost elements, variance direction is UNFAVORABLE when actual amount is greater than planned amount
+- For revenue cost elements, variance direction is FAVORABLE when actual amount is greater than planned amount
+- For revenue cost elements, variance direction is UNFAVORABLE when actual amount is less than planned amount
+- When actual equals planned on a detail line, variance amount is zero and variance direction is FAVORABLE
+- Actual amounts are sourced exclusively from POSTED journal entries in the finance-ledger module
+- DRAFT journal entries are excluded from actual amount aggregation
+- Actual amounts are aggregated by cost element, cost object, and accounting period
+- Planned amounts are sourced from BudgetLineItems in the budget-management module, matched by cost element
+- A variance report cannot be generated if no budget line items exist for the specified cost object and period
+- A VarianceReportLine is created for each cost element that has either a planned amount or an actual amount (or both)
+- A cost element with actual postings but no corresponding budget line item generates a detail line with zero planned amount
+- Variance reports for cost centers aggregate all journal lines assigned to that cost center in the given period, grouped by cost element
+- Variance reports for profit centers aggregate all journal lines assigned to that profit center in the given period, grouped by cost element
+- Variance reports for internal orders aggregate all journal lines assigned to that internal order in the given period, grouped by cost element
+- Hierarchy aggregation for cost centers sums child cost center variances into the parent cost center report
+- Hierarchy aggregation for profit centers sums child profit center variances into the parent profit center report
+- Hierarchy-aggregated reports include both the individual child variances and the consolidated parent totals
+- A DRAFT variance report can be updated (e.g., to correct a cost object reference) before finalization
+- A FINAL variance report cannot be modified
+- Generating a variance report for a period with no posted journal entries results in zero actual amounts
+- Variance reports are scoped to a single company; data from other companies is excluded
+- Multiple variance reports can exist for the same cost object across different accounting periods
+- Regenerating a variance report for the same cost object and period replaces the existing DRAFT report
+- A FINAL variance report is not overwritten by regeneration; a new DRAFT is created alongside it if source data changes
+- Variance report includes both the absolute variance amount and the variance percentage
+- Variance report records the variance direction as either FAVORABLE or UNFAVORABLE
+
+## Reference Links
+
+- [SAP S/4HANA Variance Analysis in Controlling](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/ee3509643e954b3da2e0ebfa846c02e1/b33fa239f4d446e9a6c8a585c4e148c8.html)
+- [Oracle Fusion Budgetary Control and Variance Reporting](https://docs.oracle.com/en/cloud/saas/financials/24d/oafcf/budgetary-control.html)
+- [Odoo Budget Management and Analysis](https://www.odoo.com/documentation/19.0/applications/finance/accounting/reporting/budget.html)
+- [NetSuite Budget vs. Actual Reporting](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1584498.html)
+- [CIMA Management Accounting Variance Analysis](https://www.cimaglobal.com/resources/)

package/src/modules/accounting/docs/models/AllocationCycle.md

@@ -0,0 +1,81 @@
+# AllocationCycle
+
+## Description
+
+AllocationCycle is the controlling entity that groups a set of allocation rules for distributing overhead costs from sender cost centers to receiver cost objects (cost centers, profit centers, or internal orders). Each cycle carries a name, allocation type (ASSESSMENT or DISTRIBUTION), company scope, accounting period reference, and a status. Assessment-type allocations post using secondary cost elements, aggregating original cost elements into a single overhead category on the receiver. Distribution-type allocations preserve the original primary cost elements on the receiver side for full cost transparency. Allocation cycles progress through a controlled lifecycle — DRAFT, VALIDATED, EXECUTED, POSTED, and optionally REVERSED — ensuring allocations are reviewed and tested before affecting the general ledger.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createAllocationCycle
+    Draft --> Draft: updateAllocationCycle / createAllocationRule / deleteAllocationRule
+    Draft --> Validated: validateAllocationCycle
+    Validated --> Draft: invalidateAllocationCycle
+    Validated --> Executed: executeAllocationCycle (ACTUAL)
+    Executed --> Posted: postAllocationCycle
+    Posted --> Reversed: reverseAllocationCycle
+    Draft --> [*]: deleteAllocationCycle
+```
+
+### Command Definitions
+
+- [createAllocationCycle](../commands/CreateAllocationCycle.md) - Create a new allocation cycle in DRAFT status with type, name, company, and accounting period
+- [updateAllocationCycle](../commands/UpdateAllocationCycle.md) - Update mutable fields of a DRAFT allocation cycle (name)
+- [validateAllocationCycle](../commands/ValidateAllocationCycle.md) - Validate a DRAFT cycle, verifying all rules have percentages summing to 100% per sender
+- [invalidateAllocationCycle](../commands/InvalidateAllocationCycle.md) - Return a VALIDATED cycle to DRAFT for further editing
+- [executeAllocationCycle](../commands/ExecuteAllocationCycle.md) - Execute a VALIDATED cycle in ACTUAL mode, creating immutable allocation result records
+- [postAllocationCycle](../commands/PostAllocationCycle.md) - Post an EXECUTED cycle, creating journal entries through finance-ledger subledger integration
+- [reverseAllocationCycle](../commands/ReverseAllocationCycle.md) - Reverse a POSTED cycle by creating reversal journal entries with inverted amounts
+- [deleteAllocationCycle](../commands/DeleteAllocationCycle.md) - Delete a DRAFT allocation cycle and its associated rules
+- [createAllocationRule](../commands/CreateAllocationRule.md) - Add an allocation rule to a DRAFT cycle defining sender, receiver, and percentage
+- [deleteAllocationRule](../commands/DeleteAllocationRule.md) - Remove an allocation rule from a DRAFT cycle
+
+### Query Definitions
+
+- [GetAllocationCycle](../queries/GetAllocationCycle.md) - Retrieve an allocation cycle by id with its rules and results
+- [ListAllocationCycles](../queries/ListAllocationCycles.md) - List allocation cycles with filters (type, status, company, period)
+
+### Models
+
+- AllocationCycle
+- AllocationRule
+- AllocationResult
+
+### Invariants
+
+- 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 only be added to or removed from a DRAFT cycle
+- Allocation rule percentages for a given sender must sum to exactly 100%
+- Allocation rule percentage values must be positive (greater than zero)
+- A sender cost center cannot also appear as a receiver within the same allocation rule set
+- Validating a cycle with no allocation rules fails
+- A VALIDATED cycle can be returned to DRAFT for further editing
+- Executing a cycle that is not in VALIDATED status fails
+- Execution in ACTUAL mode creates immutable AllocationResult records
+- Posting transitions the cycle from EXECUTED to POSTED, creating journal entries
+- 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 an allocation cycle to a CLOSED or PERMANENTLY_CLOSED period is rejected
+- Reversing a POSTED cycle creates reversal journal entries with inverted amounts
+- A REVERSED cycle cannot be reversed again
+- Updating allocation cycle fields is only permitted while in DRAFT status
+- Deleting an allocation cycle is only permitted while in DRAFT status
+- Allocation cycles are scoped to a company; cycles from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each allocation cycle is scoped to a Company via companyId (organization module)
+- **References AccountingPeriod**: Each allocation cycle references an AccountingPeriod via accountingPeriodId (finance-ledger module)
+- **Has Many AllocationRule**: An allocation cycle contains one or more allocation rules defining sender-receiver-percentage mappings
+- **Has Many AllocationResult**: An executed allocation cycle produces immutable allocation result records

package/src/modules/accounting/docs/models/AllocationResult.md

@@ -0,0 +1,37 @@
+# AllocationResult
+
+## Description
+
+AllocationResult is an immutable record produced when an allocation cycle is executed in ACTUAL mode, capturing the outcome of a single sender-receiver cost distribution. Each result carries an allocation cycle reference, sender cost center reference, receiver type, receiver id, allocated amount, and cost element reference. Allocation results serve as the authoritative audit trail for cost allocations, linking the cycle, sender, receiver, allocated amount, and cost element used. Once created, allocation result records cannot be modified or deleted — corrections are handled exclusively through cycle reversal and re-execution.
+
+## Domain Model Definitions
+
+### Model type
+
+AppendOnly
+
+### Command Definitions
+
+- [executeAllocationCycle](../commands/ExecuteAllocationCycle.md) - Allocation results are created as part of executing an allocation cycle in ACTUAL mode
+
+### Query Definitions
+
+- [GetAllocationCycle](../queries/GetAllocationCycle.md) - Retrieve allocation results as part of the parent allocation cycle
+
+### Models
+
+- AllocationResult
+
+### Invariants
+
+- Allocation results are created exclusively during allocation cycle execution in ACTUAL mode
+- Allocation results cannot be modified or deleted after creation
+- Each allocation result references the allocation cycle, sender, receiver, allocated amount, and cost element used
+- Allocation results serve as the immutable audit trail for cost allocations
+
+### Relationships
+
+- **Belongs to AllocationCycle**: Each allocation result belongs to an AllocationCycle via allocationCycleId
+- **References CostCenter (sender)**: Each allocation result references a sender CostCenter via senderCostCenterId
+- **Polymorphic Receiver**: Each allocation result references a receiver via receiverType and receiverId, which can be a CostCenter, ProfitCenter, or InternalOrder
+- **References CostElement**: Each allocation result references a CostElement via costElementId

package/src/modules/accounting/docs/models/AllocationRule.md

@@ -0,0 +1,41 @@
+# AllocationRule
+
+## Description
+
+AllocationRule defines a single sender-receiver-percentage mapping within an allocation cycle, specifying which cost center sends costs, which cost object receives them, and the allocation percentage. Each rule carries an allocation cycle reference, sender cost center reference, receiver type, receiver id, and percentage. Receivers can be cost centers, profit centers, or internal orders (polymorphic reference). Multiple rules within a cycle define how a sender's costs are split across multiple receivers, with the constraint that percentages for a given sender must sum to exactly 100%.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createAllocationRule](../commands/CreateAllocationRule.md) - Add an allocation rule to a DRAFT allocation cycle
+- [deleteAllocationRule](../commands/DeleteAllocationRule.md) - Remove an allocation rule from a DRAFT allocation cycle
+
+### Query Definitions
+
+- [GetAllocationCycle](../queries/GetAllocationCycle.md) - Retrieve allocation rules as part of the parent allocation cycle
+
+### Models
+
+- AllocationRule
+
+### Invariants
+
+- Allocation rule must reference a valid allocation cycle via allocationCycleId
+- Allocation rule can only be added to or removed from a DRAFT allocation cycle
+- Allocation rule must reference a valid sender cost center
+- 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 percentage must be a positive value (greater than zero)
+- Allocation rule percentages for a given sender must sum to exactly 100% across all rules in the cycle
+- Allocation rules cannot be modified after the cycle leaves DRAFT status
+
+### Relationships
+
+- **Belongs to AllocationCycle**: Each allocation rule belongs to an AllocationCycle via allocationCycleId
+- **References CostCenter (sender)**: Each allocation rule references a sender CostCenter via senderCostCenterId
+- **Polymorphic Receiver**: Each allocation rule references a receiver via receiverType and receiverId, which can be a CostCenter, ProfitCenter, or InternalOrder

package/src/modules/accounting/docs/models/Budget.md

@@ -0,0 +1,77 @@
+# Budget
+
+## Description
+
+Budget is the financial planning entity 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. Each budget carries a name, optional description, budget holder, fiscal year reference, company scope, cost object type and id (polymorphic reference to cost center, profit center, or internal order), plan version reference, total amount, and status. Budgets follow a five-stage lifecycle — DRAFT, SUBMITTED, APPROVED, ACTIVE, CLOSED — enforcing segregation of duties between budget creation, approval, and cost posting. When active, budgets enable budgetary control (funds check) that validates transactions against available budget using the formula: Available = Budget - (Actual + Commitments + Encumbrances).
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createBudget
+    Draft --> Draft: updateBudget / createBudgetLineItem / deleteBudgetLineItem
+    Draft --> Submitted: submitBudget
+    Submitted --> Approved: approveBudget
+    Submitted --> Draft: rejectBudget
+    Approved --> Active: activateBudget
+    Active --> Closed: closeBudget
+    Draft --> [*]: deleteBudget
+```
+
+### Command Definitions
+
+- [createBudget](../commands/CreateBudget.md) - Create a new budget in DRAFT status with name, budget holder, fiscal year, cost object, and plan version
+- [updateBudget](../commands/UpdateBudget.md) - Update mutable fields of a DRAFT budget (name, description, budget holder)
+- [submitBudget](../commands/SubmitBudget.md) - Submit a DRAFT budget for approval review
+- [approveBudget](../commands/ApproveBudget.md) - Approve a SUBMITTED budget, advancing it toward activation
+- [rejectBudget](../commands/RejectBudget.md) - Reject a SUBMITTED budget back to DRAFT with a rejection reason
+- [activateBudget](../commands/ActivateBudget.md) - Activate an APPROVED budget, enabling budgetary control (funds check)
+- [closeBudget](../commands/CloseBudget.md) - Close an ACTIVE budget, preventing further modifications
+- [deleteBudget](../commands/DeleteBudget.md) - Delete a DRAFT budget and all associated line items
+- [createBudgetLineItem](../commands/CreateBudgetLineItem.md) - Add a budget line item to a DRAFT budget specifying cost element, period, and planned amount
+- [deleteBudgetLineItem](../commands/DeleteBudgetLineItem.md) - Remove a budget line item from a DRAFT budget
+
+### Query Definitions
+
+- [GetBudget](../queries/GetBudget.md) - Retrieve a budget by id with all line items
+- [ListBudgets](../queries/ListBudgets.md) - List budgets with filters (status, company, fiscal year, cost object)
+- [CalculateBudgetAvailability](../queries/CalculateBudgetAvailability.md) - Compute budget availability as Budget - (Actual + Commitments + Encumbrances) for a cost element, period, and cost object
+
+### Models
+
+- Budget
+- BudgetLineItem
+
+### Invariants
+
+- 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 budget with no line items cannot be submitted
+- Only a user different from the budget creator can approve the budget (segregation of duties)
+- Rejection requires a reason text
+- 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
+- Line items can only be added to or removed from a DRAFT budget
+- A CLOSED budget cannot be reopened; no further modifications are permitted
+- 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
+- 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
+- Budgets are scoped to a company; budgets from different companies are fully isolated
+
+### Relationships
+
+- **References Company**: Each budget is scoped to a Company via companyId (organization module)
+- **References FiscalYear**: Each budget references a FiscalYear via fiscalYearId (finance-ledger module)
+- **References PlanVersion**: Each budget references a PlanVersion via planVersionId
+- **Polymorphic Cost Object**: Each budget references a cost object via costObjectType and costObjectId, which can be a CostCenter, ProfitCenter, or InternalOrder
+- **Has Many BudgetLineItem**: A budget contains one or more budget line items specifying planned amounts per cost element and period