# ListInboundShipments

## Overview

ListInboundShipments lists InboundShipment records and includes their InboundShipmentLine rows.

## Business Rules

- Accepts an optional status filter on the InboundShipment header
- Accepts optional line-level source filters (sourceDocumentType, sourceDocumentId); these join to InboundShipmentLine because source references now live at the line level
- Accepts an optional effectiveDate range filter
- Results are ordered by createdAt descending
- Supports limit and offset pagination
- Returns hasNextPage when more records are available
- Returns an empty list when no records match

## Process Flow

```mermaid
flowchart TD
    A[Receive optional filters] --> B[Build InboundShipment query]
    B --> C{Line-level source filters present?}
    C -->|Yes| D[Join to InboundShipmentLine on source refs]
    C -->|No| E[Apply header filters only]
    D --> F[Apply header filters and pagination]
    E --> F
    F --> G[Load page of shipments]
    G --> H{Any shipments?}
    H -->|No| I[Return empty items]
    H -->|Yes| J[Load InboundShipmentLine rows]
    J --> K[Group lines by shipment]
    K --> L[Return items and hasNextPage]
```

## External Dependencies

- None

## Error Scenarios

- Returns empty list if no matching records exist

## Test Cases

- lists inbound shipments with lines
- filters by status
- filters by line-level source document type and id
- returns empty list when no matches