# ListDepartmentsByCompany

## Overview

ListDepartmentsByCompany retrieves departments belonging to a specific company with paginated results. Returns a paginated list of department records for the given companyId. This supports organizational structure display, department selection UIs, and operations that need to enumerate departments within a company.

## Business Rules

- companyId is required
- Returns departments for the specified company regardless of status by default
- Results are paginated using offset/limit (default page size applies)
- An optional `status` filter can restrict results to ACTIVE or INACTIVE departments
- An optional `parentDepartmentId` filter can restrict results to departments under a specific parent (null for top-level only)
- Returns an empty list if the company has no departments
- Results are ordered by department name by default; sortable by name, code, or createdAt
- `hasNextPage` indicates whether more results exist beyond the current page

## Process Flow

```mermaid
flowchart TD
    A[Receive request with companyId] --> B[Query departments where companyId matches]
    B --> C{Status filter provided?}
    C -->|Yes| D[Filter by status]
    C -->|No| E[Continue]
    D --> E
    E --> F{parentDepartmentId filter provided?}
    F -->|Yes| G[Filter by parentDepartmentId]
    F -->|No| H[Continue]
    G --> H
    H --> I[Order by name]
    I --> I2[Apply limit+1 / offset pagination]
    I2 --> J[Return paginated department list]
```

## External Dependencies

- None

## Error Scenarios

- None (returns empty list when no departments found)

## Test Cases

- returns departments for a company
- returns empty list when no departments exist
- filters by status when provided
- filters by parentDepartmentId when provided
- filters root departments when parentDepartmentId is null
- filters departments by INACTIVE status
- returns departments ordered by name
- returns hasNextPage true when more results exist
- respects limit parameter