@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/accounting/docs/commands/CreateAllocationCycle.md

@@ -0,0 +1,55 @@
+# CreateAllocationCycle
+
+## Overview
+
+createAllocationCycle establishes a new allocation cycle in DRAFT status. An allocation cycle groups a set of allocation rules that define how overhead costs are distributed from sender cost centers to receiver cost objects. It requires a name, allocation type (ASSESSMENT or DISTRIBUTION), a company reference, and an accounting period reference.
+
+## Business Rules
+
+- Allocation cycle is always created in DRAFT status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a valid `name`
+- Requires a valid `type` of either ASSESSMENT or DISTRIBUTION
+- Requires a valid `accountingPeriodId` referencing an existing accounting period from finance-ledger
+- Allocation cycles are scoped to a company; cycles from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create allocation cycle request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Valid allocation type?}
+    D -->|No| E[Return error: INVALID_ALLOCATION_TYPE]
+    D -->|Yes| F{Accounting period exists?}
+    F -->|No| G[Return error: ACCOUNTING_PERIOD_NOT_FOUND]
+    F -->|Yes| H{Name provided?}
+    H -->|No| I[Return error: INVALID_NAME]
+    H -->|Yes| J[Create allocation cycle in DRAFT status]
+    J --> K[Emit audit event]
+    K --> L[Return created allocation cycle]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the referenced accounting period exists
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **INVALID_ALLOCATION_TYPE**: Type is not ASSESSMENT or DISTRIBUTION
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_NAME**: Name is missing or empty
+
+## Test Cases
+
+- creates allocation cycle in DRAFT status with required fields
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when allocation type is invalid
+- returns error when accounting period does not exist
+- returns error when name is missing
+- allocation cycles from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

package/src/modules/accounting/docs/commands/CreateAllocationRule.md

@@ -0,0 +1,60 @@
+# CreateAllocationRule
+
+## Overview
+
+createAllocationRule adds an allocation rule to a DRAFT allocation cycle. Each rule defines a sender cost center, one or more receiver cost objects (cost center, profit center, or internal order), and the allocation percentage for each receiver. The sender cannot also appear as a receiver within the same rule. Percentage values must be positive.
+
+## Business Rules
+
+- Allocation cycle must exist and be in DRAFT status
+- Rules cannot be added to cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status
+- Requires a valid sender cost center reference
+- Requires one or more valid receiver cost objects (cost center, profit center, or internal order)
+- Sender cost center cannot also be a receiver within the same rule set
+- Percentage values for each receiver must be positive (greater than zero)
+- Emits an audit event recording the rule creation and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create allocation rule request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Sender cost center valid?}
+    F -->|No| G[Return error: SENDER_NOT_FOUND]
+    F -->|Yes| H{All receivers valid?}
+    H -->|No| I[Return error: RECEIVER_NOT_FOUND]
+    H -->|Yes| J{Sender appears as receiver?}
+    J -->|Yes| K[Return error: SENDER_IS_RECEIVER]
+    J -->|No| L{All percentages positive?}
+    L -->|No| M[Return error: INVALID_PERCENTAGE]
+    L -->|Yes| N[Create allocation rule]
+    N --> O[Emit audit event]
+    O --> P[Return created allocation rule]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
+- **INVALID_STATE**: Allocation cycle is not in DRAFT status
+- **SENDER_NOT_FOUND**: Referenced sender cost center does not exist
+- **RECEIVER_NOT_FOUND**: One or more referenced receiver cost objects do not exist
+- **SENDER_IS_RECEIVER**: Sender cost center appears as a receiver in the same rule
+- **INVALID_PERCENTAGE**: One or more percentage values are not positive
+
+## Test Cases
+
+- adds an allocation rule to a DRAFT allocation cycle
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in DRAFT status
+- returns error when sender cost center does not exist
+- returns error when a receiver cost object does not exist
+- returns error when sender appears as a receiver
+- returns error when percentage value is zero or negative
+- emits audit event recording the rule creation and acting user

package/src/modules/accounting/docs/commands/CreateBudget.md

