@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/accounting/db/profitCenterHierarchyAssignment.ts

@@ -0,0 +1,62 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { profitCenter } from "./profitCenter";
+import { profitCenterHierarchy } from "./profitCenterHierarchy";
+import { profitCenterHierarchyNode } from "./profitCenterHierarchyNode";
+
+export interface CreateProfitCenterHierarchyAssignmentTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+  profitCenterType?: TailorAnyDBType;
+  profitCenterHierarchyType?: TailorAnyDBType;
+  profitCenterHierarchyNodeType?: TailorAnyDBType;
+}
+
+export function createProfitCenterHierarchyAssignmentType<
+  const F extends Record<string, TailorAnyDBField>,
+>(params: CreateProfitCenterHierarchyAssignmentTypeParams<F>) {
+  return db
+    .type("ProfitCenterHierarchyAssignment", {
+      profitCenterId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.profitCenterType ?? profitCenter },
+          backward: "hierarchyAssignments",
+        })
+        .description("Foreign key to ProfitCenter"),
+      hierarchyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.profitCenterHierarchyType ?? profitCenterHierarchy },
+          backward: "profitCenterAssignments",
+        })
+        .description("Foreign key to ProfitCenterHierarchy"),
+      hierarchyNodeId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.profitCenterHierarchyNodeType ?? profitCenterHierarchyNode },
+          backward: "profitCenterAssignments",
+        })
+        .description("Foreign key to ProfitCenterHierarchyNode"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .indexes({
+      fields: ["profitCenterId", "hierarchyId"],
+      unique: true,
+      name: "profit_center_hierarchy_assignment_unique_idx",
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const profitCenterHierarchyAssignment = createProfitCenterHierarchyAssignmentType({});

package/src/modules/accounting/db/profitCenterHierarchyNode.ts

@@ -0,0 +1,48 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { profitCenterHierarchy } from "./profitCenterHierarchy";
+
+export interface CreateProfitCenterHierarchyNodeTypeParams<
+  F extends Record<string, TailorAnyDBField>,
+> {
+  fields?: F;
+  profitCenterHierarchyType?: TailorAnyDBType;
+}
+
+export function createProfitCenterHierarchyNodeType<
+  const F extends Record<string, TailorAnyDBField>,
+>(params: CreateProfitCenterHierarchyNodeTypeParams<F>) {
+  return db
+    .type("ProfitCenterHierarchyNode", {
+      name: db.string().description("Name of the hierarchy node"),
+      hierarchyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.profitCenterHierarchyType ?? profitCenterHierarchy },
+          backward: "nodes",
+        })
+        .description("Foreign key to ProfitCenterHierarchy"),
+      parentNodeId: db
+        .uuid({ optional: true })
+        .relation({
+          type: "n-1",
+          toward: { type: "self" },
+          backward: "childNodes",
+        })
+        .description("Optional self-referencing foreign key to parent node"),
+      sortOrder: db.int().description("Sort order within the hierarchy level"),
+      level: db.int().description("Depth level in the hierarchy"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const profitCenterHierarchyNode = createProfitCenterHierarchyNodeType({});

package/src/modules/accounting/db/varianceReport.ts

@@ -0,0 +1,54 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { accountingPeriod as accountingPeriodStub, company as companyStub } from "../lib/_db_deps";
+
+export const VARIANCE_REPORT_STATUSES = ["DRAFT", "FINAL"] as const;
+
+export interface CreateVarianceReportTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  companyType?: TailorAnyDBType;
+  accountingPeriodType?: TailorAnyDBType;
+}
+
+export function createVarianceReportType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateVarianceReportTypeParams<F>,
+) {
+  return db
+    .type("VarianceReport", {
+      costObjectType: db.string().description("Polymorphic cost object type"),
+      costObjectId: db.uuid().description("Polymorphic cost object identifier"),
+      accountingPeriodId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountingPeriodType ?? accountingPeriodStub },
+          backward: "varianceReports",
+        })
+        .description("Foreign key to AccountingPeriod"),
+      companyId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.companyType ?? companyStub },
+          backward: "varianceReports",
+        })
+        .description("Foreign key to Company"),
+      totalPlanned: db.float().description("Total planned amount"),
+      totalActual: db.float().description("Total actual amount"),
+      totalVariance: db.float().description("Total variance amount"),
+      status: db
+        .enum([...VARIANCE_REPORT_STATUSES])
+        .description("Variance report lifecycle status"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const varianceReport = createVarianceReportType({});

package/src/modules/accounting/db/varianceReportLine.ts

@@ -0,0 +1,62 @@
+import {
+  db,
+  type TailorAnyDBField,
+  type TailorAnyDBType,
+  unsafeAllowAllGqlPermission,
+  unsafeAllowAllTypePermission,
+} from "@tailor-platform/sdk";
+import { accountingPeriod as accountingPeriodStub } from "../lib/_db_deps";
+import { varianceReport } from "./varianceReport";
+import { costElement } from "./costElement";
+
+export const VARIANCE_DIRECTIONS = ["FAVORABLE", "UNFAVORABLE"] as const;
+
+export interface CreateVarianceReportLineTypeParams<F extends Record<string, TailorAnyDBField>> {
+  fields?: F;
+  varianceReportType?: TailorAnyDBType;
+  costElementType?: TailorAnyDBType;
+  accountingPeriodType?: TailorAnyDBType;
+}
+
+export function createVarianceReportLineType<const F extends Record<string, TailorAnyDBField>>(
+  params: CreateVarianceReportLineTypeParams<F>,
+) {
+  return db
+    .type("VarianceReportLine", {
+      varianceReportId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.varianceReportType ?? varianceReport },
+          backward: "lines",
+        })
+        .description("Foreign key to VarianceReport"),
+      costElementId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.costElementType ?? costElement },
+          backward: "varianceReportLines",
+        })
+        .description("Foreign key to CostElement"),
+      accountingPeriodId: db
+        .uuid()
+        .relation({
+          type: "n-1",
+          toward: { type: params.accountingPeriodType ?? accountingPeriodStub },
+          backward: "varianceReportLines",
+        })
+        .description("Foreign key to AccountingPeriod"),
+      plannedAmount: db.float().description("Planned/budgeted amount"),
+      actualAmount: db.float().description("Actual amount"),
+      varianceAmount: db.float().description("Variance amount (actual - planned)"),
+      variancePercentage: db.float().description("Variance as a percentage"),
+      varianceDirection: db.enum([...VARIANCE_DIRECTIONS]).description("Direction of the variance"),
+      ...((params.fields ?? {}) as F),
+      ...db.fields.timestamps(),
+    })
+    .permission(unsafeAllowAllTypePermission)
+    .gqlPermission(unsafeAllowAllGqlPermission);
+}
+
+export const varianceReportLine = createVarianceReportLineType({});

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

