@tailor-platform/erp-kit 0.7.0 → 0.8.0

package/src/modules/accounting/docs/models/VarianceReportLine.md

@@ -0,0 +1,43 @@
+# VarianceReportLine
+
+## Description
+
+VarianceReportLine is a child record of a VarianceReport that captures the planned amount, actual amount, computed variance amount, variance percentage, and variance direction (FAVORABLE or UNFAVORABLE) for a specific cost element within a specific accounting period. Each line carries a variance report reference, cost element reference, accounting period reference, planned amount, actual amount, variance amount, variance percentage, and variance direction. Variance direction is determined by account type: for cost/expense elements, actual below plan is FAVORABLE; for revenue elements, actual above plan is FAVORABLE. This cost-element-level detail enables managers to diagnose exactly which cost types are driving deviations from the budget.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [generateVarianceReport](../commands/GenerateVarianceReport.md) - Variance report lines are created as part of generating a variance report
+
+### Query Definitions
+
+- [GetVarianceReport](../queries/GetVarianceReport.md) - Retrieve variance report lines as part of the parent variance report
+
+### Models
+
+- VarianceReportLine
+
+### Invariants
+
+- Variance report line must reference a valid variance report via varianceReportId
+- Variance report line must reference a valid cost element via costElementId
+- Variance report line must reference a valid accounting period via accountingPeriodId
+- Variance amount is calculated as actual amount minus planned amount
+- Variance percentage is calculated as (actual - planned) / planned * 100; division by zero is handled gracefully when planned amount is zero
+- For cost/expense cost elements, variance direction is FAVORABLE when actual is less than planned, UNFAVORABLE when actual is greater than planned
+- For revenue cost elements, variance direction is FAVORABLE when actual is greater than planned, UNFAVORABLE when actual is less than planned
+- When actual equals planned, variance amount is zero and variance direction is FAVORABLE
+- A variance report line is created for each cost element that has either a planned amount or an actual amount (or both)
+- A cost element with actual postings but no corresponding budget line item generates a detail line with zero planned amount
+- Variance report lines cannot be modified independently of the parent variance report
+
+### Relationships
+
+- **Belongs to VarianceReport**: Each variance report line belongs to a VarianceReport via varianceReportId
+- **References CostElement**: Each variance report line references a CostElement via costElementId
+- **References AccountingPeriod**: Each variance report line references an AccountingPeriod via accountingPeriodId (finance-ledger module)

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

