@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/src/modules/accounting/docs/queries/GetCostCenterHierarchy.md

@@ -0,0 +1,45 @@
+# GetCostCenterHierarchy
+
+## Overview
+
+GetCostCenterHierarchy retrieves a cost center hierarchy by id, returning the full tree structure including all hierarchy nodes (root, intermediate grouping nodes, and leaf nodes) with their parent-child relationships, sort order, and level attributes. Each node includes the list of cost centers assigned to it. This query supports hierarchical roll-up reporting, cost center organization browsing, and hierarchy-based cost aggregation.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the hierarchy record with all nodes assembled into a tree structure
+- Each node includes its id, name, parent node reference, sort order, level, and list of assigned cost centers
+- The root node has no parent reference
+- Child nodes are nested under their parent nodes in the tree
+- Assigned cost centers on each node include their full master data fields
+- Returns null if no matching hierarchy is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from CostCenterHierarchy where id = input.id]
+    B --> C{Hierarchy found?}
+    C -->|Yes| D[Load all hierarchy nodes]
+    D --> E[Assemble nodes into tree structure using parent-child references]
+    E --> F[Load assigned cost centers for each node]
+    F --> G[Return hierarchy with complete tree and cost center assignments]
+    C -->|No| H[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_HIERARCHY_NOT_FOUND**: No cost center hierarchy matches the given id — caller receives null
+
+## Test Cases
+
+- returns hierarchy with all nodes in tree structure when found by id
+- returns hierarchy with root node and nested child nodes
+- returns hierarchy nodes with assigned cost centers populated
+- returns leaf nodes with no children
+- returns null when no hierarchy matches the given id

package/src/modules/accounting/docs/queries/GetCostElement.md

@@ -0,0 +1,39 @@
+# GetCostElement
+
+## Overview
+
+GetCostElement retrieves a single cost element record by id, returning all fields including code, name, type (PRIMARY or SECONDARY), category, status, validity period (valid-from/to), GL account reference (for primary elements), company reference, and description. This is the primary query for viewing cost element details, validating cost element configuration, and supporting downstream processes such as cost posting validation and allocation rule setup.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full cost element record including all header fields
+- For PRIMARY cost elements, the GL account reference is included
+- For SECONDARY cost elements, the GL account reference is null
+- Returns null if no matching cost element is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from CostElement where id = input.id]
+    B --> C{Cost element found?}
+    C -->|Yes| D[Return cost element with all fields]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_ELEMENT_NOT_FOUND**: No cost element matches the given id — caller receives null
+
+## Test Cases
+
+- returns cost element with all fields when found by id
+- returns primary cost element with GL account reference populated
+- returns secondary cost element with GL account reference as null
+- returns null when no cost element matches the given id

package/src/modules/accounting/docs/queries/GetInternalOrder.md

@@ -0,0 +1,42 @@
+# GetInternalOrder
+
+## Overview
+
+GetInternalOrder retrieves a single internal order record by id, returning all fields including order number, order type (OVERHEAD, INVESTMENT, ACCRUAL), description, status (CREATED, RELEASED, TECHNICALLY_COMPLETED, CLOSED), responsible person, responsible cost center reference, validity period (valid-from/to), company reference, and optional budget assignment. This is the primary query for viewing internal order details, validating order status for cost postings, and reviewing accumulated costs against budgets.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full internal order record including all header fields
+- Includes the responsible cost center reference
+- Includes the budget assignment reference if one exists
+- Returns null if no matching internal order is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from InternalOrder where id = input.id]
+    B --> C{Internal order found?}
+    C -->|Yes| D[Load responsible cost center reference]
+    D --> E[Load budget assignment if present]
+    E --> F[Return internal order with all fields]
+    C -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INTERNAL_ORDER_NOT_FOUND**: No internal order matches the given id — caller receives null
+
+## Test Cases
+
+- returns internal order with all fields when found by id
+- returns internal order with responsible cost center reference populated
+- returns internal order with budget assignment when one exists
+- returns internal order without budget assignment when none exists
+- returns null when no internal order matches the given id

package/src/modules/accounting/docs/queries/GetProfitCenter.md

@@ -0,0 +1,38 @@
+# GetProfitCenter
+
+## Overview
+
+GetProfitCenter retrieves a single profit center record by id, returning all fields including code, name, description, status (DRAFT, ACTIVE, INACTIVE), responsible person, validity period (valid-from/to), company reference, and hierarchy node assignment. This is the primary query for viewing profit center details, validating profit center configuration, and supporting transaction tagging and profitability reporting workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full profit center record including all master data fields
+- Includes the hierarchy node assignment within the profit center hierarchy
+- Returns null if no matching profit center is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from ProfitCenter where id = input.id]
+    B --> C{Profit center found?}
+    C -->|Yes| D[Return profit center with all fields]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PROFIT_CENTER_NOT_FOUND**: No profit center matches the given id — caller receives null
+
+## Test Cases
+
+- returns profit center with all fields when found by id
+- returns profit center with hierarchy node assignment populated
+- returns profit center with responsible person and validity period
+- returns null when no profit center matches the given id