@@ -0,0 +1,65 @@
+# CreateBudget
+
+## Overview
+
+createBudget establishes a new budget in DRAFT status. A budget is a financial plan that allocates planned amounts to cost elements across accounting periods for a specific cost object. It requires a name, budget holder, fiscal year reference, company reference, cost object type and ID, and a plan version reference.
+
+## Business Rules
+
+- Budget is always created in DRAFT status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a `name`
+- Requires a `budgetHolderId`
+- Requires a valid `fiscalYearId` referencing an existing fiscal year from finance-ledger
+- Requires a `costObjectType` and `costObjectId` referencing a valid cost object (cost center, profit center, or internal order)
+- Requires a valid `planVersionId` referencing an existing plan version
+- Budgets are scoped to a company; budgets from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create budget request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Fiscal year exists?}
+    D -->|No| E[Return error: FISCAL_YEAR_NOT_FOUND]
+    D -->|Yes| F{Cost object exists?}
+    F -->|No| G[Return error: COST_OBJECT_NOT_FOUND]
+    F -->|Yes| H{Plan version exists?}
+    H -->|No| I[Return error: PLAN_VERSION_NOT_FOUND]
+    H -->|Yes| J{Name provided?}
+    J -->|No| K[Return error: INVALID_NAME]
+    J -->|Yes| L{Budget holder provided?}
+    L -->|No| M[Return error: BUDGET_HOLDER_REQUIRED]
+    L -->|Yes| N[Create budget in DRAFT status]
+    N --> O[Emit audit event]
+    O --> P[Return created budget]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+- [finance-ledger::getFiscalYear](../../../finance-ledger/docs/queries/GetFiscalYear.md) — Validates that the referenced fiscal year exists
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **FISCAL_YEAR_NOT_FOUND**: Referenced fiscal year does not exist
+- **COST_OBJECT_NOT_FOUND**: Referenced cost object (cost center, profit center, or internal order) does not exist
+- **PLAN_VERSION_NOT_FOUND**: Referenced plan version does not exist
+- **INVALID_NAME**: Name is missing or empty
+- **BUDGET_HOLDER_REQUIRED**: Budget holder reference is missing
+
+## Test Cases
+
+- creates budget in DRAFT status with required fields
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when fiscal year does not exist
+- returns error when cost object does not exist
+- returns error when plan version does not exist
+- returns error when name is missing
+- returns error when budget holder is missing
+- budgets from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

package/src/modules/accounting/docs/commands/CreateBudgetLineItem.md