@@ -0,0 +1,64 @@
+# CalculateBudgetAvailability
+
+## Overview
+
+CalculateBudgetAvailability computes the available budget for a given cost element, cost object, and accounting period using the formula: Available = Budget - (Actual + Commitments + Encumbrances). The budget amount is sourced from the matching BudgetLineItem in the ACTIVE budget for the cost object. Actual amounts are sourced from posted journal entries in the finance-ledger module. Commitment amounts are sourced from outstanding purchase order commitment records received from the purchase module. Encumbrances are reserved for future extension and treated as zero in the current implementation. This query is the foundation for budgetary control (funds check) and is invoked during transaction validation to prevent overspending.
+
+## Business Rules
+
+- Accepts required parameters: `{ costElementId, costObjectId, costObjectType, accountingPeriodId }`
+- Locates the ACTIVE budget matching the cost object and fiscal year containing the given accounting period
+- Retrieves the BudgetLineItem matching the cost element and accounting period
+- If no matching budget or line item exists, returns available as null with a flag indicating no budget is defined
+- Budget amount is the planned amount from the matching BudgetLineItem
+- Actual amount is the sum of posted journal entry line amounts matching the cost element, cost object, and accounting period
+- Commitment amount is the sum of outstanding purchase order commitment records matching the cost element, cost object, and accounting period
+- Encumbrance amount is zero (future extension placeholder)
+- Available = Budget - (Actual + Commitments + Encumbrances)
+- Returns the computed availability along with each component amount (budget, actual, commitments, encumbrances, available)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input: costElementId, costObjectId, costObjectType, accountingPeriodId] --> B[Find ACTIVE budget for cost object and fiscal year]
+    B --> C{ACTIVE budget found?}
+    C -->|No| D[Return null availability with NO_BUDGET_DEFINED flag]
+    C -->|Yes| E[Find BudgetLineItem matching cost element and period]
+    E --> F{Line item found?}
+    F -->|No| G[Return null availability with NO_BUDGET_LINE_ITEM flag]
+    F -->|Yes| H[Retrieve budget amount from line item]
+    H --> I[Sum actual amounts from posted journal entries]
+    I --> J[Sum commitment amounts from commitment records]
+    J --> K[Set encumbrance amount to zero]
+    K --> L[Compute Available = Budget - Actual + Commitments + Encumbrances]
+    L --> M[Return budget, actual, commitments, encumbrances, and available amounts]
+```
+
+## External Dependencies
+
+- [finance-ledger::listJournalEntries](../../../finance-ledger/docs/queries/ListJournalEntries.md) - Actual amounts sourced from posted journal entries
+
+## Error Scenarios
+
+- **NO_BUDGET_DEFINED**: No ACTIVE budget exists for the specified cost object and fiscal year — caller receives null availability
+- **NO_BUDGET_LINE_ITEM**: ACTIVE budget exists but no line item matches the specified cost element and period — caller receives null availability
+- **COST_ELEMENT_NOT_FOUND**: Provided costElementId does not reference an existing cost element
+- **COST_OBJECT_NOT_FOUND**: Provided costObjectId does not reference an existing cost object of the specified type
+- **ACCOUNTING_PERIOD_NOT_FOUND**: Provided accountingPeriodId does not reference an existing accounting period
+
+## Test Cases
+
+- returns error when cost element does not exist
+- returns error when cost object does not exist
+- returns error when accounting period does not exist
+- returns budget availability with all component amounts when budget and line item exist
+- computes available as budget minus actual plus commitments plus encumbrances
+- returns actual amount aggregated from posted journal entries only
+- excludes draft journal entries from actual amount calculation
+- returns commitment amount from outstanding purchase order records
+- returns encumbrance amount as zero
+- returns null availability with NO_BUDGET_DEFINED flag when no active budget exists
+- returns null availability with NO_BUDGET_LINE_ITEM flag when line item does not exist for cost element and period
+- handles zero budget amount gracefully
+- handles case where actual exceeds budget resulting in negative availability

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

@@ -0,0 +1,43 @@
+# GetAllocationCycle
+
+## Overview
+
+GetAllocationCycle retrieves a single allocation cycle record by id, returning all header fields (name, type, status, company reference, accounting period reference) along with all associated allocation rules (sender cost center, receiver cost objects, percentages) and allocation results (sender, receiver, allocated amount, cost element). This is the primary query for reviewing allocation cycle configuration, verifying test run results, and auditing posted allocations.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full allocation cycle record including all header fields
+- Includes all associated allocation rules with sender, receiver, and percentage details
+- Includes all allocation results if the cycle has been executed (EXECUTED, POSTED, or REVERSED status)
+- Allocation results are immutable records created during execution
+- Returns null if no matching allocation cycle is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from AllocationCycle where id = input.id]
+    B --> C{Allocation cycle found?}
+    C -->|Yes| D[Load all associated allocation rules]
+    D --> E[Load all associated allocation results]
+    E --> F[Return allocation cycle with rules and results]
+    C -->|No| G[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ALLOCATION_CYCLE_NOT_FOUND**: No allocation cycle matches the given id — caller receives null
+
+## Test Cases
+
+- returns allocation cycle with all fields and allocation rules when found by id
+- returns allocation cycle with allocation results when cycle has been executed
+- returns allocation cycle with empty results when cycle is in DRAFT or VALIDATED status
+- returns allocation rules with sender, receiver, and percentage details
+- returns null when no allocation cycle matches the given id

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

@@ -0,0 +1,42 @@
+# GetBudget
+
+## Overview
+
+GetBudget retrieves a single budget record by id, returning all header fields (name, budget holder, fiscal year reference, cost object reference, cost object type, status, plan version type, total amount) along with all associated budget line items. Each line item includes the cost element reference, accounting period reference, planned amount, and the GL account derived from the primary cost element's mapping. This is the primary query for viewing budget details, reviewing planned amounts by cost element and period, and supporting budget vs. actual comparison workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full budget record including all header fields
+- Includes all associated BudgetLineItem records
+- Each line item includes cost element reference, accounting period reference, planned amount, and derived GL account
+- The GL account on each line item is derived from the referenced primary cost element's GL account mapping
+- Returns null if no matching budget is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from Budget where id = input.id]
+    B --> C{Budget found?}
+    C -->|Yes| D[Load all associated BudgetLineItem records]
+    D --> E[Return budget with all line items]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BUDGET_NOT_FOUND**: No budget matches the given id — caller receives null
+
+## Test Cases
+
+- returns budget with all header fields and line items when found by id
+- returns budget line items with cost element, period, and planned amount
+- returns budget line items with derived GL account from cost element mapping
+- returns budget with empty line items when budget has no line items
+- returns null when no budget matches the given id

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

@@ -0,0 +1,38 @@
+# GetCostCenter
+
+## Overview
+
+GetCostCenter retrieves a single cost center record by id, including all master data fields (code, name, description, category, responsible person, department reference, validity period) and the hierarchy node assignment within the cost center hierarchy. This is the primary query for viewing cost center details, validating cost center configuration, and supporting cost posting, budget, and allocation workflows.
+
+## Business Rules
+
+- Accepts a single lookup parameter: `{ id }`
+- Returns the full cost center record including all master data fields
+- Includes the hierarchy node assignment (node id and hierarchy reference) for the cost center
+- Returns null if no matching cost center is found
+- Lookup is an exact match on id
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input with id] --> B[SELECT from CostCenter where id = input.id]
+    B --> C{Cost center found?}
+    C -->|Yes| D[Load hierarchy node assignment]
+    D --> E[Return cost center with hierarchy node]
+    C -->|No| F[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COST_CENTER_NOT_FOUND**: No cost center matches the given id — caller receives null
+
+## Test Cases
+
+- returns cost center with all fields and hierarchy node assignment when found by id
+- returns cost center with responsible person and department reference populated
+- returns null when no cost center matches the given id

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