package/src/modules/accounting/docs/queries/GetProfitCenterHierarchy.md

@@ -0,0 +1,46 @@
+# GetProfitCenterHierarchy
+
+## Overview
+
+GetProfitCenterHierarchy retrieves a profit center hierarchy by id, returning the full tree structure including all hierarchy nodes (root, intermediate grouping nodes, and leaf nodes) with their parent-child relationships. Each node includes the list of profit centers assigned to it. This query supports hierarchical roll-up profitability reporting, segment analysis, and profit center organization browsing.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the hierarchy record with all nodes assembled into a tree structure
+- Each node includes its id, name, parent node reference, and list of assigned profit centers
+- The root node has no parent reference
+- Child nodes are nested under their parent nodes in the tree
+- Assigned profit centers on each node include their full master data fields
+- A profit center can appear in multiple hierarchies but only once within a given hierarchy
+- Returns null if no matching hierarchy is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from ProfitCenterHierarchy where id = input.id]
+    B --> C{Hierarchy found?}
+    C -->|Yes| D[Load all hierarchy nodes]
+    D --> E[Assemble nodes into tree structure using parent-child references]
+    E --> F[Load assigned profit centers for each node]
+    F --> G[Return hierarchy with complete tree and profit center assignments]
+    C -->|No| H[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PROFIT_CENTER_HIERARCHY_NOT_FOUND**: No profit center hierarchy matches the given id — caller receives null
+
+## Test Cases
+
+- returns hierarchy with all nodes in tree structure when found by id
+- returns hierarchy with root node and nested child nodes
+- returns hierarchy nodes with assigned profit centers populated
+- returns leaf nodes with no children
+- returns null when no hierarchy matches the given id

package/src/modules/accounting/docs/queries/GetVarianceReport.md

@@ -0,0 +1,45 @@
+# GetVarianceReport
+
+## Overview
+
+GetVarianceReport retrieves a single variance report record by id, returning all header fields (cost object reference, cost object type, accounting period reference, status, total planned, total actual, total variance) along with all associated VarianceReportLine detail records. Each detail line includes the cost element reference, accounting period, planned amount, actual amount, variance amount, variance percentage, and variance direction (FAVORABLE or UNFAVORABLE). This is the primary query for reviewing period-end variance analysis results, drilling into cost element-level deviations, and supporting management reporting workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full variance report record including all header fields and summary totals
+- Includes all associated VarianceReportLine records with cost element-level detail
+- Each detail line includes planned amount, actual amount, variance amount, variance percentage, and variance direction
+- Variance direction is FAVORABLE when actual costs are below plan (for cost/expense elements) or actual revenue is above plan (for revenue elements)
+- Variance direction is UNFAVORABLE when actual costs are above plan or actual revenue is below plan
+- Summary totals (total planned, total actual, total variance) are the sums of the corresponding detail line amounts
+- Returns null if no matching variance report is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from VarianceReport where id = input.id]
+    B --> C{Variance report found?}
+    C -->|Yes| D[Load all associated VarianceReportLine records]
+    D --> E[Return variance report with summary totals and detail lines]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **VARIANCE_REPORT_NOT_FOUND**: No variance report matches the given id — caller receives null
+
+## Test Cases
+
+- returns variance report with all header fields and detail lines when found by id
+- returns variance report with summary totals matching the sum of detail lines
+- returns detail lines with planned amount, actual amount, variance amount, and variance percentage
+- returns detail lines with variance direction FAVORABLE for cost elements where actual is below plan
+- returns detail lines with variance direction UNFAVORABLE for cost elements where actual is above plan
+- returns null when no variance report matches the given id

package/src/modules/accounting/docs/queries/ListAllocationCycles.md

