# Spec: alarm-clock-module

## Requirement: Alarm scheduling
The app MUST support creating enabled/disabled alarms with a local time, one-shot or recurring schedule, and next occurrence calculation.

### Scenario: one-shot alarm fires once
Given an enabled one-shot alarm for a future date/time
When its scheduled occurrence fires
Then the app MUST start the alarm flow
And the alarm MUST be disabled or marked completed after that occurrence unless snoozed.

### Scenario: weekday recurring alarm
Given an enabled recurring alarm with selected weekdays
When the next matching weekday/time arrives
Then the app MUST start the alarm flow
And MUST schedule the following matching occurrence.

## Requirement: Snooze
The app MUST offer snooze durations of 3, 5, and 10 minutes when an alarm is ringing.

### Scenario: snooze selected
Given an alarm is ringing
When the user selects snooze 5 minutes
Then the app MUST stop current alarm playback
And MUST schedule a one-off snooze occurrence 5 minutes later.

## Requirement: Pre-alarm notification
The app MUST schedule a silent notification 30 minutes before each next alarm occurrence when notification permission is available.

### Scenario: skip next occurrence from notification
Given a pre-alarm notification is visible
When the user taps skip next occurrence
Then the app MUST record a skip for that alarm occurrence
And MUST not fire that specific occurrence
And MUST preserve future recurring occurrences.

## Requirement: Vacation ranges
The app MUST support global vacation ranges with start/end dates and per-alarm `soundOnVacation` flag defaulting to true.

### Scenario: alarm disabled for vacation date
Given today is inside an enabled vacation range
And an alarm has `soundOnVacation=false`
When calculating next occurrence
Then the app MUST skip occurrences inside that vacation range.

## Requirement: Audio fallback
The app MUST never depend solely on an internet radio stream to ring.

### Scenario: selected station fails
Given an alarm starts with a selected radio station
When the stream fails or does not become ready before timeout
Then the app MUST try a fallback station if configured
And otherwise MUST play a bundled internal alarm sound.

## Requirement: Android reliability
The app MUST use native Android scheduling for alarm occurrences and expose permission/diagnostic status.

### Scenario: exact alarm permission missing
Given Android denies exact alarm scheduling
When the user views alarm diagnostics
Then the app MUST show that exact alarm permission is missing
And MUST provide guidance to enable it.