@@ -0,0 +1,54 @@
+# ActivateBudget
+
+## Overview
+
+activateBudget transitions a budget from APPROVED status to ACTIVE status, enabling funds checking (budgetary control) for the associated cost object. Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year. Multiple FORECAST or SIMULATION versions can coexist.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in APPROVED status to be activated
+- Upon activation, funds checking is enabled for the cost object
+- Only one ACTIVE budget of type BUDGET can exist per cost object per fiscal year
+- Multiple ACTIVE FORECAST or SIMULATION plan versions can coexist for the same cost object and fiscal year
+- Transitions status from APPROVED to ACTIVE
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is APPROVED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Plan version type is BUDGET?}
+    F -->|Yes| G{Another ACTIVE BUDGET exists for same cost object and fiscal year?}
+    G -->|Yes| H[Return error: DUPLICATE_ACTIVE_BUDGET]
+    G -->|No| I[Transition status from APPROVED to ACTIVE]
+    F -->|No| I
+    I --> J[Enable funds checking]
+    J --> K[Emit audit event]
+    K --> L[Return activated budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in APPROVED status
+- **DUPLICATE_ACTIVE_BUDGET**: Another ACTIVE budget of type BUDGET already exists for the same cost object and fiscal year
+
+## Test Cases
+
+- activates an APPROVED budget transitioning it to ACTIVE status
+- enables funds checking upon activation
+- returns error when budget does not exist
+- returns error when budget is not in APPROVED status
+- returns error when another ACTIVE BUDGET exists for the same cost object and fiscal year
+- allows multiple ACTIVE FORECAST versions for the same cost object and fiscal year
+- allows multiple ACTIVE SIMULATION versions for the same cost object and fiscal year
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,43 @@
+# ActivateCostElement
+
+## Overview
+
+activateCostElement transitions a cost element from DRAFT status to ACTIVE status, making it available for use in cost postings and allocation processes. Only cost elements currently in DRAFT status can be activated.
+
+## Business Rules
+
+- Cost element must exist
+- Cost element must be in DRAFT status to be activated
+- Activating an already ACTIVE or INACTIVE cost element is rejected as an invalid state transition
+- Upon activation, the cost element becomes available for cost postings and allocations
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate cost element request] --> B{Cost element exists?}
+    B -->|No| C[Return error: COST_ELEMENT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from DRAFT to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return activated cost element]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_ELEMENT_NOT_FOUND**: Cost element with the specified ID does not exist
+- **INVALID_STATE**: Cost element is not in DRAFT status (e.g., already ACTIVE or INACTIVE)
+
+## Test Cases
+
+- activates a DRAFT cost element transitioning it to ACTIVE status
+- returns error when cost element does not exist
+- returns error when cost element is already ACTIVE
+- returns error when cost element is INACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,43 @@
+# ActivateProfitCenter
+
+## Overview
+
+activateProfitCenter transitions a profit center from DRAFT status to ACTIVE status, making it available for transaction tagging and profitability reporting. Only profit centers currently in DRAFT status can be activated.
+
+## Business Rules
+
+- Profit center must exist
+- Profit center must be in DRAFT status to be activated
+- Activating an already ACTIVE or INACTIVE profit center is rejected as an invalid state transition
+- Upon activation, the profit center becomes available for revenue and cost transaction assignments
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate profit center request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from DRAFT to ACTIVE]
+    F --> G[Emit audit event]
+    G --> H[Return activated 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 not in DRAFT status (e.g., already ACTIVE or INACTIVE)
+
+## Test Cases
+
+- activates a DRAFT profit center transitioning it to ACTIVE status
+- returns error when profit center does not exist
+- returns error when profit center is already ACTIVE
+- returns error when profit center is INACTIVE
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,46 @@
+# ApproveBudget
+
+## Overview
+
+approveBudget transitions a budget from SUBMITTED status to APPROVED status. The approver must be a different user from the budget creator to enforce segregation of duties. Only SUBMITTED budgets can be approved.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in SUBMITTED status to be approved
+- Approver must be a different user from the budget creator (segregation of duties)
+- Transitions status from SUBMITTED to APPROVED
+- Emits an audit event recording the status transition, approver, and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is SUBMITTED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F{Approver different from creator?}
+    F -->|No| G[Return error: SELF_APPROVAL_NOT_ALLOWED]
+    F -->|Yes| H[Transition status from SUBMITTED to APPROVED]
+    H --> I[Emit audit event]
+    I --> J[Return approved budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in SUBMITTED status
+- **SELF_APPROVAL_NOT_ALLOWED**: Approver is the same user who created the budget (segregation of duties violation)
+
+## Test Cases
+
+- approves a SUBMITTED budget transitioning it to APPROVED status
+- returns error when budget does not exist
+- returns error when budget is not in SUBMITTED status
+- returns error when approver is the same as the budget creator
+- emits audit event recording the status transition and approver

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

@@ -0,0 +1,46 @@
+# AssignCostCenterToHierarchyNode
+
+## Overview
+
+assignCostCenterToHierarchyNode moves an existing cost center to a different hierarchy node within the same company's cost center hierarchy. This enables reorganization of the cost center structure without recreating cost center master data.
+
+## Business Rules
+
+- Cost center must exist
+- Target hierarchy node must exist within the same company's hierarchy
+- Cost center and target node must belong to the same company
+- Multiple cost centers can be assigned to the same hierarchy node
+- Emits an audit event recording the hierarchy assignment change and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign cost center to hierarchy node request] --> B{Cost center exists?}
+    B -->|No| C[Return error: COST_CENTER_NOT_FOUND]
+    B -->|Yes| D{Target hierarchy node exists?}
+    D -->|No| E[Return error: HIERARCHY_NODE_NOT_FOUND]
+    D -->|Yes| F{Same company?}
+    F -->|No| G[Return error: COMPANY_MISMATCH]
+    F -->|Yes| H[Assign cost center to target hierarchy node]
+    H --> I[Emit audit event]
+    I --> J[Return updated cost center]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: Cost center with the specified ID does not exist
+- **HIERARCHY_NODE_NOT_FOUND**: Target hierarchy node does not exist
+- **COMPANY_MISMATCH**: Cost center and target hierarchy node do not belong to the same company
+
+## Test Cases
+
+- returns error when cost center does not exist
+- returns error when target hierarchy node does not exist
+- returns error when cost center and node belong to different companies
+- assigns cost center to hierarchy node successfully
+- updates the hierarchyNodeId field on the cost center

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

@@ -0,0 +1,47 @@
+# AssignProfitCenterToHierarchyNode
+
+## Overview
+
+assignProfitCenterToHierarchyNode assigns a profit center to a specific node within a profit center hierarchy. A profit center can be assigned to exactly one node per hierarchy but can be assigned to nodes in multiple hierarchies simultaneously, enabling multi-dimensional reporting.
+
+## Business Rules
+
+- Profit center must exist
+- Target hierarchy node must exist
+- 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
+- Assigning to a new node within the same hierarchy replaces the previous assignment
+- Emits an audit event recording the hierarchy assignment and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive assign profit center to hierarchy node request] --> B{Profit center exists?}
+    B -->|No| C[Return error: PROFIT_CENTER_NOT_FOUND]
+    B -->|Yes| D{Target hierarchy node exists?}
+    D -->|No| E[Return error: HIERARCHY_NODE_NOT_FOUND]
+    D -->|Yes| F{Already assigned to a node in this hierarchy?}
+    F -->|Yes| G[Replace existing assignment with new node]
+    F -->|No| H[Create new assignment to target node]
+    G --> I[Emit audit event]
+    H --> I
+    I --> J[Return updated assignment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PROFIT_CENTER_NOT_FOUND**: Profit center with the specified ID does not exist
+- **HIERARCHY_NODE_NOT_FOUND**: Target hierarchy node does not exist
+
+## Test Cases
+
+- assigns a profit center to a hierarchy node (creates new assignment)
+- replaces existing assignment when profit center is already assigned in the same hierarchy
+- allows a profit center to be assigned to nodes in multiple hierarchies
+- returns error when profit center does not exist
+- returns error when target hierarchy node does not exist

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

@@ -0,0 +1,47 @@
+# CloseBudget
+
+## Overview
+
+closeBudget transitions a budget from ACTIVE status to CLOSED status. Once closed, no further modifications are permitted and the budget cannot be reopened. This is the terminal state of the budget lifecycle.
+
+## Business Rules
+
+- Budget must exist
+- Budget must be in ACTIVE status to be closed
+- Transitions status from ACTIVE to CLOSED
+- No further modifications are permitted after closure
+- A CLOSED budget cannot be reopened
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close budget request] --> B{Budget exists?}
+    B -->|No| C[Return error: BUDGET_NOT_FOUND]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from ACTIVE to CLOSED]
+    F --> G[Emit audit event]
+    G --> H[Return closed budget]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: Budget with the specified ID does not exist
+- **INVALID_STATE**: Budget is not in ACTIVE status
+
+## Test Cases
+
+- closes an ACTIVE budget transitioning it to CLOSED status
+- returns error when budget does not exist
+- returns error when budget is not in ACTIVE status
+- returns error when budget is in DRAFT status
+- returns error when budget is in SUBMITTED status
+- returns error when budget is in APPROVED status
+- returns error when budget is already CLOSED
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,45 @@
+# CloseInternalOrder
+
+## Overview
+
+closeInternalOrder transitions an internal order from TECHNICALLY_COMPLETED status to CLOSED status. Once closed, no further changes or cost postings are permitted. This is the terminal state of the internal order lifecycle.
+
+## Business Rules
+
+- Internal order must exist
+- Internal order must be in TECHNICALLY_COMPLETED status to be closed
+- Closing a CREATED, RELEASED, or already CLOSED order is rejected as an invalid state transition
+- CLOSED orders cannot transition to any other status
+- No further modifications are permitted after closure
+- Emits an audit event recording the status transition and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close internal order request] --> B{Internal order exists?}
+    B -->|No| C[Return error: INTERNAL_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is TECHNICALLY_COMPLETED?}
+    D -->|No| E[Return error: INVALID_STATE]
+    D -->|Yes| F[Transition status from TECHNICALLY_COMPLETED to CLOSED]
+    F --> G[Emit audit event]
+    G --> H[Return closed 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 TECHNICALLY_COMPLETED status
+
+## Test Cases
+
+- closes a TECHNICALLY_COMPLETED internal order transitioning it to CLOSED status
+- returns error when internal order does not exist
+- returns error when internal order is in CREATED status
+- returns error when internal order is in RELEASED status
+- returns error when internal order is already CLOSED
+- emits audit event recording the status transition and acting user

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

@@ -0,0 +1,53 @@
+# ConsumeCommitment
+
+## Overview
+
+consumeCommitment reduces an existing commitment and increases the actual amount when goods are received or an invoice is matched against a purchase order. This reclassifies committed funds as actual expenditure, keeping budget availability unchanged for the consumed portion.
+
+## Business Rules
+
+- Commitment must exist for the specified cost element, cost object, and period
+- Requires a positive consumption amount
+- Consumption amount must not exceed the remaining commitment amount
+- Reduces the commitment amount by the consumption amount
+- Increases the actual amount by the consumption amount
+- Budget availability remains unchanged for the consumed portion (commitment decreases, actual increases by the same amount)
+- Emits an audit event recording the consumption and acting user
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive consume commitment request] --> B{Commitment exists?}
+    B -->|No| C[Return error: COMMITMENT_NOT_FOUND]
+    B -->|Yes| D{Consumption amount positive?}
+    D -->|No| E[Return error: INVALID_CONSUMPTION_AMOUNT]
+    D -->|Yes| F{Consumption amount <= remaining commitment?}
+    F -->|No| G[Return error: CONSUMPTION_EXCEEDS_COMMITMENT]
+    F -->|Yes| H[Reduce commitment by consumption amount]
+    H --> I[Increase actual by consumption amount]
+    I --> J[Emit audit event]
+    J --> K[Return updated commitment]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMMITMENT_NOT_FOUND**: No commitment exists for the specified cost element, cost object, and period
+- **INVALID_CONSUMPTION_AMOUNT**: Consumption amount is not positive
+- **CONSUMPTION_EXCEEDS_COMMITMENT**: Consumption amount exceeds the remaining commitment amount
+
+## Test Cases
+
+- consumes a portion of an existing commitment
+- reduces commitment amount by the consumption amount
+- increases actual amount by the consumption amount
+- budget availability remains unchanged for the consumed portion
+- returns error when commitment does not exist
+- returns error when consumption amount is zero or negative
+- returns error when consumption amount exceeds remaining commitment
+- fully consumes a commitment when consumption equals remaining amount
+- emits audit event recording the consumption and acting user