@@ -0,0 +1,63 @@
+# ListAllocationCycles
+
+## Overview
+
+ListAllocationCycles retrieves a list of allocation cycle records matching optional filter criteria. Callers can filter by companyId, type (ASSESSMENT or DISTRIBUTION), status (DRAFT, VALIDATED, EXECUTED, POSTED, REVERSED), and accountingPeriodId. This query supports allocation cycle browsing, period-end processing review, and allocation audit workflows.
+
+## Business Rules
+
+- Accepts optional filter parameters: `{ companyId, type, status, accountingPeriodId }`
+- Returns a list of allocation cycles matching all provided filters (AND logic)
+- When no filters are provided, returns all allocation cycles accessible to the caller
+- Each returned allocation cycle includes header fields but does not include nested rules and results (use GetAllocationCycle for full details)
+- Returns an empty list if no allocation cycles match the given filters
+- Results are scoped to the caller's accessible companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with optional filters] --> B[Build query with provided filters]
+    B --> C{companyId provided?}
+    C -->|Yes| D[Add companyId filter]
+    C -->|No| E[Skip companyId filter]
+    D --> F{type provided?}
+    E --> F
+    F -->|Yes| G[Add type filter]
+    F -->|No| H[Skip type filter]
+    G --> I{status provided?}
+    H --> I
+    I -->|Yes| J[Add status filter]
+    I -->|No| K[Skip status filter]
+    J --> L{accountingPeriodId provided?}
+    K --> L
+    L -->|Yes| M[Add accountingPeriodId filter]
+    L -->|No| N[Skip accountingPeriodId filter]
+    M --> O[Execute query]
+    N --> O
+    O --> P[Return list of matching allocation cycles]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_TYPE_FILTER**: Provided type value is not ASSESSMENT or DISTRIBUTION
+- **INVALID_STATUS_FILTER**: Provided status value is not DRAFT, VALIDATED, EXECUTED, POSTED, or REVERSED
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Provided accountingPeriodId does not reference an existing accounting period
+
+## Test Cases
+
+- returns all allocation cycles when no filters are provided
+- returns allocation cycles filtered by companyId
+- returns allocation cycles filtered by type ASSESSMENT
+- returns allocation cycles filtered by type DISTRIBUTION
+- returns allocation cycles filtered by status POSTED
+- returns allocation cycles filtered by accountingPeriodId
+- returns allocation cycles matching multiple filters simultaneously
+- returns an empty list when no allocation cycles match the given filters
+- returns error when type filter is invalid
+- returns error when status filter is invalid
+- returns error when accountingPeriodId does not exist

package/src/modules/accounting/docs/queries/ListBudgets.md

@@ -0,0 +1,70 @@
+# ListBudgets
+
+## Overview
+
+ListBudgets retrieves a list of budget records matching optional filter criteria. Callers can filter by companyId, fiscalYearId, costObjectType (cost center, profit center, or internal order), costObjectId, status (DRAFT, SUBMITTED, APPROVED, ACTIVE, CLOSED), and planVersionId. This query supports budget browsing, budget vs. actual reporting setup, and budget administration workflows.
+
+## Business Rules
+
+- Accepts optional filter parameters: `{ companyId, fiscalYearId, costObjectType, costObjectId, status, planVersionId }`
+- Returns a list of budgets matching all provided filters (AND logic)
+- When no filters are provided, returns all budgets accessible to the caller
+- Each returned budget includes header fields but does not include nested line items (use GetBudget for full details)
+- Returns an empty list if no budgets match the given filters
+- Results are scoped to the caller's accessible companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with optional filters] --> B[Build query with provided filters]
+    B --> C{companyId provided?}
+    C -->|Yes| D[Add companyId filter]
+    C -->|No| E[Skip companyId filter]
+    D --> F{fiscalYearId provided?}
+    E --> F
+    F -->|Yes| G[Add fiscalYearId filter]
+    F -->|No| H[Skip fiscalYearId filter]
+    G --> I{costObjectType provided?}
+    H --> I
+    I -->|Yes| J[Add costObjectType filter]
+    I -->|No| K[Skip costObjectType filter]
+    J --> L{costObjectId provided?}
+    K --> L
+    L -->|Yes| M[Add costObjectId filter]
+    L -->|No| N[Skip costObjectId filter]
+    M --> O{status provided?}
+    N --> O
+    O -->|Yes| P[Add status filter]
+    O -->|No| Q[Skip status filter]
+    P --> R{planVersionId provided?}
+    Q --> R
+    R -->|Yes| S[Add planVersionId filter]
+    R -->|No| T[Skip planVersionId filter]
+    S --> U[Execute query]
+    T --> U
+    U --> V[Return list of matching budgets]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_STATUS_FILTER**: Provided status value is not DRAFT, SUBMITTED, APPROVED, ACTIVE, or CLOSED
+- **INVALID_COST_OBJECT_TYPE_FILTER**: Provided costObjectType is not a recognized cost object type
+
+## Test Cases
+
+- returns all budgets when no filters are provided
+- returns budgets filtered by companyId
+- returns budgets filtered by fiscalYearId
+- returns budgets filtered by costObjectType
+- returns budgets filtered by costObjectId
+- returns budgets filtered by status ACTIVE
+- returns budgets filtered by planVersionId
+- returns budgets matching multiple filters simultaneously
+- returns an empty list when no budgets match the given filters
+- returns error when status filter is invalid
+- returns error when costObjectType filter is invalid

