# GetTimecard

## Overview

Retrieves a single `Timecard` by its id, in any lifecycle status. Used to view one worker's period sign-off record directly — its category totals, current status, sign-off trail, and whether it carries a historical correction.

## Business Rules

- Returns the Timecard regardless of `status` (OPEN, SUBMITTED, APPROVED, LOCKED)
- Category total minutes are returned as non-negative integers, reconciled to the sum of covered CalculatedTimeBlocks
- `submittedAt` is present once the Timecard has reached SUBMITTED or later; `approvedAt`/`approvedBy` are present once it has reached APPROVED or later
- `historicalCorrection` reflects whether at least one change was applied after the Timecard first reached LOCKED

## Process Flow

```mermaid
flowchart TD
    A[Caller supplies timecardId] --> B{Timecard exists?}
    B -- No --> C[Return TIMECARD_NOT_FOUND]
    B -- Yes --> D[Return Timecard with status, period, category totals, sign-off trail, historicalCorrection]
```

## External Dependencies

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

## Error Scenarios

- **TIMECARD_NOT_FOUND**: no Timecard exists for the given id

## Test Cases

- returns the Timecard when found by id, including status and category totals
- returns TIMECARD_NOT_FOUND when the id does not exist
- returns approvedAt/approvedBy for an APPROVED or LOCKED Timecard
- returns historicalCorrection = true for a LOCKED Timecard that was changed after lock