# ListTimecardsByAssignment

## Overview

Lists a worker's Timecards across periods for a given Assignment, paginated. This is the per-worker history view — for example to review a worker's sign-off record across months, or to find the current OPEN period for that Assignment.

## Business Rules

- Filters by `assignmentId`; returns Timecards across all statuses and periods for that Assignment
- At most one Timecard exists per Assignment and non-overlapping period, so results do not contain overlapping periods for the same Assignment
- Results are paginated, typically ordered by `periodStart`

## Process Flow

```mermaid
flowchart TD
    A[Caller supplies assignmentId + pagination params] --> B{Valid assignmentId?}
    B -- No --> C[Return INVALID_QUERY_PARAMS]
    B -- Yes --> D[Look up Timecards for assignmentId across all periods and statuses]
    D --> E[Return paginated page ordered by periodStart]
```

## External Dependencies

- [time-tracking::Timecard](../model/Timecard.md) model — entity being queried

## Error Scenarios

- **INVALID_QUERY_PARAMS**: a required query parameter is missing or malformed
- **INVALID_PAGINATION_CURSOR**: supplied pagination cursor is not valid for this query

## Test Cases

- returns Timecards for the given Assignment across multiple periods and statuses
- returns an empty page when the Assignment has no Timecards
- returns paginated results across multiple pages when the Assignment has many periods
- returns INVALID_QUERY_PARAMS when assignmentId is missing