@@ -0,0 +1,66 @@
+# CreateBudgetLineItem
+
+## Overview
+
+createBudgetLineItem adds a line item to a DRAFT budget. Each line item specifies a cost element, an accounting period, and a planned amount. The GL account is derived automatically from the primary cost element's GL account mapping. Duplicate line items (same cost element and period) within a single budget are rejected.
+
+## Business Rules
+
+- Budget must exist and be in DRAFT status
+- Line items cannot be added to budgets in SUBMITTED, APPROVED, ACTIVE, or CLOSED status
+- Requires a valid `costElementId` referencing a PRIMARY cost element in ACTIVE status
+- Requires a valid `accountingPeriodId` referencing an existing accounting period from finance-ledger
+- Requires a `plannedAmount` that is a positive value
+- GL account is derived automatically from the referenced primary cost element's GL account mapping
+- Duplicate line items (same cost element and same period) within the same budget are rejected
+- Emits an audit event recording the line item creation and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create budget line item request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Cost element exists, is PRIMARY, and ACTIVE?}
+    F -->|No| G[Return error: INVALID_COST_ELEMENT]
+    F -->|Yes| H{Accounting period exists?}
+    H -->|No| I[Return error: ACCOUNTING_PERIOD_NOT_FOUND]
+    H -->|Yes| J{Planned amount is positive?}
+    J -->|No| K[Return error: INVALID_PLANNED_AMOUNT]
+    J -->|Yes| L{Duplicate line item exists?}
+    L -->|Yes| M[Return error: DUPLICATE_LINE_ITEM]
+    L -->|No| N[Derive GL account from cost element]
+    N --> O[Create budget line item]
+    O --> P[Emit audit event]
+    P --> Q[Return created line item]
+```
+
+## External Dependencies
+
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the referenced accounting period exists
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in DRAFT status
+- **INVALID_COST_ELEMENT**: Referenced cost element does not exist, is not PRIMARY type, or is not in ACTIVE status
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Referenced accounting period does not exist
+- **INVALID_PLANNED_AMOUNT**: Planned amount is not a positive value
+- **DUPLICATE_LINE_ITEM**: A line item with the same cost element and period already exists in this budget
+
+## Test Cases
+
+- adds a line item to a DRAFT budget with valid cost element, period, and amount
+- derives GL account automatically from the primary cost element
+- returns error when budget does not exist
+- returns error when budget is not in DRAFT status
+- returns error when cost element does not exist
+- returns error when cost element is not PRIMARY type
+- returns error when cost element is not in ACTIVE status
+- returns error when accounting period does not exist
+- returns error when planned amount is zero
+- returns error when planned amount is negative
+- returns error when duplicate line item exists (same cost element and period)
+- emits audit event recording the line item creation and acting user

package/src/modules/accounting/docs/commands/CreateCostCenter.md

@@ -0,0 +1,64 @@
+# CreateCostCenter
+
+## Overview
+
+createCostCenter establishes a new cost center within a company. A cost center is a responsibility area that accumulates overhead costs for management accounting reporting. It requires a unique code within the company, a name, a category, a reference to a hierarchy node within the same company, and a valid-from date. Cost centers serve as the primary receiver for overhead costs and are foundational cost objects for allocation, budgeting, and variance analysis.
+
+## Business Rules
+
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a `code` that is unique within the company scope
+- Requires a `name`
+- Requires a `category` from a defined set: overhead, production, administration, sales, or research
+- Requires a `hierarchyNodeId` referencing an existing node within the same company's cost center hierarchy
+- A cost center hierarchy must exist before cost centers can be created
+- Requires a `validFrom` date
+- `validTo` is optional; when provided, it must be on or after the `validFrom` date
+- `responsiblePersonId` is optional
+- `departmentId` is optional (informational mapping to the organization module)
+- Cost centers are scoped to a company; cost centers from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create cost center request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Code unique within company?}
+    D -->|No| E[Return error: DUPLICATE_COST_CENTER_CODE]
+    D -->|Yes| F{Valid category?}
+    F -->|No| G[Return error: INVALID_CATEGORY]
+    F -->|Yes| H{Hierarchy node exists in same company?}
+    H -->|No| I[Return error: HIERARCHY_NODE_NOT_FOUND]
+    H -->|Yes| J{validTo >= validFrom when both set?}
+    J -->|No| K[Return error: INVALID_VALIDITY_PERIOD]
+    J -->|Yes| L[Create cost center]
+    L --> M[Emit audit event]
+    M --> N[Return created cost center]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **DUPLICATE_COST_CENTER_CODE**: A cost center with the same code already exists within the company
+- **INVALID_CATEGORY**: Category is not one of the recognized values (overhead, production, administration, sales, research)
+- **HIERARCHY_NODE_NOT_FOUND**: Referenced hierarchy node does not exist or does not belong to the same company
+- **INVALID_VALIDITY_PERIOD**: validTo is before validFrom
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when name is empty
+- returns error when code already exists within company
+- returns error when category is invalid
+- returns error when hierarchy node does not exist
+- returns error when hierarchy node belongs to different company
+- returns error when validTo is before validFrom
+- creates cost center with valid inputs
+- creates cost center without optional fields

package/src/modules/accounting/docs/commands/CreateCostCenterHierarchy.md

@@ -0,0 +1,45 @@
+# CreateCostCenterHierarchy
+
+## Overview
+
+createCostCenterHierarchy establishes a new cost center hierarchy within a company. The hierarchy provides the tree structure required for organizing cost centers into grouping nodes for hierarchical roll-up reporting. A hierarchy carries a name, version identifier, and company reference. Hierarchies are scoped to a company and must be established before cost centers can be created.
+
+## Business Rules
+
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a `name` for the hierarchy
+- Requires a `version` identifier
+- Hierarchy is scoped to a company; hierarchies from different companies are fully isolated
+- A company can have multiple hierarchy versions
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create cost center hierarchy request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Name provided?}
+    D -->|No| E[Return error: INVALID_NAME]
+    D -->|Yes| F[Create cost center hierarchy]
+    F --> G[Emit audit event]
+    G --> H[Return created hierarchy]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **INVALID_NAME**: Hierarchy name is missing or empty
+
+## Test Cases
+
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when name is empty
+- returns error when name is whitespace only
+- creates hierarchy with valid inputs
+- emits audit event by calling insert

package/src/modules/accounting/docs/commands/CreateCostCenterHierarchyNode.md

@@ -0,0 +1,61 @@
+# CreateCostCenterHierarchyNode
+
+## Overview
+
+createCostCenterHierarchyNode adds a new node to an existing cost center hierarchy. Nodes form a tree structure with parent-child relationships, supporting hierarchical roll-up reporting. A root node must be created before child nodes can be added. Nodes carry a name, sort order, and level attribute within the hierarchy.
+
+## Business Rules
+
+- Hierarchy must exist
+- Parent node must exist when creating a child node (except for root node creation)
+- A root node must be established before child nodes can be added
+- A node cannot reference itself as its parent (no self-referencing)
+- Creating a node must not introduce a circular reference in the hierarchy
+- Node carries a name, sort order, and level attribute
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create hierarchy node request] --> B{Hierarchy exists?}
+    B -->|No| C[Return error: HIERARCHY_NOT_FOUND]
+    B -->|Yes| D{Is root node creation?}
+    D -->|Yes| E{Root node already exists?}
+    E -->|Yes| F[Return error: DUPLICATE_ROOT_NODE]
+    E -->|No| G[Create root node]
+    D -->|No| H{Parent node exists?}
+    H -->|No| I[Return error: PARENT_NODE_NOT_FOUND]
+    H -->|Yes| J{Self-referencing?}
+    J -->|Yes| K[Return error: SELF_REFERENCE]
+    J -->|No| L{Circular reference?}
+    L -->|Yes| M[Return error: CIRCULAR_REFERENCE]
+    L -->|No| N[Create child node under parent]
+    G --> O[Emit audit event]
+    N --> O
+    O --> P[Return created node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **HIERARCHY_NOT_FOUND**: Referenced hierarchy does not exist
+- **PARENT_NODE_NOT_FOUND**: Referenced parent node does not exist within the hierarchy
+- **DUPLICATE_ROOT_NODE**: A root node already exists in this hierarchy
+- **SELF_REFERENCE**: Node cannot reference itself as its parent
+- **CIRCULAR_REFERENCE**: Creating this node would introduce a circular reference in the hierarchy
+
+## Test Cases
+
+- returns error when name is empty
+- returns error when hierarchy does not exist
+- returns error when parent node does not exist in hierarchy
+- returns error when creating duplicate root node (no parentNodeId)
+- creates root node when no root exists
+- creates child node with correct computed level
+- returns error when node references itself as parent
+- returns error when node would create a circular reference
+- emits audit event by calling insert

package/src/modules/accounting/docs/commands/CreateCostElement.md

@@ -0,0 +1,91 @@
+# CreateCostElement
+
+## Overview
+
+createCostElement establishes a new cost element in DRAFT status within the management accounting module. The cost element carries a company reference, a unique code within the company scope, a name, a type (PRIMARY or SECONDARY), a category that must match the type, an optional GL account reference (required for PRIMARY, forbidden for SECONDARY), optional validity dates (validFrom, validTo), and an optional description. Cost elements are the foundational classification for all cost postings and allocations in the accounting module.
+
+## Business Rules
+
+- Cost element is always created in DRAFT status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a `code` that is unique within the company scope
+- Requires a `name`
+- Requires a `type` of either PRIMARY or SECONDARY
+- Requires a `category` appropriate to its type: overhead, material, labor, or depreciation for PRIMARY; assessment, distribution, internal_activity_allocation, or settlement for SECONDARY
+- PRIMARY cost elements must provide a `glAccountId` referencing an active GL account from an active Chart of Accounts
+- SECONDARY cost elements must not provide a `glAccountId`; supplying one is rejected
+- Two PRIMARY cost elements within the same company cannot reference the same GL account
+- When both `validFrom` and `validTo` are provided, `validFrom` must be less than or equal to `validTo`
+- `validFrom` and `validTo` are optional; omitting them means the element is valid indefinitely
+- `description` is optional and can be set on creation
+- Cost elements are scoped to a company; elements from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create cost element request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Code unique within company?}
+    D -->|No| E[Return error: DUPLICATE_COST_ELEMENT_CODE]
+    D -->|Yes| F{Valid type: PRIMARY or SECONDARY?}
+    F -->|No| G[Return error: INVALID_COST_ELEMENT_TYPE]
+    F -->|Yes| H{Category matches type?}
+    H -->|No| I[Return error: INVALID_CATEGORY_FOR_TYPE]
+    H -->|Yes| J{Type is PRIMARY?}
+    J -->|Yes| K{glAccountId provided?}
+    K -->|No| L[Return error: GL_ACCOUNT_REQUIRED]
+    K -->|Yes| M{GL account exists and is active in active CoA?}
+    M -->|No| N[Return error: GL_ACCOUNT_NOT_FOUND]
+    M -->|Yes| O{Another PRIMARY element references same GL account?}
+    O -->|Yes| P[Return error: DUPLICATE_GL_ACCOUNT_REFERENCE]
+    O -->|No| Q[Validate dates]
+    J -->|No| R{glAccountId provided?}
+    R -->|Yes| S[Return error: GL_ACCOUNT_NOT_ALLOWED]
+    R -->|No| Q
+    Q --> T{validFrom <= validTo when both set?}
+    T -->|No| U[Return error: INVALID_VALIDITY_PERIOD]
+    T -->|Yes| V[Create cost element in DRAFT status]
+    V --> W[Emit audit event]
+    W --> X[Return created cost element]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) — Validates that the referenced GL account exists and is active within an active Chart of Accounts
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **DUPLICATE_COST_ELEMENT_CODE**: A cost element with the same code already exists within the company
+- **INVALID_COST_ELEMENT_TYPE**: Type is not PRIMARY or SECONDARY
+- **INVALID_CATEGORY_FOR_TYPE**: Category does not match the cost element type (e.g., assessment category on a PRIMARY element)
+- **GL_ACCOUNT_REQUIRED**: PRIMARY cost element is missing the required glAccountId
+- **GL_ACCOUNT_NOT_FOUND**: Referenced GL account does not exist or is not active within an active Chart of Accounts
+- **GL_ACCOUNT_NOT_ALLOWED**: SECONDARY cost element must not reference a GL account
+- **DUPLICATE_GL_ACCOUNT_REFERENCE**: Another PRIMARY cost element within the same company already references the specified GL account
+- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo
+
+## Test Cases
+
+- creates cost element in DRAFT status with required fields
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when code already exists within the company
+- returns error when type is not PRIMARY or SECONDARY
+- returns error when category does not match the type (primary category on secondary element)
+- returns error when category does not match the type (secondary category on primary element)
+- returns error when PRIMARY element is missing glAccountId
+- returns error when GL account does not exist
+- returns error when GL account is not active
+- returns error when GL account is not in an active Chart of Accounts
+- returns error when SECONDARY element provides a glAccountId
+- returns error when another PRIMARY element in the same company references the same GL account
+- returns error when validFrom is after validTo
+- creates cost element with optional description
+- creates cost element with validFrom and validTo dates
+- creates cost element without validity dates (indefinitely valid)
+- cost elements from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

package/src/modules/accounting/docs/commands/CreateInternalOrder.md

@@ -0,0 +1,72 @@
+# CreateInternalOrder
+
+## Overview
+
+createInternalOrder establishes a new internal order in CREATED status. An internal order is a temporary cost collector for tracking expenses associated with specific short-to-medium-term activities such as projects, marketing campaigns, and R&D initiatives. It requires a unique order number within the company, an order type, a description, a responsible person, a responsible cost center within the same company, and a company reference. Optional fields include validity dates and a budget reference.
+
+## Business Rules
+
+- Internal order is always created in CREATED status
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires an `orderNumber` that is unique within the company scope
+- Requires an `orderType` of OVERHEAD, INVESTMENT, or ACCRUAL
+- Requires a `description`
+- Requires a `responsiblePersonId`
+- Requires a `costCenterId` referencing a valid cost center within the same company
+- `validFrom` and `validTo` are optional; when both are provided, validFrom must precede validTo
+- Budget assignment is optional; when assigned, the budget must exist and belong to the same company
+- Internal orders are scoped to a company; orders from different companies are fully isolated
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create internal order request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Order number unique within company?}
+    D -->|No| E[Return error: DUPLICATE_ORDER_NUMBER]
+    D -->|Yes| F{Valid order type?}
+    F -->|No| G[Return error: INVALID_ORDER_TYPE]
+    F -->|Yes| H{Description provided?}
+    H -->|No| I[Return error: DESCRIPTION_REQUIRED]
+    H -->|Yes| J{Responsible person provided?}
+    J -->|No| K[Return error: RESPONSIBLE_PERSON_REQUIRED]
+    J -->|Yes| L{Cost center exists in same company?}
+    L -->|No| M[Return error: COST_CENTER_NOT_FOUND]
+    L -->|Yes| N{validFrom <= validTo when both set?}
+    N -->|No| O[Return error: INVALID_VALIDITY_PERIOD]
+    N -->|Yes| P[Create internal order in CREATED status]
+    P --> Q[Emit audit event]
+    Q --> R[Return created internal order]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **DUPLICATE_ORDER_NUMBER**: An internal order with the same order number already exists within the company
+- **INVALID_ORDER_TYPE**: Order type is not one of the recognized values (OVERHEAD, INVESTMENT, ACCRUAL)
+- **DESCRIPTION_REQUIRED**: Description is missing or empty
+- **RESPONSIBLE_PERSON_REQUIRED**: Responsible person reference is missing
+- **COST_CENTER_NOT_FOUND**: Referenced cost center does not exist or does not belong to the same company
+- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo
+
+## Test Cases
+
+- creates internal order in CREATED status with required fields
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when order number already exists within the company
+- returns error when order type is invalid
+- returns error when description is missing
+- returns error when responsible person is missing
+- returns error when cost center does not exist
+- returns error when cost center belongs to a different company
+- returns error when validFrom is after validTo
+- creates internal order with optional validity dates
+- internal orders from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

package/src/modules/accounting/docs/commands/CreatePlanVersion.md

@@ -0,0 +1,59 @@
+# CreatePlanVersion
+
+## Overview
+
+createPlanVersion establishes a new plan version for multi-version budget planning. A plan version defines the type of planning exercise (BUDGET, FORECAST, or SIMULATION) and is scoped to a company. An optional base version can be referenced to copy line items from an existing version.
+
+## Business Rules
+
+- Requires a `name`
+- Requires a valid `type` of BUDGET, FORECAST, or SIMULATION
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- `baseVersionId` is optional; when provided, it must reference an existing plan version from which line items can be copied
+- Plan versions are scoped to a company
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create plan version request] --> B{Company exists and is ACTIVE?}
+    B -->|No| C[Return error: COMPANY_NOT_FOUND]
+    B -->|Yes| D{Valid version type?}
+    D -->|No| E[Return error: INVALID_VERSION_TYPE]
+    D -->|Yes| F{Name provided?}
+    F -->|No| G[Return error: INVALID_NAME]
+    F -->|Yes| H{Base version provided?}
+    H -->|Yes| I{Base version exists?}
+    I -->|No| J[Return error: BASE_VERSION_NOT_FOUND]
+    I -->|Yes| K[Create plan version with base reference]
+    H -->|No| L[Create plan version without base reference]
+    K --> M[Emit audit event]
+    L --> M
+    M --> N[Return created plan version]
+```
+
+## External Dependencies
+
+- [organization::getCompany](../../../organization/docs/queries/GetCompany.md) — Validates that the referenced company exists and is ACTIVE
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist or is not in ACTIVE status
+- **INVALID_VERSION_TYPE**: Type is not BUDGET, FORECAST, or SIMULATION
+- **INVALID_NAME**: Name is missing or empty
+- **BASE_VERSION_NOT_FOUND**: Referenced base version does not exist
+
+## Test Cases
+
+- creates a plan version of type BUDGET
+- creates a plan version of type FORECAST
+- creates a plan version of type SIMULATION
+- creates a plan version with a base version reference
+- creates a plan version without a base version reference
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when version type is invalid
+- returns error when name is missing
+- returns error when base version does not exist
+- emits audit event recording acting user, timestamp, and initial field values