@tailor-platform/erp-kit 0.7.0 → 0.8.0

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

@@ -0,0 +1,55 @@
+# ReverseAllocationCycle
+
+## Overview
+
+reverseAllocationCycle transitions an allocation cycle from POSTED to REVERSED status by creating reversal journal entries with inverted amounts. This offsets the original allocation postings to zero. An already REVERSED cycle cannot be reversed again. The reversal period must be in OPEN or FUTURE_ENTERABLE status.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in POSTED status to be reversed
+- Reversing an already REVERSED cycle is rejected
+- Creates reversal journal entries with inverted (negated) amounts
+- Reversal journal entries must target a period that is in OPEN or FUTURE_ENTERABLE status
+- Transitions status from POSTED to REVERSED
+- Original allocation postings remain in the ledger for auditability
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reverse allocation cycle request] --> B{Allocation cycle exists?}
+    B -->|No| C[Return error: ALLOCATION_CYCLE_NOT_FOUND]
+    B -->|Yes| D{Status is POSTED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Reversal period is OPEN or FUTURE_ENTERABLE?}
+    F -->|No| G[Return error: PERIOD_NOT_OPEN]
+    F -->|Yes| H[Create reversal journal entries with inverted amounts]
+    H --> I[Post reversal entries via finance-ledger]
+    I --> J[Transition status from POSTED to REVERSED]
+    J --> K[Emit audit event]
+    K --> L[Return reversed allocation cycle]
+```
+
+## External Dependencies
+
+- [finance-ledger::getAccountingPeriod](../../../finance-ledger/docs/queries/GetAccountingPeriod.md) — Validates that the reversal period is in OPEN or FUTURE_ENTERABLE status
+- [finance-ledger::createJournalEntry](../../../finance-ledger/docs/commands/CreateJournalEntry.md) — Creates reversal journal entries
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: Allocation cycle with the specified ID does not exist
+- **INVALID_STATE**: Allocation cycle is not in POSTED status (e.g., DRAFT, VALIDATED, EXECUTED, or already REVERSED)
+- **PERIOD_NOT_OPEN**: Reversal period is not in OPEN or FUTURE_ENTERABLE status
+
+## Test Cases
+
+- reverses a POSTED allocation cycle transitioning it to REVERSED status
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in POSTED status
+- returns error when allocation cycle is already REVERSED
+- returns error when reversal period is not OPEN or FUTURE_ENTERABLE
+- returns error when allocation cycle is in DRAFT status
+- returns error when allocation cycle is in VALIDATED status
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,47 @@
+# SubmitBudget
+
+## Overview
+
+submitBudget transitions a budget from DRAFT status to SUBMITTED status, initiating the approval workflow. The budget must have at least one line item before it can be submitted.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in DRAFT status to be submitted
+- Budget must have at least one line item
+- Submitting a budget without line items is rejected
+- Transitions status from DRAFT to SUBMITTED
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive submit budget 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{Has at least one line item?}
+    F -->|No| G[Return error: NO_LINE_ITEMS]
+    F -->|Yes| H[Transition status from DRAFT to SUBMITTED]
+    H --> I[Emit audit event]
+    I --> J[Return submitted budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in DRAFT status
+- **NO_LINE_ITEMS**: Budget has no line items and cannot be submitted
+
+## Test Cases
+
+- submits a DRAFT budget with line items transitioning it to SUBMITTED status
+- returns error when budget does not exist
+- returns error when budget is not in DRAFT status
+- returns error when budget has no line items
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,44 @@
+# TechnicallyCompleteInternalOrder
+
+## Overview
+
+technicallyCompleteInternalOrder transitions an internal order from RELEASED status to TECHNICALLY_COMPLETED status. This indicates that the activity tracked by the order is complete and no further cost postings are expected, though the order remains open for final review before closure.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in RELEASED status to be technically completed
+- Technically completing a CREATED, already TECHNICALLY_COMPLETED, or CLOSED order is rejected as an invalid state transition
+- Once technically completed, no further cost postings are accepted
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive technically complete internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is RELEASED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from RELEASED to TECHNICALLY_COMPLETED]
+    F --> G[Emit audit event]
+    G --> H[Return technically completed internal order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INTERNAL_ORDER_NOT_FOUND**: Internal order with the specified ID does not exist
+- **INVALID_STATE**: Internal order is not in RELEASED status
+
+## Test Cases
+
+- technically completes a RELEASED internal order transitioning it to TECHNICALLY_COMPLETED status
+- returns error when internal order does not exist
+- returns error when internal order is in CREATED status
+- returns error when internal order is already TECHNICALLY_COMPLETED
+- returns error when internal order is CLOSED
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,45 @@
+# UpdateAllocationCycle
+
+## Overview
+
+updateAllocationCycle modifies an existing allocation cycle. Updates are only permitted when the cycle is in DRAFT status. In the current implementation, only the cycle name can be updated while in DRAFT.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in DRAFT status to be updated
+- Updates to cycles in VALIDATED, EXECUTED, POSTED, or REVERSED status are rejected
+- Only `name` can be updated
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update allocation cycle 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[Apply updates to allocation cycle]
+    F --> G[Emit audit event]
+    G --> H[Return updated allocation cycle]
+```
+
+## 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
+
+## Test Cases
+
+- updates name on a DRAFT allocation cycle
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is in VALIDATED status
+- returns error when allocation cycle is in EXECUTED status
+- returns error when allocation cycle is in POSTED status
+- returns error when allocation cycle is in REVERSED status
+- emits audit event recording previous and new field values

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

