@tailor-platform/erp-kit 0.7.0 → 0.9.0

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)

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)