@tailor-platform/erp-kit 0.6.0 → 0.8.0

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

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

@@ -0,0 +1,63 @@
+# CreateProfitCenter
+
+## Overview
+
+createProfitCenter establishes a new profit center in DRAFT status within the management accounting module. A profit center represents a discrete business segment for which profitability can be independently evaluated. It carries a company reference, a unique code within the company scope, a name, a required valid-from date, an optional valid-to date, an optional description, and an optional responsible person reference.
+
+## Business Rules
+
+- Profit center 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 `validFrom` date
+- `validTo` is optional; when provided, it must be on or after the `validFrom` date
+- `description` is optional and can be set on creation
+- `responsiblePersonId` is optional and can be set on creation
+- Profit centers are scoped to a company; profit 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 profit 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_PROFIT_CENTER_CODE]
+    D -->|Yes| F{Name provided?}
+    F -->|No| G[Return error: INVALID_NAME]
+    F -->|Yes| H{validFrom provided?}
+    H -->|No| I[Return error: VALID_FROM_REQUIRED]
+    H -->|Yes| J{validTo >= validFrom when both set?}
+    J -->|No| K[Return error: INVALID_VALIDITY_PERIOD]
+    J -->|Yes| L[Create profit center in DRAFT status]
+    L --> M[Emit audit event]
+    M --> N[Return created profit 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_PROFIT_CENTER_CODE**: A profit center with the same code already exists within the company
+- **INVALID_NAME**: Name is missing or empty
+- **VALID_FROM_REQUIRED**: validFrom date is required but not provided
+- **INVALID_VALIDITY_PERIOD**: validTo is before validFrom
+
+## Test Cases
+
+- creates profit center 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 name is missing
+- returns error when validFrom is not provided
+- returns error when validTo is before validFrom
+- creates profit center with optional description
+- creates profit center without validTo
+- profit centers from different companies are isolated
+- emits audit event recording acting user, timestamp, and initial field values

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

@@ -0,0 +1,45 @@
+# CreateProfitCenterHierarchy
+
+## Overview
+
+createProfitCenterHierarchy establishes a new profit center hierarchy within a company. The hierarchy provides the tree structure required for organizing profit centers into grouping nodes for hierarchical roll-up profitability reporting. A hierarchy carries a name and company reference. Hierarchies are scoped to a company.
+
+## Business Rules
+
+- Requires a valid `companyId` referencing an ACTIVE company from the organization module
+- Requires a `name` for the hierarchy
+- Hierarchy is scoped to a company; hierarchies from different companies are fully isolated
+- A company can have multiple profit center hierarchies
+- Emits an audit event recording the acting user, timestamp, and initial field values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create profit 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 profit 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
+
+- creates a profit center hierarchy with name and company reference
+- returns error when company does not exist
+- returns error when company is not ACTIVE
+- returns error when name is missing
+- hierarchies from different companies are isolated
+- a company can have multiple profit center hierarchies
+- emits audit event recording acting user, timestamp, and initial field values

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

@@ -0,0 +1,60 @@
+# CreateProfitCenterHierarchyNode
+
+## Overview
+
+createProfitCenterHierarchyNode adds a new node to an existing profit center hierarchy. Nodes form a tree structure with parent-child relationships, supporting hierarchical roll-up profitability reporting. A root node must be created before child nodes can be added. The same structural rules as cost center hierarchy nodes apply.
+
+## 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
+
+- creates a root node in an existing hierarchy
+- creates a child node under an existing parent node
+- returns error when hierarchy does not exist
+- returns error when parent node does not exist
+- returns error when attempting to create a second root node
+- returns error when node references itself as parent
+- returns error when node would create a circular reference
+- emits audit event recording acting user, timestamp, and initial field values