@@ -0,0 +1,47 @@
+# UpdateBudget
+
+## Overview
+
+updateBudget modifies fields on an existing budget. Updates are only permitted when the budget is in DRAFT status. Name, description, and budget holder can be updated while in DRAFT.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in DRAFT status to be updated
+- Name, description, and budget holder can be updated
+- Updates to budgets in SUBMITTED, APPROVED, ACTIVE, or CLOSED status are rejected
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update budget 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[Apply updates to budget]
+    F --> G[Emit audit event]
+    G --> H[Return updated budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in DRAFT status
+
+## Test Cases
+
+- updates name on a DRAFT budget
+- updates description on a DRAFT budget
+- updates budget holder on a DRAFT budget
+- returns error when budget does not exist
+- returns error when budget is in SUBMITTED status
+- returns error when budget is in APPROVED status
+- returns error when budget is in ACTIVE status
+- returns error when budget is in CLOSED status
+- emits audit event recording previous and new field values

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

@@ -0,0 +1,50 @@
+# UpdateCostCenter
+
+## Overview
+
+updateCostCenter modifies fields on an existing cost center. Name, description, category, responsible person, department, and validity period can be updated. The cost center code is fixed by the existing record and is not part of the update input.
+
+## Business Rules
+
+- Cost center must exist
+- Name, description, category, responsible person, and department can be updated
+- Category must be from the defined set: overhead, production, administration, sales, or research
+- When updating validTo, it must remain on or after validFrom
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update cost center request] --> B{Lookup by costCenterId}
+    B -->|Not found| C[Return error: COST_CENTER_NOT_FOUND]
+    B -->|Found| D{Valid name if provided?}
+    D -->|No| E[Return error: INVALID_NAME]
+    D -->|Yes| F{Valid category if changed?}
+    F -->|No| G[Return error: INVALID_CATEGORY]
+    F -->|Yes| H{validTo >= validFrom when both set?}
+    H -->|No| I[Return error: INVALID_VALIDITY_PERIOD]
+    H -->|Yes| J[Apply updates to cost center]
+    J --> K[Emit audit event]
+    K --> L[Return updated cost center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: Cost center with the specified ID does not exist
+- **INVALID_NAME**: Name is empty or blank when provided
+- **INVALID_CATEGORY**: Category is not one of the recognized values (overhead, production, administration, sales, research)
+- **INVALID_VALIDITY_PERIOD**: validTo is before validFrom
+
+## Test Cases
+
+- returns error when cost center does not exist
+- returns error when name is empty string
+- returns error when category is invalid
+- returns error when validTo is before validFrom
+- updates cost center with valid fields
+- updates multiple fields at once

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

@@ -0,0 +1,82 @@
+# UpdateCostElement
+
+## Overview
+
+updateCostElement modifies fields on an existing cost element that is in DRAFT or ACTIVE status. Description and name can be updated in both DRAFT and ACTIVE status. Category and GL account reference changes are only permitted while the element is in DRAFT status. Type changes are never permitted. The command enforces field-level mutability rules based on the current lifecycle status to preserve referential integrity of downstream cost postings and allocations.
+
+## Business Rules
+
+- Cost element must exist and be in DRAFT or ACTIVE status
+- Description can be updated in both DRAFT and ACTIVE status
+- Name can be updated in both DRAFT and ACTIVE status
+- Category change is not permitted when the cost element is in ACTIVE status
+- GL account reference change is not permitted after activation (only updatable in DRAFT)
+- Type change (PRIMARY to SECONDARY or vice versa) is never permitted
+- When updating category, the new category must still match the element's type
+- When updating GL account reference on a DRAFT PRIMARY element, the new GL account must be active in an active CoA
+- When updating GL account reference, no other PRIMARY element in the same company may reference the new GL account
+- When updating validFrom/validTo, validFrom must be less than or equal to validTo when both are set
+- INACTIVE cost elements cannot be updated
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update cost element request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT or ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Type change attempted?}
+    F -->|Yes| G[Return error: TYPE_CHANGE_NOT_ALLOWED]
+    F -->|No| H{Status is ACTIVE and category change attempted?}
+    H -->|Yes| I[Return error: CATEGORY_CHANGE_NOT_ALLOWED]
+    H -->|No| J{Status is ACTIVE and GL account change attempted?}
+    J -->|Yes| K[Return error: GL_ACCOUNT_CHANGE_NOT_ALLOWED]
+    J -->|No| L{Category matches type if changed?}
+    L -->|No| M[Return error: INVALID_CATEGORY_FOR_TYPE]
+    L -->|Yes| N{GL account valid if changed?}
+    N -->|No| O[Return error: GL_ACCOUNT_NOT_FOUND]
+    N -->|Yes| P{Duplicate GL account reference?}
+    P -->|Yes| Q[Return error: DUPLICATE_GL_ACCOUNT_REFERENCE]
+    P -->|No| R{validFrom <= validTo when both set?}
+    R -->|No| S[Return error: INVALID_VALIDITY_PERIOD]
+    R -->|Yes| T[Apply updates to cost element]
+    T --> U[Emit audit event]
+    U --> V[Return updated cost element]
+```
+
+## External Dependencies
+
+- [coa-management::getAccount](../../../coa-management/docs/queries/GetAccount.md) — Validates updated GL account reference if changed
+
+## Error Scenarios
+
+- **COST_ELEMENT_NOT_FOUND**: Cost element with the specified ID does not exist
+- **INVALID_STATE**: Cost element is in INACTIVE status and cannot be updated
+- **TYPE_CHANGE_NOT_ALLOWED**: Changing the type (PRIMARY/SECONDARY) is never permitted
+- **CATEGORY_CHANGE_NOT_ALLOWED**: Category cannot be changed when the cost element is in ACTIVE status
+- **GL_ACCOUNT_CHANGE_NOT_ALLOWED**: GL account reference cannot be changed after activation
+- **INVALID_CATEGORY_FOR_TYPE**: New category does not match the cost element type
+- **GL_ACCOUNT_NOT_FOUND**: Updated GL account does not exist or is not active in an active Chart of Accounts
+- **DUPLICATE_GL_ACCOUNT_REFERENCE**: Another PRIMARY cost element in the same company already references the specified GL account
+- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo
+
+## Test Cases
+
+- updates description on a DRAFT cost element
+- updates description on an ACTIVE cost element
+- updates name on a DRAFT cost element
+- updates name on an ACTIVE cost element
+- updates category on a DRAFT cost element
+- returns error when changing category on an ACTIVE cost element
+- returns error when changing type on any cost element
+- returns error when changing GL account on an ACTIVE cost element
+- updates GL account on a DRAFT PRIMARY cost element
+- returns error when updated GL account does not exist
+- returns error when updated GL account is already referenced by another PRIMARY element
+- returns error when new category does not match the element type
+- returns error when cost element does not exist
+- returns error when cost element is INACTIVE
+- returns error when validFrom is after validTo
+- emits audit event recording previous and new field values

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

@@ -0,0 +1,62 @@
+# UpdateInternalOrder
+
+## Overview
+
+updateInternalOrder modifies fields on an existing internal order. Updates are permitted when the order is in CREATED or RELEASED status. Orders in TECHNICALLY_COMPLETED or CLOSED status cannot be updated. The order type cannot be changed after the order has been released.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in CREATED or RELEASED status
+- Description, responsible person, cost center, and validity dates can be updated in CREATED or RELEASED status
+- Order type cannot be changed after the order is released
+- Orders in TECHNICALLY_COMPLETED or CLOSED status cannot be updated
+- When updating validity dates, validFrom must precede validTo when both are set
+- Updated cost center must belong to the same company
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is CREATED or RELEASED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Order type change attempted after release?}
+    F -->|Yes| G[Return error: ORDER_TYPE_CHANGE_NOT_ALLOWED]
+    F -->|No| H{Cost center valid if changed?}
+    H -->|No| I[Return error: COST_CENTER_NOT_FOUND]
+    H -->|Yes| J{validFrom <= validTo when both set?}
+    J -->|No| K[Return error: INVALID_VALIDITY_PERIOD]
+    J -->|Yes| L[Apply updates to internal order]
+    L --> M[Emit audit event]
+    M --> N[Return updated internal order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INTERNAL_ORDER_NOT_FOUND**: Internal order with the specified ID does not exist
+- **INVALID_STATE**: Internal order is in TECHNICALLY_COMPLETED or CLOSED status and cannot be updated
+- **ORDER_TYPE_CHANGE_NOT_ALLOWED**: Order type cannot be changed after the order is released
+- **COST_CENTER_NOT_FOUND**: Updated cost center does not exist or does not belong to the same company
+- **INVALID_VALIDITY_PERIOD**: validFrom is after validTo
+
+## Test Cases
+
+- updates description on a CREATED internal order
+- updates description on a RELEASED internal order
+- updates responsible person on a CREATED internal order
+- updates cost center on a CREATED internal order
+- updates validity dates on a CREATED internal order
+- returns error when internal order does not exist
+- returns error when internal order is TECHNICALLY_COMPLETED
+- returns error when internal order is CLOSED
+- returns error when changing order type after release
+- returns error when updated cost center does not exist
+- returns error when validFrom is after validTo
+- emits audit event recording previous and new field values

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

@@ -0,0 +1,56 @@
+# UpdateProfitCenter
+
+## Overview
+
+updateProfitCenter modifies fields on an existing profit center. In DRAFT status, all mutable fields can be updated. In ACTIVE status, only limited fields (description, responsible person) can be updated. INACTIVE profit centers cannot be updated.
+
+## Business Rules
+
+- Profit center must exist
+- Profit center must be in DRAFT or ACTIVE status
+- In DRAFT status: name, description, responsible person, validFrom, validTo can be updated
+- In ACTIVE status: only description and responsible person can be updated
+- When updating validTo, it must remain on or after validFrom
+- INACTIVE profit centers cannot be updated
+- Emits an audit event recording previous and new field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update profit center request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT or ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Status is ACTIVE and restricted field change?}
+    F -->|Yes| G[Return error: FIELD_NOT_UPDATABLE]
+    F -->|No| H{validTo >= validFrom when both set?}
+    H -->|No| I[Return error: INVALID_VALIDITY_PERIOD]
+    H -->|Yes| J[Apply updates to profit center]
+    J --> K[Emit audit event]
+    K --> L[Return updated profit center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PROFIT_CENTER_NOT_FOUND**: Profit center with the specified ID does not exist
+- **INVALID_STATE**: Profit center is in INACTIVE status and cannot be updated
+- **FIELD_NOT_UPDATABLE**: Attempted to change a field that is not updatable in ACTIVE status
+- **INVALID_VALIDITY_PERIOD**: validTo is before validFrom
+
+## Test Cases
+
+- updates name on a DRAFT profit center
+- updates description on a DRAFT profit center
+- updates description on an ACTIVE profit center
+- updates responsible person on a DRAFT profit center
+- updates responsible person on an ACTIVE profit center
+- returns error when changing restricted fields on an ACTIVE profit center
+- returns error when profit center does not exist
+- returns error when profit center is INACTIVE
+- returns error when validTo is before validFrom
+- emits audit event recording previous and new field values

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

@@ -0,0 +1,57 @@
+# ValidateAllocationCycle
+
+## Overview
+
+validateAllocationCycle transitions an allocation cycle from DRAFT status to VALIDATED status. Validation verifies that the cycle has at least one allocation rule and that receiver percentages sum to exactly 100% for each sender. Only DRAFT cycles can be validated.
+
+## Business Rules
+
+- Allocation cycle must exist
+- Allocation cycle must be in DRAFT status to be validated
+- Cycle must have at least one allocation rule
+- Allocation rule percentages for each sender must sum to exactly 100%
+- Percentage values must be positive (greater than zero)
+- Upon validation, the cycle becomes eligible for execution
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive validate allocation cycle 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{Has at least one allocation rule?}
+    F -->|No| G[Return error: NO_ALLOCATION_RULES]
+    F -->|Yes| P{All percentages positive?}
+    P -->|No| Q[Return error: INVALID_PERCENTAGE]
+    P -->|Yes| H{Percentages sum to 100% per sender?}
+    H -->|No| I[Return error: INVALID_PERCENTAGE_SUM]
+    H -->|Yes| J[Transition status from DRAFT to VALIDATED]
+    J --> K[Emit audit event]
+    K --> L[Return validated allocation cycle]
+```
+
+## 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
+- **NO_ALLOCATION_RULES**: Cycle has no allocation rules defined
+- **INVALID_PERCENTAGE**: One or more percentage values are zero or negative
+- **INVALID_PERCENTAGE_SUM**: Allocation rule percentages for one or more senders do not sum to exactly 100%
+
+## Test Cases
+
+- validates a DRAFT allocation cycle with valid rules transitioning it to VALIDATED status
+- returns error when allocation cycle does not exist
+- returns error when allocation cycle is not in DRAFT status
+- returns error when cycle has no allocation rules
+- returns error when any percentage is zero or negative
+- returns error when percentages do not sum to 100% for a sender
+- validates with multiple senders each summing to 100%
+- emits audit event recording the status transition and acting user