package/src/modules/accounting/docs/queries/ListCostCenters.md

@@ -0,0 +1,55 @@
+# ListCostCenters
+
+## Overview
+
+ListCostCenters retrieves a list of cost center records matching optional filter criteria. Callers can filter by companyId, category (overhead, production, administration, sales, research), and hierarchyNodeId to find cost centers assigned to a specific node in the hierarchy. This query supports cost center browsing, allocation rule setup, and budget planning.
+
+## Business Rules
+
+- Accepts optional filter parameters: `{ companyId, category, hierarchyNodeId }`
+- Returns a list of cost centers matching all provided filters (AND logic)
+- When no filters are provided, returns all cost centers accessible to the caller
+- Each returned cost center includes all master data fields and hierarchy node assignment
+- Returns an empty list if no cost centers match the given filters
+- Results are scoped to the caller's accessible companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with optional filters] --> B[Build query with provided filters]
+    B --> C{companyId provided?}
+    C -->|Yes| D[Add companyId filter]
+    C -->|No| E[Skip companyId filter]
+    D --> F{category provided?}
+    E --> F
+    F -->|Yes| G[Add category filter]
+    F -->|No| H[Skip category filter]
+    G --> I{hierarchyNodeId provided?}
+    H --> I
+    I -->|Yes| J[Add hierarchyNodeId filter]
+    I -->|No| K[Skip hierarchyNodeId filter]
+    J --> L[Execute query]
+    K --> L
+    L --> M[Return list of matching cost centers]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_CATEGORY_FILTER**: Provided category value is not a recognized cost center category
+- **HIERARCHY_NODE_NOT_FOUND**: Provided hierarchyNodeId does not reference an existing hierarchy node
+
+## Test Cases
+
+- returns all cost centers when no filters are provided
+- returns cost centers filtered by companyId
+- returns cost centers filtered by category
+- returns cost centers filtered by hierarchyNodeId
+- returns cost centers matching multiple filters simultaneously
+- returns an empty list when no cost centers match the given filters
+- returns error when category filter is invalid
+- returns error when hierarchyNodeId does not exist

package/src/modules/accounting/docs/queries/ListCostElements.md

@@ -0,0 +1,63 @@
+# ListCostElements
+
+## Overview
+
+ListCostElements retrieves a list of cost element records matching optional filter criteria. Callers can filter by companyId, type (PRIMARY or SECONDARY), category (overhead, material, labor, depreciation for primary; assessment, distribution, internal_activity_allocation, settlement for secondary), and status (DRAFT, ACTIVE, INACTIVE). This query supports cost element catalog browsing, allocation rule configuration, and budget line item setup.
+
+## Business Rules
+
+- Accepts optional filter parameters: `{ companyId, type, category, status }`
+- Returns a list of cost elements matching all provided filters (AND logic)
+- When no filters are provided, returns all cost elements accessible to the caller
+- Each returned cost element includes all fields (code, name, type, category, status, validity period, GL account reference, companyId, description)
+- Returns an empty list if no cost elements match the given filters
+- Results are scoped to the caller's accessible companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with optional filters] --> B[Build query with provided filters]
+    B --> C{companyId provided?}
+    C -->|Yes| D[Add companyId filter]
+    C -->|No| E[Skip companyId filter]
+    D --> F{type provided?}
+    E --> F
+    F -->|Yes| G[Add type filter]
+    F -->|No| H[Skip type filter]
+    G --> I{category provided?}
+    H --> I
+    I -->|Yes| J[Add category filter]
+    I -->|No| K[Skip category filter]
+    J --> L{status provided?}
+    K --> L
+    L -->|Yes| M[Add status filter]
+    L -->|No| N[Skip status filter]
+    M --> O[Execute query]
+    N --> O
+    O --> P[Return list of matching cost elements]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_TYPE_FILTER**: Provided type value is not PRIMARY or SECONDARY
+- **INVALID_STATUS_FILTER**: Provided status value is not DRAFT, ACTIVE, or INACTIVE
+- **INVALID_CATEGORY_FILTER**: Provided category value is not a recognized cost element category
+
+## Test Cases
+
+- returns all cost elements when no filters are provided
+- returns cost elements filtered by companyId
+- returns cost elements filtered by type PRIMARY
+- returns cost elements filtered by type SECONDARY
+- returns cost elements filtered by category
+- returns cost elements filtered by status ACTIVE
+- returns cost elements matching multiple filters simultaneously
+- returns an empty list when no cost elements match the given filters
+- returns error when type filter is invalid
+- returns error when status filter is invalid
+- returns error when category filter is invalid

