# GetPeriodByDate

## Overview

GetPeriodByDate finds the accounting period that contains a given date for a specific company. It looks up the operating period where the date falls between startDate and endDate (inclusive). This query is the primary mechanism used by upstream modules (purchase, sales, inventory, manufacturing) to determine which accounting period a transaction date maps to and whether posting is permitted.

## Business Rules

- Requires `companyId` and `date` as input parameters
- Searches for an accounting period where `startDate <= date <= endDate` and `periodType = OPERATING`
- Only OPERATING periods are returned; ADJUSTMENT periods are excluded from date-based lookup
- Returns the full accounting period record including status, enabling callers to check posting eligibility
- Returns null if no operating period covers the given date (e.g., date falls outside all defined fiscal year boundaries)
- If multiple periods could theoretically match (should not occur with properly configured non-overlapping periods), the query returns the first match

## Process Flow

```mermaid
flowchart TD
    A[Receive input with companyId and date] --> B[SELECT from AccountingPeriod where companyId = input.companyId AND startDate <= input.date AND endDate >= input.date AND periodType = OPERATING]
    B --> C{Period found?}
    C -->|Yes| D[Return accounting period record]
    C -->|No| E[Return null]
```

## External Dependencies

- None

## Error Scenarios

- **PERIOD_NOT_FOUND**: No operating period covers the given date for the specified company — caller receives null

## Test Cases

- returns period when date falls within range
- returns null when no period covers the date
- only returns OPERATING periods (not ADJUSTMENT)