package/src/modules/accounting/docs/queries/ListInternalOrders.md

@@ -0,0 +1,62 @@
+# ListInternalOrders
+
+## Overview
+
+ListInternalOrders retrieves a list of internal order records matching optional filter criteria. Callers can filter by companyId, orderType (OVERHEAD, INVESTMENT, ACCRUAL), status (CREATED, RELEASED, TECHNICALLY_COMPLETED, CLOSED), and costCenterId to find orders assigned to a specific responsible cost center. This query supports internal order browsing, project portfolio review, and cost posting target selection.
+
+## Business Rules
+
+- Accepts optional filter parameters: `{ companyId, orderType, status, costCenterId }`
+- Returns a list of internal orders matching all provided filters (AND logic)
+- When no filters are provided, returns all internal orders accessible to the caller
+- Each returned internal order includes all header fields, responsible cost center reference, and budget assignment
+- Returns an empty list if no internal orders match the given filters
+- Results are scoped to the caller's accessible companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with optional filters] --> B[Build query with provided filters]
+    B --> C{companyId provided?}
+    C -->|Yes| D[Add companyId filter]
+    C -->|No| E[Skip companyId filter]
+    D --> F{orderType provided?}
+    E --> F
+    F -->|Yes| G[Add orderType filter]
+    F -->|No| H[Skip orderType filter]
+    G --> I{status provided?}
+    H --> I
+    I -->|Yes| J[Add status filter]
+    I -->|No| K[Skip status filter]
+    J --> L{costCenterId provided?}
+    K --> L
+    L -->|Yes| M[Add costCenterId filter]
+    L -->|No| N[Skip costCenterId filter]
+    M --> O[Execute query]
+    N --> O
+    O --> P[Return list of matching internal orders]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_ORDER_TYPE_FILTER**: Provided orderType value is not OVERHEAD, INVESTMENT, or ACCRUAL
+- **INVALID_STATUS_FILTER**: Provided status value is not CREATED, RELEASED, TECHNICALLY_COMPLETED, or CLOSED
+- **COST_CENTER_NOT_FOUND**: Provided costCenterId does not reference an existing cost center
+
+## Test Cases
+
+- returns all internal orders when no filters are provided
+- returns internal orders filtered by companyId
+- returns internal orders filtered by orderType OVERHEAD
+- returns internal orders filtered by status RELEASED
+- returns internal orders filtered by costCenterId
+- returns internal orders matching multiple filters simultaneously
+- returns an empty list when no internal orders match the given filters
+- returns error when orderType filter is invalid
+- returns error when status filter is invalid
+- returns error when costCenterId does not exist

package/src/modules/accounting/docs/queries/ListProfitCenters.md

@@ -0,0 +1,49 @@
+# ListProfitCenters
+
+## Overview
+
+ListProfitCenters retrieves a list of profit center records matching optional filter criteria. Callers can filter by companyId and status (DRAFT, ACTIVE, INACTIVE). This query supports profit center browsing, transaction tagging setup, and profitability reporting configuration.
+
+## Business Rules
+
+- Accepts optional filter parameters: `{ companyId, status }`
+- Returns a list of profit centers matching all provided filters (AND logic)
+- When no filters are provided, returns all profit centers accessible to the caller
+- Each returned profit center includes all master data fields and hierarchy node assignment
+- Returns an empty list if no profit centers match the given filters
+- Results are scoped to the caller's accessible companies
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with optional filters] --> B[Build query with provided filters]
+    B --> C{companyId provided?}
+    C -->|Yes| D[Add companyId filter]
+    C -->|No| E[Skip companyId filter]
+    D --> F{status provided?}
+    E --> F
+    F -->|Yes| G[Add status filter]
+    F -->|No| H[Skip status filter]
+    G --> I[Execute query]
+    H --> I
+    I --> J[Return list of matching profit centers]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_STATUS_FILTER**: Provided status value is not DRAFT, ACTIVE, or INACTIVE
+
+## Test Cases
+
+- returns all profit centers when no filters are provided
+- returns profit centers filtered by companyId
+- returns profit centers filtered by status ACTIVE
+- returns profit centers filtered by status DRAFT
+- returns profit centers matching companyId and status filters simultaneously
+- returns an empty list when no profit centers match the given filters
+- returns error when status filter is invalid